@alter-ai/alter-sdk 0.3.1 → 0.5.0

package/dist/index.d.cts

@@ -48,6 +48,14 @@ declare class TokenResponse {
     readonly injectionHeader: string;
     /** Header value format with {token} placeholder (e.g., "Bearer {token}", "{token}") */
     readonly injectionFormat: string;
+    /** Extra credentials for multi-part auth (e.g. AWS SigV4 secret_key, region) */
+    readonly additionalCredentials: Record<string, string> | null;
+    /** Additional injection rules for multi-header or query param auth */
+    readonly additionalInjections: ReadonlyArray<{
+        readonly target: string;
+        readonly key: string;
+        readonly value_source: string;
+    }> | null;
     constructor(data: {
         access_token: string;
         token_type?: string;
@@ -58,6 +66,12 @@ declare class TokenResponse {
         provider_id?: string;
         injection_header?: string;
         injection_format?: string;
+        additional_credentials?: Record<string, string> | null;
+        additional_injections?: Array<{
+            target: string;
+            key: string;
+            value_source: string;
+        }> | null;
     });
     /**
      * Parse expires_at from ISO string.
@@ -101,6 +115,7 @@ declare class ConnectionInfo {
     readonly accountIdentifier: string | null;
     readonly accountDisplayName: string | null;
     readonly status: string;
+    readonly scopeMismatch: boolean;
     readonly expiresAt: string | null;
     readonly createdAt: string;
     readonly lastUsedAt: string | null;
@@ -111,6 +126,7 @@ declare class ConnectionInfo {
         account_identifier?: string | null;
         account_display_name?: string | null;
         status: string;
+        scope_mismatch?: boolean;
         expires_at?: string | null;
         created_at: string;
         last_used_at?: string | null;
@@ -157,6 +173,40 @@ declare class ConnectionListResult {
         has_more: boolean;
     });
 }
+/**
+ * Result of a headless connect() flow.
+ *
+ * Returned by connect() after the user completes OAuth in the browser.
+ * Contains the connection metadata (no tokens — use request() with
+ * the connectionId to make authenticated API calls).
+ */
+/**
+ * Per-connection policy (e.g., TTL expiry).
+ */
+interface ConnectionPolicy {
+    /** Hard expiry timestamp (ISO 8601 UTC) */
+    expires_at?: string | null;
+    /** Who set the policy: 'developer' or 'end_user' */
+    created_by?: string | null;
+    /** When the policy was set (ISO 8601 UTC) */
+    created_at?: string | null;
+}
+declare class ConnectResult {
+    readonly connectionId: string;
+    readonly providerId: string;
+    readonly accountIdentifier: string | null;
+    readonly scopes: string[];
+    readonly connectionPolicy: ConnectionPolicy | null;
+    constructor(data: {
+        connection_id: string;
+        provider_id: string;
+        account_identifier?: string | null;
+        scopes?: string[];
+        connection_policy?: ConnectionPolicy | null;
+    });
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
 /**
  * Audit log entry for an API call to a provider.
  *
@@ -243,10 +293,72 @@ declare class APICallAuditLog {
  * ```
  */
 declare enum Provider {
-    GOOGLE = "google",
+    ACUITY_SCHEDULING = "acuity-scheduling",
+    ADOBE = "adobe",
+    AIRCALL = "aircall",
+    AIRTABLE = "airtable",
+    APOLLO = "apollo",
+    ASANA = "asana",
+    ATLASSIAN = "atlassian",
+    ATTIO = "attio",
+    AUTODESK = "autodesk",
+    BASECAMP = "basecamp",
+    BITBUCKET = "bitbucket",
+    BITLY = "bitly",
+    BOX = "box",
+    BREX = "brex",
+    CALENDLY = "calendly",
+    CAL_COM = "cal-com",
+    CANVA = "canva",
+    CLICKUP = "clickup",
+    CLOSE = "close",
+    CONSTANT_CONTACT = "constant-contact",
+    CONTENTFUL = "contentful",
+    DEEL = "deel",
+    DIALPAD = "dialpad",
+    DIGITALOCEAN = "digitalocean",
+    DISCORD = "discord",
+    DOCUSIGN = "docusign",
+    DROPBOX = "dropbox",
+    EBAY = "ebay",
+    EVENTBRITE = "eventbrite",
+    FACEBOOK = "facebook",
+    FIGMA = "figma",
     GITHUB = "github",
+    GOOGLE = "google",
+    HUBSPOT = "hubspot",
+    INSTAGRAM = "instagram",
+    LINEAR = "linear",
+    LINKEDIN = "linkedin",
+    MAILCHIMP = "mailchimp",
+    MERCURY = "mercury",
+    MICROSOFT = "microsoft",
+    MIRO = "miro",
+    MONDAY = "monday",
+    NOTION = "notion",
+    OUTREACH = "outreach",
+    PAGERDUTY = "pagerduty",
+    PAYPAL = "paypal",
+    PINTEREST = "pinterest",
+    PIPEDRIVE = "pipedrive",
+    QUICKBOOKS = "quickbooks",
+    RAMP = "ramp",
+    REDDIT = "reddit",
+    RINGCENTRAL = "ringcentral",
+    SALESFORCE = "salesforce",
+    SENTRY = "sentry",
     SLACK = "slack",
-    SENTRY = "sentry"
+    SNAPCHAT = "snapchat",
+    SPOTIFY = "spotify",
+    SQUARE = "square",
+    SQUARESPACE = "squarespace",
+    STRIPE = "stripe",
+    TIKTOK = "tiktok",
+    TODOIST = "todoist",
+    TWITTER = "twitter",
+    TYPEFORM = "typeform",
+    WEBEX = "webex",
+    WEBFLOW = "webflow"
 }
 /**
  * HTTP methods for type-safe method selection.
@@ -292,6 +404,8 @@ interface AlterVaultOptions {
     clientType?: string;
     /** AI framework (e.g., "langchain", "langgraph", "crewai") */
     framework?: string;
+    /** JWT identity resolution: callable that returns the current user's JWT */
+    userTokenGetter?: () => string | Promise<string>;
 }
 /**
  * Options for the request() method.
@@ -313,6 +427,10 @@ interface RequestOptions {
     threadId?: string;
     /** Tool invocation ID */
     toolCallId?: string;
+    /** Provider ID for identity resolution (e.g., "google"). Alternative to connectionId. */
+    provider?: string;
+    /** Account identifier for multi-account disambiguation (only with provider) */
+    account?: string;
 }
 /**
  * Options for the listConnections() method.
@@ -325,16 +443,30 @@ interface ListConnectionsOptions {
     /** Offset for pagination (default 0) */
     offset?: number;
 }
