@alter-ai/alter-sdk 0.2.1 → 0.2.2

package/README.md

@@ -8,7 +8,7 @@ Official TypeScript SDK for [Alter Vault](https://alterai.dev) — OAuth token m
 - **Single Entry Point**: One method (`vault.request()`) for all provider APIs
 - **Type-Safe Enums**: `Provider` and `HttpMethod` enums with autocomplete
 - **URL Templating**: Path parameter substitution with automatic URL encoding
-- **Automatic Audit Logging**: All API calls logged as fire-and-forget background tasks
+- **Automatic Audit Logging**: All API calls logged with request metadata (HTTP method and URL) for full audit trail
 - **Real-time Policy Enforcement**: Every token request checked against current policies
 - **Automatic Token Refresh**: Tokens refreshed transparently by the backend
 - **Actor Tracking**: First-class support for AI agent and MCP server observability
@@ -103,6 +103,58 @@ const response = await vault.request(
 );
 ```
 
+### Connection Management
+
+#### List Connections
+
+Retrieve OAuth connections for your app, optionally filtered by provider:
+
+```typescript
+const result = await vault.listConnections();
+for (const conn of result.connections) {
+  console.log(`${conn.providerId}: ${conn.accountDisplayName} (${conn.status})`);
+}
+
+// Filter by provider with pagination
+const googleConns = await vault.listConnections({
+  providerId: "google",
+  limit: 10,
+  offset: 0,
+});
+console.log(`Total: ${googleConns.total}, Has more: ${googleConns.hasMore}`);
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `providerId` | `string` | - | Filter by provider (e.g., `"google"`) |
+| `limit` | `number` | `100` | Max connections to return |
+| `offset` | `number` | `0` | Pagination offset |
+
+Returns `ConnectionListResult` with: `connections` (`ConnectionInfo[]`), `total`, `limit`, `offset`, `hasMore`.
+
+#### Create Connect Session
+
+Generate a session URL for end-users to authenticate with OAuth providers:
+
+```typescript
+const session = await vault.createConnectSession({
+  endUser: { id: "alice" },
+  allowedProviders: ["google", "github"],
+  returnUrl: "https://myapp.com/callback",
+});
+console.log(`Connect URL: ${session.connectUrl}`);
+console.log(`Expires in: ${session.expiresIn}s`);
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `endUser` | `{ id: string }` | *required* | End user identity |
+| `attributes` | `Record<string, unknown>` | - | Connection attributes |
+| `allowedProviders` | `string[]` | - | Restrict to specific providers |
+| `returnUrl` | `string` | - | Redirect URL after OAuth flow |
+
+Returns `ConnectSession` with: `sessionToken`, `connectUrl`, `expiresIn`, `expiresAt`.
+
 ### AI Agent Actor Tracking
 
 ```typescript

package/dist/index.cjs

@@ -23,6 +23,9 @@ __export(index_exports, {
   APICallAuditLog: () => APICallAuditLog,
   AlterSDKError: () => AlterSDKError,
   AlterVault: () => AlterVault,
+  ConnectSession: () => ConnectSession,
+  ConnectionInfo: () => ConnectionInfo,
+  ConnectionListResult: () => ConnectionListResult,
   ConnectionNotFoundError: () => ConnectionNotFoundError,
   HttpMethod: () => HttpMethod,
   NetworkError: () => NetworkError,
@@ -182,6 +185,87 @@ var TokenResponse = class _TokenResponse {
     return this.toString();
   }
 };
+var ConnectionInfo = class {
+  id;
+  providerId;
+  attributes;
+  scopes;
+  accountIdentifier;
+  accountDisplayName;
+  status;
+  expiresAt;
+  createdAt;
+  lastUsedAt;
+  constructor(data) {
+    this.id = data.id;
+    this.providerId = data.provider_id;
+    this.attributes = data.attributes ?? {};
+    this.scopes = data.scopes ?? [];
+    this.accountIdentifier = data.account_identifier ?? null;
+    this.accountDisplayName = data.account_display_name ?? null;
+    this.status = data.status;
+    this.expiresAt = data.expires_at ?? null;
+    this.createdAt = data.created_at;
+    this.lastUsedAt = data.last_used_at ?? null;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      id: this.id,
+      provider_id: this.providerId,
+      attributes: this.attributes,
+      scopes: this.scopes,
+      account_identifier: this.accountIdentifier,
+      account_display_name: this.accountDisplayName,
+      status: this.status,
+      expires_at: this.expiresAt,
+      created_at: this.createdAt,
+      last_used_at: this.lastUsedAt
+    };
+  }
+  toString() {
+    return `ConnectionInfo(id=${this.id}, provider=${this.providerId}, status=${this.status})`;
+  }
+};
+var ConnectSession = class {
+  sessionToken;
+  connectUrl;
+  expiresIn;
+  expiresAt;
+  constructor(data) {
+    this.sessionToken = data.session_token;
+    this.connectUrl = data.connect_url;
+    this.expiresIn = data.expires_in;
+    this.expiresAt = data.expires_at;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      session_token: this.sessionToken,
+      connect_url: this.connectUrl,
+      expires_in: this.expiresIn,
+      expires_at: this.expiresAt
+    };
+  }
+  toString() {
+    return `ConnectSession(url=${this.connectUrl}, expires_in=${this.expiresIn})`;
+  }
+};
+var ConnectionListResult = class {
+  connections;
+  total;
+  limit;
+  offset;
+  hasMore;
+  constructor(data) {
+    this.connections = data.connections;
+    this.total = data.total;
+    this.limit = data.limit;
+    this.offset = data.offset;
+    this.hasMore = data.has_more;
+    Object.freeze(this);
+  }
+};
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "authorization",
   "cookie",
