@vercel/connect 0.9.0 → 2.0.0

package/README.md

@@ -5,7 +5,7 @@ SDK for obtaining scoped tokens for third-party services on behalf of apps or us
 Seven entrypoints, all ESM:
 
 - `@vercel/connect` — core token / authorization SDK
-- `@vercel/connect/chat` — adapter helpers for the [Chat SDK](https://chat-sdk.dev) (`chat`): `connectSlackAdapter`, `connectDiscordAdapter`, `connectGitHubAdapter`, `connectLinearAdapter`, `connectNotionAdapter`, `connectTelegramAdapter` (no Chat SDK dependency — returns structural config)
+- `@vercel/connect/chat` — adapter helpers for the [Chat SDK](https://chat-sdk.dev) (`chat`): `connectSlackAdapter`, `connectDiscordAdapter`, `connectGitHubAdapter`, `connectLinearAdapter`, `connectNotionAdapter`, `connectTelegramAdapter`, `connectSendblueAdapter` (no Chat SDK dependency — returns structural config)
 - `@vercel/connect/ai-sdk` — [Vercel AI SDK](https://ai-sdk.dev) glue: re-exports `connectAuthProvider` for MCP transports (optional peers: `ai`, `@ai-sdk/mcp`)
 - `@vercel/connect/mcp` — canonical MCP-spec `OAuthClientProvider` for any MCP client (optional peer: `@ai-sdk/mcp`)
 - `@vercel/connect/eve` — adapter helpers for [Eve](https://github.com/vercel/eve) connections (optional peer: `eve`)
@@ -64,10 +64,12 @@ createSlackAdapter({
 
 `connectDiscordAdapter` (`botToken` and `applicationId`),
 `connectGitHubAdapter` (`installationToken`), and `connectLinearAdapter`
-(`accessToken`) follow the same shape. `connectNotionAdapter` supplies only the
-outbound `token`; native Notion webhooks still require
-`NOTION_VERIFICATION_TOKEN`. `connectTelegramAdapter` supplies only
-`botToken`; Telegram retains native webhook verification or polling. See the
+(`accessToken`) follow the same shape. `connectSendblueAdapter` supplies a
+lazy Sendblue `accessToken` and Connect OIDC webhook verifier.
+`connectNotionAdapter` supplies only the outbound `token`; native Notion
+webhooks still require `NOTION_VERIFICATION_TOKEN`. `connectTelegramAdapter`
+supplies only `botToken`; Telegram retains native webhook verification or
+polling. See the
 [Chat SDK integration guide](https://github.com/vercel/vercel/blob/main/packages/connect/docs/chat-integration.md)
 for connector setup, trigger forwarding, and per-platform examples.
 
@@ -110,7 +112,21 @@ SDK's `toolApproval` option or `wrapMcpTools` from `@ai-sdk/policy-opa`.
 Non-AI-SDK MCP clients (the official MCP TypeScript SDK, Mastra, etc.)
 can import the same `connectAuthProvider` from `@vercel/connect/mcp`.
 
-### eve
+### Eve
+
+Use `connectSendblueCredentials` with Eve's native Sendblue channel. It
+resolves the app-scoped bearer token and managed sending line together, and
+includes Vercel OIDC webhook verification. When the connector has multiple
+lines, pass `fromNumber` to choose one.
+
+```ts
+import { connectSendblueCredentials } from '@vercel/connect/eve';
+import { sendblueChannel } from 'eve/channels/sendblue';
+
+export default sendblueChannel({
+  credentials: connectSendblueCredentials('sendblue/my-agent'),
+});
+```
 
 ```ts
 import { defineMcpClientConnection } from 'eve/connections';
@@ -118,13 +134,15 @@ import { connect } from '@vercel/connect/eve';
 
 export default defineMcpClientConnection({
   url: 'https://mcp.linear.app/sse',
-  auth: connect('linear'),
+  auth: connect({ connector: 'linear', autoProvision: true }),
 });
 ```
 
-By default, `connect()` provisions or links the connector for the deploying
-Vercel project on first use. Pass `autoProvision: false` when the connector is
-managed elsewhere.
+By default, `connect()` only uses connectors already linked to the project and
+does not provision or modify connectors at runtime. Pass `autoProvision: true`
+to opt in. When enabled, `connect()` first tries the token or authorization
+request; if the connector is missing or not linked, it provisions or links the
+connector and retries the request once.
 
 ### Better Auth
 

package/dist/authorization.d.ts

@@ -1,4 +1,4 @@
-import type { ConnectTokenParams } from './token.js';
+import { type ConnectTokenParams } from './token.js';
 export interface ConnectAuthorizationOptions {
     vercelToken?: string;
     callbackUrl?: string;
@@ -7,6 +7,12 @@ export interface ConnectAuthorizationOptions {
     expiresInMs?: number;
     /** OAuth prompt value to pass to the connector's authorization server. */
     prompt?: string;
+    /**
+     * Region to send the request to, e.g. `sfo1`. Defaults to the
+     * `VERCEL_REGION` environment variable; override it to target a
+     * different region.
+     */
+    region?: string;
 }
 export interface ConnectAuthorizationResponse {
     request: string;

package/dist/authorization.js

@@ -1,5 +1,8 @@
 import { getVercelOidcToken } from '@vercel/oidc';
 import { isDetachedInteractiveAuth, validateCallbackUrl, validateWebhookUrl, } from './internal/url-validation.js';
+import { withDefaultScopes } from './internal/default-scopes.js';
+import { resolveBaseUrl } from './internal/base-url.js';
+import { createConnectErrorFromResponse, } from './token.js';
 export async function startAuthorization(connector, params, options) {
     if (!connector) {
         throw new Error('connector is required');
@@ -12,13 +15,14 @@ export async function startAuthorization(connector, params, options) {
         validateWebhookUrl(options.webhook);
     }
     const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
-    const endpoint = `https://api.vercel.com/v1/connect/authorize/${encodeURIComponent(connector)}`;
+    const baseUrl = resolveBaseUrl(options);
+    const endpoint = `${baseUrl}/v1/connect/authorize/${encodeURIComponent(connector)}`;
     const deviceCode = options?.deviceCode ?? (detachedInteractiveAuth ? true : undefined);
     const returnUrl = !detachedInteractiveAuth && options?.callbackUrl !== undefined
         ? { returnUrl: options.callbackUrl }
         : {};
     const body = {
-        ...params,
+        ...withDefaultScopes(params),
         ...returnUrl,
         ...(options?.webhook !== undefined && { webhook: options.webhook }),
         ...(deviceCode !== undefined && {
@@ -39,12 +43,7 @@ export async function startAuthorization(connector, params, options) {
         body: JSON.stringify(body),
     });
     if (!response.ok) {
-        let errorText;
-        try {
-            errorText = await response.text();
-        }
-        catch { }
-        throw new Error(`Failed to start authorization: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ''}`);
+        throw await createConnectErrorFromResponse(response, 'Failed to start authorization');
     }
     const data = await response.json();
     return data;

package/dist/chat/index.d.ts

@@ -21,7 +21,7 @@
  * ```
  */
 export { createConnectWebhookVerifier, type ConnectWebhookVerifier, type ConnectWebhookVerifierOptions, } from './webhook-verifier.js';
-export type { ConnectDiscordAdapterConfig, ConnectGitHubAdapterConfig, ConnectLinearAdapterConfig, ConnectLinqAdapterConfig, ConnectLinqCredentials, ConnectNotionAdapterConfig, ConnectTelegramAdapterConfig, ConnectTokenResolver, } from './types.js';
+export type { ConnectDiscordAdapterConfig, ConnectGitHubAdapterConfig, ConnectLinearAdapterConfig, ConnectLinqAdapterConfig, ConnectLinqCredentials, ConnectNotionAdapterConfig, ConnectSendblueAdapterConfig, ConnectTelegramAdapterConfig, ConnectTokenResolver, } from './types.js';
 export { connectDiscordAdapter, type ConnectDiscordAdapterParams, } from './discord-adapter.js';
 export { connectSlackAdapter, type ConnectSlackAdapterConfig, type ConnectSlackAdapterParams, } from './slack-adapter.js';
 export { connectGitHubAdapter, type ConnectGitHubAdapterParams, } from './github-adapter.js';
@@ -29,3 +29,4 @@ export { connectLinearAdapter, type ConnectLinearAdapterParams, } from './linear
 export { connectLinqAdapter, type ConnectLinqAdapterParams, } from './linq-adapter.js';
 export { connectNotionAdapter, type ConnectNotionAdapterParams, } from './notion-adapter.js';
 export { connectTelegramAdapter, type ConnectTelegramAdapterParams, } from './telegram-adapter.js';
+export { connectSendblueAdapter, type ConnectSendblueAdapterParams, } from './sendblue-adapter.js';

package/dist/chat/index.js

@@ -28,3 +28,4 @@ export { connectLinearAdapter, } from './linear-adapter.js';
 export { connectLinqAdapter, } from './linq-adapter.js';
 export { connectNotionAdapter, } from './notion-adapter.js';
 export { connectTelegramAdapter, } from './telegram-adapter.js';
+export { connectSendblueAdapter, } from './sendblue-adapter.js';

package/dist/chat/sendblue-adapter.d.ts

@@ -0,0 +1,25 @@
+import type { ConnectOptions } from '../index.js';
+import { type ConnectSendblueParams } from '../internal/sendblue-lines.js';
+import type { ConnectSendblueAdapterConfig } from './types.js';
+/**
+ * Token parameters accepted by {@link connectSendblueAdapter}.
+ *
+ * Mirrors {@link ConnectTokenParams} from `@vercel/connect`, minus `subject`.
+ * Sendblue account credentials are app-scoped, so this helper pins the subject
+ * to `{ type: 'app' }`.
+ */
+export type ConnectSendblueAdapterParams = ConnectSendblueParams;
+/**
+ * Build a Sendblue adapter config fragment backed by a Vercel Connect
+ * connector.
+ *
+ * Sendblue connectors issue a short-lived, line-scoped bearer token. The
+ * returned `accessToken` resolver fetches that token for each adapter API
+ * operation so Connect token rotation takes effect without rebuilding the
+ * adapter. When the connector has one line, that line is selected
+ * automatically; select a line explicitly when it has more than one. The
+ * webhook verifier accepts Connect trigger-forwarded webhooks using Vercel
+ * OIDC, replacing Sendblue's provider-native verification at the deployment
+ * boundary.
+ */
+export declare function connectSendblueAdapter(connector: string, params?: ConnectSendblueAdapterParams, options?: ConnectOptions): ConnectSendblueAdapterConfig;

package/dist/chat/sendblue-adapter.js

@@ -0,0 +1,21 @@
+import { createConnectSendblueConfig, } from '../internal/sendblue-lines.js';
+import { createConnectWebhookVerifier } from './webhook-verifier.js';
+/**
+ * Build a Sendblue adapter config fragment backed by a Vercel Connect
+ * connector.
+ *
+ * Sendblue connectors issue a short-lived, line-scoped bearer token. The
+ * returned `accessToken` resolver fetches that token for each adapter API
+ * operation so Connect token rotation takes effect without rebuilding the
+ * adapter. When the connector has one line, that line is selected
+ * automatically; select a line explicitly when it has more than one. The
+ * webhook verifier accepts Connect trigger-forwarded webhooks using Vercel
+ * OIDC, replacing Sendblue's provider-native verification at the deployment
+ * boundary.
+ */
+export function connectSendblueAdapter(connector, params = {}, options) {
+    return {
+        ...createConnectSendblueConfig(connector, params, options),
+        webhookVerifier: createConnectWebhookVerifier(),
+    };
+}

package/dist/chat/types.d.ts

@@ -76,3 +76,15 @@ export interface ConnectNotionAdapterConfig {
 export interface ConnectTelegramAdapterConfig {
     botToken: ConnectTokenResolver;
 }
+/**
+ * Partial Sendblue adapter config backed by Vercel Connect.
+ *
+ * Structurally matches the `accessToken` and `webhookVerifier` options of
+ * `createSendblueAdapter` from `chat-adapter-sendblue`.
+ */
+export interface ConnectSendblueAdapterConfig {
+    accessToken: ConnectTokenResolver;
+    defaultFromNumber: string | (() => Promise<string>);
+    allowedFromNumbers: readonly string[] | (() => Promise<readonly string[]>);
+    webhookVerifier: ConnectWebhookVerifier;
+}

package/dist/connector.js

@@ -1,5 +1,6 @@
 import { getVercelOidcToken } from '@vercel/oidc';
 import { createConnectErrorFromResponse, } from './token.js';
+import { resolveBaseUrl } from './internal/base-url.js';
 /**
  * Fetch a connector's metadata from Vercel Connect.
  *
@@ -11,7 +12,8 @@ import { createConnectErrorFromResponse, } from './token.js';
  */
 export async function getConnectorMetadata(connector, options) {
     const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
-    const endpoint = `https://api.vercel.com/v1/connect/connectors/${encodeURIComponent(connector)}`;
+    const baseUrl = resolveBaseUrl(options);
+    const endpoint = `${baseUrl}/v1/connect/connectors/${encodeURIComponent(connector)}`;
     const response = await fetch(endpoint, {
         method: 'GET',
         headers: {

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

@@ -117,17 +117,18 @@ export interface EveAuthorizationOptions {
     readonly connectOptions?: ConnectOptions;
     /**
      * Create or link the declared connector against the deploying Vercel
-     * project before the first token / authorization call. Defaults to
-     * `true`.
+     * project when a token / authorization call reports that the connector
+     * is missing or not linked. Defaults to `false`; set this to `true` to
+     * opt in to runtime provisioning.
      *
      * The provision request is authenticated with the deployment OIDC token
      * and carries the eve connection's `url` plus this connector UID. Connect
      * creates the managed OAuth connector when missing, links an existing
      * OAuth connector when the UID already exists, and scopes the new project
-     * link to the OIDC token's environment and higher promotion targets.
+     * link to the OIDC token's authenticated environment.
      *
-     * Set this to `false` for callers that intentionally manage the connector
-     * linkage elsewhere. Opaque connector ids (`scl_...`) and connections
+     * Existing linked connectors are always used directly without a
+     * provisioning request. Opaque connector ids (`scl_...`) and connections
      * without a URL are skipped automatically.
      */
     readonly autoProvision?: boolean;

package/dist/eve/connection-authorization.js

@@ -30,7 +30,7 @@
  */
 import { ConnectionAuthorizationFailedError, ConnectionAuthorizationRequiredError, } from 'eve/connections';
 import { startAuthorization } from '../authorization.js';
-import { ConnectorInstallationRequiredError, deleteTokenCacheEntry, getTokenResponse, NoValidTokenError, revokeToken, UserAuthorizationRequiredError, } from '../token.js';
+import { ConnectError, ConnectorInstallationRequiredError, deleteTokenCacheEntry, getTokenResponse, NoValidTokenError, revokeToken, UserAuthorizationRequiredError, } from '../token.js';
 import { provisionEveOAuthConnector } from './provision-oauth-connector.js';
 export function connect(input) {
     const options = normalizeAuthorizationOptions(input);
@@ -85,8 +85,8 @@ function buildInteractiveDefinition(options) {
         principalType: 'user',
         async getToken({ principal, connection, }) {
             try {
-                await autoProvisionConnectorIfEnabled(options, connection);
-                const response = await getTokenResponse(options.connector, await buildTokenParams(options, principal, connection), getTokenConnectOptions(options));
+                const params = await buildTokenParams(options, principal, connection);
+                const response = await withConnectorProvisioningFallback(options, connection, () => getTokenResponse(options.connector, params, getTokenConnectOptions(options)));
                 return { token: response.token, expiresAt: response.expiresAt };
             }
             catch (error) {
@@ -95,7 +95,6 @@ function buildInteractiveDefinition(options) {
         },
         async startAuthorization({ principal, connection, callbackUrl, webhook, }) {
             try {
-                await autoProvisionConnectorIfEnabled(options, connection);
                 // eve's `webhook` parameter is also the browser-redirect
                 // target when `callbackUrl` is absent — the orchestrator mints
                 // it via `createWebhook({ respondWith:
@@ -115,12 +114,13 @@ function buildInteractiveDefinition(options) {
                 // OIDC, which is what lets per-workflow dynamic webhook URLs
                 // work without an OAuth-style redirect-URI allowlist.
                 const completionWebhook = connectCompletionWebhook(webhook);
-                const response = await startAuthorization(options.connector, await buildTokenParams(options, principal, connection), {
+                const params = await buildTokenParams(options, principal, connection);
+                const response = await withConnectorProvisioningFallback(options, connection, () => startAuthorization(options.connector, params, {
                     ...options.connectOptions,
                     callbackUrl: callbackUrl ?? webhook,
                     ...(completionWebhook ? { webhook: completionWebhook } : null),
                     deviceCode: true,
-                });
+                }));
                 // Sign-in buttons name the destination service ("Sign in with
                 // Salesforce"), matching the OAuth idiom — the consent screen
                 // names the specific requesting app. The connector's own name is
@@ -149,8 +149,8 @@ function buildInteractiveDefinition(options) {
         },
         async completeAuthorization({ principal, connection, }) {
             try {
-                await autoProvisionConnectorIfEnabled(options, connection);
-                const response = await getTokenResponse(options.connector, await buildTokenParams(options, principal, connection), options.connectOptions);
+                const params = await buildTokenParams(options, principal, connection);
+                const response = await withConnectorProvisioningFallback(options, connection, () => getTokenResponse(options.connector, params, options.connectOptions));
                 return { token: response.token, expiresAt: response.expiresAt };
             }
             catch (error) {
@@ -175,8 +175,8 @@ function buildNonInteractiveDefinition(options) {
         principalType: 'app',
         async getToken({ principal, connection, }) {
             try {
-                await autoProvisionConnectorIfEnabled(options, connection);
-                const response = await getTokenResponse(options.connector, await buildTokenParams(options, principal, connection), getTokenConnectOptions(options));
+                const params = await buildTokenParams(options, principal, connection);
+                const response = await withConnectorProvisioningFallback(options, connection, () => getTokenResponse(options.connector, params, getTokenConnectOptions(options)));
                 return { token: response.token, expiresAt: response.expiresAt };
             }
             catch (error) {
@@ -185,15 +185,33 @@ function buildNonInteractiveDefinition(options) {
         },
     };
 }
-async function autoProvisionConnectorIfEnabled(options, connection) {
-    if (options.autoProvision === false) {
-        return;
+async function withConnectorProvisioningFallback(options, connection, operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (options.autoProvision !== true ||
+            !isMissingConnectorOrProjectLink(error)) {
+            throw error;
+        }
     }
     await provisionEveOAuthConnector({
         connector: options.connector,
         connection,
         connectOptions: options.connectOptions,
     });
+    return operation();
+}
+function isMissingConnectorOrProjectLink(error) {
+    if (!(error instanceof ConnectError)) {
+        return false;
+    }
+    if (error.status === 404 && error.code === 'not_found') {
+        return true;
+    }
+    return (error.status === 403 &&
+        error.code === 'forbidden' &&
+        /connector is not linked to this project/i.test(error.message));
 }
 /**
  * Connect SDK options for `getToken` calls. When {@link

package/dist/eve/index.d.ts

@@ -14,3 +14,4 @@ export { connectLinearCredentials, type ConnectLinearCredentialsParams, } from '
 export { connectLinqCredentials, type ConnectLinqCredentials, type ConnectLinqCredentialsParams, } from './linq-credentials.js';
 export { connectPhotonCredentials, type ConnectPhotonCredentialProvider, type PhotonCredentials, type ConnectPhotonCredentialsParams, } from './photon-credentials.js';
 export { connectSlackCredentials, type ConnectSlackCredentialsParams, } from './slack-credentials.js';
+export { connectSendblueCredentials, type ConnectSendblueCredentials, type ConnectSendblueCredentialsParams, } from './sendblue-credentials.js';

package/dist/eve/index.js

@@ -14,3 +14,4 @@ export { connectLinearCredentials, } from './linear-credentials.js';
 export { connectLinqCredentials, } from './linq-credentials.js';
 export { connectPhotonCredentials, } from './photon-credentials.js';
 export { connectSlackCredentials, } from './slack-credentials.js';
+export { connectSendblueCredentials, } from './sendblue-credentials.js';

package/dist/eve/provision-oauth-connector.js

@@ -1,6 +1,7 @@
 import { getVercelOidcToken } from '@vercel/oidc';
 import { ConnectError, createConnectErrorFromResponse } from '../token.js';
-const MANAGED_OAUTH_CONNECTOR_ENDPOINT = 'https://api.vercel.com/v1/connect/connectors/managed/oauth';
+import { resolveBaseUrl } from '../internal/base-url.js';
+const MANAGED_OAUTH_CONNECTOR_PATH = '/v1/connect/connectors/managed/oauth';
 const RESERVED_UID_PATTERN = /^(vc\/|[^/]*\.vercel\.com\/)/;
 const ALLOWED_RESERVED_UID_PREFIXES = ['mcp.vercel.com/'];
 const RESERVED_ID_PREFIXES = ['scl_', 'sca_', 'store_', 'ir_'];
@@ -12,9 +13,11 @@ export async function provisionEveOAuthConnector({ connector, connection, connec
         return;
     }
     const vercelToken = connectOptions?.vercelToken ?? (await getVercelOidcToken());
+    const endpoint = `${resolveBaseUrl(connectOptions)}${MANAGED_OAUTH_CONNECTOR_PATH}`;
     const cacheKey = JSON.stringify({
         connector,
         serverUrl,
+        endpoint,
         token: await tokenCacheKeyPart(vercelToken),
     });
     let promise = provisionCache.get(cacheKey);
@@ -23,6 +26,7 @@ export async function provisionEveOAuthConnector({ connector, connection, connec
             connector,
             serverUrl,
             vercelToken,
+            endpoint,
         }).catch(error => {
             if (isNonOAuthConnectorConflict(error)) {
                 return;
@@ -80,8 +84,8 @@ function isNonOAuthConnectorConflict(error) {
         error.status === 409 &&
         /not an OAuth connector/i.test(error.message));
 }
-async function provisionManagedOAuthConnector({ connector, serverUrl, vercelToken, }) {
-    const response = await fetch(MANAGED_OAUTH_CONNECTOR_ENDPOINT, {
+async function provisionManagedOAuthConnector({ connector, serverUrl, vercelToken, endpoint, }) {
+    const response = await fetch(endpoint, {
         method: 'POST',
         headers: {
             Accept: 'application/json',

package/dist/eve/sendblue-credentials.d.ts

@@ -0,0 +1,23 @@
+import type { ConnectOptions } from '../index.js';
+import { type ConnectSendblueParams } from '../internal/sendblue-lines.js';
+import { vercelOidc } from 'eve/channels/auth';
+/** Managed Sendblue channel credentials returned by {@link connectSendblueCredentials}. */
+export interface ConnectSendblueCredentials {
+    /** Short-lived bearer token for outbound Sendblue API calls. */
+    accessToken: () => Promise<string>;
+    /** Default managed Sendblue line. */
+    defaultFromNumber: () => Promise<string>;
+    /** Every Sendblue line authorized for this connector. */
+    allowedFromNumbers: () => Promise<readonly string[]>;
+    /** Verifies webhooks forwarded by Vercel Connect. */
+    webhookVerifier: ReturnType<typeof vercelOidc>;
+}
+/** Token parameters accepted by {@link connectSendblueCredentials}. */
+export type ConnectSendblueCredentialsParams = ConnectSendblueParams;
+/**
+ * Builds managed Sendblue channel credentials backed by a Vercel Connect
+ * connector. The access-token resolver and managed line resolvers keep token
+ * rotation and line selection delegated to Connect. Vercel OIDC verifies
+ * Connect-forwarded webhooks.
+ */
+export declare function connectSendblueCredentials(connector: string, params?: ConnectSendblueCredentialsParams, options?: ConnectOptions): ConnectSendblueCredentials;

package/dist/eve/sendblue-credentials.js

@@ -0,0 +1,14 @@
+import { createConnectSendblueConfig, } from '../internal/sendblue-lines.js';
+import { vercelOidc } from 'eve/channels/auth';
+/**
+ * Builds managed Sendblue channel credentials backed by a Vercel Connect
+ * connector. The access-token resolver and managed line resolvers keep token
+ * rotation and line selection delegated to Connect. Vercel OIDC verifies
+ * Connect-forwarded webhooks.
+ */
+export function connectSendblueCredentials(connector, params = {}, options) {
+    return {
+        ...createConnectSendblueConfig(connector, params, options),
+        webhookVerifier: vercelOidc(),
+    };
+}

package/dist/installation.d.ts

@@ -7,6 +7,12 @@ export interface ConnectInstallationOptions {
     tenantId?: string;
     deviceCode?: boolean;
     expiresInMs?: number;
+    /**
+     * Region to send the request to, e.g. `sfo1`. Defaults to the
+     * `VERCEL_REGION` environment variable; override it to target a
+     * different region.
+     */
+    region?: string;
 }
 export interface ConnectInstallationResponse {
     request: string;

package/dist/installation.js

@@ -1,6 +1,7 @@
 import { getVercelOidcToken } from '@vercel/oidc';
 import { isDetachedInteractiveAuth, validateCallbackUrl, validateWebhookUrl, } from './internal/url-validation.js';
 import { createConnectErrorFromResponse } from './token.js';
+import { resolveBaseUrl } from './internal/base-url.js';
 /**
  * Create an operator installation request for an app-scoped connector.
  *
@@ -19,7 +20,8 @@ export async function experimental_startInstallation(connector, params = {}, opt
         validateWebhookUrl(options.webhook);
     }
     const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
-    const endpoint = `https://api.vercel.com/v1/connect/install/${encodeURIComponent(connector)}`;
+    const baseUrl = resolveBaseUrl(options);
+    const endpoint = `${baseUrl}/v1/connect/install/${encodeURIComponent(connector)}`;
     const deviceCode = options?.deviceCode ?? (detachedInteractiveAuth ? true : undefined);
     const returnUrl = !detachedInteractiveAuth && options?.returnUrl !== undefined
         ? { returnUrl: options.returnUrl }

package/dist/internal/base-url.d.ts

@@ -0,0 +1,10 @@
+/** Base URL for the Vercel API when no region is available. */
+export declare const API_BASE_URL = "https://api.vercel.com";
+/**
+ * Resolves the Vercel API base URL for a region. The region comes from the
+ * `region` argument, then the `VERCEL_REGION` environment variable; without
+ * either, requests go to the global {@link API_BASE_URL}.
+ */
+export declare function resolveBaseUrl({ region }?: {
+    region?: string;
+}): string;

package/dist/internal/base-url.js

@@ -0,0 +1,12 @@
+import { readNonEmptyEnv } from './env.js';
+/** Base URL for the Vercel API when no region is available. */
+export const API_BASE_URL = 'https://api.vercel.com';
+/**
+ * Resolves the Vercel API base URL for a region. The region comes from the
+ * `region` argument, then the `VERCEL_REGION` environment variable; without
+ * either, requests go to the global {@link API_BASE_URL}.
+ */
+export function resolveBaseUrl({ region } = {}) {
+    const resolved = region ?? readNonEmptyEnv('VERCEL_REGION');
+    return resolved ? `https://api-${resolved}.vercel.com` : API_BASE_URL;
+}

package/dist/internal/default-scopes.d.ts

@@ -0,0 +1,2 @@
+import type { ConnectTokenParams } from '../token.js';
+export declare function withDefaultScopes(params: ConnectTokenParams): ConnectTokenParams;

package/dist/internal/default-scopes.js

@@ -0,0 +1,3 @@
+export function withDefaultScopes(params) {
+    return params.scopes === undefined ? { ...params, scopes: ['*'] } : params;
+}

package/dist/internal/sendblue-lines.d.ts

@@ -0,0 +1,33 @@
+import { type ConnectOptions, type ConnectTokenParams } from '../token.js';
+export type SendblueFromNumber = string | (() => Promise<string>);
+/** Shared token parameters accepted by Sendblue Connect helpers. */
+export type ConnectSendblueParams = Omit<ConnectTokenParams, 'subject'> & {
+    /** Select a Sendblue line when the connector owns more than one. */
+    fromNumber?: SendblueFromNumber;
+};
+/** Shared Connect-backed Sendblue credentials and line resolvers. */
+export interface ConnectSendblueConfig {
+    accessToken: () => Promise<string>;
+    defaultFromNumber: () => Promise<string>;
+    allowedFromNumbers: () => Promise<readonly string[]>;
+}
+/** Reads non-empty Sendblue line numbers from Connect connector metadata. */
+export declare function readPhoneNumbers(vendor: Record<string, unknown>): string[];
+/** Resolvers for a selected Sendblue line and every line managed by Connect. */
+export interface SendblueLineResolvers {
+    fromNumber: () => Promise<string>;
+    allowedFromNumbers: () => Promise<readonly string[]>;
+}
+/**
+ * Builds shared lazy resolvers for the connector's managed Sendblue lines.
+ * An explicit selected line must be one of the managed lines; when no line is
+ * selected, Connect's sole line is used automatically.
+ */
+export declare function createSendblueLineResolvers(connector: string, fromNumber: SendblueFromNumber | undefined, options?: ConnectOptions): SendblueLineResolvers;
+/** Resolves an explicit Sendblue line, or the connector's sole managed line. */
+export declare function createSendblueFromNumberResolver(connector: string, fromNumber: SendblueFromNumber | undefined, options?: ConnectOptions): () => Promise<string>;
+/**
+ * Builds the shared credential and line configuration for Sendblue Connect
+ * integrations. Callers add the webhook verifier required by their runtime.
+ */
+export declare function createConnectSendblueConfig(connector: string, params?: ConnectSendblueParams, options?: ConnectOptions): ConnectSendblueConfig;

package/dist/internal/sendblue-lines.js

@@ -0,0 +1,80 @@
+import { getConnectorMetadata } from '../connector.js';
+import { getToken, } from '../token.js';
+/** Reads non-empty Sendblue line numbers from Connect connector metadata. */
+export function readPhoneNumbers(vendor) {
+    const lines = vendor.lines;
+    if (!Array.isArray(lines))
+        return [];
+    const phoneNumbers = [];
+    for (const line of lines) {
+        if (typeof line !== 'object' || line === null)
+            return [];
+        const phoneNumber = line.phone_number;
+        if (typeof phoneNumber !== 'string' || phoneNumber.length === 0)
+            return [];
+        phoneNumbers.push(phoneNumber);
+    }
+    return phoneNumbers;
+}
+/**
+ * Builds shared lazy resolvers for the connector's managed Sendblue lines.
+ * An explicit selected line must be one of the managed lines; when no line is
+ * selected, Connect's sole line is used automatically.
+ */
+export function createSendblueLineResolvers(connector, fromNumber, options) {
+    let pending;
+    let resolved;
+    function resolveAllowedFromNumbers() {
+        if (resolved !== undefined)
+            return Promise.resolve(resolved);
+        if (!pending) {
+            pending = getConnectorMetadata(connector, options)
+                .then(metadata => {
+                const phoneNumbers = readPhoneNumbers(metadata.vendor);
+                if (phoneNumbers.length === 0) {
+                    throw new Error(`Vercel Connect connector ${connector} has no Sendblue lines.`);
+                }
+                resolved = phoneNumbers;
+                return phoneNumbers;
+            })
+                .finally(() => {
+                pending = undefined;
+            });
+        }
+        return pending;
+    }
+    async function resolveFromNumber() {
+        const phoneNumbers = await resolveAllowedFromNumbers();
+        const selected = typeof fromNumber === 'function' ? await fromNumber() : fromNumber;
+        if (selected === undefined) {
+            if (phoneNumbers.length === 1)
+                return phoneNumbers[0];
+            throw new Error(`Vercel Connect connector ${connector} has multiple Sendblue lines. Pass fromNumber to select one.`);
+        }
+        if (!phoneNumbers.includes(selected)) {
+            throw new Error(`Vercel Connect connector ${connector} did not authorize Sendblue line ${selected}.`);
+        }
+        return selected;
+    }
+    return {
+        fromNumber: resolveFromNumber,
+        allowedFromNumbers: resolveAllowedFromNumbers,
+    };
+}
+/** Resolves an explicit Sendblue line, or the connector's sole managed line. */
+export function createSendblueFromNumberResolver(connector, fromNumber, options) {
+    return createSendblueLineResolvers(connector, fromNumber, options).fromNumber;
+}
+/**
+ * Builds the shared credential and line configuration for Sendblue Connect
+ * integrations. Callers add the webhook verifier required by their runtime.
+ */
+export function createConnectSendblueConfig(connector, params = {}, options) {
+    const { fromNumber, ...tokenParams } = params;
+    const { fromNumber: defaultFromNumber, allowedFromNumbers } = createSendblueLineResolvers(connector, fromNumber, options);
+    return {
+        accessToken: () => getToken(connector, { ...tokenParams, subject: { type: 'app' } }, options),
+        defaultFromNumber,
+        allowedFromNumbers,
+    };
+}

package/dist/token.d.ts

@@ -27,8 +27,8 @@ export interface ConnectTokenParams {
     installationId?: string;
     audience?: string[];
     /**
-     * Access scopes to request. Use `['*']` to request the default scopes for
-     * the specified subject type.
+     * Access scopes to request. Defaults to `['*']`, which requests the default
+     * scopes for the specified subject type.
      */
     scopes?: string[];
     resources?: string[];
@@ -103,6 +103,12 @@ export interface ConnectOptions {
      * a stale bearer.
      */
     forceRefresh?: boolean;
+    /**
+     * Region to send the request to, e.g. `sfo1`. Defaults to the
+     * `VERCEL_REGION` environment variable; override it to target a
+     * different region.
+     */
+    region?: string;
 }
 export declare function getToken(connector: string, params: ConnectTokenParams, options?: ConnectOptions): Promise<string>;
 export declare function getTokenResponse(connector: string, params: ConnectTokenParams, options?: ConnectOptions): Promise<ConnectTokenResponse>;

package/dist/token.js

@@ -1,4 +1,6 @@
 import { getVercelOidcToken } from '@vercel/oidc';
+import { resolveBaseUrl } from './internal/base-url.js';
+import { withDefaultScopes } from './internal/default-scopes.js';
 export class ConnectError extends Error {
     code;
     status;
@@ -36,8 +38,9 @@ export async function getToken(connector, params, options) {
     return token;
 }
 export async function getTokenResponse(connector, params, options) {
-    const bufferMs = params.validityBufferMs ?? DEFAULT_VALIDITY_BUFFER_MS;
-    const cacheKey = tokenCacheKey(connector, params);
+    const requestParams = withDefaultScopes(params);
+    const bufferMs = requestParams.validityBufferMs ?? DEFAULT_VALIDITY_BUFFER_MS;
+    const cacheKey = tokenCacheKey(connector, requestParams);
     if (options?.forceRefresh) {
         cache.delete(cacheKey);
     }
@@ -53,7 +56,8 @@ export async function getTokenResponse(connector, params, options) {
         }
     }
     const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
-    const endpoint = `https://api.vercel.com/v1/connect/token/${encodeURIComponent(connector)}`;
+    const baseUrl = resolveBaseUrl(options);
+    const endpoint = `${baseUrl}/v1/connect/token/${encodeURIComponent(connector)}`;
     const response = await fetch(endpoint, {
         method: 'POST',
         headers: {
@@ -61,7 +65,7 @@ export async function getTokenResponse(connector, params, options) {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${vercelToken}`,
         },
-        body: JSON.stringify(params),
+        body: JSON.stringify(requestParams),
     });
     if (!response.ok) {
         throw await createConnectErrorFromResponse(response, 'Failed to get token');
@@ -75,7 +79,8 @@ export async function getTokenResponse(connector, params, options) {
 }
 export async function revokeToken(connector, params, options) {
     const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
-    const endpoint = `https://api.vercel.com/v1/connect/connectors/${encodeURIComponent(connector)}/tokens`;
+    const baseUrl = resolveBaseUrl(options);
+    const endpoint = `${baseUrl}/v1/connect/connectors/${encodeURIComponent(connector)}/tokens`;
     const response = await fetch(endpoint, {
         method: 'DELETE',
         headers: {
@@ -108,7 +113,7 @@ export async function revokeToken(connector, params, options) {
  * call. No-op when no matching entry exists.
  */
 export function deleteTokenCacheEntry(connector, params) {
-    cache.delete(tokenCacheKey(connector, params));
+    cache.delete(tokenCacheKey(connector, withDefaultScopes(params)));
 }
 const DEFAULT_VALIDITY_BUFFER_MS = 30_000;
 const MAX_CACHE_SIZE = 100;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/connect",
-  "version": "0.9.0",
+  "version": "2.0.0",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {