@vercel/connect 0.4.2 → 0.5.0

package/README.md

@@ -30,6 +30,22 @@ const token = await getToken(process.env.CONNECTOR_LINEAR!, {
 });
 ```
 
+To create an operator installation request for an app-scoped connector, use the
+experimental install helper:
+
+This feature is gated while experimental. Contact Vercel to enable access
+before using it.
+
+```ts
+import { experimental_startInstallation } from '@vercel/connect';
+
+const { url } = await experimental_startInstallation(
+  process.env.CONNECTOR_SLACK!,
+  {},
+  { returnUrl: 'https://example.com/settings/integrations' }
+);
+```
+
 ### Chat SDK
 
 Spread the helper into the matching `create*Adapter` factory. Each helper
@@ -123,4 +139,4 @@ import { connect } from '@vercel/connect/authjs';
 const providers = [connect({ connector: 'linear' })];
 ```
 
-See the source under `src/` for the full API (additional helpers like `revokeToken`, `getTokenResponse`, `startAuthorization`, typed error classes, and per-adapter options).
+See the source under `src/` for the full API (additional helpers like `revokeToken`, `getTokenResponse`, `startAuthorization`, `experimental_startInstallation`, typed error classes, and per-adapter options).

package/dist/ai-sdk/index.d.ts

@@ -49,4 +49,4 @@
  * ```
  */
 export { connectAuthProvider, ConsentRequiredError, type ConnectAuthProviderOptions, type ConsentChallenge, } from '../mcp/connect-auth-provider.js';
-export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, type ConnectErrorOptions, type ConnectTokenParams, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from '../token.js';
+export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, type ConnectErrorOptions, type ConnectTokenExchangeSubject, type ConnectTokenParams, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from '../token.js';

package/dist/authorization.js

@@ -1,11 +1,10 @@
 import { getVercelOidcToken } from '@vercel/oidc';
-const DETACHED_INTERACTIVE_AUTH_MODE = 'detached';
-const INTERACTIVE_AUTH_MODE_ENV = 'VERCEL_CONNECT_INTERACTIVE_AUTH_MODE';
+import { isDetachedInteractiveAuth, validateCallbackUrl, validateWebhookUrl, } from './internal/url-validation.js';
 export async function startAuthorization(connector, params, options) {
     if (!connector) {
         throw new Error('connector is required');
     }
-    const detachedInteractiveAuth = process.env[INTERACTIVE_AUTH_MODE_ENV] === DETACHED_INTERACTIVE_AUTH_MODE;
+    const detachedInteractiveAuth = isDetachedInteractiveAuth();
     if (!detachedInteractiveAuth && options?.callbackUrl !== undefined) {
         validateCallbackUrl(options.callbackUrl);
     }
@@ -49,35 +48,3 @@ export async function startAuthorization(connector, params, options) {
     const data = await response.json();
     return data;
 }
-function validateCallbackUrl(value) {
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch {
-        throw new Error(`Invalid callbackUrl: ${value}`);
-    }
-    if (url.protocol === 'https:')
-        return;
-    if (url.protocol === 'http:' && isLocalHttpCallbackHostname(url.hostname)) {
-        return;
-    }
-    throw new Error(`callbackUrl must be https://, http://localhost, or http://*.localhost, got: ${value}`);
-}
-function isLocalHttpCallbackHostname(hostname) {
-    return (hostname === 'localhost' ||
-        hostname.endsWith('.localhost') ||
-        hostname === '127.0.0.1');
-}
-function validateWebhookUrl(value) {
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch {
-        throw new Error(`Invalid webhook URL: ${value}`);
-    }
-    if (url.protocol !== 'https:') {
-        throw new Error(`webhook must be https://, got: ${value}`);
-    }
-}

package/dist/connector.d.ts

