@zackbart/connecta 0.22.0 → 0.22.1

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.22.0";
+export declare const CONNECTA_VERSION = "0.22.1";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.22.0";
+export const CONNECTA_VERSION = "0.22.1";

package/documentation/connector-guides.md

@@ -136,11 +136,11 @@ few things both shapes fully own:
 
 - [Hand-written HTTP providers](./provider-conventions.md#hand-written-http-providers)
   (H1–H14) — `api()` surfaces where Connecta owns every name, schema,
-  projection, and error. Cloudflare and Notion.
+  projection, and error. Cloudflare, Notion, and Vercel.
 - [Hosted-MCP proxies](./provider-conventions.md#hosted-mcp-proxies) (P1–P13) —
   `remoteMcp()` wrappers where the downstream owns the catalog and Connecta
   owns the endpoint, credential, classification, guide, and budget. Linear,
-  Stripe, and Mixpanel.
+  Stripe, Mixpanel, and RevenueCat.
 
 Both sets are judged by one measure: what the convention saves the model that
 interacts with connecta, priced in discovery tokens, wrong-tool selection,

package/documentation/connectors.md

@@ -137,6 +137,7 @@ Maintained provider guides:
 - [Notion](./notion.md)
 - [RevenueCat](./revenuecat.md)
 - [Stripe](./stripe.md)
+- [Vercel](./vercel.md)
 
 ## The `api()` construction contract
 
@@ -226,12 +227,13 @@ into a result or a typed failure. That split is not fastidiousness. Notion's
 cannot fix it — while Cloudflare's means a token scope, and the two want
 opposite next moves. A helper that guessed would be wrong for one of them.
 
-Cloudflare and Notion both run on it. Their existing suites carried over
-unchanged, which proves the migration kept the behavior those suites cover —
-not that nothing changed. Three things did, and the changelog names them: a
-3xx is refused where both providers used to follow it, both now fail past
-their byte ceiling, and `cloudflare()`'s `baseUrl` is validated at
-construction. Each suite gained one test for the ceiling, because the one
+Cloudflare, Notion, and Vercel run on it. The first two existing suites carried
+over unchanged when the helper was extracted, which proves that migration kept
+the behavior those suites cover — not that nothing changed. Three things did,
+and the changelog names them: a 3xx is refused where both providers used to
+follow it, both now fail past their byte ceiling, and `cloudflare()`'s
+`baseUrl` is validated at construction. Each suite gained one test for the
+ceiling, because the one
 guard the helper was written to add is the one a provider's own mapper can
 most easily disarm: a bare `catch` around `response.json()` swallows the
 transport's refusal along with a parse error, and turns a response nobody was

package/documentation/operations.md

@@ -258,7 +258,7 @@ in.
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
 | `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, ambient Access requests without a browser-readable token, `gate()`, the generation fence, and the request path |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
-| `provider-registry.test.ts` | all six maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
+| `provider-registry.test.ts` | all seven maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
 | `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
 | `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
@@ -274,6 +274,7 @@ in.
 | `ui-credentials.test.ts` | credential-management routes: save, test, delete, validation, authentication, same-origin checks, and multi-field credential shapes |
 | `ui.test.ts` | the server shell and remaining `/ui/*` routes: gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, plus the URL safety gates |
 | `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, per-schema validator caching, and an unusable schema passed through with one warning |
+| `vercel-provider.test.ts` | `vercel()` construction, team scoping, project and deployment projections, finite build and runtime logs, value-safe environment variables, domains, lifecycle writes, REST hatches, typed failures, and credential test |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
 

package/documentation/provider-conventions.md

@@ -1,6 +1,6 @@
 # Provider conventions
 
-The six maintained prebuilt connections grew one at a time, and until now
+The seven maintained prebuilt connections grew one at a time, and until now
 "excellent provider" meant whatever the last author thought. This document
 writes the judgment down so it can be argued with, audited, and reused.
 
@@ -8,7 +8,7 @@ There are two genuinely different provider shapes, and one convention set
 cannot honestly cover both:
 
 - **Hand-written HTTP providers** — `api()` surfaces where Connecta owns every
-  tool name, schema, projection, and error. Today: Cloudflare, Notion.
+  tool name, schema, projection, and error. Today: Cloudflare, Notion, Vercel.
 - **Hosted-MCP proxies** — `remoteMcp()` wrappers around a server somebody else
   operates, where the names, schemas, results, and error prose arrive as they
   are. Today: Linear, Stripe, Mixpanel, RevenueCat.
@@ -85,7 +85,7 @@ other source with no description or no `inputSchema`.
 ## Hand-written HTTP providers
 
 Connecta owns the whole surface here, which means every miss is ours. These
-apply to `api()`-based prebuilt connections (Cloudflare, Notion) and are the
+apply to `api()`-based prebuilt connections (Cloudflare, Notion, Vercel) and are the
 bar any future one is written to.
 
 None of them asks an author to re-derive transport safety. URL confinement,
@@ -646,11 +646,11 @@ evidence and nothing else: no tool is generated from one, which is the
 ## What the audit checks
 
 The provider audit ([#342](https://github.com/zackbart/connecta/issues/342))
-runs this document against each of the six providers and returns a verdict per
+runs this document against each of the seven providers and returns a verdict per
 convention: **meets**, **misses** (with the fix), or **not applicable** (with
 the reason). A convention is never quietly skipped, and an accepted miss is
 recorded as a provider-specific exception with its argument, not left blank.
-Its six reports live in [provider-audit.md](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md), and the
+Its seven reports live in [provider-audit.md](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md), and the
 mechanically checkable half of the hand-written bar runs on every test run in
 [`test/provider-conventions.test.ts`](https://github.com/zackbart/connecta/blob/main/test/provider-conventions.test.ts) —
 so a convention that was met once stays met, or fails loudly.

package/documentation/upgrading.md

@@ -57,7 +57,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.22.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.22.1 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +106,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.22.0
+npm pkg set dependencies.@zackbart/connecta=0.22.1
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.22.0 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.22.1 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.22.0 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.22.1 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,7 +207,7 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
-### 0.21.2 → 0.22.0
+### 0.21.2 → 0.22.1
 
 Connector and user policy remain config-as-code. If `identity.connectorAccess`
 is configured, every interactive human may now manage the authentication of

package/documentation/vercel.md

@@ -0,0 +1,194 @@
+# Vercel
+
+Import `vercel()` independently from `@zackbart/connecta/providers/vercel`.
+It is a hand-written `api()` connection over Vercel's public REST API. The
+connection owns 18 named operations and three provider-relative REST hatches.
+It adds no provider dependency, imports no `node:` builtin, and is not reachable
+from Connecta's root entry.
+
+```ts
+import { vercel } from "@zackbart/connecta/providers/vercel";
+
+const hosting = vercel("hosting", {
+  purpose: "Production web applications for the product team",
+  teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
+});
+```
+
+The deployment stores one Vercel access token in Connecta's credential vault.
+Create the token in Vercel Account Settings under Tokens. Scope it to the
+personal account or team this connection needs and give it an expiration date.
+The operator UI's Test action calls `GET /v2/user` and reports the authenticated
+username, email, name, or id. Connecta never probes it in the background.
+
+## Why this uses REST instead of Vercel MCP
+
+Vercel MCP provides useful project, deployment, and log reads, but it does not
+cover the public API. This connection keeps those common reads and adds project
+domains, value-safe environment-variable management, deployment promotion and
+deletion, and direct access to versioned REST endpoints. The three hatches mean
+a newly published Vercel endpoint does not require a Connecta release before an
+agent can use it.
+
+This is still authored rather than generated. No OpenAPI document creates tools
+at runtime. The named operations are reviewed, projected, classified, and
+tested by hand. The published OpenAPI document is used only by
+`npm run drift:check` to compare the 19 named endpoints this connection calls.
+
+## Configuration
+
+```ts
+vercel("hosting", {
+  title: "Production hosting",
+  authScope: "shared",
+  purpose: "Customer-facing sites owned by Platform",
+  teamId: "team_...",
+  defaultPageSize: 20,
+  instructions: "Never promote the docs project from this connection.",
+  maxResultBytes: 512_000,
+  callAdmission: {
+    rules: [{ maxConcurrency: 6 }],
+  },
+});
+```
+
+`purpose` is required and blank text throws at construction. `teamId` is a
+default, not a hidden lock. Named account-scoped tools accept a `teamId`
+override; pass `null` to target the token owner's personal account explicitly.
+Without a configured default or an override, Vercel uses that personal account.
+`list_teams` returns the ids needed to reach a team.
+
+`defaultPageSize` defaults to 20 and must be a whole number from 1 through 100.
+Vercel meters endpoints separately, so the connection invents no global request
+budget. A deployment may supply `callAdmission` when it has its own concurrency
+or call-rate requirement.
+
+`baseUrl` exists for a test double or an HTTPS proxy. The guarded transport
+confines every path under that base, refuses redirects, prevents request headers
+from replacing `Authorization`, passes `ctx.signal`, and stops reading at 8 MiB.
+The runtime-log read also returns at most 500 rows and stops a stream that stays
+open past 10 seconds. HTTP is accepted only for a loopback test double.
+
+## Named tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_teams` | Lists teams the token can reach. |
+| `list_projects` | Searches or lists lean project summaries. |
+| `get_project` | Reads build settings, Git identity, and the production deployment. |
+| `list_deployments` | Filters deployments by project, target, state, branch, or SHA. |
+| `get_deployment` | Reads one deployment by id or hostname. |
+| `get_build_logs` | Reads at most 1,000 existing build events with live following disabled. |
+| `get_runtime_logs` | Reads a 1–500 row runtime-log snapshot and stops a stream open past 10 seconds. |
+| `list_project_domains` | Lists verification, redirect, branch, and custom-environment state. |
+| `add_project_domain` | Adds a regular, redirect, branch, or custom-environment domain. |
+| `verify_project_domain` | Rechecks a pending domain after its DNS challenge is complete. |
+| `remove_project_domain` | Removes a project domain, optionally with domains redirecting to it. |
+| `list_project_env_vars` | Lists metadata without asking Vercel to decrypt values. |
+| `upsert_project_env_var` | Creates or replaces one variable. |
+| `update_project_env_var` | Patches one variable by its id. |
+| `delete_project_env_var` | Removes one variable from future deployments. |
+| `promote_deployment` | Promotes an existing build to production without rebuilding. |
+| `cancel_deployment` | Cancels work that is queued, initializing, or building. |
+| `delete_deployment` | Permanently removes a deployment and its URL. |
+
+Every read returns a lean projection by default. Projects drop security,
+billing, and presentation settings. Deployments keep state, target, timestamps,
+creator, and Git identity. Domain reads keep the verification challenge because
+dropping it would make an unverified result unusable. The project, deployment,
+domain, and build-log reads accept `raw: true` when a Vercel field omitted by
+the projection matters.
+
+`raw: true` preserves unprojected list items while keeping the named tool's
+declared envelope: list calls still return their item key and `page`, and build
+logs still return `{ events }`.
+
+## Environment values are write-only here
+
+`list_project_env_vars` sends `decrypt=false`, then drops `value` even if
+Vercel returns one anyway. It returns the key, id, storage type, visibility,
+targets, branch, custom-environment ids, comment, and timestamps. The create and
+update tools accept a value as input, but their result projection drops it too.
+
+That boundary is deliberate. An agent can audit placement and make a requested
+change without filling its context with database URLs or API keys. Sensitive
+values cannot be read back from Vercel in any case. The generic
+`vercel_api_get` hatch returns the endpoint's untouched response, so a caller
+that deliberately requests an endpoint capable of decrypting a non-sensitive
+value has asked to cross the named tool's safer boundary.
+
+Environment changes affect future deployments. They do not rewrite a value
+already embedded in an existing deployment, and none of the environment tools
+triggers a deployment on its own.
+
+## REST hatches
+
+Vercel's API is too large and changes too often for every operation to deserve
+a permanent named tool.
+
+- `vercel_api_get` accepts only GET and is explicitly read-only.
+- `vercel_api_mutate` accepts JSON POST, PUT, PATCH, and DELETE. It always
+  crosses `call_destructive_tool`.
+- `vercel_api_upload` accepts POST or PUT with exactly one explicit UTF-8 or
+  base64 body. It also crosses `call_destructive_tool`.
+
+All three take a path beginning with `/` and including Vercel's version, such
+as `/v1/edge-config`. Query parameters are name/value rows rather than a string
+to parse. They use the configured default team unless the caller passes
+`personalAccount: true`; that flag cannot be combined with a `teamId` or `slug`
+query row. The upload hatch accepts endpoint-specific headers such as a digest,
+but refuses credential, cookie, host, content-type, content-length, and
+transfer-encoding headers. It reads no local file. The caller supplies the
+bytes, content type, and any checksum the endpoint requires.
+
+Use a named tool when one exists. A named tool wins on argument validation,
+result size, or safety routing. The hatch is for products such as Edge Config,
+feature flags, drains, checks, security, and team settings that are not worth a
+large permanent catalog.
+
+## Pagination
+
+The four list families expose one connector-wide contract:
+
+```ts
+{
+  items: [],
+  page: { hasMore: true, nextCursor: "opaque" }
+}
+```
+
+The item key is `teams`, `projects`, `deployments`, or `domains`. Pass
+`nextCursor` back as `cursor` unchanged. Vercel uses different parameter names
+and cursor types behind the four endpoints. The connector owns that mapping so
+programs do not parse timestamps or branch on provider-specific pagination.
+
+Environment-variable listing has no pagination in Vercel's published contract
+and returns `{ variables }` without a false page object.
+
+## Typed failures
+
+- HTTP 401 and 403 become `auth_required`. Vercel uses 403 both for a bad token
+  and for a token outside the requested team or operation scope.
+- HTTP 404 becomes `not_found`. Re-list the owning project, deployment, domain,
+  or environment variable before using the id again.
+- HTTP 400, 409, and 422 become `invalid_args`.
+- HTTP 429 becomes `rate_limited`. `Retry-After` wins; otherwise the connector
+  derives the delay from `X-RateLimit-Reset`.
+- HTTP 5xx becomes `unavailable`.
+
+The error text keeps Vercel's error code and message. It never parses prose to
+invent a class.
+
+## No SDK on purpose
+
+The connection imports only Connecta modules and Web APIs. `@vercel/sdk` is not
+a dependency or optional peer. Direct fetch keeps the root Workers-safe, avoids
+shipping the generated model graph, and lets the reviewed named operations and
+the REST hatches share one guarded transport.
+
+The trade is API drift, handled explicitly. `scripts/drift/vercel-endpoints.json`
+records the method, versioned path, specification revision, and request/response
+digest for every fixed endpoint. Before a release, `npm run drift:check` compares
+those rows with Vercel's published OpenAPI document at
+`https://openapi.vercel.sh/`. The hatches are intentionally absent from that
+list because their endpoint is chosen by deployment code at call time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -90,6 +90,10 @@
     "./providers/stripe": {
       "types": "./dist/providers/stripe.d.ts",
       "import": "./dist/providers/stripe.js"
+    },
+    "./providers/vercel": {
+      "types": "./dist/providers/vercel.d.ts",
+      "import": "./dist/providers/vercel.js"
     }
   },
   "scripts": {

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.22.0",
+    "@zackbart/connecta": "0.22.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {