@alter-ai/alter-sdk 0.2.1 → 0.3.1

package/README.md

@@ -1,17 +1,19 @@
 # Alter SDK for TypeScript / Node.js
 
-Official TypeScript SDK for [Alter Vault](https://alterai.dev) — OAuth token management 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
 - **Single Entry Point**: One method (`vault.request()`) for all provider APIs
-- **Type-Safe Enums**: `Provider` and `HttpMethod` enums with autocomplete
+- **Type-Safe Enums**: `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
+- **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
 
 ## Installation
@@ -23,17 +25,20 @@ npm install @alter-ai/alter-sdk
 ## Quick Start
 
 ```typescript
-import { AlterVault, Provider, HttpMethod } from "@alter-ai/alter-sdk";
+import { AlterVault, ActorType, Provider, HttpMethod } from "@alter-ai/alter-sdk";
 
-const vault = new AlterVault({ apiKey: "alter_key_..." });
+const vault = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: ActorType.AI_AGENT,
+  actorIdentifier: "my-agent",
+});
 
 // Make API request — token injected automatically, never exposed
 const response = await vault.request(
-  Provider.GOOGLE,
+  "CONNECTION_ID",  // from Alter Connect (see below)
   HttpMethod.GET,
   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
   {
-    user: { user_id: "alice" },
     queryParams: { maxResults: "10" },
   },
 );
@@ -44,16 +49,38 @@ console.log(events);
 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)