@@ -0,0 +1,32 @@
+import { type ConnectOptions } from './token.js';
+/**
+ * Connector metadata as returned by Vercel Connect. This is the stable, useful
+ * subset of the connector object the management APIs return.
+ */
+export interface ConnectorMetadata {
+    /** Opaque Vercel Connect connector id (e.g. `scl_…`). */
+    id: string;
+    /** Human-readable Vercel Connect connector UID. */
+    uid: string;
+    name: string;
+    /** Connector type identifier (e.g. `snowflake`, `oauth`). */
+    type: string;
+    /** Service the connector integrates with. */
+    service: string;
+    /** Fully-qualified URL for the connector's service when derivable. */
+    clientUrl?: string;
+    createdAt: number;
+    updatedAt: number;
+    /** Vendor-specific public configuration. */
+    vendor: Record<string, unknown>;
+}
+/**
+ * Fetch a connector's metadata from Vercel Connect.
+ *
+ * Authenticates with the deployment's Vercel OIDC token (same as
+ * {@link getToken}); the connector must be attached to the requesting
+ * deployment's project and enabled for its environment.
+ *
+ * @param connector - The connector id or UID.
+ */
+export declare function getConnectorMetadata(connector: string, options?: ConnectOptions): Promise<ConnectorMetadata>;

package/dist/connector.js

@@ -0,0 +1,27 @@
+import { getVercelOidcToken } from '@vercel/oidc';
+import { createConnectErrorFromResponse, } from './token.js';
+/**
+ * Fetch a connector's metadata from Vercel Connect.
+ *
+ * Authenticates with the deployment's Vercel OIDC token (same as
+ * {@link getToken}); the connector must be attached to the requesting
+ * deployment's project and enabled for its environment.
+ *
+ * @param connector - The connector id or UID.
+ */
+export async function getConnectorMetadata(connector, options) {
+    const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
+    const endpoint = `https://api.vercel.com/v1/connect/connectors/${encodeURIComponent(connector)}`;
+    const response = await fetch(endpoint, {
+        method: 'GET',
+        headers: {
+            Accept: 'application/json',
+            Authorization: `Bearer ${vercelToken}`,
+        },
+    });
+    if (!response.ok) {
+        throw await createConnectErrorFromResponse(response, 'Failed to get connector');
+    }
+    const { data, ...rest } = (await response.json());
+    return { ...rest, vendor: data ?? {} };
+}

package/dist/eve/connect-oauth.js

@@ -1,4 +1,5 @@
 import { extractBearerToken, verifyOidc, } from 'eve/channels/auth';
+import { readNonEmptyEnv } from '../internal/env.js';
 export const CONNECT_OAUTH_ISSUER = 'https://connect.vercel.com';
 /**
  * Returns an Eve route auth callback for Vercel Connect OAuth gateway
@@ -110,10 +111,6 @@ function buildClaimMatchers(opts) {
         typ: ['at'],
     };
 }
-function readNonEmptyEnv(name) {
-    const value = typeof process === 'undefined' ? undefined : process.env?.[name]?.trim();
-    return value === undefined || value.length === 0 ? undefined : value;
-}
 function extractAudiences(payload) {
     const aud = payload.aud;
     if (typeof aud === 'string') {

package/dist/eve/index.d.ts

@@ -10,4 +10,5 @@ export { connect, type EveAuthorizationInput, type EveAuthorizationOptions, type
 export { CONNECT_OAUTH_ISSUER, connectOAuth, type ConnectOAuthAudienceEnvironment, type ConnectOAuthEnvironment, type ConnectOAuthOptions, } from './connect-oauth.js';
 export { connectGitHubCredentials, type ConnectGitHubCredentialsParams, } from './github-credentials.js';
 export { connectLinearCredentials, type ConnectLinearCredentialsParams, } from './linear-credentials.js';
+export { connectPhotonCredentials, type ConnectPhotonCredentialProvider, type PhotonCredentials, type ConnectPhotonCredentialsParams, } from './photon-credentials.js';
 export { connectSlackCredentials, type ConnectSlackCredentialsParams, } from './slack-credentials.js';

package/dist/eve/index.js

@@ -10,4 +10,5 @@ export { connect, } from './connection-authorization.js';
 export { CONNECT_OAUTH_ISSUER, connectOAuth, } from './connect-oauth.js';
 export { connectGitHubCredentials, } from './github-credentials.js';
 export { connectLinearCredentials, } from './linear-credentials.js';
+export { connectPhotonCredentials, } from './photon-credentials.js';
 export { connectSlackCredentials, } from './slack-credentials.js';

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

@@ -0,0 +1,34 @@
+import { type ConnectOptions, type ConnectTokenParams } from '../index.js';
+/** Photon project credentials resolved by {@link connectPhotonCredentials}. */
+export interface PhotonCredentials {
+    projectId: string;
+    projectSecret: string;
+}
+/** Lazy Photon credential provider returned by {@link connectPhotonCredentials}. */
+export type ConnectPhotonCredentialProvider = () => Promise<PhotonCredentials>;
+/**
+ * Token parameters accepted by {@link connectPhotonCredentials}.
+ *
+ * Mirrors {@link ConnectTokenParams} from `@vercel/connect`, minus
+ * `subject` — Photon project credentials are app-scoped, so `subject`
+ * is pinned to `{ type: "app" }` by this helper and cannot be overridden.
+ */
+export type ConnectPhotonCredentialsParams = Omit<ConnectTokenParams, 'subject'>;
+/**
+ * Build a lazy Photon credential provider backed by a Vercel Connect
+ * connector.
+ *
+ * Photon connectors issue the project secret as an app-scoped token and the
+ * project ID as public token metadata. The returned provider resolves both
+ * fields when the Photon client or adapter first needs them.
+ *
+ * ```ts
+ * import { connectPhotonCredentials } from '@vercel/connect/eve';
+ * import { createiMessageAdapter } from '@photon-ai/chat-adapter-imessage';
+ *
+ * const imessage = createiMessageAdapter({
+ *   credentials: connectPhotonCredentials('photon/my-project'),
+ * });
+ * ```
+ */
+export declare function connectPhotonCredentials(connector: string, params?: ConnectPhotonCredentialsParams, options?: ConnectOptions): ConnectPhotonCredentialProvider;

package/dist/eve/photon-credentials.js

@@ -0,0 +1,31 @@
+import { getTokenResponse, } from '../index.js';
+/**
+ * Build a lazy Photon credential provider backed by a Vercel Connect
+ * connector.
+ *
+ * Photon connectors issue the project secret as an app-scoped token and the
+ * project ID as public token metadata. The returned provider resolves both
+ * fields when the Photon client or adapter first needs them.
+ *
+ * ```ts
+ * import { connectPhotonCredentials } from '@vercel/connect/eve';
+ * import { createiMessageAdapter } from '@photon-ai/chat-adapter-imessage';
+ *
+ * const imessage = createiMessageAdapter({
+ *   credentials: connectPhotonCredentials('photon/my-project'),
+ * });
+ * ```
+ */
+export function connectPhotonCredentials(connector, params = {}, options) {
+    return async () => {
+        const response = await getTokenResponse(connector, { ...params, subject: { type: 'app' } }, options);
+        const projectId = response.metadata?.projectId;
+        if (typeof projectId !== 'string' || projectId.length === 0) {
+            throw new Error('Photon connector returned invalid credentials.');
+        }
+        return {
+            projectId,
+            projectSecret: response.token,
+        };
+    };
+}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
-export { deleteTokenCacheEntry, getToken, getTokenResponse, revokeToken, ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, type ConnectErrorOptions, type ConnectOptions, type ConnectTokenParams, type ConnectTokenResponse, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from './token.js';
+export { deleteTokenCacheEntry, getToken, getTokenResponse, revokeToken, ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, type ConnectErrorOptions, type ConnectOptions, type ConnectTokenExchangeSubject, type ConnectTokenParams, type ConnectTokenResponse, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from './token.js';
 export { startAuthorization, type ConnectAuthorizationOptions, type ConnectAuthorizationResponse, } from './authorization.js';
+export { experimental_startInstallation, type ConnectInstallationOptions, type ConnectInstallationParams, type ConnectInstallationResponse, } from './installation.js';
 export type { ConnectAuthorizationDetail } from './authorization-details.js';
+export { getConnectorMetadata, type ConnectorMetadata, } from './connector.js';

package/dist/index.js

@@ -1,2 +1,4 @@
 export { deleteTokenCacheEntry, getToken, getTokenResponse, revokeToken, ConnectError, NoValidTokenError, UserAuthorizationRequiredError, ConnectorInstallationRequiredError, } from './token.js';
 export { startAuthorization, } from './authorization.js';
+export { experimental_startInstallation, } from './installation.js';
+export { getConnectorMetadata, } from './connector.js';

package/dist/installation.d.ts

@@ -0,0 +1,42 @@
+import type { ConnectTokenParams } from './token.js';
+export type ConnectInstallationParams = Omit<ConnectTokenParams, 'subject'>;
+export interface ConnectInstallationOptions {
+    vercelToken?: string;
+    returnUrl?: string;
+    webhook?: string;
+    tenantId?: string;
+    deviceCode?: boolean;
+    expiresInMs?: number;
+}
+export interface ConnectInstallationResponse {
+    request: string;
+    verifier: string;
+    url: string;
+    deviceCode?: string;
+    expiresAt: number;
+    connector: {
+        /** Client id. */
+        id: string;
+        /** Client uid. */
+        uid: string;
+        /** Client type, eg. `oauth`, `salesforce`. */
+        type: string;
+        /** Resolved service id when known, eg. `salesforce`. */
+        service?: string;
+        /**
+         * Curated display name of the resolved service, eg. `Salesforce`,
+         * present when the service is known to Vercel Connect. Suited for
+         * end-user surfaces like "Sign in with {serviceName}".
+         */
+        serviceName?: string;
+        /** The connector's own (operator-given) name. */
+        name: string;
+    };
+}
+/**
+ * Create an operator installation request for an app-scoped connector.
+ *
+ * @experimental This API is feature-gated while experimental. Contact Vercel
+ * to enable access before using it.
+ */
+export declare function experimental_startInstallation(connector: string, params?: ConnectInstallationParams, options?: ConnectInstallationOptions): Promise<ConnectInstallationResponse>;

package/dist/installation.js

@@ -0,0 +1,50 @@
+import { getVercelOidcToken } from '@vercel/oidc';
+import { isDetachedInteractiveAuth, validateCallbackUrl, validateWebhookUrl, } from './internal/url-validation.js';
+import { createConnectErrorFromResponse } from './token.js';
+/**
+ * Create an operator installation request for an app-scoped connector.
+ *
+ * @experimental This API is feature-gated while experimental. Contact Vercel
+ * to enable access before using it.
+ */
+export async function experimental_startInstallation(connector, params = {}, options) {
+    if (!connector) {
+        throw new Error('connector is required');
+    }
+    const detachedInteractiveAuth = isDetachedInteractiveAuth();
+    if (!detachedInteractiveAuth && options?.returnUrl !== undefined) {
+        validateCallbackUrl(options.returnUrl, 'returnUrl');
+    }
+    if (options?.webhook !== undefined) {
+        validateWebhookUrl(options.webhook);
+    }
+    const vercelToken = options?.vercelToken ?? (await getVercelOidcToken());
+    const endpoint = `https://api.vercel.com/v1/connect/install/${encodeURIComponent(connector)}`;
+    const deviceCode = options?.deviceCode ?? (detachedInteractiveAuth ? true : undefined);
+    const returnUrl = !detachedInteractiveAuth && options?.returnUrl !== undefined
+        ? { returnUrl: options.returnUrl }
+        : {};
+    const response = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${vercelToken}`,
+        },
+        body: JSON.stringify({
+            ...params,
+            ...returnUrl,
+            ...(options?.webhook !== undefined && { webhook: options.webhook }),
+            ...(options?.tenantId !== undefined && { tenantId: options.tenantId }),
+            ...(deviceCode !== undefined && { deviceCode }),
+            ...(options?.expiresInMs !== undefined && {
+                expiresInMs: options.expiresInMs,
+            }),
+        }),
+    });
+    if (!response.ok) {
+        throw await createConnectErrorFromResponse(response, 'Failed to start installation');
+    }
+    const data = await response.json();
+    return data;
+}

package/dist/internal/env.d.ts

@@ -0,0 +1 @@
+export declare function readNonEmptyEnv(name: string): string | undefined;

package/dist/internal/env.js

@@ -0,0 +1,4 @@
+export function readNonEmptyEnv(name) {
+    const value = typeof process === 'undefined' ? undefined : process.env?.[name]?.trim();
+    return value === undefined || value.length === 0 ? undefined : value;
+}

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

@@ -0,0 +1,3 @@
+export declare function isDetachedInteractiveAuth(): boolean;
+export declare function validateCallbackUrl(value: string, label?: string): void;
+export declare function validateWebhookUrl(value: string): void;

package/dist/internal/url-validation.js

@@ -0,0 +1,39 @@
+import { readNonEmptyEnv } from './env.js';
+const DETACHED_INTERACTIVE_AUTH_MODE = 'detached';
+const INTERACTIVE_AUTH_MODE_ENV = 'VERCEL_CONNECT_INTERACTIVE_AUTH_MODE';
+export function isDetachedInteractiveAuth() {
+    return (readNonEmptyEnv(INTERACTIVE_AUTH_MODE_ENV) ===
+        DETACHED_INTERACTIVE_AUTH_MODE);
+}
+export function validateCallbackUrl(value, label = 'callbackUrl') {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid ${label}: ${value}`);
+    }
+    if (url.protocol === 'https:')
+        return;
+    if (url.protocol === 'http:' && isLocalHttpCallbackHostname(url.hostname)) {
+        return;
+    }
+    throw new Error(`${label} must be https://, http://localhost, or http://*.localhost, got: ${value}`);
+}
+export function validateWebhookUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`Invalid webhook URL: ${value}`);
+    }
+    if (url.protocol !== 'https:') {
+        throw new Error(`webhook must be https://, got: ${value}`);
+    }
+}
+function isLocalHttpCallbackHostname(hostname) {
+    return (hostname === 'localhost' ||
+        hostname.endsWith('.localhost') ||
+        hostname === '127.0.0.1');
+}

