@vuevox/sdk 0.4.0 → 0.5.0

package/README.md

@@ -8,6 +8,12 @@ TypeScript SDK for the VueVox Developer API.
 npm install @vuevox/sdk
 ```
 
+Requirements:
+
+- Node.js 18 or newer.
+- A VueVox Developer API client ID and secret.
+- Server-side usage only. Do not expose `clientSecret` in browser code.
+
 ## Create API Credentials
 
 In VueVox, open:
@@ -23,11 +29,14 @@ Available scopes:
 ```text
 hello:read
 spaces:read
+agents:read
 calls:read
 leads:read
 ```
 
-## Basic Usage
+The token request can only request scopes that were granted to that API client.
+
+## Quickstart
 
 ```ts
 import { createVueVoxClient } from "@vuevox/sdk";
@@ -35,85 +44,84 @@ import { createVueVoxClient } from "@vuevox/sdk";
 const vuevox = createVueVoxClient({
   clientId: process.env.VUEVOX_CLIENT_ID!,
   clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
-  scope: ["hello:read", "spaces:read", "calls:read", "leads:read"],
+  scope: ["hello:read", "spaces:read", "agents:read", "calls:read", "leads:read"],
 });
 
 const hello = await vuevox.hello.get();
 console.log(hello.data.message, hello.requestId);
 
-const spaces = await vuevox.spaces.list({ limit: 50 });
-console.log(spaces.data.data, spaces.requestId);
-
 const calls = await vuevox.calls.list({ limit: 50 });
 console.log(calls.data.data, calls.requestId);
-
-const leads = await vuevox.leads.list({ limit: 50 });
-console.log(leads.data.data, leads.requestId);
 ```
 
 The SDK requests and caches a short-lived access token using client credentials, then sends it as a bearer token for API calls.
 
-## Request IDs
+## Client Reference
 
-Every Developer API response includes an `X-Request-Id` header. SDK endpoint methods return response metadata with the response body so you can log that ID for support requests.
+### `createVueVoxClient(options)`
 
-```ts
-const call = await vuevox.calls.get("call-id");
-
-console.log(call.requestId);
-console.log(call.data.data.transcript);
-```
-
-For centralized logging, pass `onResponse`. The hook runs for every SDK-managed HTTP response, including the token request.
+Creates a VueVox API client.
 
 ```ts
 const vuevox = createVueVoxClient({
+  baseUrl: "https://api.vuevox.com",
   clientId: process.env.VUEVOX_CLIENT_ID!,
   clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
   scope: ["calls:read"],
+  retries: 2,
+  retryBaseDelayMs: 250,
+  retryMaxDelayMs: 2000,
   onResponse: ({ method, path, status, requestId }) => {
     console.log({ method, path, status, requestId });
   },
 });
 ```
 
-## Error Handling
+Options:
 
-API errors throw `VueVoxApiError`. The SDK exposes `error.requestId`, `error.details`, `error.retryAfter`, and `error.isRateLimited`.
+| Option | Type | Required | Description |
+| --- | --- | --- | --- |
+| `clientId` | `string` | Yes | Developer API client ID. |
+| `clientSecret` | `string` | Yes | Developer API client secret. Keep this server-side. |
+| `baseUrl` | `string` | No | API base URL. Defaults to `https://api.vuevox.com`. |
+| `scope` | `string \| string[]` | No | Space-separated string or array of requested token scopes. If omitted, the token request uses all scopes granted to the client. |
+| `fetch` | `typeof fetch` | No | Custom fetch implementation. Defaults to global `fetch`. |
+| `onResponse` | `(event: VueVoxResponseEvent) => void` | No | Called for every SDK-managed HTTP response, including token requests. |
+| `retries` | `number` | No | Retry count for token requests and GET endpoints. Defaults to `0`. |
+| `retryBaseDelayMs` | `number` | No | Initial retry delay. Defaults to `250`. |
+| `retryMaxDelayMs` | `number` | No | Maximum retry delay. Defaults to `2000`. |
+
+Returns a namespaced client:
 
 ```ts
-import { VueVoxApiError, createVueVoxClient } from "@vuevox/sdk";
+vuevox.getAccessToken();
+vuevox.hello.get();
+vuevox.spaces.list();
+vuevox.spaces.paginate();
+vuevox.agents.list();
+vuevox.agents.paginate();
+vuevox.calls.list();
+vuevox.calls.get("call-id");
+vuevox.calls.paginate();
+vuevox.leads.list();
+vuevox.leads.get("lead-id");
+vuevox.leads.paginate();
+vuevox.raw.GET("/v1/hello", { headers: { Authorization: `Bearer ${await vuevox.getAccessToken()}` } });
+```
 
