@alter-ai/alter-sdk 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -1,3 +1,212 @@
+/**
+ * Models for Alter SDK.
+ *
+ * These models provide type-safe data structures for SDK operations.
+ *
+ * Security Hardening (v0.4.0):
+ * - TokenResponse: accessToken stored in module-private WeakMap in client.ts
+ *   (not readable as property, not importable from this module)
+ * - TokenResponse: Object.freeze(this) prevents mutation after creation
+ * - toJSON() and toString() exclude access token from serialization
+ */
+/**
+ * Actor types for tracking SDK callers.
+ */
+declare enum ActorType {
+    BACKEND_SERVICE = "backend_service",
+    AI_AGENT = "ai_agent",
+    MCP_SERVER = "mcp_server"
+}
+/**
+ * OAuth token response from Alter Vault.
+ *
+ * This represents an access token retrieved from the backend.
+ * The access_token is NOT stored as a readable property — it lives in a
+ * module-private WeakMap in client.ts and is only accessible internally.
+ *
+ * SECURITY:
+ * - No accessToken property (stored in WeakMap inside client.ts)
+ * - Instance is frozen after construction to prevent mutation
+ * - toJSON() and toString() exclude access token
+ * - _extractAccessToken() lives in client.ts, NOT in this file,
+ *   so it cannot be imported by consumers even via deep imports
+ */
+declare class TokenResponse {
+    /** Token type (usually "Bearer") */
+    readonly tokenType: string;
+    /** Seconds until token expires */
+    readonly expiresIn: number | null;
+    /** Absolute expiration time */
+    readonly expiresAt: Date | null;
+    /** OAuth scopes granted */
+    readonly scopes: string[];
+    /** Connection ID that provided this token */
+    readonly connectionId: string;
+    /** Provider ID (google, github, etc.) */
+    readonly providerId: string;
+    /** 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}") */
+    readonly injectionFormat: string;
+    constructor(data: {
+        access_token: string;
+        token_type?: string;
+        expires_in?: number | null;
+        expires_at?: string | null;
+        scopes?: string[];
+        connection_id: string;
+        provider_id?: string;
+        injection_header?: string;
+        injection_format?: string;
+    });
+    /**
+     * Parse expires_at from ISO string.
+     */
+    private static parseExpiresAt;
+    /**
+     * Check if token is expired.
+     *
+     * @param bufferSeconds - Consider token expired N seconds before actual expiry.
+     *                        Useful for preventing race conditions.
+     * @returns True if token is expired or will expire within bufferSeconds.
+     */
+    isExpired(bufferSeconds?: number): boolean;
+    /**
+     * Check if token should be refreshed soon.
+     *
+     * @param bufferSeconds - Consider token needing refresh N seconds before expiry.
+     *                        Default 5 minutes (300 seconds).
+     * @returns True if token will expire within bufferSeconds.
+     */
+    needsRefresh(bufferSeconds?: number): boolean;
+    /**
+     * Custom JSON serialization — EXCLUDES access_token for security.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Custom string representation — EXCLUDES access_token for security.
+     */
+    toString(): string;
+}
+/**
+ * OAuth connection info from Alter Vault.
+ *
+ * Represents a connected OAuth service (e.g., Google, GitHub).
+ * Returned by listConnections(). Contains metadata only — no tokens.
+ */
+declare class ConnectionInfo {
+    readonly id: string;
+    readonly providerId: string;
+    readonly scopes: string[];
+    readonly accountIdentifier: string | null;
+    readonly accountDisplayName: string | null;
+    readonly status: string;
+    readonly expiresAt: string | null;
+    readonly createdAt: string;
+    readonly lastUsedAt: string | null;
+    constructor(data: {
+        id: string;
+        provider_id: string;
+        scopes?: string[];
+        account_identifier?: string | null;
+        account_display_name?: string | null;
+        status: string;
+        expires_at?: string | null;
+        created_at: string;
+        last_used_at?: string | null;
+    });
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
+/**
+ * Connect session for initiating OAuth flows.
+ *
+ * Returned by createConnectSession(). Contains a URL the user
+ * opens in their browser to authorize access.
+ */
+declare class ConnectSession {
+    readonly sessionToken: string;
+    readonly connectUrl: string;
+    readonly expiresIn: number;
+    readonly expiresAt: string;
+    constructor(data: {
+        session_token: string;
+        connect_url: string;
+        expires_in: number;
+        expires_at: string;
+    });
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
+/**
+ * Paginated list of connections.
+ *
+ * Returned by listConnections(). Contains connection array plus pagination metadata.
+ */
+declare class ConnectionListResult {
+    readonly connections: ConnectionInfo[];
+    readonly total: number;
+    readonly limit: number;
+    readonly offset: number;
+    readonly hasMore: boolean;
+    constructor(data: {
+        connections: ConnectionInfo[];
+        total: number;
+        limit: number;
+        offset: number;
+        has_more: boolean;
+    });
+}
+/**
+ * Audit log entry for an API call to a provider.
+ *
+ * This is sent to the backend audit endpoint.
+ */
+declare class APICallAuditLog {
+    readonly connectionId: string;
+    readonly providerId: string;
+    readonly method: string;
+    readonly url: string;
+    readonly requestHeaders: Record<string, string> | null;
+    readonly requestBody: unknown | null;
+    readonly responseStatus: number;
+    readonly responseHeaders: Record<string, string> | null;
+    readonly responseBody: unknown | null;
+    readonly latencyMs: number;
+    /** Client-side timestamp (excluded from sanitize() output, like Python SDK) */
+    readonly timestamp: Date;
+    readonly reason: string | null;
+    /** Execution run ID for actor tracking */
+    readonly runId: string | null;
+    /** Conversation thread ID for actor tracking */
+    readonly threadId: string | null;
+    /** Tool invocation ID for actor tracking */
+    readonly toolCallId: string | null;
+    constructor(data: {
+        connectionId: string;
+        providerId: 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;
+        reason?: string | null;
+        runId?: string | null;
+        threadId?: string | null;
+        toolCallId?: string | null;
+    });
+    /**
+     * Sanitize sensitive data before sending.
+     *
+     * Removes Authorization headers, cookies, etc.
+     */
+    sanitize(): Record<string, unknown>;
+    private filterSensitiveHeaders;
+}
+
 /**
  * Provider and HttpMethod enums for type-safe SDK usage.
  *
@@ -37,8 +246,6 @@ declare enum Provider {
     GOOGLE = "google",
     GITHUB = "github",
     SLACK = "slack",
-    MICROSOFT = "microsoft",
-    SALESFORCE = "salesforce",
     SENTRY = "sentry"
 }
 /**
@@ -71,14 +278,12 @@ declare enum HttpMethod {
 interface AlterVaultOptions {
     /** Alter Vault API key (must start with "alter_key_") */
     apiKey: string;
-    /** Base URL for Alter Vault API */
-    baseUrl?: string;
     /** HTTP request timeout in milliseconds (default: 30000) */
     timeout?: number;
-    /** Actor type ("ai_agent" or "mcp_server") for tracking */
-    actorType?: string;
+    /** Actor type (use ActorType enum: AI_AGENT, MCP_SERVER, BACKEND_SERVICE) */
+    actorType: ActorType | string;
     /** Unique identifier for the actor (e.g., "email-assistant-v2") */
-    actorIdentifier?: string;
+    actorIdentifier: string;
     /** Human-readable name for the actor */
     actorName?: string;
     /** Actor version string (e.g., "1.0.0") */
@@ -92,8 +297,6 @@ interface AlterVaultOptions {
  * Options for the request() method.
  */
 interface RequestOptions {
-    /** User attributes to match connection (e.g., { user_id: "alice" }) */
-    user: Record<string, unknown>;
     /** Optional JSON request body */
     json?: Record<string, unknown>;
     /** Optional additional headers */
@@ -111,6 +314,39 @@ interface RequestOptions {
     /** Tool invocation ID */
     toolCallId?: string;
 }
+/**
+ * Options for the listConnections() method.
+ */
+interface ListConnectionsOptions {
+    /** Filter by provider ID (e.g., "google") */
+    providerId?: string;
+    /** Maximum number of connections to return (default 100, max 1000) */
+    limit?: number;
+    /** Offset for pagination (default 0) */
+    offset?: 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 */
+    returnUrl?: string;
+    /** Allowed origin for postMessage communication */
+    allowedOrigin?: string;
+    /** Request metadata for audit */
+    metadata?: {
+        ipAddress?: string;
+        userAgent?: string;
+    };
+}
 /**
  * Main SDK class for Alter Vault OAuth token management.
  *
@@ -129,9 +365,8 @@ interface RequestOptions {
  *
  * // Make API request (token injected automatically)
  * const response = await vault.request(
- *   Provider.GOOGLE, HttpMethod.GET,
+ *   "connection-uuid-here", HttpMethod.GET,
  *   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
- *   { user: { user_id: "alice" } },
  * );
  * const events = await response.json();
  *
@@ -153,140 +388,30 @@ declare class AlterVault {
      * 4. Logs the call for audit (fire-and-forget)
      * 5. Returns the raw response
      */
-    request(provider: Provider | string, method: HttpMethod | string, url: string, options: RequestOptions): Promise<Response>;
+    request(connectionId: string, method: HttpMethod | string, url: string, options?: RequestOptions): Promise<Response>;
     /**
-     * Close HTTP clients and release resources.
-     * Waits for any pending audit tasks before closing.
-     */
-    close(): Promise<void>;
-    /**
-     * Async dispose support for `await using vault = new AlterVault(...)`.
-     * Requires TypeScript 5.2+ and Node.js 18+.
-     */
-    [Symbol.asyncDispose](): Promise<void>;
-}
-
-/**
- * Models for Alter SDK.
- *
- * These models provide type-safe data structures for SDK operations.
- *
- * Security Hardening (v0.4.0):
- * - TokenResponse: accessToken stored in module-private WeakMap in client.ts
- *   (not readable as property, not importable from this module)
- * - TokenResponse: Object.freeze(this) prevents mutation after creation
- * - toJSON() and toString() exclude access token from serialization
- */
-/**
- * OAuth token response from Alter Vault.
- *
- * This represents an access token retrieved from the backend.
- * The access_token is NOT stored as a readable property — it lives in a
- * module-private WeakMap in client.ts and is only accessible internally.
- *
- * SECURITY:
- * - No accessToken property (stored in WeakMap inside client.ts)
- * - Instance is frozen after construction to prevent mutation
- * - toJSON() and toString() exclude access token
- * - _extractAccessToken() lives in client.ts, NOT in this file,
- *   so it cannot be imported by consumers even via deep imports
- */
-declare class TokenResponse {
-    /** Token type (usually "Bearer") */
-    readonly tokenType: string;
-    /** Seconds until token expires */
-    readonly expiresIn: number | null;
-    /** Absolute expiration time */
-    readonly expiresAt: Date | null;
-    /** OAuth scopes granted */
-    readonly scopes: string[];
-    /** Connection ID that provided this token */
-    readonly connectionId: string;
-    constructor(data: {
-        access_token: string;
-        token_type?: string;
-        expires_in?: number | null;
-        expires_at?: string | null;
-        scopes?: string[];
-        connection_id: string;
-    });
-    /**
-     * Parse expires_at from ISO string.
-     */
-    private static parseExpiresAt;
-    /**
-     * Check if token is expired.
+     * List OAuth connections for this app.
      *
-     * @param bufferSeconds - Consider token expired N seconds before actual expiry.
-     *                        Useful for preventing race conditions.
-     * @returns True if token is expired or will expire within bufferSeconds.
+     * Returns paginated connection metadata (no tokens).
+     * Useful for discovering which services a user has connected.
      */
-    isExpired(bufferSeconds?: number): boolean;
+    listConnections(options?: ListConnectionsOptions): Promise<ConnectionListResult>;
     /**
-     * Check if token should be refreshed soon.
+     * Create a Connect session for initiating OAuth flows.
      *
-     * @param bufferSeconds - Consider token needing refresh N seconds before expiry.
-     *                        Default 5 minutes (300 seconds).
-     * @returns True if token will expire within bufferSeconds.
+     * Returns a URL the user can open in their browser to authorize access.
      */
-    needsRefresh(bufferSeconds?: number): boolean;
+    createConnectSession(options: CreateConnectSessionOptions): Promise<ConnectSession>;
     /**
-     * Custom JSON serialization — EXCLUDES access_token for security.
-     */
-    toJSON(): Record<string, unknown>;
-    /**
-     * Custom string representation — EXCLUDES access_token for security.
+     * Close HTTP clients and release resources.
+     * Waits for any pending audit tasks before closing.
      */
-    toString(): string;
-}
-/**
- * Audit log entry for an API call to a provider.
- *
- * This is sent to the backend audit endpoint.
- */
-declare class APICallAuditLog {
-    readonly connectionId: string;
-    readonly providerId: string;
-    readonly method: string;
-    readonly url: string;
-    readonly requestHeaders: Record<string, string> | null;
-    readonly requestBody: unknown | null;
-    readonly responseStatus: number;
-    readonly responseHeaders: Record<string, string> | null;
-    readonly responseBody: unknown | null;
-    readonly latencyMs: number;
-    /** Client-side timestamp (excluded from sanitize() output, like Python SDK) */
-    readonly timestamp: Date;
-    readonly reason: string | null;
-    /** Execution run ID for actor tracking */
-    readonly runId: string | null;
-    /** Conversation thread ID for actor tracking */
-    readonly threadId: string | null;
-    /** Tool invocation ID for actor tracking */
-    readonly toolCallId: string | null;
-    constructor(data: {
-        connectionId: string;
-        providerId: 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;
-        reason?: string | null;
-        runId?: string | null;
-        threadId?: string | null;
-        toolCallId?: string | null;
-    });
+    close(): Promise<void>;
     /**
-     * Sanitize sensitive data before sending.
-     *
-     * Removes Authorization headers, cookies, etc.
+     * Async dispose support for `await using vault = new AlterVault(...)`.
+     * Requires TypeScript 5.2+ and Node.js 18+.
      */
-    sanitize(): Record<string, unknown>;
-    private filterSensitiveHeaders;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 
 /**
@@ -321,7 +446,7 @@ declare class PolicyViolationError extends TokenRetrievalError {
 /**
  * Raised when OAuth connection not found.
  *
- * This indicates no connection exists for the given provider and attributes.
+ * This indicates no connection exists for the given connection_id.
  */
 declare class ConnectionNotFoundError extends TokenRetrievalError {
     constructor(message: string, details?: Record<string, unknown>);
@@ -368,4 +493,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectionNotFoundError, HttpMethod, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };
+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 };