@voiflow/sdk 0.0.0-stage → 0.1.0

package/dist/cjs/webhooks.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookSignatureError = exports.SIGNATURE_HEADER = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.parseWebhookEvent = parseWebhookEvent;
+const node_crypto_1 = require("node:crypto");
+exports.SIGNATURE_HEADER = "VoiFlow-Signature";
+class WebhookSignatureError extends Error {
+}
+exports.WebhookSignatureError = WebhookSignatureError;
+/**
+ * Verifies `VoiFlow-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>` against the raw request
+ * body bytes. Signed payload is the UTF-8 timestamp, a literal period, then the raw bytes.
+ */
+function verifyWebhookSignature(rawBody, signatureHeader, secret, options = {}) {
+    const tolerance = options.toleranceSeconds ?? 300;
+    const now = options.now ?? (() => Date.now() / 1000);
+    const parts = Object.fromEntries(signatureHeader.split(",").map((part) => {
+        const [key, value] = part.split("=", 2);
+        return [key, value];
+    }));
+    const timestamp = parts["t"];
+    const signature = parts["v1"];
+    if (!timestamp || !signature) {
+        throw new WebhookSignatureError("Malformed VoiFlow-Signature header.");
+    }
+    const timestampSeconds = Number(timestamp);
+    if (!Number.isFinite(timestampSeconds) || Math.abs(now() - timestampSeconds) > tolerance) {
+        throw new WebhookSignatureError("Webhook timestamp is outside the allowed tolerance.");
+    }
+    const signedPayload = Buffer.concat([
+        Buffer.from(timestamp, "utf8"),
+        Buffer.from(".", "utf8"),
+        Buffer.from(rawBody),
+    ]);
+    const expected = (0, node_crypto_1.createHmac)("sha256", secret).update(signedPayload).digest("hex");
+    const expectedBuf = Buffer.from(expected, "utf8");
+    const actualBuf = Buffer.from(signature, "utf8");
+    if (expectedBuf.length !== actualBuf.length || !(0, node_crypto_1.timingSafeEqual)(expectedBuf, actualBuf)) {
+        throw new WebhookSignatureError("Webhook signature does not match.");
+    }
+}
+/** Parses the verified webhook body. Call verifyWebhookSignature first. */
+function parseWebhookEvent(rawBody) {
+    return JSON.parse(Buffer.from(rawBody).toString("utf8"));
+}

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+import { ClientOptions, HttpClient } from "./http.js";
+import { GeneratedResources } from "./resources.generated.js";
+/** Server-side client. Every published /v1 resource group is a property (`client.agents`, `client.aiWork`, ...). */
+export declare class VoiFlowClient extends GeneratedResources {
+    private readonly transport;
+    constructor(options: ClientOptions);
+    get environment(): "live" | "test";
+}
+export { HttpClient, ClientOptions };
+export * from "./resources.generated.js";
+export { VoiFlowError, VoiFlowConnectionError, VoiFlowOperationPending } from "./errors.js";
+export { verifyWebhookSignature, parseWebhookEvent, WebhookSignatureError, SIGNATURE_HEADER } from "./webhooks.js";
+export type { VoiFlowEvent } from "./webhooks.js";
+export type { SSEEvent } from "./sse.js";

package/dist/client.js