-const vuevox = createVueVoxClient({
-  clientId: process.env.VUEVOX_CLIENT_ID!,
-  clientSecret: process.env.VUEVOX_CLIENT_SECRET!,
-  scope: ["calls:read"],
-});
+## Response Envelope
 
-try {
-  await vuevox.calls.list({ limit: 50 });
-} catch (error) {
-  if (error instanceof VueVoxApiError) {
-    console.error(error.status, error.code, error.message, error.requestId);
-  }
+All SDK endpoint methods return a response envelope:
 
-  throw error;
-}
+```ts
+type VueVoxApiResponse<T> = {
+  data: T;
+  status: number;
+  requestId?: string;
+};
 ```
 
-Common API error codes:
-
-```text
-missing_token
-invalid_token
-invalid_client
-invalid_scope
-insufficient_scope
-rate_limited
-invalid_request
-call_not_found
-lead_not_found
-```
+Use `requestId` in logs and support requests. It maps to the API `X-Request-Id` response header.
 
 ## Pagination
 
@@ -130,6 +138,13 @@ if (firstPage.data.pagination.nextCursor) {
 }
 ```
 
+List option fields shared by paginated endpoints:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `limit` | `number` | Number of items to return. Defaults to `50`; maximum is `100`. |
+| `cursor` | `string` | Cursor from the previous response's `pagination.nextCursor`. |
+
 The SDK also includes async iterable helpers:
 
 ```ts
