@vuevox/sdk 0.6.0 → 0.8.0

package/README.md

@@ -31,7 +31,10 @@ hello:read
 spaces:read
 agents:read
 calls:read
+calls:write
 leads:read
+leads:write
+lead_custom_fields:manage
 ```
 
 The token request can only request scopes that were granted to that API client.
@@ -102,10 +105,18 @@ 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");
+vuevox.leads.update("lead-id", { customFields: { crm_stage: "qualified" } });
+vuevox.leads.upsertByExternalId("crm-lead-id", { firstName: "Ada", lastName: "Lovelace" });
 vuevox.leads.paginate();
+vuevox.leadCustomFields.list();
+vuevox.leadCustomFields.create({ key: "crm_stage", label: "CRM Stage", type: "select", options: ["new", "qualified"] });
+vuevox.leadCustomFields.update("crm_stage", { label: "CRM Stage" });
 vuevox.raw.GET("/v1/hello", { headers: { Authorization: `Bearer ${await vuevox.getAccessToken()}` } });
 ```
 
@@ -273,12 +284,16 @@ Options: `ListCallsOptions`
 | `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. |
+| `leadCustomFields` | `Record<string, CustomFieldFilterValue>` | Optional filters on lead custom fields attached to calls. |
 
 ```ts
 const response = await vuevox.calls.list({
   limit: 50,
   spaceId: "space-id",
   createdAfter: "2026-01-01T00:00:00.000Z",
+  leadCustomFields: {
+    crm_stage: "qualified",
+  },
 });
 
 for (const call of response.data.data) {
@@ -301,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.
@@ -321,7 +436,7 @@ Returns: `AsyncGenerator<CallSummary>`.
 
 Lists organization leads. The `leads:read` scope includes lead email and phone contact details.
 
-Lead records include nullable `externalId` when you store an ID from another system.
+Lead records include nullable `externalId` when you store an ID from another system, and a `customFields` object for organization-defined CRM fields.
 
 Required scope: `leads:read`.
 
@@ -334,12 +449,20 @@ Options: `ListLeadsOptions`
 | `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. |
+| `customFields` | `Record<string, CustomFieldFilterValue>` | Optional filters on lead custom fields. |
 
 ```ts
-const response = await vuevox.leads.list({ limit: 50, spaceId: "space-id" });
+const response = await vuevox.leads.list({
+  limit: 50,
+  spaceId: "space-id",
+  customFields: {
+    crm_stage: "qualified",
+    deal_value: { gte: 10000 },
+  },
+});
 
 for (const lead of response.data.data) {
-  console.log(lead.id, lead.externalId, lead.email, lead.phone);
+  console.log(lead.id, lead.externalId, lead.email, lead.phone, lead.customFields);
 }
 ```
 
@@ -353,7 +476,53 @@ Required scope: `leads:read`.
 
 ```ts
 const response = await vuevox.leads.get("lead-id");
-console.log(response.data.externalId, response.data.email, response.data.phone);
+console.log(response.data.data.externalId, response.data.data.email, response.data.data.phone, response.data.data.customFields);
+```
+
+Returns: `Promise<VueVoxApiResponse<LeadDetailResponse>>`.
+
+### `vuevox.leads.update(leadId, input)`
+
+Updates a lead and/or its custom fields.
+
+Required scope: `leads:write`.
+
+Input: `LeadUpdateRequest`
+
+```ts
+const response = await vuevox.leads.update("lead-id", {
+  email: "ada@example.com",
+  customFields: {
+    crm_stage: "qualified",
+    renewal_date: "2026-09-01",
+  },
+});
+
+console.log(response.data.data.customFields);
+```
+
+Returns: `Promise<VueVoxApiResponse<LeadDetailResponse>>`.
+
+### `vuevox.leads.upsertByExternalId(externalId, input)`
+
+Creates or updates a lead by the integrating CRM/system ID. This is the preferred write method for CRM integrations because callers can use their own stable lead ID.
+
+Required scope: `leads:write`.
+
+Input: `LeadUpsertRequest`
+
+```ts
+const response = await vuevox.leads.upsertByExternalId("hubspot_123", {
+  firstName: "Ada",
+  lastName: "Lovelace",
+  email: "ada@example.com",
+  customFields: {
+    crm_stage: "qualified",
+    deal_value: 12000,
+  },
+});
+
+console.log(response.data.data.id, response.data.data.customFields);
 ```
 
 Returns: `Promise<VueVoxApiResponse<LeadDetailResponse>>`.
@@ -374,6 +543,64 @@ for await (const lead of vuevox.leads.paginate({ createdAfter: "2026-01-01T00:00
 
 Returns: `AsyncGenerator<Lead>`.
 
+### `vuevox.leadCustomFields.list(options?)`
+
+Lists organization lead custom field definitions.
+
+Required scope: `leads:read`.
+
+Options: `ListLeadCustomFieldsOptions`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `includeArchived` | `boolean` | Include archived definitions. Defaults to `false`. |
+
+```ts
+const response = await vuevox.leadCustomFields.list();
+console.log(response.data.data);
+```
+
+Returns: `Promise<VueVoxApiResponse<LeadCustomFieldsListResponse>>`.
+
+### `vuevox.leadCustomFields.create(input)`
+
+Creates a lead custom field definition. Supported types are `text`, `number`, `boolean`, `date`, `datetime`, `select`, and `multi_select`.
+
+Required scope: `lead_custom_fields:manage`.
+
+Input: `LeadCustomFieldCreateRequest`
+
+```ts
+const response = await vuevox.leadCustomFields.create({
+  key: "crm_stage",
+  label: "CRM Stage",
+  type: "select",
+  options: ["new", "qualified", "customer"],
+  isFilterable: true,
+});
+
+console.log(response.data.data.key);
+```
+
+Returns: `Promise<VueVoxApiResponse<LeadCustomFieldResponse>>`.
+
+### `vuevox.leadCustomFields.update(key, input)`
+
+Updates mutable metadata for a lead custom field definition. Field keys and types are immutable.
+
+Required scope: `lead_custom_fields:manage`.
+
+Input: `LeadCustomFieldUpdateRequest`
+
+```ts
+await vuevox.leadCustomFields.update("crm_stage", {
+  label: "CRM Pipeline Stage",
+  archived: false,
+});
+```
+
+Returns: `Promise<VueVoxApiResponse<LeadCustomFieldResponse>>`.
+
 ## Lower-Level Calls
 
 For advanced integrations, `raw` exposes a typed lower-level OpenAPI client. You must attach authorization yourself.
@@ -428,7 +655,17 @@ 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
 ```
 
 ## Retries
@@ -483,23 +720,37 @@ import 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,
   VueVoxErrorResponse,
   VueVoxResponseEvent,
   VueVoxResponseMetadata,
+  WaitForAnalysisOptions,
 } from "@vuevox/sdk";
 ```
 

package/dist/client.d.ts

@@ -1,15 +1,35 @@
 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 type HelloResponse = components["schemas"]["HelloResponse"];
+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"];
+export type LeadCustomFieldResponse = components["schemas"]["LeadCustomFieldResponse"];
+export type LeadCustomFieldCreateRequest = components["schemas"]["LeadCustomFieldCreateRequest"];
+export type LeadCustomFieldUpdateRequest = components["schemas"]["LeadCustomFieldUpdateRequest"];
+export type LeadUpsertRequest = components["schemas"]["LeadUpsertRequest"];
+export type LeadUpdateRequest = components["schemas"]["LeadUpdateRequest"];
+export type Space = components["schemas"]["Space"];
+export type Agent = components["schemas"]["Agent"];
+export type CallSummary = components["schemas"]["CallSummary"];
+export type Lead = components["schemas"]["Lead"];
+export type LeadCustomField = components["schemas"]["LeadCustomField"];
+export type CustomFieldFilterValue = string | number | boolean | {
+    eq?: string | number | boolean;
+    gt?: string | number;
+    gte?: string | number;
+    lt?: string | number;
+    lte?: string | number;
+    before?: string;
+    after?: string;
+    contains?: string;
+};
+export type CustomFieldFilters = Record<string, CustomFieldFilterValue>;
 export interface ListSpacesOptions {
     limit?: number;
     cursor?: string;
@@ -20,6 +40,18 @@ export interface ListCallsOptions extends ListSpacesOptions {
     agentId?: string;
     createdAfter?: string;
     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;
@@ -28,6 +60,10 @@ export interface ListLeadsOptions extends ListSpacesOptions {
     spaceId?: string;
     createdAfter?: string;
     createdBefore?: string;
+    customFields?: CustomFieldFilters;
+}
+export interface ListLeadCustomFieldsOptions {
+    includeArchived?: boolean;
 }
 export interface VueVoxResponseMetadata {
     requestId?: string;
@@ -81,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"];
@@ -98,6 +138,8 @@ export declare function createVueVoxClient(options: VueVoxClientOptions): {
     leads: {
         list: (listOptions?: ListLeadsOptions) => Promise<VueVoxApiResponse<LeadsListResponse>>;
         get: (leadId: string) => Promise<VueVoxApiResponse<LeadDetailResponse>>;
+        update: (leadId: string, input: LeadUpdateRequest) => Promise<VueVoxApiResponse<LeadDetailResponse>>;
+        upsertByExternalId: (externalId: string, input: LeadUpsertRequest) => Promise<VueVoxApiResponse<LeadDetailResponse>>;
         paginate: (listOptions?: ListLeadsOptions) => AsyncGenerator<{
             id: string;
             externalId: string | null;
@@ -105,11 +147,16 @@ export declare function createVueVoxClient(options: VueVoxClientOptions): {
             lastName: string;
             email: string | null;
             phone: string | null;
+            customFields: components["schemas"]["CustomFields"];
             space: components["schemas"]["ResourceSummary"];
             createdAt: string;
             updatedAt: string;
         }, any, any>;
     };
+    leadCustomFields: {
+        list: (listOptions?: ListLeadCustomFieldsOptions) => Promise<VueVoxApiResponse<LeadCustomFieldsListResponse>>;
+        create: (input: LeadCustomFieldCreateRequest) => Promise<VueVoxApiResponse<LeadCustomFieldResponse>>;
+        update: (key: string, input: LeadCustomFieldUpdateRequest) => Promise<VueVoxApiResponse<LeadCustomFieldResponse>>;
+    };
     raw: import("openapi-fetch").Client<paths, `${string}/${string}`>;
 };
-export type { Agent, AgentsListResponse, CallDetailResponse, CallsListResponse, CallSummary, HelloResponse, Lead, LeadDetailResponse, LeadsListResponse, Space, SpacesListResponse };

package/dist/client.js

@@ -46,12 +46,55 @@ 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);
     }
     async function getLead(leadId) {
         return apiGet(`/v1/leads/${encodeURIComponent(leadId)}`);
     }
+    async function updateLead(leadId, input) {
+        return apiJson("PATCH", `/v1/leads/${encodeURIComponent(leadId)}`, input);
+    }
+    async function upsertLeadByExternalId(externalId, input) {
+        return apiJson("PUT", `/v1/leads/by-external-id/${encodeURIComponent(externalId)}`, input);
+    }
+    async function listLeadCustomFields(listOptions = {}) {
+        return apiGet("/v1/lead-custom-fields", listOptions);
+    }
+    async function createLeadCustomField(input) {
+        return apiJson("POST", "/v1/lead-custom-fields", input);
+    }
+    async function updateLeadCustomField(key, input) {
+        return apiJson("PATCH", `/v1/lead-custom-fields/${encodeURIComponent(key)}`, input);
+    }
     async function apiGet(path, query) {
         const accessToken = await getAccessToken();
         const result = await requestJson("GET", path, {
@@ -63,6 +106,30 @@ export function createVueVoxClient(options) {
         });
         return withMetadata(result.data, result.response, result.requestId);
     }
+    async function apiJson(method, path, body) {
+        const accessToken = await getAccessToken();
+        const result = await requestJson(method, path, {
+            method,
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        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);
@@ -76,7 +143,7 @@ export function createVueVoxClient(options) {
                 }
                 return { data: body, requestId, response };
             }
-            if (attempt < retries && shouldRetry(response.status)) {
+            if (attempt < retries && (method === "GET" || path === "/oauth/token") && shouldRetry(response.status)) {
                 await sleep(retryDelayMs(attempt, retryAfter));
                 continue;
             }
@@ -106,13 +173,23 @@ export function createVueVoxClient(options) {
         calls: {
             list: listCalls,
             get: getCall,
+            upload: uploadCall,
+            queueAnalysis: queueCallAnalysis,
+            waitForAnalysis: waitForCallAnalysis,
             paginate: (listOptions = {}) => paginate(listCalls, listOptions),
         },
         leads: {
             list: listLeads,
             get: getLead,
+            update: updateLead,
+            upsertByExternalId: upsertLeadByExternalId,
             paginate: (listOptions = {}) => paginate(listLeads, listOptions),
         },
+        leadCustomFields: {
+            list: listLeadCustomFields,
+            create: createLeadCustomField,
+            update: updateLeadCustomField,
+        },
         raw,
     };
 }
@@ -127,12 +204,27 @@ function trimTrailingSlash(value) {
 }
 function buildUrl(baseUrl, path, query) {
     const url = new URL(`${baseUrl}${path}`);
-    for (const [key, value] of Object.entries(query ?? {})) {
-        if ((typeof value === "string" || typeof value === "number") && value !== "") {
-            url.searchParams.set(key, String(value));
+    appendQueryParams(url.searchParams, query ?? {});
+    return url.toString();
+}
+function appendQueryParams(searchParams, query, prefix) {
+    for (const [rawKey, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === "") {
+            continue;
+        }
+        const key = queryKey(rawKey, prefix);
+        if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+            searchParams.set(key, String(value));
+            continue;
+        }
+        if (typeof value === "object" && !Array.isArray(value)) {
+            appendQueryParams(searchParams, value, key);
         }
     }
-    return url.toString();
+}
+function queryKey(key, prefix) {
+    const publicKey = key === "customFields" ? "custom" : key === "leadCustomFields" ? "leadCustom" : key;
+    return prefix ? `${prefix}[${publicKey}]` : publicKey;
 }
 async function parseJson(response) {
     try {

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;
@@ -161,9 +185,77 @@ export interface paths {
         delete?: never;
         options?: never;
         head?: never;
+        /**
+         * Update a lead
+         * @description Updates an organization-scoped lead and its custom fields.
+         */
+        patch: operations["updateLead"];
+        trace?: never;
+    };
+    "/v1/leads/by-external-id/{externalId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Upsert a lead by external ID
+         * @description Creates or updates a lead identified by the CRM/system external ID.
+         */
+        put: operations["upsertLeadByExternalId"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/lead-custom-fields": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List lead custom field definitions
+         * @description Returns lead custom field definitions for the API client's organization.
+         */
+        get: operations["listLeadCustomFields"];
+        put?: never;
+        /**
+         * Create a lead custom field definition
+         * @description Creates a typed lead custom field definition for CRM integrations and platform filters.
+         */
+        post: operations["createLeadCustomField"];
+        delete?: never;
+        options?: never;
+        head?: never;
         patch?: never;
         trace?: never;
     };
+    "/v1/lead-custom-fields/{key}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /**
+         * Update a lead custom field definition
+         * @description Updates mutable metadata for a lead custom field definition. Keys and types are immutable.
+         */
+        patch: operations["updateLeadCustomField"];
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -175,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
+             * @example hello:read spaces:read agents:read calls:read calls:write leads:read leads:write lead_custom_fields:manage
              */
             scope?: string;
         };
@@ -185,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 */
+            /** @example hello:read spaces:read agents:read calls:read calls:write leads:read leads:write lead_custom_fields:manage */
             scope: string;
         };
         HelloResponse: {
@@ -237,6 +329,7 @@ export interface components {
             externalId: string | null;
             firstName: string;
             lastName: string;
+            customFields: components["schemas"]["CustomFields"];
         } | null;
         AgentSummary: {
             /** Format: uuid */
@@ -248,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"];
@@ -288,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;
@@ -298,6 +431,7 @@ export interface components {
             /** Format: email */
             email: string | null;
             phone: string | null;
+            customFields: components["schemas"]["CustomFields"];
             space: components["schemas"]["ResourceSummary"];
             /** Format: date-time */
             createdAt: string;
@@ -311,6 +445,72 @@ export interface components {
         LeadDetailResponse: {
             data: components["schemas"]["Lead"];
         };
+        LeadUpsertRequest: {
+            firstName: string;
+            lastName: string;
+            /** Format: email */
+            email?: string | null;
+            phone?: string | null;
+            /** Format: uuid */
+            spaceId?: string | null;
+            customFields?: components["schemas"]["CustomFields"];
+        };
+        LeadUpdateRequest: {
+            firstName?: string;
+            lastName?: string;
+            /** Format: email */
+            email?: string | null;
+            phone?: string | null;
+            /** Format: uuid */
+            spaceId?: string | null;
+            customFields?: components["schemas"]["CustomFields"];
+        };
+        /** @description Lead custom field values keyed by custom field key. */
+        CustomFields: {
+            [key: string]: string | number | boolean | string[] | null;
+        };
+        /** @description Custom field filters keyed by custom field key. Scalar values use equality; objects specify one operator. */
+        CustomFieldFilters: {
+            [key: string]: string | number | boolean | {
+                [key: string]: string | number | boolean;
+            };
+        };
+        LeadCustomField: {
+            /** @example crm_stage */
+            key: string;
+            /** @example CRM Stage */
+            label: string;
+            /** @enum {string} */
+            type: "text" | "number" | "boolean" | "date" | "datetime" | "select" | "multi_select";
+            options: string[];
+            isFilterable: boolean;
+            archived: boolean;
+            /** Format: date-time */
+            createdAt: string;
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        LeadCustomFieldsListResponse: {
+            data: components["schemas"]["LeadCustomField"][];
+        };
+        LeadCustomFieldResponse: {
+            data: components["schemas"]["LeadCustomField"];
+        };
+        LeadCustomFieldCreateRequest: {
+            key: string;
+            label: string;
+            /** @enum {string} */
+            type: "text" | "number" | "boolean" | "date" | "datetime" | "select" | "multi_select";
+            options?: string[];
+            /** @default true */
+            isFilterable: boolean;
+        };
+        LeadCustomFieldUpdateRequest: {
+            label?: string;
+            options?: string[];
+            isFilterable?: boolean;
+            archived?: boolean;
+        };
         CursorPagination: {
             /** @example 50 */
             limit: number;
@@ -593,6 +793,8 @@ export interface operations {
                 createdAfter?: string;
                 /** @description Return calls created at or before this timestamp. */
                 createdBefore?: string;
+                /** @description Filter calls by lead custom fields. Use equality by default, or one operator such as gte, lte, contains, before, or after. */
+                leadCustom?: components["schemas"]["CustomFieldFilters"];
             };
             header?: never;
             path?: never;
@@ -651,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;
@@ -714,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?: {
@@ -727,6 +1068,8 @@ export interface operations {
                 createdAfter?: string;
                 /** @description Return leads created at or before this timestamp. */
                 createdBefore?: string;
+                /** @description Filter leads by custom fields. Use equality by default, or one operator such as gte, lte, contains, before, or after. */
+                custom?: components["schemas"]["CustomFieldFilters"];
             };
             header?: never;
             path?: never;
@@ -848,4 +1191,294 @@ export interface operations {
             };
         };
     };
+    updateLead: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Lead ID. */
+                leadId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LeadUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description Lead updated. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LeadDetailResponse"];
+                };
+            };
+            /** @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 Lead was not found in the API client's organization. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Request body failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    upsertLeadByExternalId: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description External lead ID from the integrating system. */
+                externalId: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LeadUpsertRequest"];
+            };
+        };
+        responses: {
+            /** @description Existing lead updated. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LeadDetailResponse"];
+                };
+            };
+            /** @description New lead created. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LeadDetailResponse"];
+                };
+            };
+            /** @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 Request body failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    listLeadCustomFields: {
+        parameters: {
+            query?: {
+                /** @description Include archived field definitions. */
+                includeArchived?: boolean;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Lead custom field definitions. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LeadCustomFieldsListResponse"];
+                };
+            };
+            /** @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"];
+                };
+            };
+        };
+    };
+    createLeadCustomField: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LeadCustomFieldCreateRequest"];
+            };
+        };
+        responses: {
+            /** @description Lead custom field created. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LeadCustomFieldResponse"];
+                };
+            };
+            /** @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 A custom field with this key already exists. */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Request body failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
+    updateLeadCustomField: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Custom field key. */
+                key: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LeadCustomFieldUpdateRequest"];
+            };
+        };
+        responses: {
+            /** @description Lead custom field updated. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["LeadCustomFieldResponse"];
+                };
+            };
+            /** @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 Custom field was not found in the API client's organization. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description Request body failed validation. */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { createVueVoxClient } 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 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.6.0",
+  "version": "0.8.0",
   "description": "TypeScript SDK for the VueVox Developer API.",
   "type": "module",
   "main": "./dist/index.js",