@alter-ai/alter-sdk 0.3.1 → 0.5.0

package/README.md

@@ -1,10 +1,10 @@
 # Alter SDK for TypeScript / Node.js
 
-Official TypeScript SDK for [Alter Vault](https://alterai.dev) — Credential management for agents with policy enforcement.
+Official TypeScript SDK for [Alter Vault](https://alterai.dev) -Credential management for agents with policy enforcement.
 
 ## Features
 
-- **Zero Token Exposure**: Tokens are never exposed to developers — injected automatically
+- **Zero Token Exposure**: Tokens are never exposed to developers -injected automatically
 - **Single Entry Point**: One method (`vault.request()`) for all provider APIs
 - **Type-Safe Enums**: `HttpMethod` enums with autocomplete
 - **URL Templating**: Path parameter substitution with automatic URL encoding
@@ -14,7 +14,7 @@ Official TypeScript SDK for [Alter Vault](https://alterai.dev) — Credential ma
 - **API Key and Custom Credential Support**: Handles OAuth tokens, API keys, and custom credential formats automatically
 - **Actor Tracking**: First-class support for AI agent and MCP server observability
 - **HMAC Request Signing**: All SDK-to-backend requests are signed with a derived HMAC-SHA256 key for integrity, authenticity, and replay protection
-- **Native Promises**: Built on native `fetch` — no heavy dependencies
+- **Native Promises**: Built on native `fetch` -no heavy dependencies
 
 ## Installation
 
@@ -33,7 +33,7 @@ const vault = new AlterVault({
   actorIdentifier: "my-agent",
 });
 
-// Make API request — token injected automatically, never exposed
+// Make API request -token injected automatically, never exposed
 const response = await vault.request(
   "CONNECTION_ID",  // from Alter Connect (see below)
   HttpMethod.GET,
@@ -51,16 +51,16 @@ await vault.close();
 
 ### Where does `connectionId` come from?
 
-**OAuth connections:**
-1. User completes OAuth via [Alter Connect](https://docs.alterai.dev/sdks/javascript/quickstart) (frontend widget)
-2. The `onSuccess` callback returns a `connectionId` (UUID)
+**OAuth connections** (per-user, from end user action):
+1. Your **end user** completes OAuth via [Alter Connect](https://docs.alterai.dev/sdks/javascript/quickstart) (frontend widget) or `vault.connect()` (headless)
+2. The `onSuccess` callback returns a `connectionId` (UUID) -one per user per account
 3. You save it in your database, mapped to your user
 4. You pass it to `vault.request()` when making API calls
 
-**Managed secrets** (API keys, service tokens):
-1. Store credentials in the [Developer Portal](https://portal.alterai.dev) under **Managed Secrets**
-2. Copy the `connectionId` returned
-3. Use the same `vault.request()` — credentials are injected automatically
+**Managed secrets** (per-service, from developer action):
+1. **You** store credentials in the [Developer Portal](https://portal.alterai.dev) under **Managed Secrets**
+2. The portal returns a `connectionId` -one per stored credential, shared across your backend
+3. Use the same `vault.request()` -credentials are injected automatically
 
 ```typescript
 // You can also discover connectionIds programmatically:
@@ -184,7 +184,6 @@ 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",
 });
@@ -194,12 +193,50 @@ console.log(`Expires in: ${session.expiresIn}s`);
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `endUser` | `{ id: string }` | *required* | End user identity |
 | `allowedProviders` | `string[]` | - | Restrict to specific providers |
 | `returnUrl` | `string` | - | Redirect URL after OAuth flow |
 
 Returns `ConnectSession` with: `sessionToken`, `connectUrl`, `expiresIn`, `expiresAt`.
 
+#### Headless Connect (from code)
+
+For CLI tools, scripts, and server-side applications -- opens the browser, waits for the user to complete OAuth, and returns the result:
+
+```typescript
+const results = await vault.connect({
+  providers: ["google"],
+  connectionPolicy: {  // optional TTL bounds
+    maxTtlSeconds: 86400,
+    defaultTtlSeconds: 3600,
+  },
+  timeout: 300,        // max wait in seconds (default: 5 min)
+  openBrowser: true,   // set false to print URL instead
+});
+for (const result of results) {
+  console.log(`Connected: ${result.connectionId} (${result.providerId})`);
+  console.log(`Account: ${result.accountIdentifier}`);
+}
+
+// Now use the connectionId with vault.request()
+const response = await vault.request(
+  results[0].connectionId,
+  HttpMethod.GET,
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+);
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `providers` | `string[]` | - | Restrict to specific providers |
+| `timeout` | `number` | `300` | Max seconds to wait for completion |
+| `pollInterval` | `number` | `2` | Seconds between status checks |
+| `connectionPolicy` | `{ maxTtlSeconds?: number; defaultTtlSeconds?: number }` | - | TTL bounds (optional) |
+| `openBrowser` | `boolean` | `true` | Open browser automatically |
+
+Returns `ConnectResult[]` -one per connected provider. Each has: `connectionId`, `providerId`, `accountIdentifier`, `scopes`, and optionally `connectionPolicy` (if a TTL was set).
+
+Throws `ConnectTimeoutError` if the user doesn't complete in time, `ConnectDeniedError` if the user denies authorization, `ConnectConfigError` if the OAuth app is misconfigured.
+
 ### AI Agent Actor Tracking
 
 ```typescript
@@ -284,20 +321,49 @@ const vault = new AlterVault({
 
 ## Error Handling
 
+The SDK provides a typed exception hierarchy so you can handle each failure mode precisely:
+
+```
+AlterSDKError (base)
+├── BackendError                     // Generic backend error
+│   ├── ReAuthRequiredError          // User must re-authorize via Alter Connect
+│   │   ├── ConnectionExpiredError   // 403 — connection TTL elapsed
+│   │   ├── ConnectionRevokedError   // 400 — auth permanently broken (revoked, invalid_grant)
+│   │   └── ConnectionDeletedError   // 410 — user disconnected via Wallet (new ID on re-auth)
+│   ├── ConnectionNotFoundError      // 404 — wrong connection_id
+│   └── PolicyViolationError         // 403 — policy denied (business hours, IP, etc.)
+├── ConnectFlowError                 // Headless connect() failed
+│   ├── ConnectDeniedError           // User clicked Deny
+│   ├── ConnectConfigError           // OAuth app misconfigured
+│   └── ConnectTimeoutError          // User didn't complete in time
+├── ProviderAPIError                 // Provider returned 4xx/5xx
+│   └── ScopeReauthRequiredError    // 403 + scope mismatch — user must re-authorize
+└── NetworkError                     // Backend or provider unreachable
+    └── TimeoutError                 // Request timed out (safe to retry)
+```
+
 > **Note:** Input validation errors (invalid `apiKey`, invalid/missing `actorType`, missing `actorIdentifier`, invalid URL scheme, missing `pathParams`) throw `AlterSDKError`.
 
 ```typescript
 import {
   AlterVault,
   HttpMethod,
-  AlterSDKError,              // Base error (including validation: apiKey, actorType, actorIdentifier, URL scheme, pathParams)
-  PolicyViolationError,
-  ConnectionNotFoundError,
-  TokenExpiredError,
-  TokenRetrievalError,
-  NetworkError,
-  TimeoutError,
-  ProviderAPIError,
+  AlterSDKError,              // Base error (including validation errors)
+  BackendError,               // Generic backend error
+  ReAuthRequiredError,        // Parent for all re-auth errors
+  ConnectionDeletedError,     // User disconnected via Wallet — new ID on re-auth (410)
+  ConnectionExpiredError,     // TTL expired — user must re-authorize (403)
+  ConnectionNotFoundError,    // Wrong connection_id — check for typos (404)
+  ConnectionRevokedError,     // Auth permanently broken — revoked/invalid_grant (400)
+  PolicyViolationError,       // Policy denied — business hours, IP, etc. (403)
+  ConnectFlowError,           // Headless connect() failed (denied, provider error)
+  ConnectDeniedError,         // User denied authorization
+  ConnectConfigError,         // OAuth app misconfigured
+  ConnectTimeoutError,        // Headless connect() timed out
+  NetworkError,               // Backend or provider unreachable
+  TimeoutError,               // Request timed out (subclass of NetworkError)
+  ProviderAPIError,           // Provider API returned error (4xx/5xx)
+  ScopeReauthRequiredError,   // 403 + scope mismatch (subclass of ProviderAPIError)
 } from "@alter-ai/alter-sdk";
 
 try {
@@ -307,22 +373,54 @@ try {
     "https://www.googleapis.com/calendar/v3/calendars/primary/events",
   );
 } catch (error) {
-  if (error instanceof PolicyViolationError) {
-    console.error(`Policy denied: ${error.message}`);
+  // --- Connection unusable — user must re-authorize via Alter Connect ---
+  if (error instanceof ConnectionExpiredError) {
+    // TTL set during Connect flow has elapsed
+    console.error("Connection expired — prompt user to re-authorize");
+  } else if (error instanceof ConnectionRevokedError) {
+    // Auth permanently broken — user revoked at provider, refresh token
+    // expired, or token refresh permanently failed (invalid_grant)
+    console.error("Connection revoked — prompt user to re-authorize");
+  } else if (error instanceof ConnectionDeletedError) {
+    // User disconnected via Wallet — re-auth generates a NEW connectionId
+    console.error("Connection deleted — prompt user to re-connect, store the new ID");
   } else if (error instanceof ConnectionNotFoundError) {
-    console.error("No OAuth connection — user needs to authenticate");
-  } else if (error instanceof TokenExpiredError) {
-    console.error(`Token expired for connection: ${error.connectionId}`);
-  } else if (error instanceof TimeoutError) {
-    console.error(`Request timed out — safe to retry: ${error.message}`);
+    // No connection with this ID exists — check for typos or stale references
+    console.error("Connection not found — verify your connectionId");
+
+  // --- Policy restrictions — may resolve on its own ---
+  } else if (error instanceof PolicyViolationError) {
+    // Business hours, IP allowlist, or other Cerbos policy denial
+    console.error(`Policy denied: ${error.message} (reason: ${error.policyError})`);
+
+  // --- Transient / infrastructure errors — safe to retry ---
   } else if (error instanceof NetworkError) {
-    console.error(`Network issue: ${error.message}`);
+    // TimeoutError is a subclass, so this catches both
+    console.error(`Network issue — retry with backoff: ${error.message}`);
+
+  // --- Provider errors ---
+  } else if (error instanceof ScopeReauthRequiredError) {
+    console.error(`Scope mismatch on ${error.connectionId} - user needs to re-authorize`);
+    // Create a new Connect session so the user can grant updated scopes
   } else if (error instanceof ProviderAPIError) {
     console.error(`Provider error ${error.statusCode}: ${error.responseBody}`);
   }
 }
 ```
 
+### Re-authorization and Connection IDs
+
+When a user re-authorizes through Alter Connect, the **same `connectionId` is preserved** in most cases. The existing connection record is updated in place with fresh tokens. You do **not** need to update your stored `connectionId`.
+
+The exception is `ConnectionDeletedError` — the user disconnected via the Wallet, so re-authorization creates a new connection with a **new `connectionId`**. Store the new ID from the `ConnectResult`.
+
+| Exception | Same `connectionId` after re-auth? |
+|---|---|
+| `ConnectionExpiredError` | Yes |
+| `ConnectionRevokedError` | Yes |
+| `ConnectionDeletedError` | **No** — new ID generated |
+| `ConnectionNotFoundError` | N/A — ID never existed |
+
 ## Resource Management
 
 ```typescript
@@ -338,19 +436,51 @@ try {
   await vault.close(); // Waits for pending audit logs, cleans up timers
 }
 
-// close() is idempotent — safe to call multiple times
+// close() is idempotent -safe to call multiple times
 // Calling request() after close() throws AlterSDKError
 ```
 
 ## Supported Providers
 
-The SDK works with any OAuth provider configured in your Alter Vault dashboard. The first parameter to `vault.request()` is the `connection_id` (UUID) returned when a user connects via Alter Connect.
+The SDK includes type-safe `Provider` enums for all 66 supported providers. Use them for filtering connections or as documentation -- `request()` takes a `connectionId` string, not a provider enum.
 
 ```typescript
-// Use the connection_id from Alter Connect
-await vault.request("550e8400-e29b-41d4-a716-446655440000", HttpMethod.GET, url);
+import { Provider } from "@alter-ai/alter-sdk";
+
+// Custom providers (full OAuth implementations)
+Provider.GOOGLE       // "google"
+Provider.GITHUB       // "github"
+Provider.SLACK        // "slack"
+Provider.SENTRY       // "sentry"
+
+// Config-driven providers (63 total) -- examples:
+Provider.HUBSPOT      // "hubspot"
+Provider.SALESFORCE   // "salesforce"
+Provider.STRIPE       // "stripe"
+Provider.MICROSOFT    // "microsoft"
+Provider.DISCORD      // "discord"
+Provider.SPOTIFY      // "spotify"
+Provider.LINKEDIN     // "linkedin"
+Provider.DROPBOX      // "dropbox"
+Provider.FIGMA        // "figma"
+Provider.CALENDLY     // "calendly"
+Provider.CLICKUP      // "clickup"
+// ... and 52 more (see Provider enum for full list)
+
+// Usage: filter connections by provider
+const result = await vault.listConnections({ providerId: Provider.HUBSPOT });
+
+// Usage: make requests with connectionId
+await vault.request(connectionId, HttpMethod.GET, url);
 ```
 
+<details>
+<summary>All 66 providers</summary>
+
+Acuity Scheduling, Adobe, Aircall, Airtable, Apollo, Asana, Atlassian, Attio, Autodesk, Basecamp, Bitbucket, Bitly, Box, Brex, Cal.com, Calendly, Canva, ClickUp, Close, Constant Contact, Contentful, Deel, Dialpad, DigitalOcean, Discord, DocuSign, Dropbox, eBay, Eventbrite, Facebook, Figma, GitHub, Google, HubSpot, Instagram, Linear, LinkedIn, Mailchimp, Mercury, Microsoft, Miro, Monday, Notion, Outreach, PagerDuty, PayPal, Pinterest, Pipedrive, QuickBooks, Ramp, Reddit, RingCentral, Salesforce, Sentry, Slack, Snapchat, Spotify, Square, Squarespace, Stripe, TikTok, Todoist, Twitter, Typeform, Webex, Webflow
+
+</details>
+
 ## Requirements
 
 - Node.js 18+ (uses native `fetch`)