@@ -138,7 +153,279 @@ for await (const call of vuevox.calls.paginate({ limit: 50 })) {
 }
 ```
 
-Pagination helpers are available for `spaces`, `calls`, and `leads`.
+Pagination helpers are available for `spaces`, `agents`, `calls`, and `leads`.
+
+## Methods
+
+### `vuevox.getAccessToken()`
+
+Requests or returns a cached bearer token.
+
+```ts
+const token = await vuevox.getAccessToken();
+```
+
+Returns: `Promise<string>`.
+
+### `vuevox.hello.get()`
+
+Checks credentials and connectivity.
+
+Required scope: `hello:read`.
+
+```ts
+const response = await vuevox.hello.get();
+console.log(response.data.message);
+```
+
+Returns: `Promise<VueVoxApiResponse<HelloResponse>>`.
+
+### `vuevox.spaces.list(options?)`
+
+Lists organization spaces.
+
+Required scope: `spaces:read`.
+
+Options: `ListSpacesOptions`
+
+```ts
+const response = await vuevox.spaces.list({ limit: 50 });
+
+for (const space of response.data.data) {
+  console.log(space.id, space.name);
+}
+```
+
+Returns: `Promise<VueVoxApiResponse<SpacesListResponse>>`.
+
+### `vuevox.spaces.paginate(options?)`
+
+Iterates organization spaces across all pages.
+
+Required scope: `spaces:read`.
+
+Options: `ListSpacesOptions`
+
+```ts
+for await (const space of vuevox.spaces.paginate({ limit: 100 })) {
+  console.log(space.id, space.name);
+}
+```
+
+Returns: `AsyncGenerator<Space>`.
+
+### `vuevox.agents.list(options?)`
+
+Lists organization agents.
+
+Required scope: `agents:read`.
+
+Options: `ListAgentsOptions`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `limit` | `number` | Number of agents to return. Defaults to `50`; maximum is `100`. |
+| `cursor` | `string` | Cursor from the previous response. |
+| `spaceId` | `string` | Optional space ID filter. |
+
+```ts
+const response = await vuevox.agents.list({ limit: 50, spaceId: "space-id" });
+
+for (const agent of response.data.data) {
+  console.log(agent.id, agent.name);
+}
+```
+
+Returns: `Promise<VueVoxApiResponse<AgentsListResponse>>`.
+
+### `vuevox.agents.paginate(options?)`
+
+Iterates organization agents across all pages.
+
+Required scope: `agents:read`.
+
+Options: `ListAgentsOptions`
+
+```ts
+for await (const agent of vuevox.agents.paginate({ spaceId: "space-id" })) {
+  console.log(agent.id, agent.name);
+}
+```
+
+Returns: `AsyncGenerator<Agent>`.
+
+### `vuevox.calls.list(options?)`
+
+Lists organization calls. List responses do not include transcripts.
+
+Required scope: `calls:read`.
+
+Options: `ListCallsOptions`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `limit` | `number` | Number of calls to return. Defaults to `50`; maximum is `100`. |
+| `cursor` | `string` | Cursor from the previous response. |
+| `spaceId` | `string` | Optional space ID filter. |
+| `leadId` | `string` | Optional lead ID filter. |
+| `agentId` | `string` | Optional agent ID filter. |
+| `createdAfter` | `string` | Optional ISO 8601 lower bound for call creation time. |
+| `createdBefore` | `string` | Optional ISO 8601 upper bound for call creation time. |
+
+```ts
+const response = await vuevox.calls.list({
+  limit: 50,
+  spaceId: "space-id",
+  createdAfter: "2026-01-01T00:00:00.000Z",
+});
+
+for (const call of response.data.data) {
+  console.log(call.id, call.status, call.createdAt);
+}
+```
+
+Returns: `Promise<VueVoxApiResponse<CallsListResponse>>`.
+
+### `vuevox.calls.get(callId)`
+
+Gets a call detail record, including transcript data when available.
+
+Required scope: `calls:read`.
+
+```ts
+const response = await vuevox.calls.get("call-id");
+console.log(response.data.data.transcript);
+```
+
+Returns: `Promise<VueVoxApiResponse<CallDetailResponse>>`.
+
+### `vuevox.calls.paginate(options?)`
+
+Iterates organization calls across all pages.
+
+Required scope: `calls:read`.
+
+Options: `ListCallsOptions`
+
+```ts
+for await (const call of vuevox.calls.paginate({ leadId: "lead-id" })) {
+  console.log(call.id);
+}
+```
+
+Returns: `AsyncGenerator<CallSummary>`.
+
+### `vuevox.leads.list(options?)`
+
+Lists organization leads. The `leads:read` scope includes lead email and phone contact details.
+
+Required scope: `leads:read`.
+
+Options: `ListLeadsOptions`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `limit` | `number` | Number of leads to return. Defaults to `50`; maximum is `100`. |
+| `cursor` | `string` | Cursor from the previous response. |
+| `spaceId` | `string` | Optional space ID filter. |
+| `createdAfter` | `string` | Optional ISO 8601 lower bound for lead creation time. |
+| `createdBefore` | `string` | Optional ISO 8601 upper bound for lead creation time. |
+
+```ts
+const response = await vuevox.leads.list({ limit: 50, spaceId: "space-id" });
+
+for (const lead of response.data.data) {
+  console.log(lead.id, lead.email, lead.phone);
+}
+```
+
+Returns: `Promise<VueVoxApiResponse<LeadsListResponse>>`.
+
+### `vuevox.leads.get(leadId)`
+
+Gets a lead detail record, including email and phone contact details.
+
+Required scope: `leads:read`.
+
+```ts
+const response = await vuevox.leads.get("lead-id");
+console.log(response.data.email, response.data.phone);
+```
+
+Returns: `Promise<VueVoxApiResponse<LeadDetailResponse>>`.
+
+### `vuevox.leads.paginate(options?)`
+
+Iterates organization leads across all pages.
+
+Required scope: `leads:read`.
+
+Options: `ListLeadsOptions`
+
+```ts
+for await (const lead of vuevox.leads.paginate({ createdAfter: "2026-01-01T00:00:00.000Z" })) {
+  console.log(lead.id);
+}
+```
+
+Returns: `AsyncGenerator<Lead>`.
+
+## Lower-Level Calls
+
+For advanced integrations, `raw` exposes a typed lower-level OpenAPI client. You must attach authorization yourself.
+
+```ts
+const { data, error } = await vuevox.raw.GET("/v1/hello", {
+  headers: {
+    Authorization: `Bearer ${await vuevox.getAccessToken()}`,
+  },
+});
+```
+
+## Errors
+
+API errors throw `VueVoxApiError`.
+
+```ts
+import { VueVoxApiError, createVueVoxClient } from "@vuevox/sdk";
+
+try {
+  await vuevox.calls.list({ limit: 50 });
+} catch (error) {
+  if (error instanceof VueVoxApiError) {
+    console.error(error.status, error.code, error.message, error.requestId);
+  }
+
+  throw error;
+}
+```
+
+Error fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status` | `number` | HTTP status code. |
+| `code` | `string` | Stable API error code. |
+| `message` | `string` | Human-readable message. |
+| `requestId` | `string \| undefined` | Request ID from `X-Request-Id` or error body. |
+| `details` | `Record<string, unknown> \| undefined` | Structured error details when present. |
+| `retryAfter` | `number \| undefined` | Seconds to wait before retrying when present. |
+| `isRateLimited` | `boolean` | `true` for rate limit errors. |
+| `response` | `VueVoxErrorResponse \| undefined` | Full API error response when available. |
+
+Common API error codes:
+
+```text
+missing_token
+invalid_token
+invalid_client
+invalid_scope
+insufficient_scope
+rate_limited
+invalid_request
+call_not_found
+lead_not_found
+```
 
 ## Retries
 
