@alter-ai/alter-sdk 0.2.0

package/README.md

@@ -0,0 +1,234 @@
+# 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
+
+- **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
+- **URL Templating**: Path parameter substitution with automatic URL encoding
+- **Automatic Audit Logging**: All API calls logged as fire-and-forget background tasks
+- **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
+
+## Installation
+
+```bash
+npm install @alter-ai/alter-sdk
+```
+
+## Quick Start
+
+```typescript
+import { AlterVault, Provider, HttpMethod } from "@alter-ai/alter-sdk";
+
+const vault = new AlterVault({ apiKey: "alter_key_..." });
+
+// Make API request — token injected automatically, never exposed
+const response = await vault.request(
+  Provider.GOOGLE,
+  HttpMethod.GET,
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  {
+    user: { user_id: "alice" },
+    queryParams: { maxResults: "10" },
+  },
+);
+
+const events = await response.json();
+console.log(events);
+
+await vault.close();
+```
+
+## Usage
+
+### Simple GET Request
+
+```typescript
+const response = await vault.request(
+  Provider.GOOGLE,
+  HttpMethod.GET,
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  { user: { user_id: "alice" } },
+);
+```
+
+### POST with JSON Body
+
+```typescript
+const response = await vault.request(
+  Provider.SALESFORCE,
+  HttpMethod.POST,
+  "https://api.example.com/v1/items",
+  {
+    user: { user_id: "alice" },
+    json: { name: "New Item", price: 99.99 },
+    reason: "Creating new item",
+  },
+);
+```
+
+### URL Path Templating
+
+```typescript
+const response = await vault.request(
+  Provider.SALESFORCE,
+  HttpMethod.PUT,
+  "https://api.example.com/v1/items/{item_id}",
+  {
+    user: { user_id: "alice" },
+    pathParams: { item_id: "123" },
+    json: { price: 89.99 },
+  },
+);
+```
+
+### Query Parameters and Extra Headers
+
+```typescript
+const response = await vault.request(
+  Provider.GOOGLE,
+  HttpMethod.GET,
+  "https://api.example.com/v1/items",
+  {
+    user: { user_id: "alice" },
+    queryParams: { fields: "name,price", limit: "10" },
+    extraHeaders: { "Notion-Version": "2022-06-28" },
+  },
+);
+```
+
+### AI Agent Actor Tracking
+
+```typescript
+const vault = new AlterVault({
+  apiKey: "alter_key_...",
+  actorType: "ai_agent",
+  actorIdentifier: "email-assistant-v2",
+  actorName: "Email Assistant",
+  actorVersion: "2.0.0",
+  framework: "langgraph",
+});
+
+const response = await vault.request(
+  Provider.GOOGLE,
+  HttpMethod.GET,
+  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  {
+    user: { user_id: "alice" },
+    runId: "550e8400-e29b-41d4-a716-446655440000",
+    threadId: "thread-xyz",
+  },
+);
+```
+
+## 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"
+  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
+});
+```
+
+## Error Handling
+
+> **Note:** Input validation errors (invalid `apiKey`, invalid `actorType`, SSRF URL scheme violations, missing `pathParams`) throw `AlterSDKError`.
+
+```typescript
+import {
+  AlterVault,
+  Provider,
+  HttpMethod,
+  AlterSDKError,              // Base error (including validation: apiKey, actorType, SSRF, pathParams)
+  PolicyViolationError,
+  ConnectionNotFoundError,
+  TokenExpiredError,
+  TokenRetrievalError,
+  NetworkError,
+  TimeoutError,
+  ProviderAPIError,
+} from "@alter-ai/alter-sdk";
+
+try {
+  const response = await vault.request(
+    Provider.GOOGLE,
+    HttpMethod.GET,
+    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+    { user: { user_id: "alice" } },
+  );
+} catch (error) {
+  if (error instanceof PolicyViolationError) {
+    console.error(`Policy denied: ${error.message}`);
+  } 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}`);
+  } else if (error instanceof NetworkError) {
+    console.error(`Network issue: ${error.message}`);
+  } else if (error instanceof ProviderAPIError) {
+    console.error(`Provider error ${error.statusCode}: ${error.responseBody}`);
+  }
+}
+```
+
+## Resource Management
+
+```typescript
+// Manual cleanup (recommended)
+const vault = new AlterVault({ apiKey: "alter_key_..." });
+try {
+  const response = await vault.request(...);
+} finally {
+  await vault.close(); // Waits for pending audit logs, cleans up timers
+}
+
+// close() is idempotent — safe to call multiple times
+// Calling request() after close() throws AlterSDKError
+```
+
+## Architecture
+
+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
+
+## Development
+
+```bash
+npm install
+npm run test           # Run tests (70 tests)
+npm run typecheck      # Type check
+npm run build          # Build for distribution
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- TypeScript 5.0+
+
+## License
+
+MIT License