@pyai/sdk 0.2.0 → 0.2.2

package/dist/index.js

@@ -1,10 +1,9 @@
 /**
- * @pyai/sdk — official TypeScript/JavaScript client for the PyAI API.
+ * @pyai/sdk, official TypeScript/JavaScript client for the PyAI API.
  *
  * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
  * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
- * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque —
- * never parsed.
+ * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque, * never parsed.
  */
 /** Stable, machine-readable error. Branch on `code`, not `message`. */
 export class PyAIError extends Error {
@@ -30,7 +29,7 @@ export const SPEECH_FORMATS = ["wav", "mp3", "opus", "aac", "flac", "pcm", "g711
 /** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
 export const SPEECH_SAMPLE_RATES = [8000, 16000, 24000, 48000];
 /* ------------------------------------------------------------------------- *
- * Stable enums — mirror the server so callers branch on named constants, not
+ * Stable enums, mirror the server so callers branch on named constants, not
  * magic strings, and a contract change surfaces in one place. These are plain
  * `as const` objects (not TS `enum`s) so the source still runs directly under
  * Node's type-stripping and stays tree-shakeable.
@@ -45,6 +44,8 @@ export const HearFrameType = {
     SpeechFinal: "speech_final",
     /** Corrected, full-context transcript following `speech_final`. */
     Final: "final",
+    /** Final billed-usage summary, emitted just before a graceful close. */
+    Usage: "usage",
     /** Server-side fault frame. */
     Error: "error",
 };
@@ -61,7 +62,7 @@ export const WSCloseCode = {
 };
 /**
  * Stable, machine-readable error `code`s (the documented contract). Branch on
- * these. The set is treated as open — `PyAIError.code` stays `string` — so a
+ * these. The set is treated as open, `PyAIError.code` stays `string`, so a
  * new server code never breaks the build, but the known ones are named here.
  */
 export const ErrorCode = {
@@ -99,7 +100,14 @@ export class HearStream {
         this.ws.onopen = () => {
             if (opts.grounding) {
                 try {
-                    this.ws.send(JSON.stringify({ type: "config", grounding: true }));
+                    const cfg = { type: "config", grounding: true };
+                    if (opts.groundingK != null)
+                        cfg.grounding_k = opts.groundingK;
+                    if (opts.groundingMinScore != null)
+                        cfg.grounding_min_score = opts.groundingMinScore;
+                    if (opts.groundingTimeoutMs != null)
+                        cfg.grounding_timeout_ms = opts.groundingTimeoutMs;
+                    this.ws.send(JSON.stringify(cfg));
                 }
                 catch {
                     /* surfaced via onerror */
@@ -135,11 +143,14 @@ export class HearStream {
             case HearFrameType.Final:
                 this.opts.onFinal?.(frame);
                 break;
+            case HearFrameType.Usage:
+                this.opts.onUsage?.(frame);
+                break;
             case HearFrameType.Error:
                 this.opts.onError?.(frame);
                 break;
             default:
-                // Unknown/forward-compatible frame — ignore.
+                // Unknown/forward-compatible frame, ignore.
                 break;
         }
     }
@@ -165,6 +176,317 @@ export class HearStream {
         return this.ws.readyState;
     }
 }
+/**
+ * A live AMD (answering-machine-detection) stream. The wire is Twilio's Media
+ * Streams protocol, so if you're already on Twilio the usual path is one line of
+ * TwiML pointing `<Stream url="wss://api.pyai.com/v1/amd/stream">` at PyAI, no
+ * SDK needed. This helper is for server-side clients that fork the media
+ * themselves: send Twilio `start`/`media`/`stop` frames with {@link AmdStream.send}
+ * (or raw μ-law audio with {@link AmdStream.sendAudio}) and receive the `amd`
+ * decision via `onDecision`. Construct via `pyai.amd.stream()`.
+ */
+export class AmdStream {
+    ws;
+    opts;
+    closed = false;
+    constructor(url, subprotocol, opts) {
+        this.opts = opts;
+        const WS = opts.webSocket ?? globalThis.WebSocket;
+        if (!WS) {
+            throw new Error("No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to amd.stream()");
+        }
+        this.ws = new WS(url, [subprotocol]);
+        this.ws.onopen = () => opts.onOpen?.();
+        this.ws.onmessage = (ev) => this.handleMessage(ev.data);
+        this.ws.onerror = (ev) => opts.onError?.(ev instanceof Error ? ev : new Error("WebSocket error"));
+        this.ws.onclose = (ev) => {
+            this.closed = true;
+            opts.onClose?.(ev.code, ev.reason);
+        };
+    }
+    handleMessage(data) {
+        if (typeof data !== "string")
+            return; // AMD decisions are JSON text frames
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            this.opts.onError?.(new Error(`Unparseable AMD frame: ${data.slice(0, 120)}`));
+            return;
+        }
+        if (frame.event === "amd")
+            this.opts.onDecision?.(frame);
+        this.opts.onMessage?.(frame);
+    }
+    /** Send a Twilio Media Streams control/media frame (JSON) or a raw string. */
+    send(frame) {
+        this.ws.send(typeof frame === "string" ? frame : JSON.stringify(frame));
+    }
+    /** Send a raw audio chunk (G.711 μ-law 8 kHz for the Twilio-native path). */
+    sendAudio(chunk) {
+        this.ws.send(chunk);
+    }
+    /** Close the socket. */
+    close(code = WSCloseCode.Normal, reason = "") {
+        if (!this.closed)
+            this.ws.close(code, reason);
+    }
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket() {
+        return this.ws;
+    }
+    /** Current WebSocket readyState. */
+    get readyState() {
+        return this.ws.readyState;
+    }
+}
+/* ------------------------------------------------------------------------- *
+ * Omni realtime (agentic voice), typed client over the /v1/omni WebSocket
+ * ------------------------------------------------------------------------- */
+/**
+ * Event names on Omni **server → client** frames. ⚠️ Note the asymmetry:
+ * inbound frames are keyed on `event`, but your **outbound** control frames
+ * (`configure`, `dtmf`, …) are keyed on `type`. {@link OmniConnection} handles
+ * both sides for you; this map is for matching frames in `onEvent`.
+ */
+export const OmniEvent = {
+    /** Handshake; advertises protocol version + audio formats. */
+    Hello: "hello",
+    /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
+    Configured: "configured",
+    /** Session is live; includes the resolved agent + audio caps. */
+    SessionStarted: "session_started",
+    /** Turn boundary (user/assistant speaking). */
+    Turn: "turn",
+    /** Incremental/final transcript text. */
+    Transcript: "transcript",
+    /** User interrupted; assistant audio is being cut. */
+    BargeIn: "barge_in",
+    /** Alias for barge-in on some engine builds. */
+    Flush: "flush",
+    /** Engine requests a client-loop tool invocation. */
+    ToolCall: "tool_call",
+    /** Session is closing; see close code. */
+    SessionEnd: "session_end",
+    /** Server fault frame. */
+    Error: "error",
+};
+/** Extract a byte view from a binary WS frame (Buffer / ArrayBuffer / typed
+ * array). Returns null for a Blob or unknown (can't be read synchronously). */
+function omniToBytes(data) {
+    if (data instanceof Uint8Array)
+        return data; // also covers Node Buffer
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        const v = data;
+        return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+    }
+    return null;
+}
+/** A 0x01-prefixed audio frame, the engine's client→server framing for caller
+ * PCM16 LE (see OMNI_PROTOCOL_V2.md §2). */
+function omniAudioFrame(pcm) {
+    const out = new Uint8Array(pcm.length + 1);
+    out[0] = 0x01;
+    out.set(pcm, 1);
+    return out;
+}
+/** A 0x03-prefixed control frame, the engine's client→server framing for
+ * `configure`/`dtmf`/`tool_result` (see OMNI_PROTOCOL_V2.md §2/§3). */
+function omniControlFrame(obj) {
+    const json = new TextEncoder().encode(JSON.stringify(obj));
+    const out = new Uint8Array(json.length + 1);
+    out[0] = 0x03;
+    out.set(json, 1);
+    return out;
+}
+/**
+ * A live Omni agentic-voice session over `/v1/omni`. Hides the wire protocol's
+ * frame-key asymmetry: it sends control frames keyed on `type` (`configure`,
+ * `dtmf`) and parses server frames keyed on `event`, so you cannot trip the #1
+ * Omni integration bug (mirroring the server's `event` key on outbound, which
+ * is silently dropped). Construct via `pyai.omni.connect()`.
+ *
+ * @example
+ * const omni = pyai.omni.connect({
+ *   rate: 16000,
+ *   configure: { voice_id: "stock_emma_en_gb", persona: "You are a receptionist." },
+ *   onAudio: (chunk) => speaker.write(chunk),
+ *   onTranscript: (f) => console.log(f.text),
+ * });
+ * omni.sendAudio(pcm16Chunk); // stream caller audio continuously
+ */
+export class OmniConnection {
+    ws;
+    opts;
+    closed = false;
+    /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
+    blobTail = Promise.resolve();
+    constructor(url, subprotocol, opts) {
+        this.opts = opts;
+        const WS = opts.webSocket ?? globalThis.WebSocket;
+        if (!WS) {
+            throw new Error("No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to omni.connect()");
+        }
+        this.ws = new WS(url, [subprotocol]);
+        this.ws.onopen = () => {
+            if (opts.configure) {
+                try {
+                    this.configure(opts.configure);
+                }
+                catch {
+                    /* surfaced via onerror */
+                }
+            }
+            opts.onOpen?.();
+        };
+        this.ws.onmessage = (ev) => this.handleMessage(ev.data);
+        this.ws.onerror = (ev) => opts.onError?.(ev instanceof Error ? ev : new Error("WebSocket error"));
+        this.ws.onclose = (ev) => {
+            this.closed = true;
+            opts.onClose?.(ev.code, ev.reason);
+        };
+    }
+    handleMessage(data) {
+        // Server → client binary frames are TYPE-TAGGED by their first byte:
+        // 0x01 = agent audio (PCM16) · 0x02 = transcript JSON · 0x03 = control JSON.
+        // (Treating every binary frame as audio, the old behavior, plays the
+        // 0x03/0x02 frames as a glitch and drops every event/transcript.)
+        if (typeof data !== "string") {
+            const bytes = omniToBytes(data);
+            if (!bytes) {
+                this.opts.onAudio?.(data); // Blob/unknown, best-effort
+                return;
+            }
+            const tag = bytes[0];
+            if (tag === 0x01) {
+                this.opts.onAudio?.(bytes.slice(1)); // copy → aligned PCM16
+                return;
+            }
+            if (tag === 0x02 || tag === 0x03) {
+                try {
+                    const parsed = JSON.parse(new TextDecoder().decode(bytes.subarray(1)));
+                    // The 0x02 tag is authoritative for transcript even if the JSON omits `event`.
+                    this.dispatchFrame(tag === 0x02 ? { ...parsed, event: "transcript" } : parsed);
+                }
+                catch {
+                    this.opts.onError?.(new Error("Unparseable Omni binary frame"));
+                }
+                return;
+            }
+            this.opts.onAudio?.(data); // untagged, forward-compat as audio
+            return;
+        }
+        // Text frame (e.g. a server-side broker relay).
+        try {
+            this.dispatchFrame(JSON.parse(data));
+        }
+        catch {
+            this.opts.onError?.(new Error(`Unparseable Omni frame: ${data.slice(0, 120)}`));
+        }
+    }
+    dispatchFrame(frame) {
+        const raw = frame;
+        const eventName = typeof raw.event === "string"
+            ? raw.event
+            : typeof raw.type === "string"
+                ? raw.type
+                : "";
+        this.opts.onEvent?.({ ...frame, event: eventName });
+        switch (eventName) {
+            case OmniEvent.Hello:
+                this.opts.onHello?.(frame);
+                break;
+            case OmniEvent.Configured:
+                this.opts.onConfigured?.(frame);
+                break;
+            case OmniEvent.SessionStarted:
+                this.opts.onSessionStarted?.(frame);
+                break;
+            case OmniEvent.Turn:
+                this.opts.onTurn?.(frame);
+                break;
+            case OmniEvent.Transcript:
+                this.opts.onTranscript?.(frame);
+                break;
+            case OmniEvent.BargeIn:
+            case OmniEvent.Flush:
+                this.opts.onBargeIn?.(frame);
+                break;
+            case OmniEvent.ToolCall:
+                this.opts.onToolCall?.(frame);
+                break;
+            case OmniEvent.SessionEnd:
+                this.opts.onSessionEnd?.(frame);
+                break;
+            case OmniEvent.Error:
+                this.opts.onError?.(frame);
+                break;
+            default:
+                // Unknown/forward-compatible frame, already delivered via onEvent.
+                break;
+        }
+    }
+    /**
+     * Send (or update) the agent config. Always emitted as
+     * `{"type":"configure", ...}`, the correct key. (A hand-rolled
+     * `{"event":"configure"}` is acked but silently dropped by the engine.)
+     */
+    configure(cfg) {
+        this.ws.send(omniControlFrame({ type: "configure", ...cfg }));
+    }
+    /**
+     * Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate) as a
+     * `0x01`-prefixed frame. The engine demuxes on the first byte and has no
+     * default branch, so an untagged chunk is dropped with no error.
+     */
+    sendAudio(chunk) {
+        const bytes = omniToBytes(chunk);
+        if (bytes) {
+            this.ws.send(omniAudioFrame(bytes));
+            return;
+        }
+        // A Blob can only be read asynchronously; queue behind the previous read so
+        // frames still reach the engine in call order.
+        this.blobTail = this.blobTail
+            .then(async () => {
+            const buf = await chunk.arrayBuffer();
+            this.ws.send(omniAudioFrame(new Uint8Array(buf)));
+        })
+            .catch((err) => this.opts.onError?.(err instanceof Error ? err : new Error(String(err))));
+    }
+    /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
+    sendDtmf(digits) {
+        this.ws.send(omniControlFrame({ type: "dtmf", digits }));
+    }
+    /** Reply to a client-loop {@link OmniEvent.ToolCall}. */
+    toolResult(callId, payload) {
+        this.ws.send(omniControlFrame({ type: "tool_result", call_id: callId, ...payload }));
+    }
+    /**
+     * Send an arbitrary control frame for forward-compat control types the SDK
+     * does not model yet. Reminder: client → server frames are keyed on `type`,
+     * never `event`.
+     */
+    send(frame) {
+        this.ws.send(omniControlFrame(frame));
+    }
+    /** Close the session. */
+    close(code = WSCloseCode.Normal, reason = "") {
+        if (!this.closed)
+            this.ws.close(code, reason);
+    }
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket() {
+        return this.ws;
+    }
+    /** Current WebSocket readyState. */
+    get readyState() {
+        return this.ws.readyState;
+    }
+}
 const RETRYABLE = new Set([429, 500, 502, 503, 504]);
 export class PyAI {
     apiKey;
@@ -277,7 +599,7 @@ export class PyAI {
             const res = await this.request("/v1/audio/speech", {
                 method: "POST",
                 headers: this.authHeaders({ "Content-Type": "application/json" }),
-                body: JSON.stringify({ model: "pyai-voice", ...params }),
+                body: JSON.stringify({ model: "pyai-voice", ...params, stream: true }),
             });
             if (!res.body)
                 throw new PyAIError(res.status, "Response had no body to stream");
@@ -340,7 +662,7 @@ export class PyAI {
     // --- key introspection --------------------------------------------------
     /**
      * Introspect the calling key: scopes, environment, and limits. Useful for a
-     * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+     * preflight/doctor check. (New route; older deployments may 404, handle it.)
      */
     me = () => this.getJson("/v1/me");
     // --- voice clones -------------------------------------------------------
@@ -442,7 +764,7 @@ export class PyAI {
             },
         },
         findings: {
-            /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+            /** List Tier-2 (async semantic) findings, advisory, non-blocking. Scope `trace:read`. */
             list: (params = {}) => {
                 const q = new URLSearchParams();
                 if (params.checkId)
@@ -510,17 +832,91 @@ export class PyAI {
             trigger: (callId, input) => this.postJson(`/v1/recap/calls/${encodeURIComponent(callId)}`, input),
         },
     };
+    // --- amd (answering-machine detection) ---------------------------------
+    amd = {
+        config: {
+            /** The org's AMD operating point + webhook. Scope `amd:configure`. */
+            get: () => this.getJson("/v1/amd/config"),
+            /** Set the account-default `aggressiveness` (0-1) and webhook. Scope `amd:configure`. */
+            set: (input) => this.postJson("/v1/amd/config", {
+                ...(input.aggressiveness !== undefined ? { aggressiveness: input.aggressiveness } : {}),
+                ...(input.webhookUrl !== undefined ? { webhook_url: input.webhookUrl } : {}),
+            }),
+        },
+        calls: {
+            /** Recent AMD decisions, newest first. Scope `amd:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                if (params.sessionLabel)
+                    q.set("session_label", params.sessionLabel);
+                const qs = q.toString();
+                return this.getJson(`/v1/amd/calls${qs ? `?${qs}` : ""}`);
+            },
+            /** The full decision (answered_by, reason, …) for one call. Scope `amd:read`. */
+            get: (callId) => this.getJson(`/v1/amd/calls/${encodeURIComponent(callId)}`),
+        },
+        /**
+         * Open a live AMD stream over `/v1/amd/stream` (Twilio Media Streams
+         * protocol). Server-side helper for forking media yourself; the common
+         * Twilio path is one line of TwiML, no SDK. Scope `amd:detect`.
+         */
+        stream: (opts = {}) => new AmdStream(this.amdStreamURL(opts), this.realtimeSubprotocol(), opts),
+    };
+    // --- omni (agentic voice) ----------------------------------------------
+    omni = {
+        /**
+         * Mint an ephemeral, origin-locked Omni session token a browser can use to
+         * open ONE realtime session **directly**, the public/private split for
+         * realtime. **Call this from your server** with a secret key holding
+         * `omni:session`; never ship the secret key to a page. Hand the returned
+         * `token` to the browser, which connects with
+         * `new WebSocket(session.url, ["pyai-key." + session.token])`. The token
+         * expires after `ttlSeconds` (default 60s) and only works from
+         * `allowedOrigins`. Scope `omni:session`.
+         */
+        createSession: (params) => this.postJson("/v1/omni/sessions", {
+            allowed_origins: params.allowedOrigins,
+            ...(params.ttlSeconds !== undefined ? { ttl_seconds: params.ttlSeconds } : {}),
+            ...(params.sessionLabel !== undefined ? { session_label: params.sessionLabel } : {}),
+        }),
+        /**
+         * Open a live Omni agentic-voice session over `/v1/omni`. Returns an
+         * {@link OmniConnection} that handles the wire protocol's frame-key
+         * asymmetry for you, it sends `type`-keyed control frames (`configure`,
+         * `dtmf`) and parses `event`-keyed server frames, so you can't trip the #1
+         * Omni integration bug. Omni is zero-state: nothing to create first; the
+         * agent's behavior travels in the `configure` frame. Pass `token` (from
+         * `createSession`) to connect from a browser without the secret key.
+         */
+        connect: (opts = {}) => {
+            const query = { ...(opts.query ?? {}) };
+            if (opts.format)
+                query.format = opts.format;
+            if (opts.rate)
+                query.rate = String(opts.rate);
+            const url = this.realtimeURL({ product: "omni", sessionLabel: opts.sessionLabel, query });
+            const sub = opts.token ? `pyai-key.${opts.token}` : this.realtimeSubprotocol();
+            return new OmniConnection(url, sub, opts);
+        },
+    };
     // --- realtime (WebSocket) ----------------------------------------------
     /** Build the realtime WebSocket URL for the chosen product. */
     realtimeURL(opts = {}) {
         const wsBase = this.baseURL.replace(/^http/, "ws");
         const q = new URLSearchParams(opts.query ?? {});
         if ((opts.product ?? "omni") === "omni") {
-            // Omni's native realtime surface is /v1/omni. agentId is an opaque label
-            // authorized by the key's org. format/rate are load-bearing on the
-            // connect URL, so default to browser-grade PCM16/24kHz.
-            if (opts.agentId)
-                q.set("agent_id", opts.agentId);
+            // Omni's native realtime surface is /v1/omni. The session is authorized by
+            // the key's org (zero-state), sessionLabel is an optional opaque tag.
+            // format/rate are load-bearing on the connect URL, so default to
+            // browser-grade PCM16/24kHz.
+            if (opts.sessionLabel)
+                q.set("session_label", opts.sessionLabel);
+            else if (opts.agentId)
+                q.set("agent_id", opts.agentId); // deprecated alias
             if (!q.has("format"))
                 q.set("format", "pcm16");
             if (!q.has("rate"))
@@ -549,9 +945,24 @@ export class PyAI {
             q.set("encoding", opts.encoding);
         if (opts.interimResults !== undefined)
             q.set("interim_results", String(opts.interimResults));
+        if (opts.numerals !== undefined)
+            q.set("numerals", String(opts.numerals));
+        if (opts.endpointingMs !== undefined)
+            q.set("endpointing_ms", String(opts.endpointingMs));
         const qs = q.toString();
         return `${wsBase}/v1/audio/transcriptions/stream${qs ? `?${qs}` : ""}`;
     }
+    /** Build the AMD detection WebSocket URL (`/v1/amd/stream`). */
+    amdStreamURL(opts = {}) {
+        const wsBase = this.baseURL.replace(/^http/, "ws");
+        const q = new URLSearchParams(opts.query ?? {});
+        if (opts.aggressiveness !== undefined)
+            q.set("aggressiveness", String(opts.aggressiveness));
+        if (opts.sessionLabel)
+            q.set("session_label", opts.sessionLabel);
+        const qs = q.toString();
+        return `${wsBase}/v1/amd/stream${qs ? `?${qs}` : ""}`;
+    }
     /**
      * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
      * The key travels as a subprotocol so it works from the browser without

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.2.0",
-  "description": "Official TypeScript/JavaScript SDK for PyAI — speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).",
+  "version": "0.2.2",
+  "description": "Official TypeScript/JavaScript SDK for PyAI, speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,6 +22,7 @@
   },
   "homepage": "https://pyai.com",
   "bugs": "https://github.com/atomsai/pyai-platform-backend/issues",
+  "author": "PyAI",
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "node --test test/**/*.test.ts",