package/dist/mcp/connect-auth-provider.d.ts

@@ -91,9 +91,9 @@ export declare class ConsentRequiredError extends Error {
  * @param connector Vercel Connect connector UID (e.g. `oauth/linear`)
  *   or opaque connector id.
  * @param params Token request parameters — always specify a
- *   `subject`; the three subject types
- *   (`'app'` / `'user'` / `'jwt-bearer'`) have distinct security
- *   semantics.
+ *   `subject`; the supported subject types
+ *   (`'app'` / `'user'` / `'jwt-bearer'` / `'token'`) have distinct
+ *   security semantics.
  * @param options Optional adapter behavior overrides.
  */
 export declare function connectAuthProvider(connector: string, params: ConnectTokenParams, options?: ConnectAuthProviderOptions): OAuthClientProvider;

package/dist/mcp/connect-auth-provider.js

@@ -41,9 +41,9 @@ const EMPTY_CLIENT_METADATA = {
  * @param connector Vercel Connect connector UID (e.g. `oauth/linear`)
  *   or opaque connector id.
  * @param params Token request parameters — always specify a
- *   `subject`; the three subject types
- *   (`'app'` / `'user'` / `'jwt-bearer'`) have distinct security
- *   semantics.
+ *   `subject`; the supported subject types
+ *   (`'app'` / `'user'` / `'jwt-bearer'` / `'token'`) have distinct
+ *   security semantics.
  * @param options Optional adapter behavior overrides.
  */
 export function connectAuthProvider(connector, params, options) {

package/dist/mcp/index.d.ts

@@ -30,4 +30,4 @@
  * ```
  */
 export { connectAuthProvider, ConsentRequiredError, type ConnectAuthProviderOptions, type ConsentChallenge, } from './connect-auth-provider.js';
-export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, type ConnectErrorOptions, type ConnectTokenParams, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from '../token.js';
+export { ConnectError, ConnectorInstallationRequiredError, NoValidTokenError, UserAuthorizationRequiredError, type ConnectErrorOptions, type ConnectTokenExchangeSubject, type ConnectTokenParams, type ConnectTokenSubject, type ConnectVendorErrorPayload, } from '../token.js';

package/dist/token.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectAuthorizationDetail } from './authorization-details.js';
-export type ConnectSubjectType = 'app' | 'user' | 'jwt-bearer';
-export type ConnectTokenSubject = ConnectAppTokenSubject | ConnectUserTokenSubject | ConnectJwtBearerTokenSubject;
+export type ConnectSubjectType = 'app' | 'user' | 'jwt-bearer' | 'token';
+export type ConnectTokenSubject = ConnectAppTokenSubject | ConnectUserTokenSubject | ConnectJwtBearerTokenSubject | ConnectTokenExchangeSubject;
 export interface ConnectAppTokenSubject {
     type: 'app';
 }
@@ -18,6 +18,10 @@ export interface ConnectJwtBearerTokenSubject {
     aud?: string;
     additionalClaims?: Record<string, unknown>;
 }
+export interface ConnectTokenExchangeSubject {
+    type: 'token';
+    token: string;
+}
 export interface ConnectTokenParams {
     subject: ConnectTokenSubject;
     installationId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vercel/connect",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -42,7 +42,7 @@
     "dist"
   ],
   "dependencies": {
-    "@vercel/oidc": "3.8.0"
+    "@vercel/oidc": "3.8.1"
   },
   "peerDependencies": {
     "@ai-sdk/mcp": "^1 || ^2",