Skip to content

README.md

78 lines · 3.3 KB · Markdown
Raw

@kody/vercel

Intent

Reusable Vercel REST helpers so you can inspect your teams, projects, deployments, domains, and environment-variable metadata — not a shared platform account. Auth is a saved access token (vercelToken) against api.vercel.com. Prefer the token lane; Sign in with Vercel OAuth REST permissions are still private beta and are not required for this package. 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 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

What it does

  • Read the authenticated user, teams, projects, deployments, and domains
  • List environment-variable metadata (keys/targets only — never values)
  • Create deployments, add domains, and create env vars with dry-run previews
  • Escape-hatch REST request for paths not wrapped by named helpers

Prerequisites / setup

Access token (recommended)

  1. Create a token at Account Tokens (Full Account, a team, or a single project).

  2. Save it in Kody as vercelToken (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. Approve host api.vercel.com in the secrets UI.

  4. Optional: use vercelToken-work via account: "work", or pass secretName: "vercelToken-team" for another saved token.

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

OAuth (optional / private beta for REST)

Create a Sign in with Vercel app and register redirect URI exactly https://kody.codes/connect/oauth. Prefer an access token for teams, projects, and deployments until REST OAuth permissions leave private beta. Agents: see AGENTS.md for the connect URL and integrationName usage.

Mutation safety

Pass dryRun: true on mutating helpers to preview { dryRun, method, path, body } without contacting Vercel. Live writes also require confirm: true. Env-var dry-run previews redact value. Do not create production deployments unless the caller explicitly confirms that target.

Done when

  • vercelToken is saved (or OAuth connected) and api.vercel.com is approved
  • A credential smoke check returns ok: true (live profile or setup URLs)
  • Mutating helpers refuse live writes without confirm: true
  • Env listing never returns secret values

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