@@ -276,7 +360,7 @@ function _extractAccessToken(token) {
   return value;
 }
 var _fetch;
-var SDK_VERSION = "0.2.1";
+var SDK_VERSION = "0.2.2";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var VALID_ACTOR_TYPES = ["ai_agent", "mcp_server"];
 var HTTP_FORBIDDEN = 403;
@@ -627,7 +711,7 @@ var AlterVault = class _AlterVault {
    * This is a private method. Tokens are NEVER exposed to developers.
    * Use request() instead, which handles tokens internally.
    */
-  async #getToken(providerId, attributes, reason, runId, threadId, toolCallId) {
+  async #getToken(providerId, attributes, reason, requestMetadata, runId, threadId, toolCallId) {
     const actorHeaders = this.#getActorRequestHeaders(
       runId,
       threadId,
@@ -639,7 +723,8 @@ var AlterVault = class _AlterVault {
         json: {
           provider_id: providerId,
           attributes,
-          reason: reason ?? null
+          reason: reason ?? null,
+          request: requestMetadata ?? null
         },
         headers: actorHeaders
       });
@@ -816,6 +901,7 @@ var AlterVault = class _AlterVault {
       providerStr,
       options.user,
       options.reason,
+      { method: methodStr, url },
       options.runId,
       options.threadId,
       options.toolCallId
@@ -896,6 +982,112 @@ var AlterVault = class _AlterVault {
     }
     return response;
   }
