@alter-ai/alter-sdk 0.2.0 → 0.2.2

package/README.md

@@ -1,7 +1,5 @@
 # Alter SDK for TypeScript / Node.js
 
-> **Version**: 0.4.0
-
 Official TypeScript SDK for [Alter Vault](https://alterai.dev) — OAuth token management with policy enforcement.
 
 ## Features
@@ -10,11 +8,9 @@ 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
-- **Dual HTTP Client Security**: Separate clients prevent credential leakage to providers
-- **Security Hardened (v0.4.0)**: Frozen `HttpClient` prototype, `WeakMap` token storage, unexported module-private token accessors, and hardened `fetch` capture prevent rogue agent token extraction
 - **Actor Tracking**: First-class support for AI agent and MCP server observability
 - **Native Promises**: Built on native `fetch` — no heavy dependencies
 
@@ -95,17 +91,70 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  Provider.GOOGLE,
-  HttpMethod.GET,
-  "https://api.example.com/v1/items",
+  "notion",
+  HttpMethod.POST,
+  "https://api.notion.com/v1/databases/{db_id}/query",
   {
     user: { user_id: "alice" },
-    queryParams: { fields: "name,price", limit: "10" },
+    pathParams: { db_id: "abc123" },
     extraHeaders: { "Notion-Version": "2022-06-28" },
+    json: { page_size: 10 },
   },
 );
 ```
 
+### 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
@@ -126,17 +175,55 @@ const response = await vault.request(
     user: { user_id: "alice" },
     runId: "550e8400-e29b-41d4-a716-446655440000",
     threadId: "thread-xyz",
+    toolCallId: "call_abc_123",
   },
 );
 ```
 
+### Multi-Agent Deployments
+
+Each agent must create its own `AlterVault` instance with a unique actor identity. Do not share a single instance across agents.
+
+```typescript
+// Each agent gets its own vault instance
+const emailAgent = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: "ai_agent",
+  actorIdentifier: "email-assistant-v2",
+  actorName: "Email Assistant",
+});
+
+const calendarAgent = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: "ai_agent",
+  actorIdentifier: "calendar-agent-v1",
+  actorName: "Calendar Agent",
+});
+
+// Audit logs and policies are tracked per agent
+const user = { user_id: "alice" };
+await emailAgent.request(
+  Provider.GOOGLE, HttpMethod.GET,
+  "https://gmail.googleapis.com/gmail/v1/users/me/messages",
+  { user },
+);
+await calendarAgent.request(
+  Provider.GOOGLE, HttpMethod.GET,
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  { user },
+);
+
+// Clean up each instance
+await emailAgent.close();
+await calendarAgent.close();
+```
+
 ## Configuration
 
 ```typescript
 const vault = new AlterVault({
   apiKey: "alter_key_...",              // Required: Alter Vault API key
   baseUrl: "https://api.alter.com",     // Optional: Custom API URL
-  enableAuditLogging: true,             // Optional: Enable audit logs (default: true)
   timeout: 30000,                       // Optional: HTTP timeout in ms (default: 30000)
   // Actor tracking (optional)
   actorType: "ai_agent",               // "ai_agent" or "mcp_server"
@@ -150,14 +237,14 @@ const vault = new AlterVault({
 
 ## Error Handling
 
-> **Note:** Input validation errors (invalid `apiKey`, invalid `actorType`, SSRF URL scheme violations, missing `pathParams`) throw `AlterSDKError`.
+> **Note:** Input validation errors (invalid `apiKey`, invalid `actorType`, invalid URL scheme, missing `pathParams`) throw `AlterSDKError`.
 
 ```typescript
 import {
   AlterVault,
   Provider,
   HttpMethod,
-  AlterSDKError,              // Base error (including validation: apiKey, actorType, SSRF, pathParams)
+  AlterSDKError,              // Base error (including validation: apiKey, actorType, URL scheme, pathParams)
   PolicyViolationError,
   ConnectionNotFoundError,
   TokenExpiredError,
@@ -206,22 +293,20 @@ try {
 // Calling request() after close() throws AlterSDKError
 ```
 
-## Architecture
+## Supported Providers
 
-See [ALTER_TYPESCRIPT_SDK_ARCHITECTURE.md](./ALTER_TYPESCRIPT_SDK_ARCHITECTURE.md) for details on:
-- Dual HTTP client security model
-- Zero token exposure design
-- No SDK-side caching (real-time policy enforcement)
-- SSRF prevention with case-insensitive URL scheme validation
-- Actor tracking and audit logging
+```typescript
+import { Provider } from "@alter-ai/alter-sdk";
 
-## Development
+Provider.GOOGLE       // "google"
+Provider.GITHUB       // "github"
+Provider.SLACK        // "slack"
+Provider.MICROSOFT    // "microsoft"
+Provider.SALESFORCE   // "salesforce"
+Provider.SENTRY       // "sentry"
 
-```bash
-npm install
-npm run test           # Run tests (70 tests)
-npm run typecheck      # Type check
-npm run build          # Build for distribution
+// Strings also work for any provider
+await vault.request("notion", HttpMethod.GET, url, { user });
 ```
 
 ## Requirements

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.0";
+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;
@@ -372,7 +456,6 @@ var AlterVault = class _AlterVault {
   // Public readonly properties (frozen by Object.freeze)
   // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   baseUrl;
-  enableAuditLogging;
   /** Actor tracking configuration (readonly, not secret) */
   #actorType;
   #actorIdentifier;
@@ -400,7 +483,6 @@ var AlterVault = class _AlterVault {
       /\/+$/,
       ""
     );
-    this.enableAuditLogging = options.enableAuditLogging ?? true;
     const timeoutMs = options.timeout ?? 3e4;
     this.#actorType = options.actorType;
     this.#actorIdentifier = options.actorIdentifier;
@@ -629,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,
@@ -641,7 +723,8 @@ var AlterVault = class _AlterVault {
         json: {
           provider_id: providerId,
           attributes,
-          reason: reason ?? null
+          reason: reason ?? null,
+          request: requestMetadata ?? null
         },
         headers: actorHeaders
       });
@@ -678,9 +761,6 @@ var AlterVault = class _AlterVault {
    * if audit logging fails.
    */
   async #logApiCall(params) {
-    if (!this.enableAuditLogging) {
-      return;
-    }
     try {
       const auditLog = new APICallAuditLog({
         connectionId: params.connectionId,
@@ -765,7 +845,7 @@ var AlterVault = 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
    */
   async request(provider, method, url, options) {
@@ -821,6 +901,7 @@ var AlterVault = class _AlterVault {
       providerStr,
       options.user,
       options.reason,
+      { method: methodStr, url },
       options.runId,
       options.threadId,
       options.toolCallId
@@ -901,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.
@@ -949,6 +1136,9 @@ var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
   APICallAuditLog,
   AlterSDKError,
   AlterVault,
+  ConnectSession,
+  ConnectionInfo,
+  ConnectionListResult,
   ConnectionNotFoundError,
   HttpMethod,
   NetworkError,