@vuevox/sdk 0.8.0 → 0.9.1

package/README.md

@@ -35,6 +35,8 @@ calls:write
 leads:read
 leads:write
 lead_custom_fields:manage
+webhooks:read
+webhooks:write
 ```
 
 The token request can only request scopes that were granted to that API client.
@@ -117,6 +119,12 @@ 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.webhooks.endpoints.list();
+vuevox.webhooks.endpoints.create({ url: "https://example.com/vuevox/webhooks", events: ["analysis.completed", "analysis.failed"] });
+vuevox.webhooks.endpoints.update("endpoint-id", { isActive: false });
+vuevox.webhooks.endpoints.rotateSecret("endpoint-id");
+vuevox.webhooks.endpoints.test("endpoint-id");
+vuevox.webhooks.endpoints.delete("endpoint-id");
 vuevox.raw.GET("/v1/hello", { headers: { Authorization: `Bearer ${await vuevox.getAccessToken()}` } });
 ```
 
@@ -164,7 +172,7 @@ for await (const call of vuevox.calls.paginate({ limit: 50 })) {
 }
 ```
 
-Pagination helpers are available for `spaces`, `agents`, `calls`, and `leads`.
+Pagination helpers are available for `spaces`, `agents`, `calls`, `leads`, and `webhooks.endpoints`.
 
 ## Methods
 
@@ -346,8 +354,9 @@ Options: `UploadCallInput`
 | `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.file` | `Blob \| ArrayBuffer \| Uint8Array` | Required audio file data. In Node, a `Buffer` from `readFile()` can be passed directly. |
 | `audio.filename` | `string` | Optional filename sent in multipart upload. |
+| `audio.contentType` | `string` | Optional MIME type, for example `audio/mpeg`. |
 
 ```ts
 import { readFile } from "node:fs/promises";
@@ -373,8 +382,9 @@ const response = await vuevox.calls.upload({
     },
   },
   audio: {
-    file: new Blob([buffer], { type: "audio/mpeg" }),
+    file: buffer,
     filename: "call.mp3",
+    contentType: "audio/mpeg",
   },
 });
 
