@vuevox/sdk 0.7.0 → 0.8.0

package/README.md

@@ -31,6 +31,7 @@ hello:read
 spaces:read
 agents:read
 calls:read
+calls:write
 leads:read
 leads:write
 lead_custom_fields:manage
@@ -104,6 +105,9 @@ vuevox.agents.list();
 vuevox.agents.paginate();
 vuevox.calls.list();
 vuevox.calls.get("call-id");
+vuevox.calls.upload({ idempotencyKey: "crm-call-123", spaceId: "space-id", agent: { externalId: "agent-1", name: "Morgan" }, lead: { externalId: "lead-1", firstName: "Ada", lastName: "Lovelace" }, audio: { file: audioBlob, filename: "call.mp3" } });
+vuevox.calls.queueAnalysis("call-id");
+vuevox.calls.waitForAnalysis("call-id");
 vuevox.calls.paginate();
 vuevox.leads.list();
 vuevox.leads.get("lead-id");
@@ -312,6 +316,106 @@ console.log(response.data.data.transcript);
 
 Returns: `Promise<VueVoxApiResponse<CallDetailResponse>>`.
 
+### `vuevox.calls.upload(input)`
+
+Uploads an audio recording, upserts the agent and lead by `externalId`, creates the call in an existing platform-managed space, and optionally queues analysis.
+
+Required scope: `calls:write`.
+
+The API requires an idempotency key for uploads. Reusing the same `idempotencyKey` with the same request returns the original response; reusing it with different metadata or audio returns an `idempotency_key_conflict` error.
+
+Spaces are managed in VueVox. Use `vuevox.spaces.list()` to obtain the `spaceId`.
+
+The maximum audio upload size is configured by a VueVox superadmin and defaults to 20 MB. Your server/proxy upload limits must also allow that size.
+
+Options: `UploadCallInput`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `idempotencyKey` | `string` | Required unique key for safe retries. |
+| `spaceId` | `string` | Required existing VueVox space ID. |
+| `externalId` | `string \| null` | Optional call ID from your system. |
+| `queueAnalysis` | `boolean` | Optional. Defaults to `true`; set `false` to upload now and queue later. |
+| `agent.externalId` | `string` | Required agent ID from your system. |
+| `agent.name` | `string` | Required when creating a new agent. |
+| `agent.email` | `string \| null` | Optional agent email. |
+| `agent.phone` | `string \| null` | Optional agent phone. |
+| `lead.externalId` | `string` | Required lead/prospect ID from your system. |
+| `lead.firstName` | `string` | Required when creating a new lead. |
+| `lead.lastName` | `string` | Required when creating a new lead. |
+| `lead.email` | `string \| null` | Optional lead email. |
+| `lead.phone` | `string \| null` | Optional lead phone. |
+| `lead.customFields` | `Record<string, unknown>` | Optional organization-defined lead custom fields. |
+| `audio.file` | `Blob` | Required audio file blob. In Node, use `new Blob([buffer], { type: "audio/mpeg" })`. |
+| `audio.filename` | `string` | Optional filename sent in multipart upload. |
+
+```ts
+import { readFile } from "node:fs/promises";
+
+const buffer = await readFile("./call.mp3");
+
+const response = await vuevox.calls.upload({
+  idempotencyKey: "crm-call-789",
+  externalId: "crm-call-789",
+  spaceId: "space-id",
+  queueAnalysis: true,
+  agent: {
+    externalId: "agent-123",
+    name: "Morgan Agent",
+  },
+  lead: {
+    externalId: "prospect-456",
+    firstName: "Ada",
+    lastName: "Lovelace",
+    email: "ada@example.com",
+    customFields: {
+      crm_stage: "qualified",
+    },
+  },
+  audio: {
+    file: new Blob([buffer], { type: "audio/mpeg" }),
+    filename: "call.mp3",
+  },
+});
+
+console.log(response.data.data.id, response.data.data.analysisStatus, response.requestId);
+```
+
+Returns: `Promise<VueVoxApiResponse<CallResponse>>`.
+
+### `vuevox.calls.queueAnalysis(callId)`
+
+Queues analysis for a call that was uploaded with `queueAnalysis: false`.
+
+Required scope: `calls:write`.
+
+```ts
+const response = await vuevox.calls.queueAnalysis("call-id");
+console.log(response.data.data.analysisStatus, response.data.data.queueStatus);
+```
+
+Returns: `Promise<VueVoxApiResponse<CallResponse>>`.
+
+### `vuevox.calls.waitForAnalysis(callId, options?)`
+
+Polls `vuevox.calls.get(callId)` until the call analysis status is `completed` or `failed`.
+
+Required scope: `calls:read`.
+
+Options: `WaitForAnalysisOptions`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `intervalMs` | `number` | Poll interval. Defaults to `2000`. |
+| `timeoutMs` | `number` | Timeout before throwing `analysis_timeout`. Defaults to `120000`. |
+
+```ts
+const response = await vuevox.calls.waitForAnalysis("call-id", { timeoutMs: 180000 });
+console.log(response.data.data.analysis);
+```
+
+Returns: `Promise<VueVoxApiResponse<CallDetailResponse>>`.
+
 ### `vuevox.calls.paginate(options?)`
 
 Iterates organization calls across all pages.