@@ -183,14 +470,33 @@ const vuevox = createVueVoxClient({
 });
 ```
 
-## Lower-Level Calls
+## Exported Types
 
-For advanced integrations, `raw` exposes a typed lower-level API client.
+The package exports these TypeScript types:
 
 ```ts
-const { data, error } = await vuevox.raw.GET("/v1/hello", {
-  headers: {
-    Authorization: `Bearer ${await vuevox.getAccessToken()}`,
-  },
-});
+import type {
+  Agent,
+  AgentsListResponse,
+  CallDetailResponse,
+  CallsListResponse,
+  CallSummary,
+  HelloResponse,
+  Lead,
+  LeadDetailResponse,
+  LeadsListResponse,
+  ListAgentsOptions,
+  ListCallsOptions,
+  ListLeadsOptions,
+  ListSpacesOptions,
+  Space,
+  SpacesListResponse,
+  VueVoxApiResponse,
+  VueVoxClientOptions,
+  VueVoxErrorResponse,
+  VueVoxResponseEvent,
+  VueVoxResponseMetadata,
+} from "@vuevox/sdk";
 ```
+
+Generated OpenAPI-derived types are included in the package declaration files, so editors can inspect the exact response fields for each method.

package/dist/client.d.ts

@@ -1,11 +1,13 @@
 import type { components, paths } from "./generated/schema.js";
 type HelloResponse = components["schemas"]["HelloResponse"];
 type SpacesListResponse = components["schemas"]["SpacesListResponse"];
+type AgentsListResponse = components["schemas"]["AgentsListResponse"];
 type CallsListResponse = components["schemas"]["CallsListResponse"];
 type CallDetailResponse = components["schemas"]["CallDetailResponse"];
 type LeadsListResponse = components["schemas"]["LeadsListResponse"];
 type LeadDetailResponse = components["schemas"]["LeadDetailResponse"];
 type Space = components["schemas"]["Space"];
+type Agent = components["schemas"]["Agent"];
 type CallSummary = components["schemas"]["CallSummary"];
 type Lead = components["schemas"]["Lead"];
 export interface ListSpacesOptions {
@@ -19,6 +21,9 @@ export interface ListCallsOptions extends ListSpacesOptions {
     createdAfter?: string;
     createdBefore?: string;
 }
+export interface ListAgentsOptions extends ListSpacesOptions {
+    spaceId?: string;
+}
 export interface ListLeadsOptions extends ListSpacesOptions {
     spaceId?: string;
     createdAfter?: string;
@@ -62,6 +67,16 @@ export declare function createVueVoxClient(options: VueVoxClientOptions): {
             updatedAt: string;
         }, any, any>;
     };
+    agents: {
+        list: (listOptions?: ListAgentsOptions) => Promise<VueVoxApiResponse<AgentsListResponse>>;
+        paginate: (listOptions?: ListAgentsOptions) => AsyncGenerator<{
+            id: string;
+            name: string;
+            spaces: components["schemas"]["ResourceSummary"][];
+            createdAt: string;
+            updatedAt: string;
+        }, any, any>;
+    };
     calls: {
         list: (listOptions?: ListCallsOptions) => Promise<VueVoxApiResponse<CallsListResponse>>;
         get: (callId: string) => Promise<VueVoxApiResponse<CallDetailResponse>>;
@@ -95,4 +110,4 @@ export declare function createVueVoxClient(options: VueVoxClientOptions): {
     };
     raw: import("openapi-fetch").Client<paths, `${string}/${string}`>;
 };
-export type { CallDetailResponse, CallsListResponse, CallSummary, HelloResponse, Lead, LeadDetailResponse, LeadsListResponse, Space, SpacesListResponse };
+export type { Agent, AgentsListResponse, CallDetailResponse, CallsListResponse, CallSummary, HelloResponse, Lead, LeadDetailResponse, LeadsListResponse, Space, SpacesListResponse };

package/dist/client.js

@@ -37,6 +37,9 @@ export function createVueVoxClient(options) {
     async function listSpaces(listOptions = {}) {
         return apiGet("/v1/spaces", listOptions);
     }
+    async function listAgents(listOptions = {}) {
+        return apiGet("/v1/agents", listOptions);
+    }
     async function listCalls(listOptions = {}) {
         return apiGet("/v1/calls", listOptions);
     }
@@ -96,6 +99,10 @@ export function createVueVoxClient(options) {
             list: listSpaces,
             paginate: (listOptions = {}) => paginate(listSpaces, listOptions),
         },
+        agents: {
+            list: listAgents,
+            paginate: (listOptions = {}) => paginate(listAgents, listOptions),
+        },
         calls: {
             list: listCalls,
             get: getCall,

package/dist/generated/schema.d.ts

@@ -64,6 +64,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/agents": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List organization agents
+         * @description Returns agents for the API client's organization using cursor pagination. Optionally filter agents by space ID.
+         */
+        get: operations["listAgents"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/calls": {
         parameters: {
             query?: never;
@@ -155,7 +175,7 @@ export interface components {
             client_secret: string;
             /**
              * @description Space-separated scopes requested for the access token.
-             * @example hello:read spaces:read calls:read leads:read
+             * @example hello:read spaces:read agents:read calls:read leads:read
              */
             scope?: string;
         };
@@ -165,7 +185,7 @@ export interface components {
             token_type: "Bearer";
             /** @example 3600 */
             expires_in: number;
-            /** @example hello:read spaces:read calls:read leads:read */
+            /** @example hello:read spaces:read agents:read calls:read leads:read */
             scope: string;
         };
         HelloResponse: {
@@ -188,6 +208,21 @@ export interface components {
             data: components["schemas"]["Space"][];
             pagination: components["schemas"]["CursorPagination"];
         };
+        Agent: {
+            /** Format: uuid */
+            id: string;
+            /** @example Morgan Agent */
+            name: string;
+            spaces: components["schemas"]["ResourceSummary"][];
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        AgentsListResponse: {
+            data: components["schemas"]["Agent"][];
+            pagination: components["schemas"]["CursorPagination"];
+        };
         ResourceSummary: {
             /** Format: uuid */
             id: string;
@@ -461,6 +496,73 @@ export interface operations {
             };
         };
     };
+    listAgents: {
+        parameters: {
+            query?: {
+                /** @description Number of agents to return. Defaults to 50. Maximum is 100. */
+                limit?: number;
+                /** @description Opaque cursor from the previous response's pagination.nextCursor value. */
+                cursor?: string;
+                /** @description Filter agents assigned to a space ID. */
+                spaceId?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Paginated agents response. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AgentsListResponse"];
+                };
+            };
+            /** @description Bearer token is missing, invalid, or expired. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Bearer token does not include the required scope. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Query parameters failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Per-client rate limit exceeded. */
+            429: {
+                headers: {
+                    /** @description Seconds to wait before retrying. */
+                    "Retry-After"?: string;
+                    /** @description Request limit per minute for this API client. */
+                    "X-RateLimit-Limit"?: string;
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listCalls: {
         parameters: {
             query?: {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createVueVoxClient } from "./client.js";
-export type { CallDetailResponse, CallsListResponse, CallSummary, HelloResponse, Lead, LeadDetailResponse, LeadsListResponse, ListCallsOptions, ListLeadsOptions, ListSpacesOptions, Space, SpacesListResponse, VueVoxApiResponse, VueVoxClientOptions, VueVoxResponseEvent, VueVoxResponseMetadata, } from "./client.js";
+export type { Agent, AgentsListResponse, CallDetailResponse, CallsListResponse, CallSummary, HelloResponse, Lead, LeadDetailResponse, LeadsListResponse, ListAgentsOptions, ListCallsOptions, ListLeadsOptions, ListSpacesOptions, Space, SpacesListResponse, VueVoxApiResponse, VueVoxClientOptions, VueVoxResponseEvent, VueVoxResponseMetadata, } from "./client.js";
 export { VueVoxApiError } from "./errors.js";
 export type { VueVoxErrorResponse } from "./errors.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vuevox/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "TypeScript SDK for the VueVox Developer API.",
   "type": "module",
   "main": "./dist/index.js",