+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
+
+```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}`);
+}
+```
+
 ## 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.
+
 ### Simple GET Request
 
 ```typescript
 const response = await vault.request(
-  Provider.GOOGLE,
+  connectionId,
   HttpMethod.GET,
   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
-  { user: { user_id: "alice" } },
 );
 ```
 
@@ -61,11 +88,10 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  Provider.SALESFORCE,
+  connectionId,
   HttpMethod.POST,
   "https://api.example.com/v1/items",
   {
-    user: { user_id: "alice" },
     json: { name: "New Item", price: 99.99 },
     reason: "Creating new item",
   },
@@ -76,11 +102,10 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  Provider.SALESFORCE,
+  connectionId,
   HttpMethod.PUT,
   "https://api.example.com/v1/items/{item_id}",
   {
-    user: { user_id: "alice" },
     pathParams: { item_id: "123" },
     json: { price: 89.99 },
   },
@@ -91,11 +116,10 @@ const response = await vault.request(
 
 ```typescript
 const response = await vault.request(
-  "notion",
+  connectionId,
   HttpMethod.POST,
   "https://api.notion.com/v1/databases/{db_id}/query",
   {
-    user: { user_id: "alice" },
     pathParams: { db_id: "abc123" },
     extraHeaders: { "Notion-Version": "2022-06-28" },
     json: { page_size: 10 },
@@ -103,12 +127,87 @@ const response = await vault.request(
 );
 ```
 
+### Using Managed Secrets
+
+For your own APIs with API keys or service tokens (no OAuth flow needed):
+
+```typescript
+const vault = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: ActorType.BACKEND_SERVICE,
+  actorIdentifier: "my-service",
+});
+
+const response = await vault.request(
+  "MANAGED_SECRET_CONNECTION_ID",  // from Developer Portal
+  HttpMethod.GET,
+  "https://api.internal.com/v1/data",
+);
+
+await vault.close();
+```
+
+The credential is injected automatically as the configured header type (Bearer, API Key, Basic Auth).
+
+### 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 |
+| `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
+import { AlterVault, ActorType, Provider, HttpMethod } from "@alter-ai/alter-sdk";
+
 const vault = new AlterVault({
   apiKey: "alter_key_...",
-  actorType: "ai_agent",
+  actorType: ActorType.AI_AGENT,
   actorIdentifier: "email-assistant-v2",
   actorName: "Email Assistant",
   actorVersion: "2.0.0",
@@ -116,18 +215,19 @@ const vault = new AlterVault({
 });
 
 const response = await vault.request(
-  Provider.GOOGLE,
+  connectionId,
   HttpMethod.GET,
   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
   {
-    user: { user_id: "alice" },
-    runId: "550e8400-e29b-41d4-a716-446655440000",
+    runId: "550e8400-e29b-41d4-a716-446655440000",  // auto-generated UUID if omitted
     threadId: "thread-xyz",
     toolCallId: "call_abc_123",
   },
 );
 ```
 
+> **Note**: `runId` is auto-generated as a UUID v4 if not provided. All sub-actions within a single `request()` call share the same `runId` for audit log grouping.
+
 ### Multi-Agent Deployments
 
 Each agent must create its own `AlterVault` instance with a unique actor identity. Do not share a single instance across agents.
@@ -136,29 +236,28 @@ Each agent must create its own `AlterVault` instance with a unique actor identit
 // Each agent gets its own vault instance
 const emailAgent = new AlterVault({
   apiKey: "alter_key_...",
-  actorType: "ai_agent",
+  actorType: ActorType.AI_AGENT,
   actorIdentifier: "email-assistant-v2",
   actorName: "Email Assistant",
 });
 
 const calendarAgent = new AlterVault({
   apiKey: "alter_key_...",
-  actorType: "ai_agent",
+  actorType: 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,
+  gmailConnectionId,  // from Alter Connect
+  HttpMethod.GET,
   "https://gmail.googleapis.com/gmail/v1/users/me/messages",
-  { user },
 );
 await calendarAgent.request(
-  Provider.GOOGLE, HttpMethod.GET,
+  calendarConnectionId,  // from Alter Connect
+  HttpMethod.GET,
   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
-  { user },
 );
 
 // Clean up each instance
@@ -169,30 +268,29 @@ await calendarAgent.close();
 ## Configuration
 
 ```typescript
+import { AlterVault, ActorType } from "@alter-ai/alter-sdk";
+
 const vault = new AlterVault({
   apiKey: "alter_key_...",              // Required: Alter Vault API key
-  baseUrl: "https://api.alter.com",     // Optional: Custom API URL
+  actorType: ActorType.AI_AGENT,        // Required: ActorType enum
+  actorIdentifier: "my-agent",          // Required: Unique identifier
   timeout: 30000,                       // Optional: HTTP timeout in ms (default: 30000)
-  // Actor tracking (optional)
-  actorType: "ai_agent",               // "ai_agent" or "mcp_server"
-  actorIdentifier: "my-agent",          // Unique identifier
-  actorName: "My Agent",                // Human-readable name
-  actorVersion: "1.0.0",               // Version string
-  framework: "langgraph",              // AI framework
-  clientType: "cursor",                 // MCP client type
+  actorName: "My Agent",                // Optional: Human-readable name
+  actorVersion: "1.0.0",               // Optional: Version string
+  framework: "langgraph",              // Optional: AI framework
+  clientType: "cursor",                 // Optional: MCP client type
 });
 ```
 
 ## Error Handling
 
-> **Note:** Input validation errors (invalid `apiKey`, invalid `actorType`, invalid URL scheme, missing `pathParams`) throw `AlterSDKError`.
+> **Note:** Input validation errors (invalid `apiKey`, invalid/missing `actorType`, missing `actorIdentifier`, invalid URL scheme, missing `pathParams`) throw `AlterSDKError`.
 
 ```typescript
 import {
   AlterVault,
-  Provider,
   HttpMethod,
-  AlterSDKError,              // Base error (including validation: apiKey, actorType, URL scheme, pathParams)
+  AlterSDKError,              // Base error (including validation: apiKey, actorType, actorIdentifier, URL scheme, pathParams)
   PolicyViolationError,
   ConnectionNotFoundError,
   TokenExpiredError,
@@ -204,10 +302,9 @@ import {
 
 try {
   const response = await vault.request(
-    Provider.GOOGLE,
+    connectionId,
     HttpMethod.GET,
     "https://www.googleapis.com/calendar/v3/calendars/primary/events",
-    { user: { user_id: "alice" } },
   );
 } catch (error) {
   if (error instanceof PolicyViolationError) {
@@ -230,7 +327,11 @@ try {
 
 ```typescript
 // Manual cleanup (recommended)
-const vault = new AlterVault({ apiKey: "alter_key_..." });
+const vault = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: ActorType.BACKEND_SERVICE,
+  actorIdentifier: "my-service",
+});
 try {
   const response = await vault.request(...);
 } finally {
@@ -243,18 +344,11 @@ try {
 
 ## Supported Providers
 
-```typescript
-import { Provider } from "@alter-ai/alter-sdk";
-
-Provider.GOOGLE       // "google"
-Provider.GITHUB       // "github"
-Provider.SLACK        // "slack"
-Provider.MICROSOFT    // "microsoft"
-Provider.SALESFORCE   // "salesforce"
-Provider.SENTRY       // "sentry"
+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.
 
-// Strings also work for any provider
-await vault.request("notion", HttpMethod.GET, url, { user });
+```typescript
+// Use the connection_id from Alter Connect
+await vault.request("550e8400-e29b-41d4-a716-446655440000", HttpMethod.GET, url);
 ```
 
 ## Requirements