@amigo-ai/platform-sdk 0.4.0 → 0.4.2

package/README.md

@@ -23,29 +23,43 @@ const client = new AmigoClient({
 })
 
 // List agents
-const { items: agents } = await client.agents.list()
-
-// Emit a world event
-await client.world.emitEvent({
-  entity_id: 'entity-id',
-  event_type: 'appointment_scheduled',
-  data: { appointment_id: 'appt-001' },
+const { items: agents } = await client.agents.list({ limit: 10 })
+console.log(agents.map((agent) => agent.name))
+
+// Search entities in the world model
+const entityResults = await client.world.listEntities({
+  q: 'Jane Doe',
+  entity_type: ['patient'],
+  limit: 5,
 })
+console.log(entityResults.entities[0]?.display_name)
 
 // Get call analytics for the last 30 days
-const stats = await client.analytics.getCalls({ period: '30d' })
+const stats = await client.analytics.getCalls({ days: 30 })
 console.log(stats.total_calls, stats.avg_duration_seconds)
 ```
 
+## Examples and Docs
+
+- Product docs and API reference: [docs.amigo.ai](https://docs.amigo.ai/)
+- Repo-local SDK examples: [examples/README.md](./examples/README.md)
+- Repo-local API surface guide: [api.md](./api.md)
+
+The docs site remains the primary reference. The examples in this repo stay close to the package surface and are typechecked in CI to reduce drift.
+
 ## Configuration
 
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `apiKey` | `string` | Yes | Your Platform API key — create one at Workspace Settings > API Keys |
-| `workspaceId` | `string` | Yes | Your workspace ID — all resource operations are scoped to this |
-| `baseUrl` | `string` | No | Override the API base URL (default: `https://api.platform.amigo.ai`) |
-| `retry` | `RetryOptions` | No | Retry configuration for transient failures |
-| `fetch` | `typeof fetch` | No | Custom fetch for BFF proxy, cookie forwarding, or test mocking |
+| Option        | Type           | Required | Description                                                          |
+| ------------- | -------------- | -------- | -------------------------------------------------------------------- |
+| `apiKey`      | `string`       | Yes      | Your Platform API key — create one at Workspace Settings > API Keys  |
+| `workspaceId` | `string`       | Yes      | Your workspace ID — all resource operations are scoped to this       |
+| `baseUrl`     | `string`       | No       | Override the API base URL (default: `https://api.platform.amigo.ai`) |
+| `retry`       | `RetryOptions` | No       | Retry configuration for transient failures                           |
+| `maxRetries`  | `number`       | No       | Convenience alias for retry count                                    |
+| `timeout`     | `number`       | No       | Default request timeout in milliseconds                              |
+| `headers`     | `HeadersInit`  | No       | Default headers added to every request                               |
+| `hooks`       | `ClientHooks`  | No       | Request/response lifecycle hooks for tracing or logging              |
+| `fetch`       | `typeof fetch` | No       | Custom fetch for BFF proxy, cookie forwarding, or test mocking       |
 
 ### Retry options
 
@@ -54,8 +68,8 @@ const client = new AmigoClient({
   apiKey: 'your-key',
   workspaceId: 'your-workspace-id',
   retry: {
-    maxAttempts: 3,    // Total attempts including first. Default: 3
-    baseDelayMs: 250,  // Base delay for exponential backoff. Default: 250
+    maxAttempts: 3, // Total attempts including first. Default: 3
+    baseDelayMs: 250, // Base delay for exponential backoff. Default: 250
     maxDelayMs: 30000, // Cap on delay. Default: 30_000
   },
 })
@@ -63,6 +77,17 @@ const client = new AmigoClient({
 
 GET requests are retried on 408, 429, 500, 502, 503, 504. POST requests are only retried on 429 with a `Retry-After` header. Backoff uses full jitter.
 
+### Runtime requirements
+
+The SDK is built around web-standard primitives. Use it in runtimes that provide:
+
+- `fetch`, `Request`, `Response`, `Headers`, `URL`
+- `AbortController`
+- `TextEncoder` / `TextDecoder`
+- `crypto.subtle` for webhook signature verification
+
+CI currently validates Node-based packaging and runtime behavior. Standards-based edge/server runtimes with the same APIs work well with the low-level request wrappers.
+
 ## Generated Types
 
 The SDK ships with generated OpenAPI types and re-exports them for direct use:
@@ -71,8 +96,7 @@ The SDK ships with generated OpenAPI types and re-exports them for direct use:
 import type { components, operations, paths } from '@amigo-ai/platform-sdk'
 
 type Agent = components['schemas']['AgentResponse']
-type ListAgentsQuery =
-  operations['list_agents_v1__workspace_id__agents_get']['parameters']['query']
+type ListAgentsQuery = operations['list_agents_v1__workspace_id__agents_get']['parameters']['query']
 ```
 
 Public builds are generated from the committed [`openapi.json`](./openapi.json) snapshot in this repo so type output stays deterministic across machines and CI runs. When you need to refresh that snapshot, run:
@@ -81,6 +105,76 @@ Public builds are generated from the committed [`openapi.json`](./openapi.json)
 npm run openapi:sync
 ```
 
+For a repo-local overview of the exported client surface, see [api.md](./api.md).
+
+## Advanced request control
+
+Resource wrappers cover the common path. For lower-level control, use the built-in typed HTTP helpers. Workspace-scoped routes automatically receive your configured `workspaceId`.
+
+```typescript
+const result = await client.GET('/v1/{workspace_id}/agents', {
+  params: { query: { limit: 10 } },
+  timeout: 5_000,
+  maxRetries: 1,
+  headers: { 'X-Debug-Trace': 'true' },
+})
+
+console.log(result.requestId)
+console.log(result.data.items)
+console.log(result.rateLimit.remaining)
+```
+
+Available helpers:
+
+- `client.GET(...)`
+- `client.POST(...)`
+- `client.PUT(...)`
+- `client.PATCH(...)`
+- `client.DELETE(...)`
+- `client.HEAD(...)`
+- `client.OPTIONS(...)`
+
+### Response metadata
+
+Object responses from resource methods include non-enumerable request metadata:
+
+```typescript
+const agent = await client.agents.get('agent-id')
+
+console.log(agent._request_id)
+console.log(agent.lastResponse.statusCode)
+console.log(agent.lastResponse.rateLimit.remaining)
+```
+
+Low-level request helpers return the raw `Response` alongside parsed data:
+
+```typescript
+const { data, response, requestId } = await client.GET('/v1/{workspace_id}/agents')
+
+console.log(requestId)
+console.log(response.headers.get('content-type'))
+console.log(data.items)
+```
+
+### Request hooks
+
+Use hooks for logging, tracing, and metrics without wrapping `fetch` yourself:
+
+```typescript
+const client = new AmigoClient({
+  apiKey: 'your-api-key',
+  workspaceId: 'your-workspace-id',
+  hooks: {
+    onRequest({ request, schemaPath }) {
+      console.log('request', request.method, schemaPath)
+    },
+    onResponse({ response, requestId }) {
+      console.log('response', response.status, requestId)
+    },
+  },
+})
+```
+
 ## Resources
 
 ### Agents
@@ -157,25 +251,27 @@ console.log(service.agent_name, service.channel_type, service.version_sets)
 The world model tracks entities (patients, contacts, appointments) and the events that flow through them.
 
 ```typescript
-// Create an entity
-const patient = await client.world.createEntity({
-  entity_type: 'patient',
-  canonical_id: 'MRN-12345',
-  display_name: 'Jane Doe',
+// Filter entities with simple list queries
+const patients = await client.world.listEntities({
+  q: 'Jane Doe',
+  entity_type: ['patient'],
+  limit: 10,
 })
+console.log(patients.entities.length)
 
-// Emit an event
-await client.world.emitEvent({
-  entity_id: patient.id,
-  event_type: 'call_completed',
-  data: { duration_seconds: 180, outcome: 'appointment_scheduled' },
-})
+// Get a single entity
+const patient = await client.world.getEntity('entity-id')
+console.log(patient.display_name, patient.entity_type)
 
 // Query timeline
-const timeline = await client.world.getTimeline(patient.id)
+const timeline = await client.world.getTimeline('entity-id', { limit: 20 })
 
-// Search entities
-const results = await client.world.search('Jane Doe', { entity_type: 'patient' })
+// Semantic search over the world model
+const results = await client.world.search({
+  q: 'Jane Doe',
+  entity_type: 'patient',
+  limit: 5,
+})
 
 // View sync status from connectors
 const syncStatus = await client.world.getSyncStatusBySink()
@@ -209,7 +305,7 @@ console.log(dashboard.call_volume.value, dashboard.call_volume.delta_pct)
 console.log(dashboard.avg_quality.value)
 
 // Call volume time series
-const calls = await client.analytics.getCalls({ period: '30d' })
+const calls = await client.analytics.getCalls({ days: 30, interval: '1d' })
 console.log(calls.total_calls, calls.calls_by_date)
 
 // Per-agent performance
@@ -247,11 +343,9 @@ console.log(analytics.coverage_rate, analytics.total_facts)
 const { items: integrations } = await client.integrations.list({ enabled: true })
 
 // Test a specific endpoint
-const result = await client.integrations.testEndpoint(
-  'integration-id',
-  'geocode',
-  { textQuery: '123 Main St, Springfield' },
-)
+const result = await client.integrations.testEndpoint('integration-id', 'geocode', {
+  textQuery: '123 Main St, Springfield',
+})
 ```
 
 ### Data Sources
@@ -390,10 +484,7 @@ const deliveries = await client.webhookDestinations.listDeliveries(dest.id)
 Use the raw request body when verifying webhook deliveries. Timestamped signatures are replay-protected by default.
 
 ```typescript
-import {
-  parseWebhookEvent,
-  WebhookVerificationError,
-} from '@amigo-ai/platform-sdk'
+import { parseWebhookEvent, WebhookVerificationError } from '@amigo-ai/platform-sdk'
 
 const body = await request.text()
 
@@ -482,18 +573,19 @@ Webhook verification errors are separate from API transport errors and throw `We
 
 ### Error classes
 
-| Class | HTTP Status | Description |
-|-------|-------------|-------------|
-| `BadRequestError` | 400 | Malformed request |
-| `AuthenticationError` | 401 | Invalid or expired API key |
-| `PermissionError` | 403 | Insufficient permissions |
-| `NotFoundError` | 404 | Resource does not exist |
-| `ConflictError` | 409 | Duplicate slug or version conflict |
-| `ValidationError` | 422 | Request body validation failure |
-| `RateLimitError` | 429 | Too many requests — check `.retryAfter` |
-| `ServerError` | 5xx | Server-side error |
-| `ConfigurationError` | — | SDK misconfiguration at init time |
-| `NetworkError` | — | Fetch/network failure |
+| Class                 | HTTP Status | Description                             |
+| --------------------- | ----------- | --------------------------------------- |
+| `BadRequestError`     | 400         | Malformed request                       |
+| `AuthenticationError` | 401         | Invalid or expired API key              |
+| `PermissionError`     | 403         | Insufficient permissions                |
+| `NotFoundError`       | 404         | Resource does not exist                 |
+| `ConflictError`       | 409         | Duplicate slug or version conflict      |
+| `ValidationError`     | 422         | Request body validation failure         |
+| `RateLimitError`      | 429         | Too many requests — check `.retryAfter` |
+| `ServerError`         | 5xx         | Server-side error                       |
+| `ConfigurationError`  | —           | SDK misconfiguration at init time       |
+| `NetworkError`        | —           | Fetch/network failure                   |
+| `RequestTimeoutError` | —           | Request exceeded the configured timeout |
 
 ## CommonJS (CJS) usage
 

package/api.md

@@ -0,0 +1,354 @@
+# API Surface
+
+Repo-local reference for the public TypeScript SDK surface. This document complements the product docs and stays focused on the package exports that ship from this repository.
+
+## Client
+
+### `AmigoClient`
+
+Configuration fields:
+
+- `apiKey: string`
+- `workspaceId: string`
+- `baseUrl?: string`
+- `retry?: RetryOptions`
+- `maxRetries?: number`
+- `timeout?: number`
+- `headers?: HeadersInit`
+- `hooks?: ClientHooks`
+- `fetch?: typeof fetch`
+
+Instance fields:
+
+- `workspaceId: string`
+- `baseUrl: string`
+
+Low-level typed request helpers:
+
+- `GET(path, options?)`
+- `POST(path, options?)`
+- `PUT(path, options?)`
+- `PATCH(path, options?)`
+- `DELETE(path, options?)`
+- `HEAD(path, options?)`
+- `OPTIONS(path, options?)`
+
+Notes:
+
+- Workspace-scoped paths such as `/v1/{workspace_id}/agents` receive `workspaceId` automatically.
+- Low-level helpers return `AmigoResponse<T>` with `data`, `response`, `requestId`, and `rateLimit`.
+- Object responses from resource methods include `_request_id` and `lastResponse` metadata.
+
+## Core exports
+
+- Errors: `AmigoError`, `BadRequestError`, `AuthenticationError`, `PermissionError`, `NotFoundError`, `ConflictError`, `ValidationError`, `RateLimitError`, `ServerError`, `ServiceUnavailableError`, `NetworkError`, `RequestTimeoutError`, `ParseError`, `ConfigurationError`
+- Error guards: `isAmigoError`, `isNotFoundError`, `isRateLimitError`, `isAuthenticationError`, `isRequestTimeoutError`
+- Webhooks: `verifyWebhookSignature`, `parseWebhookEvent`, `WebhookVerificationError`
+- Pagination: `paginate`
+- Rate limit helpers: `parseRateLimitHeaders`
+- Response helpers: `extractRequestId`, `buildLastResponse`
+- Generated types: `components`, `operations`, `paths`
+
+## Response types
+
+- `AmigoRequestOptions<T>`
+- `AmigoResponse<T>`
+- `ResponseMetadata`
+- `LastResponseInfo`
+- `RetryOptions`
+- `RateLimitInfo`
+- `ClientHooks`
+- `RequestHookContext`
+- `ResponseHookContext`
+- `ErrorHookContext`
+
+## Resources
+
+### `workspaces`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `archive`
+
+### `apiKeys`
+
+- `me`
+- `create`
+- `list`
+- `revoke`
+- `rotate`
+
+### `agents`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `delete`
+- `listVersions`
+- `getVersion`
+- `createVersion`
+
+### `skills`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `delete`
+- `test`
+
+### `actions`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `delete`
+- `test`
+
+### `operators`
+
+- `list`
+- `create`
+- `get`
+- `getDashboard`
+- `getQueue`
+- `getEscalations`
+- `getActiveEscalations`
+- `getEscalationStats`
+- `getPerformance`
+- `getAccessToken`
+- `joinCall`
+- `leaveCall`
+- `switchMode`
+- `sendGuidance`
+- `createBriefing`
+- `wrapUp`
+- `getCallTranscript`
+- `getAuditLog`
+
+### `triggers`
+
+- `list`
+- `create`
+- `get`
+- `update`
+- `delete`
+- `fire`
+- `pause`
+- `resume`
+- `listRuns`
+
+### `services`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `delete`
+
+### `contextGraphs`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `delete`
+- `createVersion`
+- `listVersions`
+- `getVersion`
+
+### `dataSources`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `delete`
+- `getStatus`
+- `getSyncHistory`
+
+### `world`
+
+- `listEntities`
+- `getEntity`
+- `getRelationships`
+- `getGraph`
+- `getProvenance`
+- `getLineage`
+- `getMerged`
+- `listEntityTypes`
+- `listDuplicates`
+- `search`
+- `getTimeline`
+- `getSyncStatusBySink`
+- `listSyncEvents`
+- `getSyncQueueDepth`
+- `retrySyncEvent`
+- `retryAllSyncEvents`
+- `getStats`
+- `getSourceBreakdown`
+
+### `calls`
+
+- `list`
+- `get`
+- `getIntelligence`
+- `getActiveIntelligence`
+- `getBenchmarks`
+- `getTraceAnalysis`
+
+### `phoneNumbers`
+
+- `provision`
+- `list`
+- `get`
+- `update`
+- `release`
+- `setForwarding`
+- `clearForwarding`
+
+### `integrations`
+
+- `create`
+- `list`
+- `get`
+- `update`
+- `delete`
+- `testEndpoint`
+- `getHealthCheck`
+
+### `analytics`
+
+- `getDashboard`
+- `getCalls`
+- `getAgents`
+- `getCallQuality`
+- `getEmotionTrends`
+- `getLatency`
+- `getToolPerformance`
+- `getDataQuality`
+- `getUsage`
+- `getAdvancedCallStats`
+- `compareCallPeriods`
+
+### `simulations`
+
+- `createSession`
+- `getSession`
+- `deleteSession`
+- `step`
+- `recommend`
+- `getIntelligence`
+
+### `settings`
+
+- `voice.get`
+- `voice.update`
+- `branding.get`
+- `branding.update`
+- `outreach.get`
+- `outreach.update`
+- `memory.get`
+- `memory.update`
+- `security.get`
+- `security.update`
+- `retention.get`
+- `retention.update`
+- `workflows.get`
+- `workflows.update`
+
+### `billing`
+
+- `getDashboard`
+- `getUsage`
+- `getUsageTrends`
+- `listInvoices`
+- `getInvoice`
+- `getInvoicePdf`
+
+### `memory`
+
+- `getEntityDimensions`
+- `getEntityFacts`
+- `getAnalytics`
+
+### `personas`
+
+- `list`
+- `create`
+- `get`
+- `update`
+- `delete`
+
+### `reviewQueue`
+
+- `list`
+- `get`
+- `getStats`
+- `getDashboard`
+- `getMyQueue`
+- `approve`
+- `reject`
+- `claim`
+- `unclaim`
+- `correct`
+- `batchApprove`
+- `batchReject`
+- `getHistory`
+- `getTrends`
+- `getPerformance`
+- `getCorrectionSchema`
+- `getDiff`
+
+### `recordings`
+
+- `getUrls`
+- `getMetadata`
+- `download`
+
+### `audit`
+
+- `list`
+- `getSummary`
+- `getPhiAccess`
+- `createExport`
+- `listExports`
+- `getEntityAccessLog`
+
+### `webhookDestinations`
+
+- `list`
+- `create`
+- `get`
+- `update`
+- `delete`
+- `listDeliveries`
+- `rotateSecret`
+
+### `safety`
+
+- `getConfig`
+- `updateConfig`
+- `listTemplates`
+- `getTemplate`
+- `applyTemplate`
+
+### `compliance`
+
+- `getDashboard`
+- `getHipaa`
+- `getAccessReview`
+
+### `functions`
+
+- `list`
+- `create`
+- `delete`
+- `test`
+- `getCatalog`
+- `query`
+- `sync`

package/dist/core/errors.js

@@ -3,9 +3,18 @@
  * All errors extend AmigoError which can be caught with a single catch.
  */
 const SENSITIVE_FIELDS = new Set([
-    'id_token', 'access_token', 'refresh_token', 'authorization',
-    'api_key', 'apikey', 'token', 'secret', 'password', 'x-api-key',
-    'cookie', 'set-cookie',
+    'id_token',
+    'access_token',
+    'refresh_token',
+    'authorization',
+    'api_key',
+    'apikey',
+    'token',
+    'secret',
+    'password',
+    'x-api-key',
+    'cookie',
+    'set-cookie',
 ]);
 function sanitizeErrorContext(obj) {
     if (typeof obj !== 'object' || !obj)
@@ -40,7 +49,9 @@ export class AmigoError extends Error {
         this.errorCode = ctx.errorCode;
         this.requestId = ctx.requestId;
         this.detail = ctx.detail;
-        this.context = ctx.context ? sanitizeErrorContext(ctx.context) : undefined;
+        this.context = ctx.context
+            ? sanitizeErrorContext(ctx.context)
+            : undefined;
         Object.setPrototypeOf(this, new.target.prototype);
         if (typeof Error.captureStackTrace === 'function') {
             Error.captureStackTrace(this, this.constructor);
@@ -124,6 +135,14 @@ export class NetworkError extends AmigoError {
         }
     }
 }
+/** Request timed out before receiving a response */
+export class RequestTimeoutError extends NetworkError {
+    timeoutMs;
+    constructor(message, timeoutMs, cause) {
+        super(message, cause);
+        this.timeoutMs = timeoutMs;
+    }
+}
 /** Failed to parse response body */
 export class ParseError extends AmigoError {
     body;
@@ -204,4 +223,7 @@ export function isRateLimitError(err) {
 export function isAuthenticationError(err) {
     return err instanceof AuthenticationError;
 }
+export function isRequestTimeoutError(err) {
+    return err instanceof RequestTimeoutError;
+}
 //# sourceMappingURL=errors.js.map