@@ -601,6 +611,126 @@ await vuevox.leadCustomFields.update("crm_stage", {
 
 Returns: `Promise<VueVoxApiResponse<LeadCustomFieldResponse>>`.
 
+### `vuevox.webhooks.endpoints.list(options?)`
+
+Lists webhook endpoints for the authenticated API client.
+
+Required scope: `webhooks:read`.
+
+Options: `ListWebhookEndpointsOptions`
+
+```ts
+const response = await vuevox.webhooks.endpoints.list({ limit: 50 });
+console.log(response.data.data);
+```
+
+Returns: `Promise<VueVoxApiResponse<WebhookEndpointsListResponse>>`.
+
+### `vuevox.webhooks.endpoints.create(input)`
+
+Creates a webhook endpoint. The signing secret is returned only once in this response.
+
+Required scope: `webhooks:write`.
+
+Input: `WebhookEndpointCreateRequest`
+
+```ts
+const response = await vuevox.webhooks.endpoints.create({
+  url: "https://example.com/vuevox/webhooks",
+  events: ["analysis.completed", "analysis.failed"],
+});
+
+console.log(response.data.data.id, response.data.data.secret);
+```
+
+Returns: `Promise<VueVoxApiResponse<WebhookEndpointSecretResponse>>`.
+
+### `vuevox.webhooks.endpoints.update(endpointId, input)`
+
+Updates a webhook endpoint URL, event subscriptions, or active state.
+
+Required scope: `webhooks:write`.
+
+Input: `WebhookEndpointUpdateRequest`
+
+```ts
+const response = await vuevox.webhooks.endpoints.update("endpoint-id", {
+  events: ["analysis.completed"],
+  isActive: true,
+});
+```
+
+Returns: `Promise<VueVoxApiResponse<WebhookEndpointResponse>>`.
+
+### `vuevox.webhooks.endpoints.delete(endpointId)`
+
+Deletes a webhook endpoint.
+
+Required scope: `webhooks:write`.
+
+```ts
+await vuevox.webhooks.endpoints.delete("endpoint-id");
+```
+
+Returns: `Promise<VueVoxApiResponse<null>>`.
+
+### `vuevox.webhooks.endpoints.rotateSecret(endpointId)`
+
+Rotates the endpoint signing secret. The new secret is returned only once.
+
+Required scope: `webhooks:write`.
+
+```ts
+const response = await vuevox.webhooks.endpoints.rotateSecret("endpoint-id");
+console.log(response.data.data.secret);
+```
+
+Returns: `Promise<VueVoxApiResponse<WebhookEndpointSecretResponse>>`.
+
+### `vuevox.webhooks.endpoints.test(endpointId)`
+
+Queues a `webhook.test` delivery to validate endpoint reachability and signature verification.
+
+Required scope: `webhooks:write`.
+
+```ts
+const response = await vuevox.webhooks.endpoints.test("endpoint-id");
+console.log(response.data.data.eventType, response.data.data.status);
+```
+
+Returns: `Promise<VueVoxApiResponse<WebhookTestResponse>>`.
+
+### `vuevox.webhooks.endpoints.paginate(options?)`
+
+Iterates webhook endpoints across all pages.
+
+Required scope: `webhooks:read`.
+
+```ts
+for await (const endpoint of vuevox.webhooks.endpoints.paginate({ limit: 50 })) {
+  console.log(endpoint.id, endpoint.events);
+}
+```
+
+Returns: `AsyncGenerator<WebhookEndpoint>`.
+
+### `verifyVueVoxWebhookSignature(input)`
+
+Verifies a webhook HMAC signature. Pass the raw request body string exactly as received.
+
+```ts
+import { verifyVueVoxWebhookSignature } from "@vuevox/sdk";
+
+const valid = await verifyVueVoxWebhookSignature({
+  body: rawBody,
+  secret: process.env.VUEVOX_WEBHOOK_SECRET!,
+  signature: request.headers.get("VueVox-Signature") ?? "",
+  timestamp: request.headers.get("VueVox-Timestamp") ?? "",
+});
+```
+
+Returns: `Promise<boolean>`.
+
 ## Lower-Level Calls
 
 For advanced integrations, `raw` exposes a typed lower-level OpenAPI client. You must attach authorization yourself.
@@ -654,6 +784,7 @@ invalid_scope
 insufficient_scope
 rate_limited
 invalid_request
+internal_error
 call_not_found
 call_external_id_conflict
 analysis_already_queued
@@ -742,15 +873,25 @@ import type {
   ListLeadCustomFieldsOptions,
   ListLeadsOptions,
   ListSpacesOptions,
+  ListWebhookEndpointsOptions,
   Space,
   SpacesListResponse,
   UploadCallInput,
+  VerifyWebhookSignatureInput,
   VueVoxApiResponse,
   VueVoxClientOptions,
   VueVoxErrorResponse,
   VueVoxResponseEvent,
   VueVoxResponseMetadata,
   WaitForAnalysisOptions,
+  WebhookEndpoint,
+  WebhookEndpointCreateRequest,
+  WebhookEndpointResponse,
+  WebhookEndpointSecretResponse,
+  WebhookEndpointUpdateRequest,
+  WebhookEndpointsListResponse,
+  WebhookEventPayload,
+  WebhookTestResponse,
 } from "@vuevox/sdk";
 ```
 

package/dist/client.d.ts

@@ -12,6 +12,14 @@ export type LeadCustomFieldsListResponse = components["schemas"]["LeadCustomFiel
 export type LeadCustomFieldResponse = components["schemas"]["LeadCustomFieldResponse"];
 export type LeadCustomFieldCreateRequest = components["schemas"]["LeadCustomFieldCreateRequest"];
 export type LeadCustomFieldUpdateRequest = components["schemas"]["LeadCustomFieldUpdateRequest"];
+export type WebhookEndpoint = components["schemas"]["WebhookEndpoint"];
+export type WebhookEndpointCreateRequest = components["schemas"]["WebhookEndpointCreateRequest"];
+export type WebhookEndpointUpdateRequest = components["schemas"]["WebhookEndpointUpdateRequest"];
+export type WebhookEndpointResponse = components["schemas"]["WebhookEndpointResponse"];
+export type WebhookEndpointSecretResponse = components["schemas"]["WebhookEndpointSecretResponse"];
+export type WebhookEndpointsListResponse = components["schemas"]["WebhookEndpointsListResponse"];
+export type WebhookTestResponse = components["schemas"]["WebhookTestResponse"];
+export type WebhookEventPayload = components["schemas"]["WebhookEventPayload"];
 export type LeadUpsertRequest = components["schemas"]["LeadUpsertRequest"];
 export type LeadUpdateRequest = components["schemas"]["LeadUpdateRequest"];
 export type Space = components["schemas"]["Space"];
@@ -45,8 +53,9 @@ export interface ListCallsOptions extends ListSpacesOptions {
 export interface UploadCallInput extends CallUploadMetadata {
     idempotencyKey: string;
     audio: {
-        file: Blob;
+        file: Blob | ArrayBuffer | Uint8Array;
         filename?: string;
+        contentType?: string;
     };
 }
 export interface WaitForAnalysisOptions {
@@ -65,6 +74,16 @@ export interface ListLeadsOptions extends ListSpacesOptions {
 export interface ListLeadCustomFieldsOptions {
     includeArchived?: boolean;
 }
+export interface ListWebhookEndpointsOptions extends ListSpacesOptions {
+}
+export interface VerifyWebhookSignatureInput {
+    body: string;
+    secret: string;
+    signature: string;
+    timestamp: string;
+    toleranceSeconds?: number;
+    now?: number;
+}
 export interface VueVoxResponseMetadata {
     requestId?: string;
     status: number;
@@ -158,5 +177,25 @@ export declare function createVueVoxClient(options: VueVoxClientOptions): {
         create: (input: LeadCustomFieldCreateRequest) => Promise<VueVoxApiResponse<LeadCustomFieldResponse>>;
         update: (key: string, input: LeadCustomFieldUpdateRequest) => Promise<VueVoxApiResponse<LeadCustomFieldResponse>>;
     };
+    webhooks: {
+        endpoints: {
+            list: (listOptions?: ListWebhookEndpointsOptions) => Promise<VueVoxApiResponse<WebhookEndpointsListResponse>>;
+            create: (input: WebhookEndpointCreateRequest) => Promise<VueVoxApiResponse<WebhookEndpointSecretResponse>>;
+            update: (endpointId: string, input: WebhookEndpointUpdateRequest) => Promise<VueVoxApiResponse<WebhookEndpointResponse>>;
+            delete: (endpointId: string) => Promise<VueVoxApiResponse<null>>;
+            rotateSecret: (endpointId: string) => Promise<VueVoxApiResponse<WebhookEndpointSecretResponse>>;
+            test: (endpointId: string) => Promise<VueVoxApiResponse<WebhookTestResponse>>;
+            paginate: (listOptions?: ListWebhookEndpointsOptions) => AsyncGenerator<{
+                id: string;
+                url: string;
+                events: components["schemas"]["WebhookEventType"][];
+                isActive: boolean;
+                lastDeliveredAt: string | null;
+                createdAt: string;
+                updatedAt: string;
+            }, any, any>;
+        };
+    };
     raw: import("openapi-fetch").Client<paths, `${string}/${string}`>;
 };
+export declare function verifyVueVoxWebhookSignature(input: VerifyWebhookSignatureInput): Promise<boolean>;

package/dist/client.js

@@ -50,7 +50,7 @@ export function createVueVoxClient(options) {
         const { audio, idempotencyKey, ...metadata } = input;
         const formData = new FormData();
         formData.set("metadata", JSON.stringify(metadata));
-        formData.set("audioFile", audio.file, audio.filename ?? "call-audio");
+        formData.set("audioFile", toUploadBlob(audio.file, audio.contentType), audio.filename ?? "call-audio");
         return apiMultipart("POST", "/v1/calls", formData, {
             "Idempotency-Key": idempotencyKey,
         });
@@ -95,6 +95,24 @@ export function createVueVoxClient(options) {
     async function updateLeadCustomField(key, input) {
         return apiJson("PATCH", `/v1/lead-custom-fields/${encodeURIComponent(key)}`, input);
     }
+    async function listWebhookEndpoints(listOptions = {}) {
+        return apiGet("/v1/webhooks/endpoints", listOptions);
+    }
+    async function createWebhookEndpoint(input) {
+        return apiJson("POST", "/v1/webhooks/endpoints", input);
+    }
+    async function updateWebhookEndpoint(endpointId, input) {
+        return apiJson("PATCH", `/v1/webhooks/endpoints/${encodeURIComponent(endpointId)}`, input);
+    }
+    async function deleteWebhookEndpoint(endpointId) {
+        return apiDelete(`/v1/webhooks/endpoints/${encodeURIComponent(endpointId)}`);
+    }
+    async function rotateWebhookEndpointSecret(endpointId) {
+        return apiJson("POST", `/v1/webhooks/endpoints/${encodeURIComponent(endpointId)}/rotate-secret`, {});
+    }
+    async function testWebhookEndpoint(endpointId) {
+        return apiJson("POST", `/v1/webhooks/endpoints/${encodeURIComponent(endpointId)}/test`, {});
+    }
     async function apiGet(path, query) {
         const accessToken = await getAccessToken();
         const result = await requestJson("GET", path, {
@@ -118,6 +136,24 @@ export function createVueVoxClient(options) {
         });
         return withMetadata(result.data, result.response, result.requestId);
     }
+    async function apiDelete(path) {
+        const accessToken = await getAccessToken();
+        const response = await fetchFn(buildUrl(baseUrl, path, undefined), {
+            method: "DELETE",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+        });
+        const body = await parseJson(response);
+        const requestId = getRequestId(response, body);
+        const retryAfter = retryAfterSeconds(response);
+        notifyResponse(options, "DELETE", path, response, requestId, retryAfter);
+        if (response.ok) {
+            return withMetadata(null, response, requestId);
+        }
+        const error = isErrorResponse(body) ? body.error : null;
+        throw new VueVoxApiError(response.status, error?.code ?? "api_request_failed", error?.message ?? "VueVox API request failed.", isErrorResponse(body) ? body : undefined, requestId, retryAfter);
+    }
     async function apiMultipart(method, path, body, headers) {
         const accessToken = await getAccessToken();
         const result = await requestJson(method, path, {
@@ -190,9 +226,34 @@ export function createVueVoxClient(options) {
             create: createLeadCustomField,
             update: updateLeadCustomField,
         },
+        webhooks: {
+            endpoints: {
+                list: listWebhookEndpoints,
+                create: createWebhookEndpoint,
+                update: updateWebhookEndpoint,
+                delete: deleteWebhookEndpoint,
+                rotateSecret: rotateWebhookEndpointSecret,
+                test: testWebhookEndpoint,
+                paginate: (listOptions = {}) => paginate(listWebhookEndpoints, listOptions),
+            },
+        },
         raw,
     };
 }
+export async function verifyVueVoxWebhookSignature(input) {
+    const toleranceSeconds = input.toleranceSeconds ?? 300;
+    const now = input.now ?? Date.now();
+    const timestampSeconds = Number(input.timestamp);
+    if (!Number.isFinite(timestampSeconds)) {
+        return false;
+    }
+    if (Math.abs(Math.floor(now / 1000) - timestampSeconds) > toleranceSeconds) {
+        return false;
+    }
+    const expected = await hmacSha256Hex(input.secret, `${input.timestamp}.${input.body}`);
+    const provided = input.signature.startsWith("v1=") ? input.signature.slice(3) : input.signature;
+    return constantTimeEqual(expected, provided);
+}
 function formatScope(scope) {
     if (Array.isArray(scope)) {
         return scope.join(" ");
@@ -256,6 +317,12 @@ function withMetadata(data, response, requestId) {
         status: response.status,
     };
 }
+function toUploadBlob(file, contentType) {
+    if (file instanceof Blob) {
+        return contentType && file.type !== contentType ? new Blob([file], { type: contentType }) : file;
+    }
+    return new Blob([file], { type: contentType });
+}
 function notifyResponse(options, method, path, response, requestId, retryAfter) {
     options.onResponse?.({
         method,
@@ -293,3 +360,18 @@ function retryAfterSeconds(response) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+async function hmacSha256Hex(secret, value) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(value));
+    return [...new Uint8Array(signature)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    let result = 0;
+    for (let index = 0; index < left.length; index++) {
+        result |= left.charCodeAt(index) ^ right.charCodeAt(index);
+    }
+    return result === 0;
+}