@vercel/connect 0.0.4-alpha.2

package/README.md

@@ -0,0 +1,351 @@
+# `@vercel/connect`
+
+SDK for obtaining scoped tokens for third-party services on behalf of apps or users. The runtime authenticates the calling Vercel project via [`@vercel/oidc`](https://www.npmjs.com/package/@vercel/oidc) and exchanges the OIDC token for a Vercel Connect-issued credential through the Vercel API.
+
+The package ships four entrypoints:
+
+- `@vercel/connect` — the core token / authorization SDK (no peer deps beyond `@vercel/oidc`).
+- `@vercel/connect/ash` — adapter helpers for the [Ash](https://github.com/vercel/ash) connection runtime. `experimental-ash` is an _optional_ peer dependency.
+- `@vercel/connect/betterauth` — a [Better Auth](https://www.better-auth.com/) `genericOAuth` provider. `better-auth` is an _optional_ peer dependency.
+- `@vercel/connect/authjs` — an [Auth.js](https://authjs.dev/) (NextAuth core) `OAuth2Config` provider. `@auth/core` is an _optional_ peer dependency.
+
+Consumers that don't use a given integration never load it.
+
+## Install
+
+```sh
+pnpm add @vercel/connect
+# or
+npm install @vercel/connect
+```
+
+The package is ESM-only (`"type": "module"`).
+
+---
+
+## `@vercel/connect`
+
+### `getToken(connector, params, options?)`
+
+```ts
+function getToken(
+  connector: string,
+  params: ConnectTokenParams,
+  options?: ConnectOptions,
+): Promise<string>;
+```
+
+Returns a token string for the given Vercel Connect connector and subject. Wraps `getTokenResponse` and discards the metadata.
+
+```ts
+import { getToken } from "@vercel/connect";
+
+const token = await getToken(process.env.CONNECTOR_LINEAR!, {
+  subject: { type: "user", id: "user_123" },
+});
+```
+
+### `getTokenResponse(connector, params, options?)`
+
+```ts
+function getTokenResponse(
+  connector: string,
+  params: ConnectTokenParams,
+  options?: ConnectOptions,
+): Promise<ConnectTokenResponse>;
+```
+
+Returns the full token response including `expiresAt`, `installationId`, `tenantId`, and `externalSubject`. Use this when you need the expiration or any of the metadata fields.
+
+Both functions share an in-process LRU cache (max 100 entries) keyed by `connector` plus the full `params` payload. Cached entries are reused until they fall inside the `validityBufferMs` window before expiration, after which they're refetched.
+
+`connector` accepts either the opaque service connector key (`scl_...`) or the human-readable UID (`oauth/mcp-linear-app`) — both resolve to the same connector on the Vercel Connect side.
+
+### `startAuthorization(connector, params, options?)`
+
+```ts
+function startAuthorization(
+  connector: string,
+  params: ConnectTokenParams,
+  options?: ConnectAuthorizationOptions,
+): Promise<ConnectAuthorizationResponse>;
+```
+
+Begins an interactive (user-facing) authorization flow. Returns a `{ request, verifier, url }` triple; redirect the end user to `url`, then call `getToken` / `getTokenResponse` once Vercel Connect signals completion (via the configured `webhook` or `callbackUrl`). The `verifier` is the PKCE verifier — store it alongside the in-flight request so you can correlate the callback.
+
+```ts
+import { startAuthorization } from "@vercel/connect";
+
+const { url, verifier } = await startAuthorization(
+  process.env.CONNECTOR_LINEAR!,
+  { subject: { type: "user", id: "user_123" } },
+  { callbackUrl: "https://app.example.com/connect/callback" },
+);
+```
+
+`callbackUrl` must be `https://` or `http://localhost` (for `vercel dev`). `webhook` must be `https://`. Both are validated client-side before the request is sent.
+
+### Types
+
+```ts
+interface ConnectTokenParams {
+  subject: { type: "app" } | { type: "user"; id: string; issuer?: string };
+  installationId?: string;
+  audience?: string[];
+  scopes?: string[];
+  resources?: string[];
+  authorizationDetails?: Array<{ type: string } & Record<string, unknown>>;
+  /** Buffer (ms) before expiration to consider the token invalid. Default: 30_000. */
+  validityBufferMs?: number;
+}
+
+interface ConnectTokenResponse {
+  token: string;
+  /** Expiration timestamp in ms since epoch. */
+  expiresAt: number;
+  name?: string;
+  installationId?: string;
+  tenantId?: string;
+  externalSubject?: string;
+  metadata?: Record<string, unknown>;
+}
+
+interface ConnectOptions {
+  /** Override the OIDC bearer used to authenticate to the Vercel API. */
+  vercelToken?: string;
+}
+
+interface ConnectAuthorizationOptions {
+  vercelToken?: string;
+  /** Browser-redirect target after consent. Must be https:// or http://localhost. */
+  callbackUrl?: string;
+  /** Server-POST callback. Must be https://. */
+  webhook?: string;
+}
+
+interface ConnectAuthorizationResponse {
+  request: string;
+  verifier: string;
+  url: string;
+}
+```
+
+### Errors
+
+All exchange / authorization calls reject with typed errors. Catch them by class to distinguish recoverable consent-required cases from terminal failures.
+
+| Class                                | Meaning                                                                                                           |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `NoValidTokenError`                  | Vercel Connect has no valid credential for this subject. For user subjects, recoverable via `startAuthorization`. |
+| `UserAuthorizationRequiredError`     | The user has not consented yet (or the previous grant was revoked). Recoverable via `startAuthorization`.         |
+| `ConnectorInstallationRequiredError` | The Vercel Connect connector is not installed for this team. Terminal — an operator must install the connector.   |
+
+Any other failure (network, 5xx, etc.) is thrown as a plain `Error` with the HTTP status and response body in the message.
+
+```ts
+import {
+  getToken,
+  NoValidTokenError,
+  UserAuthorizationRequiredError,
+  ConnectorInstallationRequiredError,
+} from "@vercel/connect";
+
+try {
+  await getToken(connector, { subject: { type: "user", id } });
+} catch (err) {
+  if (err instanceof UserAuthorizationRequiredError) {
+    // Redirect the user through startAuthorization().
+  } else if (err instanceof ConnectorInstallationRequiredError) {
+    // Surface "install this Vercel Connect connector" to an operator.
+  } else {
+    throw err;
+  }
+}
+```
+
+---
+
+## `@vercel/connect/ash`
+
+Adapter helpers for the [Ash](https://github.com/vercel/ash) connection runtime. Importing this subpath requires `experimental-ash >= 0.3.0-alpha.19` to be installed in the consumer project.
+
+### `connect(input)`
+
+Builds an Ash `AuthorizationDefinition` backed by Vercel Connect, collapsing the `getToken` / `startAuthorization` / `completeAuthorization` boilerplate that each Vercel Connect-backed connection would otherwise repeat.
+
+```ts
+function connect(
+  connector: string,
+): InteractiveAuthorizationDefinition<ConnectAuthorizationState>;
+function connect(
+  options: AshAuthorizationOptions & { principalType?: "user" },
+): InteractiveAuthorizationDefinition<ConnectAuthorizationState>;
+function connect(
+  options: AshAuthorizationOptions & { principalType: "app" },
+): NonInteractiveAuthorizationDefinition;
+```
+
+The shorthand form `connect("linear")` is equivalent to `connect({ connector: "linear" })` — `principalType` defaults to `"user"`, so the helper returns an interactive definition unless you opt into `"app"` explicitly.
+
+The return type narrows on `principalType`:
+
+- `"user"` (default) → interactive definition. Ash drives the consent flow through its framework-owned webhook; failures map to `ConnectionAuthorizationRequiredError` so the runtime can prompt the user.
+- `"app"` → non-interactive definition (`getToken` only). Failures map to `ConnectionAuthorizationFailedError` with `retryable: false` — there's nobody to consent for an app-scoped connector.
+
+```ts
+import { defineMcpClientConnection } from "experimental-ash/connections";
+import { connect } from "@vercel/connect/ash";
+
+export default defineMcpClientConnection({
+  url: "https://mcp.linear.app/sse",
+  description: "Linear workspace — issues, projects, cycles, and comments.",
+  auth: connect("oauth/mcp-linear-app"),
+});
+```
+
+#### `AshAuthorizationOptions`
+
+| Field            | Type                                                                       | Notes                                                                                                                                                                  |
+| ---------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connector`      | `string`                                                                   | Vercel Connect connector identifier — accepts the opaque `scl_...` key or the human-readable UID (`oauth/mcp-linear-app`).                                             |
+| `principalType`  | `"app" \| "user"`                                                          | Defaults to `"user"` when omitted. Selects which definition shape is returned.                                                                                         |
+| `tokenParams`    | `Omit<ConnectTokenParams, "subject">`                                      | Forwarded verbatim to every token / authorization call. Use to pin `scopes`, `audience`, `resources`, etc. `subject` is derived from the framework-resolved principal. |
+| `connectOptions` | `ConnectOptions`                                                           | Low-level overrides (e.g. `vercelToken`). Most callers leave this unset.                                                                                               |
+| `instructions`   | `string`                                                                   | Custom call-to-action shown on `connection.authorization_required`. Defaults to a message derived from the connection's filename.                                      |
+| `onError`        | `(error: unknown, phase: ConnectAuthorizationPhase) => Error \| undefined` | Escape hatch for translating raw errors. Return a replacement `Error`, or `undefined` to fall back to the default mapping.                                             |
+
+#### Supporting types
+
+```ts
+type AshAuthorizationInput = string | AshAuthorizationOptions;
+
+type ConnectAuthorizationPhase =
+  | "getToken"
+  | "startAuthorization"
+  | "completeAuthorization";
+
+type ConnectAuthorizationState = {
+  readonly verifier: string;
+  readonly [key: string]: JsonValue;
+};
+```
+
+`ConnectAuthorizationState` is what Ash journals between `startAuthorization` and `completeAuthorization`. The index signature satisfies Ash's `State extends JsonValue` constraint; in practice only `verifier` is set.
+
+### `connectSlackCredentials(connector)`
+
+```ts
+function connectSlackCredentials(connector: string): SlackChannelCredentials;
+```
+
+Builds `SlackChannelCredentials` for the Ash Slack channel adapter, backed by a Vercel Connect connector that stores the workspace's bot token. The returned `botToken` is a function form, invoked once per inbound webhook so the adapter always picks up a fresh token (rotation, refresh, multi-workspace tenancy are all handled server-side).
+
+Slack bot tokens are app-scoped — one token per workspace install, shared across every end-user — so this helper calls Vercel Connect with `subject: { type: "app" }`. Per-user Slack OAuth is a separate concern.
+
+```ts
+import { slackRoute } from "experimental-ash/channels/slack";
+import { connectSlackCredentials } from "@vercel/connect/ash";
+
+export default slackRoute({
+  credentials: connectSlackCredentials("scl_..."),
+});
+```
+
+The `webhookVerifier` is set to `vercelOidc()`, which authenticates inbound webhooks using the Vercel OIDC token issued for the calling project.
+
+---
+
+## `@vercel/connect/betterauth`
+
+Better Auth provider for Vercel Connect's OAuth2 endpoints. Importing this subpath requires `better-auth >= 1.5.0` to be installed in the consumer project.
+
+### `connect(options)`
+
+```ts
+function connect(options: BetterAuthConnectOptions): GenericOAuthConfig;
+```
+
+Returns a `GenericOAuthConfig` entry that drops into `genericOAuth({ config: [...] })` from `better-auth/plugins/generic-oauth`. Vercel Connect's OAuth client authentication is non-standard — the "client secret" is a Vercel OIDC token that has to be fetched per-request — so the helper overrides `getToken` and `getUserInfo` to inject the right `Authorization` headers.
+
+```ts
+import { betterAuth } from "better-auth";
+import { genericOAuth } from "better-auth/plugins/generic-oauth";
+import { connect } from "@vercel/connect/betterauth";
+
+export const auth = betterAuth({
+  plugins: [
+    genericOAuth({
+      config: [
+        connect({
+          providerId: "slack",
+          connector: process.env.CONNECTOR_SLACK!,
+        }),
+      ],
+    }),
+  ],
+});
+```
+
+#### `BetterAuthConnectOptions`
+
+| Field                | Type                    | Notes                                                                                                 |
+| -------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `id`                 | `string`                | Provider id used by Better Auth's generic OAuth plugin. Surfaces in the sign-in URL and account rows. |
+| `connector`          | `string`                | Vercel Connect connector identifier — accepts `scl_...` or the human-readable UID.                    |
+| `scopes`             | `readonly string[]`     | Scopes to request. `offline_access` is added automatically. Defaults to `["*"]`.                      |
+| `getVercelOidcToken` | `() => Promise<string>` | Override the OIDC token fetcher. Defaults to `getVercelOidcToken` from `@vercel/oidc`.                |
+
+When the OIDC token is readable, the helper scopes the Vercel Connect consent UI to the deployment's Vercel team (`?teamId=...` on the authorization URL); outside Vercel it falls back to the unqualified URL.
+
+---
+
+## `@vercel/connect/authjs`
+
+Auth.js (NextAuth core) provider for Vercel Connect's OAuth2 endpoints. Importing this subpath requires `@auth/core >= 0.37.0` to be installed in the consumer project.
+
+### `connect(options)`
+
+```ts
+function connect(options: AuthJsConnectOptions): OAuth2Config<ConnectProfile>;
+```
+
+Returns an `OAuth2Config` provider entry for `AuthConfig.providers`. Vercel Connect's token endpoint expects the Vercel OIDC token in place of a static client secret, so the helper declares `token_endpoint_auth_method: "none"` and injects the real `Authorization` headers via Auth.js's `customFetch` symbol on both the token and userinfo endpoints.
+
+```ts
+import type { AuthConfig } from "@auth/core";
+import { connect } from "@vercel/connect/authjs";
+
+export const authConfig: AuthConfig = {
+  providers: [
+    connect({
+      id: "slack",
+      name: "Slack",
+      connector: process.env.CONNECTOR_SLACK!,
+    }),
+  ],
+};
+```
+
+#### `AuthJsConnectOptions`
+
+| Field                | Type                    | Notes                                                                                                            |
+| -------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `id`                 | `string`                | Provider id surfaced by Auth.js. Becomes the path segment in callback URLs and the `provider` field on accounts. |
+| `name`               | `string`                | Human-readable display name used by Auth.js sign-in UIs.                                                         |
+| `connector`          | `string`                | Vercel Connect connector identifier — accepts `scl_...` or the human-readable UID.                               |
+| `scopes`             | `readonly string[]`     | Scopes to request. `offline_access` is added automatically. Defaults to `["*"]`.                                 |
+| `getVercelOidcToken` | `() => Promise<string>` | Override the OIDC token fetcher. Defaults to `getVercelOidcToken` from `@vercel/oidc`.                           |
+
+#### `ConnectProfile`
+
+```ts
+interface ConnectProfile {
+  sub: string;
+  email?: string;
+  email_verified?: boolean;
+  name?: string;
+  picture?: string;
+}
+```
+
+Userinfo payload returned by Vercel Connect's OIDC userinfo endpoint. The helper maps it to an Auth.js user via `profile()`; override that callback in the provider config if you need to surface additional fields.

package/dist/ash/connection-authorization.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Ash adapter helper for `@vercel/connect`.
+ *
+ * {@link connect} turns a Vercel Connect OAuth connector id plus a
+ * principal type into a ready-made Ash
+ * {@link AuthorizationDefinition} that the connection runtime
+ * consumes directly. The helper collapses the ~100 lines of
+ * `getToken` / `startAuthorization` / `completeAuthorization`
+ * boilerplate each Connect-backed connection normally writes down
+ * to a single call:
+ *
+ * ```ts
+ * import { defineMcpClientConnection } from "experimental-ash/connections";
+ * import { connect } from "@vercel/connect/ash";
+ *
+ * export default defineMcpClientConnection({
+ *   url: "https://mcp.linear.app/sse",
+ *   description: "Linear workspace — issues, projects, cycles, and comments.",
+ *   auth: connect("linear"),
+ * });
+ * ```
+ *
+ * # Module layout
+ *
+ * This entrypoint is exposed at the `@vercel/connect/ash` subpath so
+ * consumers that don't use Ash never load it. `experimental-ash` is
+ * declared as an optional peer dependency: importing
+ * `@vercel/connect/ash` requires Ash to be installed in the consumer
+ * project, but the rest of `@vercel/connect` works without it.
+ */
+import { type InteractiveAuthorizationDefinition, type JsonValue, type NonInteractiveAuthorizationDefinition } from "experimental-ash/connections";
+import type { ConnectOptions, ConnectTokenParams } from "../token.js";
+/**
+ * Authorization phase passed to {@link AshAuthorizationOptions.onError}
+ * so consumers can branch their error translation per callback.
+ */
+export type ConnectAuthorizationPhase = "getToken" | "startAuthorization" | "completeAuthorization";
+/**
+ * State journaled by Ash between
+ * {@link InteractiveAuthorizationDefinition.startAuthorization} and
+ * {@link InteractiveAuthorizationDefinition.completeAuthorization}.
+ *
+ * Currently just the PKCE verifier. The index signature exists to
+ * satisfy Ash's `State extends JsonValue` constraint; in practice
+ * the only key the helper produces or reads is `verifier`.
+ */
+export type ConnectAuthorizationState = {
+    readonly verifier: string;
+    readonly [key: string]: JsonValue;
+};
+/** Options accepted by {@link connect}. */
+export interface AshAuthorizationOptions {
+    /**
+     * Vercel Connect OAuth connector identifier. Accepts either the
+     * opaque service connector key (`scl_...`) or the human-readable
+     * UID (`oauth/mcp-linear-app`) — both resolve to the same
+     * connector on the Vercel Connect side.
+     */
+    readonly connector: string;
+    /**
+     * Whether this connection authenticates as the agent itself
+     * (`"app"`) or on behalf of the end-user (`"user"`). Defaults to
+     * `"user"` when omitted, and the returned definition shape depends
+     * on this choice:
+     *
+     * - `"user"` → full interactive OAuth definition with `getToken`,
+     *   `startAuthorization`, and `completeAuthorization`. Ash will
+     *   drive a consent flow through its framework-owned webhook.
+     * - `"app"` → non-interactive definition with `getToken` only. Ash
+     *   never runs a consent flow for app-scoped connectors; a failure
+     *   to fetch the token surfaces as a terminal authorization
+     *   failure so the channel can prompt an operator to install the
+     *   Vercel Connect app.
+     */
+    readonly principalType?: "app" | "user";
+    /**
+     * Extra parameters forwarded to every `getTokenResponse` /
+     * `startAuthorization` call, minus `subject` — the helper derives
+     * `subject` from the framework-resolved principal.
+     *
+     * Use this to pin `scopes`, `audience`, `resources`, or
+     * `authorizationDetails`. Passed through verbatim.
+     */
+    readonly tokenParams?: Omit<ConnectTokenParams, "subject">;
+    /**
+     * Low-level Vercel Connect SDK options (currently `vercelToken`
+     * for overriding the OIDC bearer). Most callers leave this unset
+     * and rely on `@vercel/oidc` auto-discovery.
+     */
+    readonly connectOptions?: ConnectOptions;
+    /**
+     * Custom call-to-action rendered on the
+     * `connection.authorization_required` event. When omitted, Ash
+     * fills in `Authorize <ConnectionName> in your browser to continue.`
+     * from the connection's filename.
+     */
+    readonly instructions?: string;
+    /**
+     * Escape hatch for turning an unexpected Vercel Connect / network
+     * error into an Ash-recognizable error. Called once per failure
+     * with the raw error and the phase that produced it.
+     *
+     * Return a new `Error` to replace the helper's default translation,
+     * or `undefined` to let the helper use its own mapping. Useful
+     * when a deployment has stricter error reporting requirements
+     * (custom `reason` codes, structured logging, etc.).
+     */
+    readonly onError?: (error: unknown, phase: ConnectAuthorizationPhase) => Error | undefined;
+}
+/** Input accepted by {@link connect}. */
+export type AshAuthorizationInput = string | AshAuthorizationOptions;
+/**
+ * Builds an Ash {@link AuthorizationDefinition} backed by Vercel
+ * Connect. The return type narrows based on
+ * {@link AshAuthorizationOptions.principalType}:
+ *
+ * - omitted or `principalType: "user"` returns an
+ *   {@link InteractiveAuthorizationDefinition}; Ash drives a consent
+ *   flow through its framework-owned webhook.
+ * - `principalType: "app"` returns a
+ *   {@link NonInteractiveAuthorizationDefinition}; Ash never runs a
+ *   consent flow for app-scoped connectors.
+ */
+export declare function connect(connector: string): InteractiveAuthorizationDefinition<ConnectAuthorizationState>;
+export declare function connect(options: AshAuthorizationOptions & {
+    readonly principalType?: "user";
+}): InteractiveAuthorizationDefinition<ConnectAuthorizationState>;
+export declare function connect(options: AshAuthorizationOptions & {
+    readonly principalType: "app";
+}): NonInteractiveAuthorizationDefinition;
+export declare function connect(options: AshAuthorizationInput): InteractiveAuthorizationDefinition<ConnectAuthorizationState> | NonInteractiveAuthorizationDefinition;

package/dist/ash/connection-authorization.js

@@ -0,0 +1,191 @@
+/**
+ * Ash adapter helper for `@vercel/connect`.
+ *
+ * {@link connect} turns a Vercel Connect OAuth connector id plus a
+ * principal type into a ready-made Ash
+ * {@link AuthorizationDefinition} that the connection runtime
+ * consumes directly. The helper collapses the ~100 lines of
+ * `getToken` / `startAuthorization` / `completeAuthorization`
+ * boilerplate each Connect-backed connection normally writes down
+ * to a single call:
+ *
+ * ```ts
+ * import { defineMcpClientConnection } from "experimental-ash/connections";
+ * import { connect } from "@vercel/connect/ash";
+ *
+ * export default defineMcpClientConnection({
+ *   url: "https://mcp.linear.app/sse",
+ *   description: "Linear workspace — issues, projects, cycles, and comments.",
+ *   auth: connect("linear"),
+ * });
+ * ```
+ *
+ * # Module layout
+ *
+ * This entrypoint is exposed at the `@vercel/connect/ash` subpath so
+ * consumers that don't use Ash never load it. `experimental-ash` is
+ * declared as an optional peer dependency: importing
+ * `@vercel/connect/ash` requires Ash to be installed in the consumer
+ * project, but the rest of `@vercel/connect` works without it.
+ */
+import { ConnectionAuthorizationFailedError, ConnectionAuthorizationRequiredError, } from "experimental-ash/connections";
+import { startAuthorization } from "../authorization.js";
+import { ConnectorInstallationRequiredError, getTokenResponse, NoValidTokenError, UserAuthorizationRequiredError, } from "../token.js";
+export function connect(input) {
+    const options = normalizeAuthorizationOptions(input);
+    if (options.principalType === "app") {
+        return buildNonInteractiveDefinition(options);
+    }
+    return buildInteractiveDefinition(options);
+}
+function normalizeAuthorizationOptions(input) {
+    if (typeof input === "string") {
+        return { connector: input };
+    }
+    return input;
+}
+function buildInteractiveDefinition(options) {
+    return {
+        principalType: "user",
+        async getToken({ principal }) {
+            try {
+                const response = await getTokenResponse(options.connector, buildTokenParams(options, principal), options.connectOptions);
+                return { token: response.token, expiresAt: response.expiresAt };
+            }
+            catch (error) {
+                throw translate(error, "getToken", options);
+            }
+        },
+        async startAuthorization({ principal, callbackUrl, webhook, }) {
+            try {
+                // Ash's `webhook` parameter is semantically a browser-redirect
+                // target — the orchestrator mints it via `createWebhook({
+                // respondWith: buildAuthorizationCompletePage() })` so the
+                // user lands on a friendly "you can close this tab" page after
+                // consent. That maps to Vercel Connect's `callbackUrl:`
+                // semantics, which accepts both `https://` (prod) and
+                // `http://localhost` (vercel dev) — one field covers both.
+                // Vercel Connect authenticates the calling Vercel project via
+                // OIDC, which is what lets per-workflow dynamic webhook URLs
+                // work without an OAuth-style redirect-URI allowlist.
+                //
+                // We don't route `https://` URLs into Vercel Connect's
+                // `webhook:` (server-POST) field, even though it would
+                // survive the user closing the consent tab right after IdP
+                // callback. That mode shows the user Vercel Connect's
+                // generic "close this window" page instead of Ash's branded
+                // landing page, and the helper would need to grow
+                // protocol-aware logic that diverges from the simple "Ash
+                // mints one URL, Vercel Connect redirects there" mental
+                // model. Revisit if tab-close timeouts become a real problem
+                // in production.
+                const response = await startAuthorization(options.connector, buildTokenParams(options, principal), { ...options.connectOptions, callbackUrl: callbackUrl ?? webhook });
+                return {
+                    challenge: buildChallenge(options, response.url),
+                    state: { verifier: response.verifier },
+                };
+            }
+            catch (error) {
+                throw translate(error, "startAuthorization", options);
+            }
+        },
+        async completeAuthorization({ principal, }) {
+            try {
+                const response = await getTokenResponse(options.connector, buildTokenParams(options, principal), options.connectOptions);
+                return { token: response.token, expiresAt: response.expiresAt };
+            }
+            catch (error) {
+                throw translate(error, "completeAuthorization", options);
+            }
+        },
+    };
+}
+function buildNonInteractiveDefinition(options) {
+    return {
+        principalType: "app",
+        async getToken({ principal }) {
+            try {
+                const response = await getTokenResponse(options.connector, buildTokenParams(options, principal), options.connectOptions);
+                return { token: response.token, expiresAt: response.expiresAt };
+            }
+            catch (error) {
+                throw translate(error, "getToken", options);
+            }
+        },
+    };
+}
+function buildTokenParams(options, principal) {
+    return {
+        ...options.tokenParams,
+        subject: principalToSubject(principal),
+    };
+}
+function principalToSubject(principal) {
+    if (principal.type === "app") {
+        return { type: "app" };
+    }
+    return { type: "user", id: principal.id, issuer: principal.issuer };
+}
+function buildChallenge(options, url) {
+    if (options.instructions === undefined) {
+        return { url };
+    }
+    return { url, instructions: options.instructions };
+}
+/**
+ * Translates raw Vercel Connect errors into Ash's public
+ * {@link ConnectionAuthorizationRequiredError} /
+ * {@link ConnectionAuthorizationFailedError} classes. Ash discriminates
+ * on `err.name` (not `instanceof`), so even if the consumer's bundle
+ * loads a different copy of `experimental-ash` than this helper, the
+ * runtime still recognizes the throw.
+ */
+function translate(error, phase, options) {
+    const override = options.onError?.(error, phase);
+    if (override !== undefined)
+        return override;
+    // `UserAuthorizationRequiredError` and `NoValidTokenError` both
+    // mean "Vercel Connect has no valid credential for this principal
+    // yet". For interactive (user) connectors that's recoverable via
+    // a consent flow; Ash will see the `Required` throw and drive
+    // `startAuthorization`. For app connectors it's terminal — there
+    // is nobody to consent — so we surface `Failed` with
+    // `retryable: false`.
+    if (error instanceof UserAuthorizationRequiredError ||
+        error instanceof NoValidTokenError) {
+        if (options.principalType === "app") {
+            return new ConnectionAuthorizationFailedError("connect", {
+                message: error.message,
+                reason: "app_not_installed",
+                retryable: false,
+            });
+        }
+        if (phase === "completeAuthorization") {
+            // The consent leg reported success (Ash would not call us
+            // otherwise) but Vercel Connect still says the user is
+            // unauthorized. Default to retryable so the model can
+            // re-prompt; most cases (network blip, replay) resolve on
+            // retry.
+            return new ConnectionAuthorizationFailedError("connect", {
+                message: "Authorization did not complete. Vercel Connect still reports the user as unauthorized.",
+            });
+        }
+        return new ConnectionAuthorizationRequiredError("connect", {
+            message: error.message,
+        });
+    }
+    // `ConnectorInstallationRequiredError` is terminal in both modes:
+    // the operator has not installed the Vercel Connect connector for
+    // this team.
+    if (error instanceof ConnectorInstallationRequiredError) {
+        return new ConnectionAuthorizationFailedError("connect", {
+            message: error.message,
+            reason: "connector_installation_required",
+            retryable: false,
+        });
+    }
+    // Every other error is re-thrown verbatim. Ash treats an unknown
+    // throw from `completeAuthorization` as a retryable failure, so the
+    // default behavior stays intuitive.
+    return error instanceof Error ? error : new Error(String(error));
+}