+/**
+ * Options for the connect() method.
+ */
+interface ConnectOptions {
+    /** Restrict to specific providers (e.g., ["google"]) */
+    providers?: string[];
+    /** Max seconds to wait for completion (default 300 = 5 min) */
+    timeout?: number;
+    /** Seconds between poll requests (default 2) */
+    pollInterval?: number;
+    /** If true, opens browser automatically. If false, prints URL. (default true) */
+    openBrowser?: boolean;
+    /** TTL bounds for connection policy. End user picks duration within bounds in Connect UI. */
+    connectionPolicy?: {
+        /** Maximum TTL the end user can select (seconds) */
+        maxTtlSeconds?: number;
+        /** Pre-selected TTL in Connect UI (seconds) */
+        defaultTtlSeconds?: number;
+    };
+}
 /**
  * Options for the createConnectSession() method.
  */
 interface CreateConnectSessionOptions {
-    /** End user to create session for (requires at least id) */
-    endUser: {
-        id: string;
-        email?: string;
-        name?: string;
-    };
     /** Restrict to specific providers (e.g., ["google", "github"]) */
     allowedProviders?: string[];
     /** URL to redirect after OAuth completion */
@@ -346,6 +478,13 @@ interface CreateConnectSessionOptions {
         ipAddress?: string;
         userAgent?: string;
     };
+    /** TTL bounds for connection policy. End user picks duration within bounds in Connect UI. */
+    connectionPolicy?: {
+        /** Maximum TTL the end user can select (seconds) */
+        maxTtlSeconds?: number;
+        /** Pre-selected TTL in Connect UI (seconds) */
+        defaultTtlSeconds?: number;
+    };
 }
 /**
  * Main SDK class for Alter Vault OAuth token management.
@@ -388,7 +527,7 @@ declare class AlterVault {
      * 4. Logs the call for audit (fire-and-forget)
      * 5. Returns the raw response
      */
