@alter-ai/alter-sdk 0.2.0 → 0.2.2

package/dist/index.d.cts

@@ -1,3 +1,197 @@
+/**
+ * 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.
+     *
+     * @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 attributes: Record<string, unknown>;
+    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;
+        attributes?: Record<string, unknown>;
+        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.
  *
@@ -60,17 +254,9 @@ declare enum HttpMethod {
 /**
  * Main Alter Vault SDK client.
  *
- * This module provides the primary AlterVault class for interacting with
- * the Alter Vault OAuth token management system.
- *
- * Security Hardening (v0.4.0):
- * - Layer 1: Prototype frozen to prevent subclass method override attacks
- * - Layer 1b: HttpClient.prototype also frozen to prevent request interception
- * - Layer 2: Instance frozen after construction (Object.freeze)
- * - Layer 3: API key not stored as instance property
- * - Layer 4: ES2022 private fields (#) for truly private internal state
- * - Layer 5: (see models.ts) TokenResponse access_token in module-private WeakMap
- * - Layer 6: Test accessors removed from production builds
+ * Provides the AlterVault class for OAuth token management with
+ * zero token exposure — tokens are retrieved and injected automatically,
+ * never returned to the caller.
  */
 
 /**
@@ -81,8 +267,6 @@ interface AlterVaultOptions {
     apiKey: string;
     /** Base URL for Alter Vault API */
     baseUrl?: string;
-    /** Whether to send audit logs to backend (default: true) */
-    enableAuditLogging?: boolean;
     /** HTTP request timeout in milliseconds (default: 30000) */
     timeout?: number;
     /** Actor type ("ai_agent" or "mcp_server") for tracking */
@@ -121,6 +305,41 @@ 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;
+    };
+    /** User attributes for connection matching */
+    attributes?: Record<string, unknown>;
+    /** 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,17 +348,7 @@ interface RequestOptions {
  * - Audit logging of API calls
  * - Actor tracking for AI agents and MCP servers
  *
- * Zero Token Exposure:
- * - Tokens are retrieved internally but NEVER exposed to developers
- * - All API calls inject tokens automatically behind the scenes
- * - Developers only see API results, never authentication credentials
- *
- * Security Hardening:
- * - Cannot be effectively subclassed (prototype is frozen)
- * - Instance is frozen after construction (Object.freeze)
- * - API key is NOT stored as an instance property
- * - Internal HTTP clients use ES2022 private fields (#)
- * - Test accessors are removed (no production leak path)
+ * Tokens are retrieved and injected automatically — never exposed to callers.
  *
  * @example
  * ```typescript
@@ -162,7 +371,6 @@ interface RequestOptions {
 declare class AlterVault {
     #private;
     readonly baseUrl: string;
-    readonly enableAuditLogging: boolean;
     constructor(options: AlterVaultOptions);
     /**
      * Execute an HTTP request to a provider API with automatic token injection.
@@ -171,143 +379,33 @@ declare class AlterVault {
      * 1. Fetches an OAuth token from Alter backend (never exposed)
      * 2. Injects the token as a Bearer header
      * 3. Calls the provider API
-     * 4. Logs the call for audit (if enabled, fire-and-forget)
+     * 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>;
     /**
-     * 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>;
 }
 
 /**
@@ -389,4 +487,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, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectSession, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };