@alter-ai/alter-sdk 0.5.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # 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://alterauth.com) -Credential management for agents with policy enforcement.
 
 ## Features
 
@@ -12,8 +12,8 @@ Official TypeScript SDK for [Alter Vault](https://alterai.dev) -Credential manag
 - **Real-time Policy Enforcement**: Every token request checked against current policies
 - **Automatic Token Refresh**: Tokens refreshed transparently by the backend
 - **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
+- **Actor Tracking**: First-class support for AI agent and backend service observability
+- **Signed Requests**: All SDK-to-backend requests are cryptographically signed for integrity, authenticity, and replay protection
 - **Native Promises**: Built on native `fetch` -no heavy dependencies
 
 ## Installation
@@ -35,9 +35,9 @@ const vault = new AlterVault({
 
 // Make API request -token injected automatically, never exposed
 const response = await vault.request(
-  "CONNECTION_ID",  // from Alter Connect (see below)
+  "GRANT_ID",  // from Alter Connect (see below)
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
   {
     queryParams: { maxResults: "10" },
   },
@@ -49,38 +49,38 @@ console.log(events);
 await vault.close();
 ```
 
-### Where does `connectionId` come from?
+### Where does `grantId` come from?
 
-**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
+**OAuth grants** (per-user, from end user action):
+1. Your **end user** completes OAuth via [Alter Connect](https://docs.alterauth.com/sdks/javascript/quickstart) (frontend widget) or `vault.connect()` (headless)
+2. The `onSuccess` callback returns a `grantId` (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** (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
+1. **You** store credentials in the [Developer Portal](https://portal.alterauth.com) under **Managed Secrets**
+2. The portal returns a `grantId` -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:
-const result = await vault.listConnections({ providerId: "google" });
-for (const conn of result.connections) {
-  console.log(`${conn.id}: ${conn.accountDisplayName}`);
+// You can also discover grantIds programmatically:
+const result = await vault.listGrants({ providerId: "google" });
+for (const grant of result.grants) {
+  console.log(`${grant.grantId}: ${grant.accountDisplayName}`);
 }
 ```
 
 ## Usage
 
-The `request()` method returns the raw `Response` object. The token is injected automatically and never exposed. The backend token response includes `connectionId` and `providerId` for audit correlation.
+The `request()` method returns the raw `Response` object. The token is injected automatically and never exposed. The backend token response includes `grantId` and `providerId` for audit correlation.
 
 ### Simple GET Request
 
 ```typescript
 const response = await vault.request(
-  connectionId,
+  grantId,
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
 );
 ```
 
@@ -88,7 +88,7 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  connectionId,
+  grantId,
   HttpMethod.POST,
   "https://api.example.com/v1/items",
   {
@@ -102,7 +102,7 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  connectionId,
+  grantId,
   HttpMethod.PUT,
   "https://api.example.com/v1/items/{item_id}",
   {
@@ -116,7 +116,7 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  connectionId,
+  grantId,
   HttpMethod.POST,
   "https://api.notion.com/v1/databases/{db_id}/query",
   {
@@ -139,7 +139,7 @@ const vault = new AlterVault({
 });
 
 const response = await vault.request(
-  "MANAGED_SECRET_CONNECTION_ID",  // from Developer Portal
+  "MANAGED_SECRET_GRANT_ID",  // from Developer Portal
   HttpMethod.GET,
   "https://api.internal.com/v1/data",
 );
@@ -149,34 +149,49 @@ await vault.close();
 
 The credential is injected automatically as the configured header type (Bearer, API Key, Basic Auth).
 
-### Connection Management
+### Grant Management
 
-#### List Connections
+#### List Grants
 
-Retrieve OAuth connections for your app, optionally filtered by provider:
+Retrieve OAuth grants 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})`);
+const result = await vault.listGrants();
+for (const grant of result.grants) {
+  console.log(`${grant.providerId}: ${grant.accountDisplayName} (${grant.status})`);
 }
 
 // Filter by provider with pagination
-const googleConns = await vault.listConnections({
+const googleGrants = await vault.listGrants({
   providerId: "google",
   limit: 10,
   offset: 0,
 });
-console.log(`Total: ${googleConns.total}, Has more: ${googleConns.hasMore}`);
+console.log(`Total: ${googleGrants.total}, Has more: ${googleGrants.hasMore}`);
 ```
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `providerId` | `string` | - | Filter by provider (e.g., `"google"`) |
-| `limit` | `number` | `100` | Max connections to return |
+| `limit` | `number` | `100` | Max grants to return |
 | `offset` | `number` | `0` | Pagination offset |
 
-Returns `ConnectionListResult` with: `connections` (`ConnectionInfo[]`), `total`, `limit`, `offset`, `hasMore`.
+Returns `GrantListResult` with: `grants` (`GrantInfo[]`), `total`, `limit`, `offset`, `hasMore`.
+
+Each `GrantInfo` has:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `grantId` | `string` | Unique grant identifier (UUID). **Not `.id`** — always use `.grantId` |
+| `providerId` | `string` | Provider slug (e.g., `"google"`, `"slack"`) |
+| `scopes` | `string[]` | Granted OAuth scopes |
+| `accountIdentifier` | `string \| null` | Provider account email or username |
+| `accountDisplayName` | `string \| null` | Human-readable account name |
+| `status` | `string` | Grant status (e.g., `"active"`) |
+| `scopeMismatch` | `boolean` | `true` if granted scopes don't match requested scopes |
+| `expiresAt` | `string \| null` | Expiry timestamp (if a grant policy TTL was set) |
+| `createdAt` | `string` | When the grant was created |
+| `lastUsedAt` | `string \| null` | When the grant was last used for an API call |
 
 #### Create Connect Session
 
@@ -205,7 +220,7 @@ For CLI tools, scripts, and server-side applications -- opens the browser, waits
 ```typescript
 const results = await vault.connect({
   providers: ["google"],
-  connectionPolicy: {  // optional TTL bounds
+  grantPolicy: {  // optional TTL bounds
     maxTtlSeconds: 86400,
     defaultTtlSeconds: 3600,
   },
@@ -213,15 +228,15 @@ const results = await vault.connect({
   openBrowser: true,   // set false to print URL instead
 });
 for (const result of results) {
-  console.log(`Connected: ${result.connectionId} (${result.providerId})`);
+  console.log(`Connected: ${result.grantId} (${result.providerId})`);
   console.log(`Account: ${result.accountIdentifier}`);
 }
 
-// Now use the connectionId with vault.request()
+// Now use the grantId with vault.request()
 const response = await vault.request(
-  results[0].connectionId,
+  results[0].grantId,
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
 );
 ```
 
@@ -230,10 +245,10 @@ const response = await vault.request(
 | `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) |
+| `grantPolicy` | `{ 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).
+Returns `ConnectResult[]` -one per connected provider. Each has: `grantId`, `providerId`, `accountIdentifier`, `scopes`, and optionally `grantPolicy` (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.
 
@@ -252,13 +267,14 @@ const vault = new AlterVault({
 });
 
 const response = await vault.request(
-  connectionId,
+  grantId,
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
   {
     runId: "550e8400-e29b-41d4-a716-446655440000",  // auto-generated UUID if omitted
     threadId: "thread-xyz",
     toolCallId: "call_abc_123",
+    toolId: "read_calendar",                        // specific tool name
   },
 );
 ```
@@ -287,14 +303,14 @@ const calendarAgent = new AlterVault({
 
 // Audit logs and policies are tracked per agent
 await emailAgent.request(
-  gmailConnectionId,  // from Alter Connect
+  gmailGrantId,  // from Alter Connect
   HttpMethod.GET,
-  "https://gmail.googleapis.com/gmail/v1/users/me/messages",
+  "https://api.example.com/v1/messages",
 );
 await calendarAgent.request(
-  calendarConnectionId,  // from Alter Connect
+  calendarGrantId,  // from Alter Connect
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
 );
 
 // Clean up each instance
@@ -319,6 +335,27 @@ const vault = new AlterVault({
 });
 ```
 
+### End-User Authentication
+
+For identity-based grant resolution, authenticate end users via the configured IDP:
+
+```typescript
+// Trigger browser-based IDP login
+const auth = await vault.authenticate({ timeout: 300_000 });
+
+console.log(auth.userInfo); // { sub: "user-123", email: "user@example.com", ... }
+
+// Subsequent requests automatically use identity resolution
+const response = await vault.request(
+  null,  // no grantId — resolved via user identity
+  HttpMethod.GET,
+  "https://api.example.com/endpoint",
+  { provider: "<provider>" },
+);
+```
+
+The `authenticate()` method opens the IDP login page in the user's browser, polls for completion, and returns an `AuthResult` with the user's token and profile info. After authentication, `request()` calls with `provider` automatically resolve to the correct grant for that user.
+
 ## Error Handling
 
 The SDK provides a typed exception hierarchy so you can handle each failure mode precisely:
@@ -327,10 +364,11 @@ The SDK provides a typed exception hierarchy so you can handle each failure mode
 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
+│   │   ├── GrantExpiredError        // 403 — grant TTL elapsed
+│   │   ├── CredentialRevokedError   // 400 — underlying auth permanently broken (revoked, invalid_grant)
+│   │   ├── GrantRevokedError        // 400 — grant revoked
+│   │   └── GrantDeletedError        // 410 — user disconnected via Wallet (new ID on re-auth)
+│   ├── GrantNotFoundError           // 404 — wrong grant_id
 │   └── PolicyViolationError         // 403 — policy denied (business hours, IP, etc.)
 ├── ConnectFlowError                 // Headless connect() failed
 │   ├── ConnectDeniedError           // User clicked Deny
@@ -351,10 +389,11 @@ import {
   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)
+  GrantDeletedError,          // User disconnected via Wallet — new ID on re-auth (410)
+  GrantExpiredError,          // TTL expired — user must re-authorize (403)
+  GrantNotFoundError,         // Wrong grant_id — check for typos (404)
+  CredentialRevokedError,     // Underlying auth permanently broken — revoked/invalid_grant (400)
+  GrantRevokedError,          // Grant revoked (400)
   PolicyViolationError,       // Policy denied — business hours, IP, etc. (403)
   ConnectFlowError,           // Headless connect() failed (denied, provider error)
   ConnectDeniedError,         // User denied authorization
@@ -368,29 +407,32 @@ import {
 
 try {
   const response = await vault.request(
-    connectionId,
+    grantId,
     HttpMethod.GET,
-    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+    "https://api.example.com/v1/resource",
   );
 } catch (error) {
-  // --- Connection unusable — user must re-authorize via Alter Connect ---
-  if (error instanceof ConnectionExpiredError) {
+  // --- Grant unusable — user must re-authorize via Alter Connect ---
+  if (error instanceof GrantExpiredError) {
     // 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
+    console.error("Grant expired — prompt user to re-authorize");
+  } else if (error instanceof CredentialRevokedError) {
+    // Underlying 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) {
-    // No connection with this ID exists — check for typos or stale references
-    console.error("Connection not found — verify your connectionId");
+  } else if (error instanceof GrantRevokedError) {
+    // Grant itself was revoked
+    console.error("Grant revoked — prompt user to re-authorize");
+  } else if (error instanceof GrantDeletedError) {
+    // User disconnected via Wallet — re-auth generates a NEW grantId
+    console.error("Grant deleted — prompt user to re-connect, store the new ID");
+  } else if (error instanceof GrantNotFoundError) {
+    // No grant with this ID exists — check for typos or stale references
+    console.error("Grant not found — verify your grantId");
 
   // --- Policy restrictions — may resolve on its own ---
   } else if (error instanceof PolicyViolationError) {
-    // Business hours, IP allowlist, or other Cerbos policy denial
+    // Business hours, IP allowlist, or other policy denial
     console.error(`Policy denied: ${error.message} (reason: ${error.policyError})`);
 
   // --- Transient / infrastructure errors — safe to retry ---
@@ -400,26 +442,29 @@ try {
 
   // --- Provider errors ---
   } else if (error instanceof ScopeReauthRequiredError) {
-    console.error(`Scope mismatch on ${error.connectionId} - user needs to re-authorize`);
+    console.error(`Scope mismatch on ${error.grantId} - 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}`);
+  } else {
+    throw error;
   }
 }
 ```
 
-### Re-authorization and Connection IDs
+### Re-authorization and Grant 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`.
+When a user re-authorizes through Alter Connect, the **same `grantId` is preserved** in most cases. The existing grant record is updated in place with fresh tokens. You do **not** need to update your stored `grantId`.
 
-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`.
+The exception is `GrantDeletedError` — the user disconnected via the Wallet, so re-authorization creates a new grant with a **new `grantId`**. Store the new ID from the `ConnectResult`.
 
-| Exception | Same `connectionId` after re-auth? |
+| Exception | Same `grantId` after re-auth? |
 |---|---|
-| `ConnectionExpiredError` | Yes |
-| `ConnectionRevokedError` | Yes |
-| `ConnectionDeletedError` | **No** — new ID generated |
-| `ConnectionNotFoundError` | N/A — ID never existed |
+| `GrantExpiredError` | Yes |
+| `CredentialRevokedError` | Yes |
+| `GrantRevokedError` | Yes |
+| `GrantDeletedError` | **No** — new ID generated |
+| `GrantNotFoundError` | N/A — ID never existed |
 
 ## Resource Management
 
@@ -442,7 +487,7 @@ try {
 
 ## Supported Providers
 
-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.
+The SDK includes type-safe `Provider` enums for all 66 supported providers. Use them for filtering grants or as documentation -- `request()` takes a `grantId` string, not a provider enum.
 
 ```typescript
 import { Provider } from "@alter-ai/alter-sdk";
@@ -467,11 +512,11 @@ 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: filter grants by provider
+const result = await vault.listGrants({ providerId: Provider.HUBSPOT });
 
-// Usage: make requests with connectionId
-await vault.request(connectionId, HttpMethod.GET, url);
+// Usage: make requests with grantId
+await vault.request(grantId, HttpMethod.GET, url);
 ```
 
 <details>