+  /**
+   * List OAuth connections for this app.
+   *
+   * Returns paginated connection metadata (no tokens).
+   * Useful for discovering which services a user has connected.
+   */
+  async listConnections(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    const actorHeaders = this.#getActorRequestHeaders();
+    let response;
+    try {
+      response = await this.#alterClient.post("/oauth/connections/list", {
+        json: {
+          provider_id: options?.providerId ?? null,
+          limit: options?.limit ?? 100,
+          offset: options?.offset ?? 0
+        },
+        headers: actorHeaders
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Request to Alter Vault backend timed out: ${error instanceof Error ? error.message : String(error)}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Failed to connect to Alter Vault backend: ${error.message}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      throw new AlterSDKError(
+        `Failed to list connections: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    const data = await response.json();
+    const connections = data.connections.map(
+      (c) => new ConnectionInfo(
+        c
+      )
+    );
+    return new ConnectionListResult({
+      connections,
+      total: data.total,
+      limit: data.limit,
+      offset: data.offset,
+      has_more: data.has_more
+    });
+  }
+  /**
+   * Create a Connect session for initiating OAuth flows.
+   *
+   * Returns a URL the user can open in their browser to authorize access.
+   */
+  async createConnectSession(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    if (!options.endUser?.id) {
+      throw new AlterSDKError("endUser.id is required");
+    }
+    const actorHeaders = this.#getActorRequestHeaders();
+    let response;
+    try {
+      response = await this.#alterClient.post("/oauth/connect/session", {
+        json: {
+          end_user: options.endUser,
+          attributes: options.attributes ?? null,
+          allowed_providers: options.allowedProviders ?? null,
+          return_url: options.returnUrl ?? null,
+          allowed_origin: options.allowedOrigin ?? null,
+          metadata: options.metadata ?? null
+        },
+        headers: actorHeaders
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Request to Alter Vault backend timed out: ${error instanceof Error ? error.message : String(error)}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Failed to connect to Alter Vault backend: ${error.message}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      throw new AlterSDKError(
+        `Failed to create connect session: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    const data = await response.json();
+    return new ConnectSession(data);
+  }
   /**
    * Close HTTP clients and release resources.
    * Waits for any pending audit tasks before closing.
@@ -944,6 +1136,9 @@ var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
   APICallAuditLog,
   AlterSDKError,
   AlterVault,
+  ConnectSession,
+  ConnectionInfo,
+  ConnectionListResult,
   ConnectionNotFoundError,
   HttpMethod,
   NetworkError,

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.
  *
@@ -111,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.
  *
@@ -155,138 +384,28 @@ declare class AlterVault {
      */
     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>;
 }
 
 /**
@@ -368,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 };

package/dist/index.d.ts

@@ -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.
  *
@@ -111,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.
  *
@@ -155,138 +384,28 @@ declare class AlterVault {
      */
     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>;
 }
 
 /**
@@ -368,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 };

package/dist/index.js

@@ -144,6 +144,87 @@ var TokenResponse = class _TokenResponse {
     return this.toString();
   }
 };
+var ConnectionInfo = class {
+  id;
+  providerId;
+  attributes;
+  scopes;
+  accountIdentifier;
+  accountDisplayName;
+  status;
+  expiresAt;
+  createdAt;
+  lastUsedAt;
+  constructor(data) {
+    this.id = data.id;
+    this.providerId = data.provider_id;
+    this.attributes = data.attributes ?? {};
+    this.scopes = data.scopes ?? [];
+    this.accountIdentifier = data.account_identifier ?? null;
+    this.accountDisplayName = data.account_display_name ?? null;
+    this.status = data.status;
+    this.expiresAt = data.expires_at ?? null;
+    this.createdAt = data.created_at;
+    this.lastUsedAt = data.last_used_at ?? null;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      id: this.id,
+      provider_id: this.providerId,
+      attributes: this.attributes,
+      scopes: this.scopes,
+      account_identifier: this.accountIdentifier,
+      account_display_name: this.accountDisplayName,
+      status: this.status,
+      expires_at: this.expiresAt,
+      created_at: this.createdAt,
+      last_used_at: this.lastUsedAt
+    };
+  }
+  toString() {
+    return `ConnectionInfo(id=${this.id}, provider=${this.providerId}, status=${this.status})`;
+  }
+};
+var ConnectSession = class {
+  sessionToken;
+  connectUrl;
+  expiresIn;
+  expiresAt;
+  constructor(data) {
+    this.sessionToken = data.session_token;
+    this.connectUrl = data.connect_url;
+    this.expiresIn = data.expires_in;
+    this.expiresAt = data.expires_at;
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      session_token: this.sessionToken,
+      connect_url: this.connectUrl,
+      expires_in: this.expiresIn,
+      expires_at: this.expiresAt
+    };
+  }
+  toString() {
+    return `ConnectSession(url=${this.connectUrl}, expires_in=${this.expiresIn})`;
+  }
+};
+var ConnectionListResult = class {
+  connections;
+  total;
+  limit;
+  offset;
+  hasMore;
+  constructor(data) {
+    this.connections = data.connections;
+    this.total = data.total;
+    this.limit = data.limit;
+    this.offset = data.offset;
+    this.hasMore = data.has_more;
+    Object.freeze(this);
+  }
+};
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "authorization",
   "cookie",
@@ -238,7 +319,7 @@ function _extractAccessToken(token) {
   return value;
 }
 var _fetch;
-var SDK_VERSION = "0.2.1";
+var SDK_VERSION = "0.2.2";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var VALID_ACTOR_TYPES = ["ai_agent", "mcp_server"];
 var HTTP_FORBIDDEN = 403;
@@ -589,7 +670,7 @@ var AlterVault = class _AlterVault {
    * This is a private method. Tokens are NEVER exposed to developers.
    * Use request() instead, which handles tokens internally.
    */
