@kody/vercel

@kody/vercel

Intent

Reusable Vercel REST helpers so Kody agents can inspect the caller's teams, projects, deployments, domains, and environment-variable metadata — not a shared platform account. Auth is a saved access token by default, or a bring-your-own Sign in with Vercel OAuth client. Reads are free-form. Mutations (create-deployment, add-domain, create-env-var, and mutating request calls) support dryRun: true, and live writes also require confirm: true.

This listing is meant to be forked. After you fork, save your own vercelToken (or connect OAuth) and call the helpers in your account. No personal project names or team slugs are hard-coded. Environment-variable listing returns keys and targets only — values are never decrypted or returned.

Share this package as https://kody.codes/@kody/vercel

Auth

Do not paste tokens or client secrets into chat.

Lane A: Access token

1. Create a token at Account Tokens. Choose Full Account, a team, or a single project.
2. Save it in Kody (do not paste the value in chat):

https://kody.codes/account/secrets/new?name=vercelToken&description=Vercel%20access%20token%20(Bearer%20for%20api.vercel.com)&allowedHosts=api.vercel.com&scope=user

3. In the account secrets UI, approve host api.vercel.com.
4. Smoke-test with ./smoke-test (see Smoke test).

Default helper input: omit secretName and integrationName. The package sends Authorization: Bearer using vercelToken.

Pass account: "work" to use secret vercelToken-work, or pass secretName: "vercelToken-team". There are no hard-coded account aliases.

Team- and project-scoped tokens infer their scope. Full-account tokens should pass teamId or teamSlug when targeting a team's resources.

Lane B: OAuth

Create a Sign in with Vercel app and register the redirect URI exactly:

https://kody.codes/connect/oauth

Then open this prefilled connect URL while signed in to Kody. Paste the client ID into the setup form (flow=pkce):

https://kody.codes/connect/oauth?provider=vercel&authorizeUrl=https%3A%2F%2Fvercel.com%2Foauth%2Fauthorize&tokenUrl=https%3A%2F%2Fapi.vercel.com%2Flogin%2Foauth%2Ftoken&flow=pkce&pkce=true&scopes=openid%20email%20profile%20offline_access&allowedHosts=api.vercel.com%2Cvercel.com&apiBaseUrl=https%3A%2F%2Fapi.vercel.com&dashboardUrl=https%3A%2F%2Fvercel.com%2Fdocs%2Fsign-in-with-vercel&providerSetupInstructions=Create%20a%20Sign%20in%20with%20Vercel%20app%20and%20register%20redirect%20URI%20exactly%20https%3A%2F%2Fkody.codes%2Fconnect%2Foauth.%20REST%20API%20permissions%20for%20this%20OAuth%20lane%20are%20in%20private%20beta%20%E2%80%94%20prefer%20an%20access%20token%20for%20teams%2C%20projects%2C%20and%20deployments.%20Paste%20the%20client%20id%20into%20this%20form.

Decoded: authorize https://vercel.com/oauth/authorize, token https://api.vercel.com/login/oauth/token, scopes openid email profile offline_access, hosts api.vercel.com,vercel.com.

Call helpers with integrationName: "vercel" (or your chosen provider name). secretName selects the token lane and ignores integrationName.

Reconnect later at https://kody.codes/connect/oauth?provider=vercel.

Hosts

• api.vercel.com — all REST calls (required)
• vercel.com — OAuth authorize + token dashboard (OAuth lane)

Mutation safety

Pass dryRun: true on create-deployment, add-domain, create-env-var, and mutating request calls to return { dryRun: true, method, path, body } without contacting Vercel.

Those same writes also throw unless confirm: true.

Env-var dry-run previews redact value. Listing env vars never requests decryption and never returns values.

import addDomain from 'kody:@kody/vercel/add-domain'

const preview = await addDomain({
	project: 'example-app',
	name: 'www.example.com',
	dryRun: true,
})

const domain = await addDomain({
	project: 'example-app',
	name: 'www.example.com',
	confirm: true,
})

Do not create production deployments unless the caller explicitly confirms that target.

Smoke test

import vercel from 'kody:@kody/vercel'

export default async function main() {
	return await vercel({ dryRun: true })
}

Without vercelToken (and without a connected vercel integration) a live call still returns { ok: true, live: false } plus the setup URLs. With credentials it reads a trimmed /v2/user profile — no writes.

Exports

• kody:@kody/vercel — action dispatcher (defaults to smoke-test)
• kody:@kody/vercel/request — low-level Vercel REST helper (escape hatch)
• kody:@kody/vercel/get-user — authenticated user (read-only)
• kody:@kody/vercel/list-teams — teams the token can see (read-only)
• kody:@kody/vercel/get-team — team detail (read-only)
• kody:@kody/vercel/list-projects — projects (read-only)
• kody:@kody/vercel/get-project — project detail (read-only)
• kody:@kody/vercel/list-deployments — deployments (read-only)
• kody:@kody/vercel/get-deployment — deployment detail (read-only)
• kody:@kody/vercel/create-deployment — create deployment (dryRun / confirm)
• kody:@kody/vercel/list-domains — account or project domains (read-only)
• kody:@kody/vercel/add-domain — add account or project domain (dryRun / confirm)
• kody:@kody/vercel/list-env-vars — env-var metadata, no values (read-only)
• kody:@kody/vercel/create-env-var — create env var (dryRun / confirm)
• kody:@kody/vercel/smoke-test — credential smoke test (read-only)

Examples

import listProjects from 'kody:@kody/vercel/list-projects'

export default async function main() {
	return await listProjects({ teamSlug: 'acme', search: 'docs' })
}

import listDeployments from 'kody:@kody/vercel/list-deployments'

export default async function main() {
	return await listDeployments({ projectId: 'prj_…', limit: 10 })
}

import listEnvVars from 'kody:@kody/vercel/list-env-vars'

export default async function main() {
	return await listEnvVars({ project: 'example-app' })
}

import createDeployment from 'kody:@kody/vercel/create-deployment'

export default async function main() {
	return await createDeployment({
		name: 'example-app',
		target: 'preview',
		dryRun: true,
	})
}

Branding

community-icon.svg is Vercel's official triangle logomark from the Vercel brand assets press kit (light / black). Vercel is a trademark of Vercel, Inc. This package is not affiliated with or endorsed by Vercel.

Docs

• Vercel REST API
• Access tokens
• Sign in with Vercel