@alter-ai/alter-sdk 0.2.2 → 0.4.0

package/README.md

@@ -1,17 +1,20 @@
 # 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 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
+- **AWS SigV4 Support**: Automatic AWS Signature Version 4 signing for S3, Bedrock, DynamoDB, and other AWS services (no AWS SDK required)
 - **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 +26,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 +50,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 +89,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 +103,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 +117,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,6 +128,28 @@ 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
@@ -149,18 +196,55 @@ 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`.
 
+#### 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({
+  endUser: { id: "alice" },
+  providers: ["google"],
+  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 |
+|-----------|------|---------|-------------|
+| `endUser` | `{ id: string }` | *required* | End user identity |
+| `providers` | `string[]` | - | Restrict to specific providers |
+| `timeout` | `number` | `300` | Max seconds to wait for completion |
+| `pollInterval` | `number` | `2` | Seconds between status checks |
+| `openBrowser` | `boolean` | `true` | Open browser automatically |
+
+Returns `ConnectResult[]` — one per connected provider. Each has: `connectionId`, `providerId`, `accountIdentifier`, `scopes`.
+
+Throws `ConnectTimeoutError` if the user doesn't complete in time, `ConnectFlowError` if denied.
+
 ### 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",
@@ -168,18 +252,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.
@@ -188,29 +273,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
@@ -221,34 +305,35 @@ 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,
   TokenRetrievalError,
+  ConnectFlowError,           // Headless connect() failed (denied, provider error)
+  ConnectTimeoutError,        // Headless connect() timed out
   NetworkError,
   TimeoutError,
   ProviderAPIError,
@@ -256,10 +341,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) {
@@ -282,7 +366,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 {
@@ -295,18 +383,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