# @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](https://vercel.com/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](https://vercel.com/docs/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](https://vercel.com/geist/brands) 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](https://vercel.com/docs/rest-api)
- [Access tokens](https://vercel.com/docs/accounts/access-tokens)
- [Sign in with Vercel](https://vercel.com/docs/sign-in-with-vercel)