@@ -0,0 +1,18 @@
+import { HttpClient } from "./http.js";
+import { GeneratedResources } from "./resources.generated.js";
+/** Server-side client. Every published /v1 resource group is a property (`client.agents`, `client.aiWork`, ...). */
+export class VoiFlowClient extends GeneratedResources {
+    transport;
+    constructor(options) {
+        const http = new HttpClient(options);
+        super(http);
+        this.transport = http;
+    }
+    get environment() {
+        return this.transport.environment;
+    }
+}
+export { HttpClient };
+export * from "./resources.generated.js";
+export { VoiFlowError, VoiFlowConnectionError, VoiFlowOperationPending } from "./errors.js";
+export { verifyWebhookSignature, parseWebhookEvent, WebhookSignatureError, SIGNATURE_HEADER } from "./webhooks.js";

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+export interface VoiFlowErrorBody {
+    code: string;
+    message: string;
+    request_id?: string;
+    details?: unknown;
+    /** Present on some errors (per the published error schema) to point at a pending operation. */
+    operation_id?: string;
+    /** Present on some errors (per the published error schema) with a resumable action link. */
+    status_url?: string;
+}
+/** Thrown for any non-2xx API response or a request that could not be sent. */
+export declare class VoiFlowError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly requestId?: string;
+    readonly details?: unknown;
+    readonly operationId?: string;
+    readonly statusUrl?: string;
+    /** The Idempotency-Key the failed call used; pass it back to retry the same logical operation. */
+    idempotencyKey?: string;
+    constructor(status: number, body: VoiFlowErrorBody);
+}
+/** The request never reached the server or the response could not be parsed (unknown outcome). */
+export declare class VoiFlowConnectionError extends Error {
+    readonly cause?: unknown;
+    /** The Idempotency-Key the call used; pass it back to retry without repeating the action. */
+    idempotencyKey?: string;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * HTTP 202: the server accepted the request but its outcome is not yet known. The action may still
+ * complete, so do not repeat it under a new Idempotency-Key — poll `operations.retrieve(operationId)`
+ * or retry with the same `idempotencyKey`.
+ */
+export declare class VoiFlowOperationPending extends VoiFlowError {
+    constructor(body: VoiFlowErrorBody);
+}

package/dist/errors.js

@@ -0,0 +1,43 @@
+/** Thrown for any non-2xx API response or a request that could not be sent. */
+export class VoiFlowError extends Error {
+    code;
+    status;
+    requestId;
+    details;
+    operationId;
+    statusUrl;
+    /** The Idempotency-Key the failed call used; pass it back to retry the same logical operation. */
+    idempotencyKey;
+    constructor(status, body) {
+        super(body.message);
+        this.name = "VoiFlowError";
+        this.status = status;
+        this.code = body.code;
+        this.requestId = body.request_id;
+        this.details = body.details;
+        this.operationId = body.operation_id;
+        this.statusUrl = body.status_url;
+    }
+}
+/** The request never reached the server or the response could not be parsed (unknown outcome). */
+export class VoiFlowConnectionError extends Error {
+    cause;
+    /** The Idempotency-Key the call used; pass it back to retry without repeating the action. */
+    idempotencyKey;
+    constructor(message, cause) {
+        super(message);
+        this.name = "VoiFlowConnectionError";
+        this.cause = cause;
+    }
+}
+/**
+ * HTTP 202: the server accepted the request but its outcome is not yet known. The action may still
+ * complete, so do not repeat it under a new Idempotency-Key — poll `operations.retrieve(operationId)`
+ * or retry with the same `idempotencyKey`.
+ */
+export class VoiFlowOperationPending extends VoiFlowError {
+    constructor(body) {
+        super(202, body);
+        this.name = "VoiFlowOperationPending";
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,66 @@
+export interface ClientOptions {
+    /** Server secret key: vf_live_... or vf_test_.... Never use a browser key here. */
+    apiKey: string;
+    baseUrl?: string;
+    /** Request timeout in ms, default 30000. */
+    timeoutMs?: number;
+    /** Max automatic retries for safe/idempotent cases, default 2. */
+    maxRetries?: number;
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** State-changing operations: the caller's key, or (when `idempotent`) a generated one. */
+    idempotencyKey?: string;
+    /** Marks a state-changing operation: a stable key is generated once per call if none is given. */
+    idempotent?: boolean;
+    signal?: AbortSignal;
+}
+export interface VoiFlowResponse<T> {
+    data: T;
+    requestId: string | undefined;
+    status: number;
+}
+export interface BinaryResponse {
+    data: Uint8Array;
+    contentType: string;
+    requestId: string | undefined;
+    status: number;
+}
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options: ClientOptions);
+    get environment(): "live" | "test";
+    resolvedUrl(path: string, query?: RequestOptions["query"]): URL;
+    /** Opens an authenticated text/event-stream GET request and returns its raw body. */
+    openStream(path: string, query: RequestOptions["query"], options?: {
+        signal?: AbortSignal;
+        lastEventId?: string;
+    }): Promise<ReadableStream<Uint8Array>>;
+    /** A successful binary response (e.g. a recording or document download) is raw bytes with an
+     * arbitrary content-type, not the {data, request_id} JSON envelope — an error response still is. */
+    requestBinary(method: string, path: string, options?: RequestOptions): Promise<BinaryResponse>;
+    /** Uploads raw bytes with an explicit content-type instead of JSON-serialising an object —
+     * the gateway forwards the body/content-type verbatim for upload routes. */
+    uploadBinary(method: string, path: string, content: Uint8Array, contentType: string, options?: {
+        query?: RequestOptions["query"];
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<VoiFlowResponse<unknown>>;
+    /** Multipart/form-data upload (a document plus optional JSON `metadata`). Idempotent: a stable key is generated once per call. */
+    uploadMultipart(method: string, path: string, file: Blob | Uint8Array, options?: {
+        filename?: string;
+        contentType?: string;
+        metadata?: Record<string, unknown>;
+        businessId?: string;
+        idempotencyKey?: string;
+    }): Promise<VoiFlowResponse<unknown>>;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<VoiFlowResponse<T>>;
+    private parseJsonResponse;
+    private runWithRetry;
+}

package/dist/http.js

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto";
+import { VoiFlowConnectionError, VoiFlowError, VoiFlowOperationPending } from "./errors.js";
+const DEFAULT_BASE_URL = "https://api.voiflow.ai/v1";
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+const REQUEST_ID_HEADER = "VoiFlow-Request-Id";
+function isKeyValid(key) {
+    return key.startsWith("vf_live_") || key.startsWith("vf_test_");
+}
+function assertServerRuntime() {
+    // This SDK holds a secret vf_live_/vf_test_ key. A browser runtime (window + document) means
+    // the key would ship to every visitor; refuse to construct the client at all in that case.
+    const g = globalThis;
+    if (typeof g.window !== "undefined" && typeof g.document !== "undefined") {
+        throw new Error("The VoiFlow SDK holds a secret server credential and must not run in a browser. " +
+            "Use it from your backend and give the browser a short-lived session token instead.");
+    }
+}
+export class HttpClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    constructor(options) {
+        assertServerRuntime();
+        if (!isKeyValid(options.apiKey)) {
+            throw new Error("apiKey must start with vf_live_ or vf_test_; browser/public keys are not supported here.");
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    get environment() {
+        return this.apiKey.startsWith("vf_live_") ? "live" : "test";
+    }
+    resolvedUrl(path, query) {
+        const url = new URL(this.baseUrl + path);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            }
+        }
+        return url;
+    }
+    /** Opens an authenticated text/event-stream GET request and returns its raw body. */
+    async openStream(path, query, options = {}) {
+        const url = this.resolvedUrl(path, query);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "text/event-stream",
+        };
+        if (options.lastEventId)
+            headers["Last-Event-ID"] = options.lastEventId;
+        const response = await this.fetchImpl(url, { headers, signal: options.signal });
+        if (!response.ok || !response.body) {
+            const body = await parseErrorBody(response);
+            throw new VoiFlowError(response.status, body);
+        }
+        return response.body;
+    }
+    /** A successful binary response (e.g. a recording or document download) is raw bytes with an
+     * arbitrary content-type, not the {data, request_id} JSON envelope — an error response still is. */
+    async requestBinary(method, path, options = {}) {
+        const url = this.resolvedUrl(path, options.query);
+        const headers = { Authorization: `Bearer ${this.apiKey}` };
+        const response = await this.runWithRetry(method, url, headers, undefined, options);
+        const requestId = readRequestId(response, undefined);
+        if (!response.ok) {
+            throw new VoiFlowError(response.status, await parseErrorBody(response));
+        }
+        const data = new Uint8Array(await response.arrayBuffer());
+        return { data, contentType: response.headers.get("content-type") ?? "application/octet-stream", requestId, status: response.status };
+    }
+    /** Uploads raw bytes with an explicit content-type instead of JSON-serialising an object —
+     * the gateway forwards the body/content-type verbatim for upload routes. */
+    async uploadBinary(method, path, content, contentType, options = {}) {
+        const url = this.resolvedUrl(path, options.query);
+        const headers = { Authorization: `Bearer ${this.apiKey}`, "Content-Type": contentType, Accept: "application/json" };
+        if (options.idempotencyKey)
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        const response = await this.runWithRetry(method, url, headers, content, { idempotencyKey: options.idempotencyKey, signal: options.signal });
+        return this.parseJsonResponse(response);
+    }
+    /** Multipart/form-data upload (a document plus optional JSON `metadata`). Idempotent: a stable key is generated once per call. */
+    async uploadMultipart(method, path, file, options = {}) {
+        const idempotencyKey = options.idempotencyKey ?? randomUUID();
+        const form = new FormData();
+        const blob = file instanceof Blob ? file : new Blob([file], { type: options.contentType ?? "application/octet-stream" });
+        form.append("file", blob, options.filename ?? "upload");
+        if (options.metadata)
+            form.append("metadata", JSON.stringify(options.metadata));
+        const url = this.resolvedUrl(path, { business_id: options.businessId });
+        // No Content-Type here: fetch sets multipart/form-data with the boundary itself.
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "Idempotency-Key": idempotencyKey,
+        };
+        try {
+            const response = await this.runWithRetry(method, url, headers, form, { idempotencyKey });
+            return await this.parseJsonResponse(response);
+        }
+        catch (err) {
+            if (err instanceof VoiFlowError || err instanceof VoiFlowConnectionError)
+                err.idempotencyKey = idempotencyKey;
+            throw err;
+        }
+    }
+    async request(method, path, options = {}) {
+        const idempotencyKey = options.idempotencyKey ?? (options.idempotent ? randomUUID() : undefined);
+        const url = this.resolvedUrl(path, options.query);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+        };
+        if (idempotencyKey)
+            headers["Idempotency-Key"] = idempotencyKey;
+        let payload;
+        if (options.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            payload = JSON.stringify(options.body);
+        }
+        try {
+            const response = await this.runWithRetry(method, url, headers, payload, { ...options, idempotencyKey });
+            return await this.parseJsonResponse(response);
+        }
+        catch (err) {
+            if (idempotencyKey && (err instanceof VoiFlowError || err instanceof VoiFlowConnectionError)) {
+                err.idempotencyKey = idempotencyKey;
+            }
+            throw err;
+        }
+    }
+    async parseJsonResponse(response) {
+        if (!response.ok) {
+            throw new VoiFlowError(response.status, await parseErrorBody(response));
+        }
+        if (response.status === 204 || response.headers.get("content-length") === "0") {
+            return { data: undefined, requestId: readRequestId(response, undefined), status: response.status };
+        }
+        const parsed = (await response.json());
+        if (response.status === 202 && parsed.error && !("data" in parsed)) {
+            throw new VoiFlowOperationPending({ ...parsed.error, request_id: parsed.error.request_id ?? readRequestId(response, undefined) });
+        }
+        const requestId = readRequestId(response, parsed?.request_id);
+        return { data: parsed, requestId, status: response.status };
+    }
+    async runWithRetry(method, url, headers, body, options) {
+        const isSafeRetry = method === "GET" || options.idempotencyKey !== undefined;
+        let attempt = 0;
+        let lastError;
+        while (attempt <= this.maxRetries) {
+            if (options.signal?.aborted) {
+                throw new VoiFlowConnectionError("Request was cancelled.", options.signal.reason);
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            const cleanupAbortLink = options.signal ? linkSignals(options.signal, controller) : undefined;
+            try {
+                const response = await this.fetchImpl(url, { method, headers, body, signal: controller.signal });
+                clearTimeout(timer);
+                cleanupAbortLink?.();
+                if (RETRYABLE_STATUS.has(response.status) && isSafeRetry && attempt < this.maxRetries) {
+                    const waited = await waitForRetry(retryDelayMs(response, attempt), options.signal);
+                    if (!waited)
+                        throw new VoiFlowConnectionError("Request was cancelled.", options.signal?.reason);
+                    attempt += 1;
+                    continue;
+                }
+                return response;
+            }
+            catch (err) {
+                clearTimeout(timer);
+                cleanupAbortLink?.();
+                if (err instanceof VoiFlowError || err instanceof VoiFlowConnectionError)
+                    throw err;
+                if (options.signal?.aborted) {
+                    throw new VoiFlowConnectionError("Request was cancelled.", options.signal.reason);
+                }
+                lastError = err;
+                if (isSafeRetry && attempt < this.maxRetries) {
+                    const waited = await waitForRetry(retryDelayMs(undefined, attempt), options.signal);
+                    if (!waited)
+                        throw new VoiFlowConnectionError("Request was cancelled.", options.signal?.reason);
+                    attempt += 1;
+                    continue;
+                }
+                throw new VoiFlowConnectionError("VoiFlow API request failed; outcome is unknown.", err);
+            }
+        }
+        throw new VoiFlowConnectionError("VoiFlow API request exhausted retries.", lastError);
+    }
+}
+function readRequestId(response, fromBody) {
+    // VoiFlow-Request-Id is a real response header on every /v1 response (success and error
+    // alike) — the only reliable source for binary/204 responses, which carry no JSON body.
+    return fromBody ?? response.headers.get(REQUEST_ID_HEADER) ?? undefined;
+}
+// The curated contract's error envelope is {error:{code,message,request_id,details?}}, but some
+// routes still raise a plain FastAPI HTTPException ({detail:{code,message}} or {detail:"..."}),
+// and parameter validation failures use FastAPI's own {detail:[{loc,msg,type},...]} shape. All
+// three are observed on the real gateway; handle all three rather than assuming the curated one.
+async function parseErrorBody(response) {
+    const requestId = response.headers.get(REQUEST_ID_HEADER) ?? undefined;
+    try {
+        const json = (await response.json());
+        if (json.error) {
+            return {
+                code: json.error.code,
+                message: json.error.message,
+                request_id: json.error.request_id ?? requestId,
+                details: json.error.details,
+                operation_id: json.error.operation_id,
+                status_url: json.error.status_url,
+            };
+        }
+        if (typeof json.detail === "string") {
+            return { code: "http_error", message: json.detail, request_id: requestId };
+        }
+        if (Array.isArray(json.detail)) {
+            return { code: "unprocessable", message: "the request was not valid", request_id: requestId, details: json.detail };
+        }
+        if (json.detail) {
+            return {
+                code: json.detail.code ?? "http_error",
+                message: json.detail.message ?? `Request failed with status ${response.status}`,
+                request_id: requestId,
+            };
+        }
+    }
+    catch {
+        // body was not JSON; fall through to generic error below
+    }
+    return { code: "unknown_error", message: `Request failed with status ${response.status}`, request_id: requestId };
+}
+function retryDelayMs(response, attempt) {
+    const retryAfter = response?.headers.get("Retry-After");
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (!Number.isNaN(seconds))
+            return seconds * 1000;
+        const whenMs = Date.parse(retryAfter);
+        if (!Number.isNaN(whenMs))
+            return Math.max(0, whenMs - Date.now());
+    }
+    return 250 * 2 ** attempt;
+}
+/** Resolves true after the delay, or false immediately if the signal aborts first — so a
+ * cancelled request doesn't sit out a retry backoff it will never use. */
+function waitForRetry(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve(false);
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Aborts `controller` when `signal` aborts, and always removes its own listener afterward —
+ * each attempt gets its own link instead of accumulating listeners across retries. */
+function linkSignals(signal, controller) {
+    const onAbort = () => controller.abort(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    return () => signal.removeEventListener("abort", onAbort);
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./client.js";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./client.js";

package/dist/pagination.d.ts

@@ -0,0 +1,7 @@
+export interface CursorPage<T> {
+    data: T[];
+    next_cursor: string;
+    request_id?: string;
+}
+/** Lazily walks every page of a cursor-paginated list endpoint. */
+export declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<CursorPage<T>>): AsyncGenerator<T, void, void>;

package/dist/pagination.js

@@ -0,0 +1,12 @@
+/** Lazily walks every page of a cursor-paginated list endpoint. */
+export async function* paginate(fetchPage) {
+    let cursor;
+    while (true) {
+        const page = await fetchPage(cursor);
+        for (const item of page.data)
+            yield item;
+        if (!page.next_cursor)
+            return;
+        cursor = page.next_cursor;
+    }
+}