-  async #getToken(providerId, attributes, reason, runId, threadId, toolCallId) {
+  async #getToken(providerId, attributes, reason, requestMetadata, runId, threadId, toolCallId) {
     const actorHeaders = this.#getActorRequestHeaders(
       runId,
       threadId,
@@ -601,7 +682,8 @@ var AlterVault = class _AlterVault {
         json: {
           provider_id: providerId,
           attributes,
-          reason: reason ?? null
+          reason: reason ?? null,
+          request: requestMetadata ?? null
         },
         headers: actorHeaders
       });
@@ -778,6 +860,7 @@ var AlterVault = class _AlterVault {
       providerStr,
       options.user,
       options.reason,
+      { method: methodStr, url },
       options.runId,
       options.threadId,
       options.toolCallId
@@ -858,6 +941,112 @@ var AlterVault = class _AlterVault {
     }
     return response;
   }
+  /**
+   * List OAuth connections for this app.
+   *
+   * Returns paginated connection metadata (no tokens).
+   * Useful for discovering which services a user has connected.
+   */
+  async listConnections(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    const actorHeaders = this.#getActorRequestHeaders();
+    let response;
+    try {
+      response = await this.#alterClient.post("/oauth/connections/list", {
+        json: {
+          provider_id: options?.providerId ?? null,
+          limit: options?.limit ?? 100,
+          offset: options?.offset ?? 0
+        },
+        headers: actorHeaders
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Request to Alter Vault backend timed out: ${error instanceof Error ? error.message : String(error)}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Failed to connect to Alter Vault backend: ${error.message}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      throw new AlterSDKError(
+        `Failed to list connections: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    const data = await response.json();
+    const connections = data.connections.map(
+      (c) => new ConnectionInfo(
+        c
+      )
+    );
+    return new ConnectionListResult({
+      connections,
+      total: data.total,
+      limit: data.limit,
+      offset: data.offset,
+      has_more: data.has_more
+    });
+  }
+  /**
+   * Create a Connect session for initiating OAuth flows.
+   *
+   * Returns a URL the user can open in their browser to authorize access.
+   */
+  async createConnectSession(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    if (!options.endUser?.id) {
+      throw new AlterSDKError("endUser.id is required");
+    }
+    const actorHeaders = this.#getActorRequestHeaders();
+    let response;
+    try {
+      response = await this.#alterClient.post("/oauth/connect/session", {
+        json: {
+          end_user: options.endUser,
+          attributes: options.attributes ?? null,
+          allowed_providers: options.allowedProviders ?? null,
+          return_url: options.returnUrl ?? null,
+          allowed_origin: options.allowedOrigin ?? null,
+          metadata: options.metadata ?? null
+        },
+        headers: actorHeaders
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Request to Alter Vault backend timed out: ${error instanceof Error ? error.message : String(error)}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Failed to connect to Alter Vault backend: ${error.message}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      throw new AlterSDKError(
+        `Failed to create connect session: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    const data = await response.json();
+    return new ConnectSession(data);
+  }
   /**
    * Close HTTP clients and release resources.
    * Waits for any pending audit tasks before closing.
@@ -905,6 +1094,9 @@ export {
   APICallAuditLog,
   AlterSDKError,
   AlterVault,
+  ConnectSession,
+  ConnectionInfo,
+  ConnectionListResult,
   ConnectionNotFoundError,
   HttpMethod,
   NetworkError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/alter-sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Official TypeScript SDK for Alter Vault — OAuth token management with policy enforcement",
   "type": "module",
   "main": "dist/index.cjs",