-    request(connectionId: string, method: HttpMethod | string, url: string, options?: RequestOptions): Promise<Response>;
+    request(connectionId: string | null | undefined, method: HttpMethod | string, url: string, options?: RequestOptions): Promise<Response>;
     /**
      * List OAuth connections for this app.
      *
@@ -402,6 +541,20 @@ declare class AlterVault {
      * Returns a URL the user can open in their browser to authorize access.
      */
     createConnectSession(options: CreateConnectSessionOptions): Promise<ConnectSession>;
+    /**
+     * Open OAuth in the user's browser and wait for completion.
+     *
+     * This is the headless connect flow for CLI tools, scripts, and
+     * server-side applications. It creates a Connect session, opens the
+     * browser, and polls until the user completes OAuth.
+     *
+     * @param options - Connect options
+     * @returns Array of ConnectResult objects (one per connected provider)
+     * @throws ConnectTimeoutError if the user doesn't complete within timeout
+     * @throws ConnectFlowError if the user denies or provider returns error
+     * @throws AlterSDKError if SDK is closed or session creation fails
+     */
+    connect(options: ConnectOptions): Promise<ConnectResult[]>;
     /**
      * Close HTTP clients and release resources.
      * Waits for any pending audit tasks before closing.
@@ -418,6 +571,25 @@ declare class AlterVault {
  * Exception hierarchy for Alter SDK.
  *
  * All exceptions inherit from AlterSDKError for easy catching.
+ * The hierarchy is organized by **developer action** — what you should do
+ * when you catch each error:
+ *
+ * AlterSDKError
+ * ├── BackendError                         — Alter Vault backend returned an error
+ * │   ├── ReAuthRequiredError              — User must re-authorize via Alter Connect
+ * │   │   ├── ConnectionExpiredError       — TTL elapsed
+ * │   │   ├── ConnectionRevokedError       — Auth permanently broken
+ * │   │   └── ConnectionDeletedError       — User disconnected via Wallet
+ * │   ├── ConnectionNotFoundError          — Wrong connection_id — fix your code
+ * │   └── PolicyViolationError             — Policy denied — may resolve on its own
+ * ├── ConnectFlowError                     — Connect flow failed
+ * │   ├── ConnectDeniedError               — User clicked Deny
+ * │   ├── ConnectConfigError               — OAuth app misconfigured
+ * │   └── ConnectTimeoutError              — User didn't complete in time
+ * ├── ProviderAPIError                     — Provider returned 4xx/5xx
+ * │   └── ScopeReauthRequiredError        — 403 + scope mismatch, user must re-authorize
+ * └── NetworkError                         — Connection/timeout errors
+ *     └── TimeoutError                     — Request timed out
  */
 /**
  * Base exception for all Alter SDK errors.
@@ -428,38 +600,110 @@ declare class AlterSDKError extends Error {
     toString(): string;
 }
 /**
- * Raised when token retrieval fails.
+ * Raised when the Alter Vault backend returns an error.
+ */
+declare class BackendError extends AlterSDKError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when the user must re-authorize via Alter Connect.
+ *
+ * This is the parent class for all errors that require the user to go through
+ * the Connect flow again. Catch this to handle all re-auth cases in one place.
  */
