@alter-ai/alter-sdk 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -11,11 +11,15 @@
  */
 /**
  * Actor types for tracking SDK callers.
+ *
+ * All agents (AI agents, MCP-connected agents, direct SDK agents) use
+ * AI_AGENT. MCP servers are transport, not actors — the agent calling
+ * through MCP is the actor. Transport metadata (clientType,
+ * connectionProtocol) is passed separately.
  */
 declare enum ActorType {
     BACKEND_SERVICE = "backend_service",
-    AI_AGENT = "ai_agent",
-    MCP_SERVER = "mcp_server"
+    AI_AGENT = "ai_agent"
 }
 /**
  * OAuth token response from Alter Vault.
@@ -40,10 +44,10 @@ declare class TokenResponse {
     readonly expiresAt: Date | null;
     /** OAuth scopes granted */
     readonly scopes: string[];
-    /** Connection ID that provided this token */
-    readonly connectionId: string;
+    /** Grant ID that provided this token */
+    readonly grantId: string;
     /** Provider ID (google, github, etc.) */
-    readonly providerId: string;
+    readonly providerId: string | null;
     /** HTTP header name for credential injection (e.g., "Authorization", "X-API-Key") */
     readonly injectionHeader: string;
     /** Header value format with {token} placeholder (e.g., "Bearer {token}", "{token}") */
