@alter-ai/alter-sdk 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -50,6 +50,12 @@ declare class TokenResponse {
     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;
@@ -61,6 +67,11 @@ declare class TokenResponse {
         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.
@@ -104,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;
@@ -114,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;
@@ -167,16 +180,29 @@ declare class ConnectionListResult {
  * 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;
@@ -267,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.
@@ -316,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.
@@ -337,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.
@@ -353,12 +447,6 @@ interface ListConnectionsOptions {
  * Options for the connect() method.
  */
 interface ConnectOptions {
-    /** End user to create session for (requires at least id) */
-    endUser: {
-        id: string;
-        email?: string;
-        name?: string;
-    };
     /** Restrict to specific providers (e.g., ["google"]) */
     providers?: string[];
     /** Max seconds to wait for completion (default 300 = 5 min) */
@@ -367,17 +455,18 @@ interface ConnectOptions {
     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 */
@@ -389,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.
@@ -431,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.
      *
@@ -452,7 +548,7 @@ declare class AlterVault {
      * server-side applications. It creates a Connect session, opens the
      * browser, and polls until the user completes OAuth.
      *
-     * @param options - Connect options (endUser is required)
+     * @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
@@ -475,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.
@@ -485,50 +600,103 @@ declare class AlterSDKError extends Error {
     toString(): string;
 }
 /**
- * Raised when token retrieval fails.
+ * Raised when the Alter Vault backend returns an error.
  */
-declare class TokenRetrievalError extends AlterSDKError {
+declare class BackendError extends AlterSDKError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when token access is denied by policy enforcement.
+ * Raised when the user must re-authorize via Alter Connect.
  *
- * This indicates the connection exists but access was denied by Cerbos policy
- * (e.g., unauthorized scopes, outside business hours, rate limit exceeded).
+ * 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 PolicyViolationError extends TokenRetrievalError {
-    readonly policyError: string | undefined;
-    constructor(message: string, policyError?: string, details?: Record<string, unknown>);
+declare class ReAuthRequiredError extends BackendError {
+    constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when OAuth connection not found.
+ * Raised when a connection's TTL has expired.
  *
- * This indicates no connection exists for the given connection_id.
+ * The time-limited access granted during the Connect flow has elapsed.
+ * The user must re-authorize to restore access.
  */
-declare class ConnectionNotFoundError extends TokenRetrievalError {
+declare class ConnectionExpiredError extends ReAuthRequiredError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when token refresh fails.
+ * Raised when a connection's auth is permanently broken.
  *
- * This indicates the connection exists but token refresh failed (e.g., refresh
- * token revoked, provider API error).
+ * 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 TokenExpiredError extends TokenRetrievalError {
+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.
+ *
+ * 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 BackendError {
+    readonly policyError: string | undefined;
+    constructor(message: string, policyError?: string, details?: Record<string, unknown>);
+}
 /**
  * Raised when the headless connect() flow fails.
  *
  * 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 ConnectFlowError extends AlterSDKError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * Raised when the user denies authorization during the Connect flow.
+ *
+ * The user explicitly clicked "Deny" or "Cancel" on the provider's
+ * authorization page.
+ */
+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.
  *
@@ -547,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.
  *
@@ -569,4 +767,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, 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 };