-declare class TokenRetrievalError extends AlterSDKError {
+declare class ReAuthRequiredError extends BackendError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when a connection's TTL has expired.
+ *
+ * The time-limited access granted during the Connect flow has elapsed.
+ * The user must re-authorize to restore access.
+ */
+declare class ConnectionExpiredError extends ReAuthRequiredError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when a connection's auth is permanently broken.
+ *
+ * This happens when:
+ * - The user revoked your app at the provider (e.g., Google Account settings)
+ * - The refresh token expired or was invalidated
+ * - Token refresh permanently failed (invalid_grant)
+ *
+ * The user must re-authorize via Alter Connect.
+ */
+declare class ConnectionRevokedError extends ReAuthRequiredError {
+    readonly connectionId: string | undefined;
+    constructor(message: string, connectionId?: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when a connection has been deliberately deleted.
+ *
+ * The end user disconnected the account via the Wallet dashboard.
+ * Re-authorization via Alter Connect will generate a **new** `connection_id`
+ * — update your stored reference from the `ConnectResult`.
+ */
+declare class ConnectionDeletedError extends ReAuthRequiredError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when OAuth connection not found.
+ *
+ * No connection exists for the given connection_id.
+ * Check for typos or stale references.
+ */
+declare class ConnectionNotFoundError extends BackendError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
  * Raised when token access is denied by policy enforcement.
  *
- * This indicates the connection exists but access was denied by Cerbos policy
- * (e.g., unauthorized scopes, outside business hours, rate limit exceeded).
+ * The connection exists but access was denied by a Cerbos policy
+ * (e.g., outside business hours, IP allowlist, rate limit exceeded).
+ * This may resolve on its own (e.g., wait until business hours).
  */
-declare class PolicyViolationError extends TokenRetrievalError {
+declare class PolicyViolationError extends BackendError {
     readonly policyError: string | undefined;
     constructor(message: string, policyError?: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when OAuth connection not found.
+ * Raised when the headless connect() flow fails.
  *
- * This indicates no connection exists for the given connection_id.
+ * This can happen when:
+ * - The user denies authorization
+ * - The provider returns an error
+ * - The OAuth app is misconfigured
+ * - The session expires before completion
  */
-declare class ConnectionNotFoundError extends TokenRetrievalError {
+declare class ConnectFlowError extends AlterSDKError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when token refresh fails.
+ * Raised when the user denies authorization during the Connect flow.
  *
- * This indicates the connection exists but token refresh failed (e.g., refresh
- * token revoked, provider API error).
+ * The user explicitly clicked "Deny" or "Cancel" on the provider's
+ * authorization page.
  */
-declare class TokenExpiredError extends TokenRetrievalError {
-    readonly connectionId: string | undefined;
-    constructor(message: string, connectionId?: string, details?: Record<string, unknown>);
+declare class ConnectDeniedError extends ConnectFlowError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when the OAuth app is misconfigured.
+ *
+ * Check your OAuth app configuration in the Developer Portal.
+ * Common causes: wrong redirect URI, invalid client ID/secret.
+ */
+declare class ConnectConfigError extends ConnectFlowError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when the connect() flow times out.
+ *
+ * The user did not complete OAuth within the specified timeout period.
+ */
+declare class ConnectTimeoutError extends ConnectFlowError {
+    constructor(message: string, details?: Record<string, unknown>);
 }
 /**
  * Raised when provider API call fails.
@@ -471,6 +715,36 @@ declare class ProviderAPIError extends AlterSDKError {
     readonly responseBody: string | undefined;
     constructor(message: string, statusCode?: number, responseBody?: string, details?: Record<string, unknown>);
 }
+/**
+ * Raised when a provider API returns 403 and the connection has a scope mismatch.
+ *
+ * This indicates the connection's OAuth scopes don't match the provider config's
+ * required scopes — typically because the developer added new scopes after the
+ * user originally authorized. The user needs to re-authorize via a Connect session
+ * to grant the updated permissions.
+ *
+ * Recovery:
+ * ```typescript
+ * try {
+ *   const result = await vault.request(connId, HttpMethod.GET, url);
+ * } catch (e) {
+ *   if (e instanceof ScopeReauthRequiredError) {
+ *     const session = await vault.createConnectSession({
+ *       allowedProviders: [e.providerId],
+ *     });
+ *     notifyUser(e.connectionId, session.connectUrl);
+ *   }
+ * }
+ * ```
+ *
+ * Extends ProviderAPIError so existing `catch` blocks for ProviderAPIError
+ * continue to work without code changes.
+ */
+declare class ScopeReauthRequiredError extends ProviderAPIError {
+    readonly connectionId: string | undefined;
+    readonly providerId: string | undefined;
+    constructor(message: string, connectionId?: string, providerId?: string, statusCode?: number, responseBody?: string, details?: Record<string, unknown>);
+}
 /**
  * Raised when network operations fail.
  *
@@ -493,4 +767,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectSession, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };
+export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, BackendError, ConnectConfigError, ConnectDeniedError, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, ConnectionDeletedError, ConnectionExpiredError, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, ConnectionRevokedError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, ReAuthRequiredError, type RequestOptions, ScopeReauthRequiredError, TimeoutError, TokenResponse };