@@ -62,7 +66,7 @@ declare class TokenResponse {
         expires_in?: number | null;
         expires_at?: string | null;
         scopes?: string[];
-        connection_id: string;
+        grant_id: string;
         provider_id?: string;
         injection_header?: string;
         injection_format?: string;
@@ -103,13 +107,13 @@ declare class TokenResponse {
     toString(): string;
 }
 /**
- * OAuth connection info from Alter Vault.
+ * OAuth grant info from Alter Vault.
  *
- * Represents a connected OAuth service (e.g., Google, GitHub).
- * Returned by listConnections(). Contains metadata only — no tokens.
+ * Represents a granted OAuth service (e.g., Google, GitHub).
+ * Returned by listGrants(). Contains metadata only — no tokens.
  */
-declare class ConnectionInfo {
-    readonly id: string;
+declare class GrantInfo {
+    readonly grantId: string;
     readonly providerId: string;
     readonly scopes: string[];
     readonly accountIdentifier: string | null;
@@ -120,7 +124,7 @@ declare class ConnectionInfo {
     readonly createdAt: string;
     readonly lastUsedAt: string | null;
     constructor(data: {
-        id: string;
+        grant_id: string;
         provider_id: string;
         scopes?: string[];
         account_identifier?: string | null;
@@ -155,54 +159,75 @@ declare class ConnectSession {
     toString(): string;
 }
 /**
- * Paginated list of connections.
+ * Paginated list of grants.
  *
- * Returned by listConnections(). Contains connection array plus pagination metadata.
+ * Returned by listGrants(). Contains grant array plus pagination metadata.
  */
-declare class ConnectionListResult {
-    readonly connections: ConnectionInfo[];
+declare class GrantListResult {
+    readonly grants: GrantInfo[];
     readonly total: number;
     readonly limit: number;
     readonly offset: number;
     readonly hasMore: boolean;
     constructor(data: {
-        connections: ConnectionInfo[];
+        grants: GrantInfo[];
         total: number;
         limit: number;
         offset: number;
         has_more: boolean;
     });
+    /**
+     * Custom JSON serialization — snake_case wire format.
+     */
+    toJSON(): Record<string, unknown>;
 }
 /**
  * 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).
+ * Contains the grant metadata (no tokens — use request() with
+ * the grantId to make authenticated API calls).
  */
 /**
- * Per-connection policy (e.g., TTL expiry).
+ * Per-grant policy (e.g., TTL expiry).
  */
-interface ConnectionPolicy {
+interface GrantPolicy {
     /** Hard expiry timestamp (ISO 8601 UTC) */
-    expires_at?: string | null;
+    readonly expiresAt?: string | null;
     /** Who set the policy: 'developer' or 'end_user' */
-    created_by?: string | null;
+    readonly createdBy?: string | null;
     /** When the policy was set (ISO 8601 UTC) */
-    created_at?: string | null;
+    readonly createdAt?: string | null;
 }
 declare class ConnectResult {
-    readonly connectionId: string;
+    readonly grantId: string;
     readonly providerId: string;
     readonly accountIdentifier: string | null;
     readonly scopes: string[];
-    readonly connectionPolicy: ConnectionPolicy | null;
+    readonly grantPolicy: GrantPolicy | null;
     constructor(data: {
-        connection_id: string;
+        grant_id: string;
         provider_id: string;
         account_identifier?: string | null;
         scopes?: string[];
-        connection_policy?: ConnectionPolicy | null;
+        grant_policy?: GrantPolicy | null;
+    });
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
+/**
+ * Result of an authenticate() flow.
+ *
+ * Returned by authenticate() after the user completes IDP login in the browser.
+ * Contains the userToken (IDP JWT) that the SDK uses for subsequent
+ * identity-based request() calls.
+ */
+declare class AuthResult {
+    readonly userToken: string;
+    readonly userInfo: Record<string, unknown>;
+    constructor(data: {
+        user_token: string;
+        user_info?: Record<string, unknown>;
     });
     toJSON(): Record<string, unknown>;
     toString(): string;
@@ -213,7 +238,7 @@ declare class ConnectResult {
  * This is sent to the backend audit endpoint.
  */
 declare class APICallAuditLog {
-    readonly connectionId: string;
+    readonly grantId: string;
     readonly providerId: string;
     readonly method: string;
     readonly url: string;
@@ -232,21 +257,27 @@ declare class APICallAuditLog {
     readonly threadId: string | null;
     /** Tool invocation ID for actor tracking */
     readonly toolCallId: string | null;
+    /** Specific tool being invoked (e.g., "read_calendar") */
+    readonly toolId: string | null;
+    /** Tool bundle identifier (e.g., "google-calendar-mcp-server") */
+    readonly toolBundleId: string | null;
     constructor(data: {
-        connectionId: string;
-        providerId: string;
+        grant_id: string;
+        provider_id: string;
         method: string;
         url: string;
-        requestHeaders?: Record<string, string> | null;
-        requestBody?: unknown | null;
-        responseStatus: number;
-        responseHeaders?: Record<string, string> | null;
-        responseBody?: unknown | null;
-        latencyMs: number;
+        request_headers?: Record<string, string> | null;
+        request_body?: unknown | null;
+        response_status: number;
+        response_headers?: Record<string, string> | null;
+        response_body?: unknown | null;
+        latency_ms: number;
         reason?: string | null;
-        runId?: string | null;
-        threadId?: string | null;
-        toolCallId?: string | null;
+        run_id?: string | null;
+        thread_id?: string | null;
+        tool_call_id?: string | null;
+        tool_id?: string | null;
+        tool_bundle_id?: string | null;
     });
     /**
      * Sanitize sensitive data before sending.
@@ -392,7 +423,7 @@ interface AlterVaultOptions {
     apiKey: string;
     /** HTTP request timeout in milliseconds (default: 30000) */
     timeout?: number;
-    /** Actor type (use ActorType enum: AI_AGENT, MCP_SERVER, BACKEND_SERVICE) */
+    /** Actor type (use ActorType enum: AI_AGENT, BACKEND_SERVICE) */
     actorType: ActorType | string;
     /** Unique identifier for the actor (e.g., "email-assistant-v2") */
     actorIdentifier: string;
@@ -400,10 +431,12 @@ interface AlterVaultOptions {
     actorName?: string;
     /** Actor version string (e.g., "1.0.0") */
     actorVersion?: string;
-    /** MCP client type (e.g., "cursor", "claude-desktop") */
+    /** Transport client type (e.g., "cursor", "claude-desktop") */
     clientType?: string;
     /** AI framework (e.g., "langchain", "langgraph", "crewai") */
     framework?: string;
+    /** Tool bundle identifier (e.g., "google-calendar-mcp-server", "stripe-toolkit") */
+    toolBundleId?: string;
     /** JWT identity resolution: callable that returns the current user's JWT */
     userTokenGetter?: () => string | Promise<string>;
 }
@@ -427,18 +460,22 @@ interface RequestOptions {
     threadId?: string;
     /** Tool invocation ID */
     toolCallId?: string;
-    /** Provider ID for identity resolution (e.g., "google"). Alternative to connectionId. */
+    /** Specific tool being invoked within the bundle (e.g., "read_calendar") */
+    toolId?: string;
+    /** Tool bundle identifier for per-request override (e.g., "google-calendar-mcp-server") */
+    toolBundleId?: string;
+    /** Provider ID for identity resolution (e.g., "google"). Alternative to grantId. */
     provider?: string;
     /** Account identifier for multi-account disambiguation (only with provider) */
     account?: string;
 }
 /**
- * Options for the listConnections() method.
+ * Options for the listGrants() method.
  */
-interface ListConnectionsOptions {
+interface ListGrantsOptions {
     /** Filter by provider ID (e.g., "google") */
     providerId?: string;
-    /** Maximum number of connections to return (default 100, max 1000) */
+    /** Maximum number of grants to return (default 100, max 1000) */
     limit?: number;
     /** Offset for pagination (default 0) */
     offset?: number;
@@ -455,8 +492,8 @@ 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?: {
+    /** TTL bounds for grant policy. End user picks duration within bounds in Connect UI. */
+    grantPolicy?: {
         /** Maximum TTL the end user can select (seconds) */
         maxTtlSeconds?: number;
         /** Pre-selected TTL in Connect UI (seconds) */
@@ -478,8 +515,8 @@ interface CreateConnectSessionOptions {
         ipAddress?: string;
         userAgent?: string;
     };
-    /** TTL bounds for connection policy. End user picks duration within bounds in Connect UI. */
-    connectionPolicy?: {
+    /** TTL bounds for grant policy. End user picks duration within bounds in Connect UI. */
+    grantPolicy?: {
         /** Maximum TTL the end user can select (seconds) */
         maxTtlSeconds?: number;
         /** Pre-selected TTL in Connect UI (seconds) */
@@ -492,7 +529,7 @@ interface CreateConnectSessionOptions {
  * This class handles:
  * - Executing API requests to any OAuth provider with automatic token injection
  * - Audit logging of API calls
- * - Actor tracking for AI agents and MCP servers
+ * - Actor tracking for AI agents and backend services
  *
  * Tokens are retrieved and injected automatically — never exposed to callers.
  *
@@ -504,7 +541,7 @@ interface CreateConnectSessionOptions {
  *
  * // Make API request (token injected automatically)
  * const response = await vault.request(
- *   "connection-uuid-here", HttpMethod.GET,
+ *   "grant-uuid-here", HttpMethod.GET,
  *   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
  * );
  * const events = await response.json();
@@ -527,14 +564,14 @@ declare class AlterVault {
      * 4. Logs the call for audit (fire-and-forget)
      * 5. Returns the raw response
      */
-    request(connectionId: string | null | undefined, method: HttpMethod | string, url: string, options?: RequestOptions): Promise<Response>;
+    request(grantId: string | null | undefined, method: HttpMethod | string, url: string, options?: RequestOptions): Promise<Response>;
     /**
-     * List OAuth connections for this app.
+     * List OAuth grants for this app.
      *
-     * Returns paginated connection metadata (no tokens).
+     * Returns paginated grant metadata (no tokens).
      * Useful for discovering which services a user has connected.
      */
-    listConnections(options?: ListConnectionsOptions): Promise<ConnectionListResult>;
+    listGrants(options?: ListGrantsOptions): Promise<GrantListResult>;
     /**
      * Create a Connect session for initiating OAuth flows.
      *
@@ -555,6 +592,23 @@ declare class AlterVault {
      * @throws AlterSDKError if SDK is closed or session creation fails
      */
     connect(options: ConnectOptions): Promise<ConnectResult[]>;
+    /**
+     * Trigger IDP login for end user via browser.
+     *
+     * Opens the app's configured IDP login page in the user's default browser.
+     * Polls for completion and returns the user's IDP JWT token.
+     *
+     * After authenticate() completes, the returned userToken is automatically
+     * used for subsequent request() calls that use identity resolution.
+     *
+     * @param options - Optional configuration (timeout in milliseconds, default 300000 = 5 min)
+     * @returns AuthResult with userToken and userInfo
+     * @throws ConnectTimeoutError if authentication times out
+     * @throws AlterSDKError if session creation or authentication fails
+     */
+    authenticate(options?: {
+        timeout?: number;
+    }): Promise<AuthResult>;
     /**
      * Close HTTP clients and release resources.
      * Waits for any pending audit tasks before closing.
@@ -577,10 +631,11 @@ declare class AlterVault {
  * 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
+ * │   │   ├── GrantExpiredError            — TTL elapsed
+ * │   │   ├── GrantRevokedError            — Grant explicitly revoked
+ * │   │   ├── CredentialRevokedError       — Underlying credential auth permanently broken
+ * │   │   └── GrantDeletedError            — User disconnected via Wallet
+ * │   ├── GrantNotFoundError               — Wrong grant_id — fix your code
  * │   └── PolicyViolationError             — Policy denied — may resolve on its own
  * ├── ConnectFlowError                     — Connect flow failed
  * │   ├── ConnectDeniedError               — User clicked Deny
@@ -615,16 +670,26 @@ declare class ReAuthRequiredError extends BackendError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when a connection's TTL has expired.
+ * Raised when a grant'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 {
+declare class GrantExpiredError extends ReAuthRequiredError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when a connection's auth is permanently broken.
+ * Raised when a grant has been explicitly revoked.
+ *
+ * The grant was revoked via the SDK or dashboard.
+ * The user must re-authorize via Alter Connect.
+ */
+declare class GrantRevokedError extends ReAuthRequiredError {
+    readonly grantId: string | undefined;
+    constructor(message: string, grantId?: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when a credential's auth is permanently broken.
  *
  * This happens when:
  * - The user revoked your app at the provider (e.g., Google Account settings)
@@ -633,33 +698,33 @@ declare class ConnectionExpiredError extends ReAuthRequiredError {
  *
  * 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>);
+declare class CredentialRevokedError extends ReAuthRequiredError {
+    readonly grantId: string | undefined;
+    constructor(message: string, grantId?: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when a connection has been deliberately deleted.
+ * Raised when a grant 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`
+ * Re-authorization via Alter Connect will generate a **new** `grant_id`
  * — update your stored reference from the `ConnectResult`.
  */
-declare class ConnectionDeletedError extends ReAuthRequiredError {
+declare class GrantDeletedError extends ReAuthRequiredError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Raised when OAuth connection not found.
+ * Raised when OAuth grant not found.
  *
- * No connection exists for the given connection_id.
+ * No grant exists for the given grant_id.
  * Check for typos or stale references.
  */
-declare class ConnectionNotFoundError extends BackendError {
+declare class GrantNotFoundError 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
+ * The grant 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).
  */
@@ -716,9 +781,9 @@ declare class ProviderAPIError extends AlterSDKError {
     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.
+ * Raised when a provider API returns 403 and the grant has a scope mismatch.
  *
- * This indicates the connection's OAuth scopes don't match the provider config's
+ * This indicates the grant'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.
@@ -726,13 +791,13 @@ declare class ProviderAPIError extends AlterSDKError {
  * Recovery:
  * ```typescript
  * try {
- *   const result = await vault.request(connId, HttpMethod.GET, url);
+ *   const result = await vault.request(grantId, HttpMethod.GET, url);
  * } catch (e) {
  *   if (e instanceof ScopeReauthRequiredError) {
  *     const session = await vault.createConnectSession({
  *       allowedProviders: [e.providerId],
  *     });
- *     notifyUser(e.connectionId, session.connectUrl);
+ *     notifyUser(e.grantId, session.connectUrl);
  *   }
  * }
  * ```
@@ -741,9 +806,9 @@ declare class ProviderAPIError extends AlterSDKError {
  * continue to work without code changes.
  */
 declare class ScopeReauthRequiredError extends ProviderAPIError {
-    readonly connectionId: string | undefined;
+    readonly grantId: string | undefined;
     readonly providerId: string | undefined;
-    constructor(message: string, connectionId?: string, providerId?: string, statusCode?: number, responseBody?: string, details?: Record<string, unknown>);
+    constructor(message: string, grantId?: string, providerId?: string, statusCode?: number, responseBody?: string, details?: Record<string, unknown>);
 }
 /**
  * Raised when network operations fail.
@@ -767,4 +832,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-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 };
+export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, AuthResult, BackendError, ConnectConfigError, ConnectDeniedError, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, type CreateConnectSessionOptions, CredentialRevokedError, GrantDeletedError, GrantExpiredError, GrantInfo, GrantListResult, GrantNotFoundError, type GrantPolicy, GrantRevokedError, HttpMethod, type ListGrantsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, ReAuthRequiredError, type RequestOptions, ScopeReauthRequiredError, TimeoutError, TokenResponse };