@@ -551,6 +655,14 @@ insufficient_scope
 rate_limited
 invalid_request
 call_not_found
+call_external_id_conflict
+analysis_already_queued
+analysis_timeout
+ai_config_missing
+evaluation_grid_missing
+audio_not_found
+idempotency_key_conflict
+idempotency_key_in_progress
 lead_not_found
 custom_field_not_found
 custom_field_conflict
@@ -608,8 +720,10 @@ import type {
   Agent,
   AgentsListResponse,
   CallDetailResponse,
+  CallResponse,
   CallsListResponse,
   CallSummary,
+  CallUploadMetadata,
   CustomFieldFilters,
   CustomFieldFilterValue,
   HelloResponse,
@@ -630,11 +744,13 @@ import type {
   ListSpacesOptions,
   Space,
   SpacesListResponse,
+  UploadCallInput,
   VueVoxApiResponse,
   VueVoxClientOptions,
   VueVoxErrorResponse,
   VueVoxResponseEvent,
   VueVoxResponseMetadata,
+  WaitForAnalysisOptions,
 } from "@vuevox/sdk";
 ```
 

package/dist/client.d.ts

@@ -4,6 +4,8 @@ export type SpacesListResponse = components["schemas"]["SpacesListResponse"];
 export type AgentsListResponse = components["schemas"]["AgentsListResponse"];
 export type CallsListResponse = components["schemas"]["CallsListResponse"];
 export type CallDetailResponse = components["schemas"]["CallDetailResponse"];
+export type CallResponse = components["schemas"]["CallResponse"];
+export type CallUploadMetadata = components["schemas"]["CallUploadMetadata"];
 export type LeadsListResponse = components["schemas"]["LeadsListResponse"];
 export type LeadDetailResponse = components["schemas"]["LeadDetailResponse"];
 export type LeadCustomFieldsListResponse = components["schemas"]["LeadCustomFieldsListResponse"];
@@ -40,6 +42,17 @@ export interface ListCallsOptions extends ListSpacesOptions {
     createdBefore?: string;
     leadCustomFields?: CustomFieldFilters;
 }
+export interface UploadCallInput extends CallUploadMetadata {
+    idempotencyKey: string;
+    audio: {
+        file: Blob;
+        filename?: string;
+    };
+}
+export interface WaitForAnalysisOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+}
 export interface ListAgentsOptions extends ListSpacesOptions {
     spaceId?: string;
 }
@@ -104,8 +117,12 @@ export declare function createVueVoxClient(options: VueVoxClientOptions): {
     calls: {
         list: (listOptions?: ListCallsOptions) => Promise<VueVoxApiResponse<CallsListResponse>>;
         get: (callId: string) => Promise<VueVoxApiResponse<CallDetailResponse>>;
+        upload: (input: UploadCallInput) => Promise<VueVoxApiResponse<CallResponse>>;
+        queueAnalysis: (callId: string) => Promise<VueVoxApiResponse<CallResponse>>;
+        waitForAnalysis: (callId: string, waitOptions?: WaitForAnalysisOptions) => Promise<VueVoxApiResponse<CallDetailResponse>>;
         paginate: (listOptions?: ListCallsOptions) => AsyncGenerator<{
             id: string;
+            externalId: string | null;
             space: components["schemas"]["ResourceSummary"];
             lead: components["schemas"]["LeadSummary"];
             agent: components["schemas"]["AgentSummary"];

package/dist/client.js

@@ -46,6 +46,34 @@ export function createVueVoxClient(options) {
     async function getCall(callId) {
         return apiGet(`/v1/calls/${encodeURIComponent(callId)}`);
     }
+    async function uploadCall(input) {
+        const { audio, idempotencyKey, ...metadata } = input;
+        const formData = new FormData();
+        formData.set("metadata", JSON.stringify(metadata));
+        formData.set("audioFile", audio.file, audio.filename ?? "call-audio");
+        return apiMultipart("POST", "/v1/calls", formData, {
+            "Idempotency-Key": idempotencyKey,
+        });
+    }
+    async function queueCallAnalysis(callId) {
+        return apiJson("POST", `/v1/calls/${encodeURIComponent(callId)}/analysis-jobs`, {});
+    }
+    async function waitForCallAnalysis(callId, waitOptions = {}) {
+        const intervalMs = waitOptions.intervalMs ?? 2_000;
+        const timeoutMs = waitOptions.timeoutMs ?? 120_000;
+        const startedAt = Date.now();
+        for (;;) {
+            const response = await getCall(callId);
+            const status = response.data.data.analysisStatus;
+            if (status === "completed" || status === "failed") {
+                return response;
+            }
+            if (Date.now() - startedAt >= timeoutMs) {
+                throw new VueVoxApiError(408, "analysis_timeout", "Timed out waiting for call analysis.", undefined, response.requestId);
+            }
+            await sleep(intervalMs);
+        }
+    }
     async function listLeads(listOptions = {}) {
         return apiGet("/v1/leads", listOptions);
     }
@@ -90,6 +118,18 @@ export function createVueVoxClient(options) {
         });
         return withMetadata(result.data, result.response, result.requestId);
     }
+    async function apiMultipart(method, path, body, headers) {
+        const accessToken = await getAccessToken();
+        const result = await requestJson(method, path, {
+            method,
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                ...headers,
+            },
+            body,
+        });
+        return withMetadata(result.data, result.response, result.requestId);
+    }
     async function requestJson(method, path, init) {
         for (let attempt = 0;; attempt++) {
             const response = await fetchFn(buildUrl(baseUrl, path, init.query), init);
@@ -133,6 +173,9 @@ export function createVueVoxClient(options) {
         calls: {
             list: listCalls,
             get: getCall,
+            upload: uploadCall,
+            queueAnalysis: queueCallAnalysis,
+            waitForAnalysis: waitForCallAnalysis,
             paginate: (listOptions = {}) => paginate(listCalls, listOptions),
         },
         leads: {

package/dist/generated/schema.d.ts

@@ -97,7 +97,11 @@ export interface paths {
          */
         get: operations["listCalls"];
         put?: never;
-        post?: never;
+        /**
+         * Upload a call and optionally queue analysis
+         * @description Uploads a call recording, upserts the agent and lead by externalId, creates the call in an existing platform-managed space, and optionally queues analysis. Requires an Idempotency-Key header for safe retries. The audio size limit is configured by a VueVox superadmin and defaults to 20 MB.
+         */
+        post: operations["uploadCall"];
         delete?: never;
         options?: never;
         head?: never;
@@ -124,6 +128,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/calls/{callId}/analysis-jobs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Queue analysis for a call
+         * @description Queues analysis for a previously uploaded organization call. Use this when a call was uploaded with queueAnalysis set to false.
+         */
+        post: operations["queueCallAnalysis"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/leads": {
         parameters: {
             query?: never;
@@ -243,7 +267,7 @@ export interface components {
             client_secret: string;
             /**
              * @description Space-separated scopes requested for the access token.
-             * @example hello:read spaces:read agents:read calls:read leads:read leads:write lead_custom_fields:manage
+             * @example hello:read spaces:read agents:read calls:read calls:write leads:read leads:write lead_custom_fields:manage
              */
             scope?: string;
         };
@@ -253,7 +277,7 @@ export interface components {
             token_type: "Bearer";
             /** @example 3600 */
             expires_in: number;
-            /** @example hello:read spaces:read agents:read calls:read leads:read leads:write lead_custom_fields:manage */
+            /** @example hello:read spaces:read agents:read calls:read calls:write leads:read leads:write lead_custom_fields:manage */
             scope: string;
         };
         HelloResponse: {
@@ -317,6 +341,8 @@ export interface components {
         CallSummary: {
             /** Format: uuid */
             id: string;
+            /** @description Optional ID from an external system. */
+            externalId: string | null;
             space: components["schemas"]["ResourceSummary"];
             lead: components["schemas"]["LeadSummary"];
             agent: components["schemas"]["AgentSummary"];
@@ -357,6 +383,44 @@ export interface components {
         CallDetailResponse: {
             data: components["schemas"]["CallDetail"];
         };
+        CallResponse: {
+            data: components["schemas"]["CallSummary"];
+        };
+        CallUploadMetadata: {
+            /** @description Optional call ID from your system. Must be unique within the organization when provided. */
+            externalId?: string | null;
+            /**
+             * Format: uuid
+             * @description Existing VueVox space ID. Spaces are managed in the VueVox platform.
+             */
+            spaceId: string;
+            /**
+             * @description When true or omitted, queues analysis immediately after upload. When false, queue later with queueCallAnalysis.
+             * @default true
+             */
+            queueAnalysis: boolean;
+            agent: components["schemas"]["CallUploadAgent"];
+            lead: components["schemas"]["CallUploadLead"];
+        };
+        CallUploadAgent: {
+            externalId: string;
+            /** @description Required when creating a new agent. */
+            name?: string;
+            /** Format: email */
+            email?: string | null;
+            phone?: string | null;
+        };
+        CallUploadLead: {
+            externalId: string;
+            /** @description Required when creating a new lead. */
+            firstName?: string;
+            /** @description Required when creating a new lead. */
+            lastName?: string;
+            /** Format: email */
+            email?: string | null;
+            phone?: string | null;
+            customFields?: components["schemas"]["CustomFields"];
+        };
         Lead: {
             /** Format: uuid */
             id: string;
@@ -789,6 +853,77 @@ export interface operations {
             };
         };
     };
+    uploadCall: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Unique key for this upload attempt. Reusing the same key with the same request returns the original response; reusing it with a different request returns a conflict. */
+                "Idempotency-Key": string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "multipart/form-data": {
+                    /** @description JSON string matching CallUploadMetadata. */
+                    metadata: string;
+                    /**
+                     * Format: binary
+                     * @description Audio file. Supported extensions include wav, mp3, aac, m4a, amr, mpeg, mpga, x-wav, ogg, oga, mp4, and mp4a.
+                     */
+                    audioFile: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Call uploaded. Analysis is queued when metadata.queueAnalysis is true. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CallResponse"];
+                };
+            };
+            /** @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 Idempotency key conflict, external call ID conflict, or analysis already queued. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Multipart upload or metadata failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     getCall: {
         parameters: {
             query?: never;
@@ -852,6 +987,74 @@ export interface operations {
             };
         };
     };
+    queueCallAnalysis: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Call ID. */
+                callId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Analysis queued. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CallResponse"];
+                };
+            };
+            /** @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 Call was not found in the API client's organization. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Analysis is already queued or processing. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Organization AI settings, evaluation grid, or audio file is missing. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listLeads: {
         parameters: {
             query?: {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createVueVoxClient } from "./client.js";
-export type { Agent, AgentsListResponse, CallDetailResponse, CallsListResponse, CallSummary, CustomFieldFilters, CustomFieldFilterValue, HelloResponse, Lead, LeadCustomField, LeadCustomFieldCreateRequest, LeadCustomFieldResponse, LeadCustomFieldUpdateRequest, LeadCustomFieldsListResponse, LeadDetailResponse, LeadUpdateRequest, LeadUpsertRequest, LeadsListResponse, ListAgentsOptions, ListCallsOptions, ListLeadCustomFieldsOptions, ListLeadsOptions, ListSpacesOptions, Space, SpacesListResponse, VueVoxApiResponse, VueVoxClientOptions, VueVoxResponseEvent, VueVoxResponseMetadata, } from "./client.js";
+export type { Agent, AgentsListResponse, CallDetailResponse, CallResponse, CallsListResponse, CallSummary, CallUploadMetadata, CustomFieldFilters, CustomFieldFilterValue, HelloResponse, Lead, LeadCustomField, LeadCustomFieldCreateRequest, LeadCustomFieldResponse, LeadCustomFieldUpdateRequest, LeadCustomFieldsListResponse, LeadDetailResponse, LeadUpdateRequest, LeadUpsertRequest, LeadsListResponse, ListAgentsOptions, ListCallsOptions, ListLeadCustomFieldsOptions, ListLeadsOptions, ListSpacesOptions, Space, SpacesListResponse, UploadCallInput, VueVoxApiResponse, VueVoxClientOptions, VueVoxResponseEvent, VueVoxResponseMetadata, WaitForAnalysisOptions, } 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.7.0",
+  "version": "0.8.0",
   "description": "TypeScript SDK for the VueVox Developer API.",
   "type": "module",
   "main": "./dist/index.js",