@pyai/sdk 0.2.1 → 0.2.3

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.
@@ -63,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 = {
@@ -151,7 +150,7 @@ export class HearStream {
                 this.opts.onError?.(frame);
                 break;
             default:
-                // Unknown/forward-compatible frame — ignore.
+                // Unknown/forward-compatible frame, ignore.
                 break;
         }
     }
@@ -177,8 +176,73 @@ 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
+ * Omni realtime (agentic voice), typed client over the /v1/omni WebSocket
  * ------------------------------------------------------------------------- */
 /**
  * Event names on Omni **server → client** frames. ⚠️ Note the asymmetry:
@@ -201,11 +265,108 @@ export const OmniEvent = {
     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",
 };
+const OMNI_TRANSCRIPT_MAX_BYTES = 16_384;
+const OMNI_TRANSCRIPT_MAX_CHARS = 4_000;
+function omniTranscriptRole(value) {
+    if (value === "user" || value === "caller" || value === "human")
+        return "user";
+    if (value === "assistant" || value === "agent")
+        return "assistant";
+    return null;
+}
+function omniTranscriptText(value) {
+    return typeof value === "string"
+        && value.length > 0
+        && value.length <= OMNI_TRANSCRIPT_MAX_CHARS
+        && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(value)
+        ? value
+        : null;
+}
+/** Normalize the live UTF-8 0x02 body and the documented direct-object legacy shape. */
+export function normalizeOmniTranscriptBody(bytes) {
+    if (bytes.byteLength === 0 || bytes.byteLength > OMNI_TRANSCRIPT_MAX_BYTES)
+        return null;
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch {
+        return null;
+    }
+    if (!decoded.trimStart().startsWith("{")) {
+        const text = omniTranscriptText(decoded);
+        return text
+            ? { event: "transcript", role: "user", text, final: false, mode: "delta" }
+            : null;
+    }
+    let value;
+    try {
+        value = JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const payload = value;
+    const role = omniTranscriptRole(payload.role ?? payload.speaker);
+    const mode = typeof payload.delta === "string" ? "delta" : "replace";
+    const text = omniTranscriptText(mode === "delta" ? payload.delta : typeof payload.text === "string" ? payload.text : payload.transcript);
+    if (!role || !text)
+        return null;
+    if (payload.final !== undefined && typeof payload.final !== "boolean")
+        return null;
+    if (payload.sequence !== undefined
+        && (typeof payload.sequence !== "number"
+            || !Number.isSafeInteger(payload.sequence)
+            || payload.sequence < 0))
+        return null;
+    return {
+        event: "transcript",
+        role,
+        text,
+        final: payload.final === true,
+        mode,
+        ...(payload.sequence === undefined ? {} : { sequence: payload.sequence }),
+    };
+}
+/** 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`,
@@ -226,6 +387,10 @@ export class OmniConnection {
     ws;
     opts;
     closed = false;
+    /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
+    blobTail = Promise.resolve();
+    /** Serializes inbound Blob decoding so browser frames stay ordered. */
+    inboundTail = Promise.resolve();
     constructor(url, subprotocol, opts) {
         this.opts = opts;
         const WS = opts.webSocket ?? globalThis.WebSocket;
@@ -244,29 +409,80 @@ export class OmniConnection {
             }
             opts.onOpen?.();
         };
-        this.ws.onmessage = (ev) => this.handleMessage(ev.data);
+        this.ws.onmessage = (ev) => {
+            const reportDecodeError = (error) => {
+                opts.onError?.(error instanceof Error ? error : new Error("Could not decode Omni frame"));
+            };
+            if (typeof Blob !== "undefined" && ev.data instanceof Blob) {
+                this.inboundTail = this.inboundTail.then(() => this.handleMessage(ev.data)).catch(reportDecodeError);
+            }
+            else {
+                void this.handleMessage(ev.data).catch(reportDecodeError);
+            }
+        };
         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) {
-        // Binary = agent audio (play it out). JSON text = an `event`-keyed frame.
+    async handleMessage(data) {
+        // Server → client binary frames are TYPE-TAGGED by their first byte:
+        // 0x01 = agent audio (PCM16) · 0x02 = transcript UTF-8 · 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") {
-            this.opts.onAudio?.(data);
+            const bytes = typeof Blob !== "undefined" && data instanceof Blob
+                ? new Uint8Array(await data.arrayBuffer())
+                : omniToBytes(data);
+            if (!bytes) {
+                this.opts.onError?.(new Error("Unsupported Omni binary frame"));
+                return;
+            }
+            const tag = bytes[0];
+            if (tag === 0x01) {
+                this.opts.onAudio?.(bytes.slice(1)); // copy → aligned PCM16
+                return;
+            }
+            if (tag === 0x02) {
+                const transcript = normalizeOmniTranscriptBody(bytes.subarray(1));
+                if (transcript)
+                    this.dispatchFrame(transcript);
+                else
+                    this.opts.onError?.(new Error("Unparseable Omni transcript frame"));
+                return;
+            }
+            if (tag === 0x03) {
+                try {
+                    const parsed = JSON.parse(new TextDecoder().decode(bytes.subarray(1)));
+                    this.dispatchFrame(parsed);
+                }
+                catch {
+                    this.opts.onError?.(new Error("Unparseable Omni binary frame"));
+                }
+                return;
+            }
+            const tagName = tag === undefined ? "empty" : `0x${tag.toString(16).padStart(2, "0")}`;
+            this.opts.onError?.(new Error(`Ignored unknown Omni binary frame tag ${tagName}`));
             return;
         }
-        let frame;
+        // Text frame (e.g. a server-side broker relay).
         try {
-            frame = JSON.parse(data);
+            this.dispatchFrame(JSON.parse(data));
         }
         catch {
             this.opts.onError?.(new Error(`Unparseable Omni frame: ${data.slice(0, 120)}`));
-            return;
         }
-        this.opts.onEvent?.(frame);
-        switch (frame.event) {
+    }
+    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;
@@ -286,6 +502,9 @@ export class OmniConnection {
             case OmniEvent.Flush:
                 this.opts.onBargeIn?.(frame);
                 break;
+            case OmniEvent.ToolCall:
+                this.opts.onToolCall?.(frame);
+                break;
             case OmniEvent.SessionEnd:
                 this.opts.onSessionEnd?.(frame);
                 break;
@@ -293,25 +512,45 @@ export class OmniConnection {
                 this.opts.onError?.(frame);
                 break;
             default:
-                // Unknown/forward-compatible frame — already delivered via onEvent.
+                // 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
+     * `{"type":"configure", ...}`, the correct key. (A hand-rolled
      * `{"event":"configure"}` is acked but silently dropped by the engine.)
      */
     configure(cfg) {
-        this.ws.send(JSON.stringify({ type: "configure", ...cfg }));
+        this.ws.send(omniControlFrame({ type: "configure", ...cfg }));
     }
-    /** Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate). */
+    /**
+     * 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) {
-        this.ws.send(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(JSON.stringify({ type: "dtmf", 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
@@ -319,7 +558,7 @@ export class OmniConnection {
      * never `event`.
      */
     send(frame) {
-        this.ws.send(JSON.stringify(frame));
+        this.ws.send(omniControlFrame(frame));
     }
     /** Close the session. */
     close(code = WSCloseCode.Normal, reason = "") {
@@ -447,7 +686,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");
@@ -510,7 +749,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 -------------------------------------------------------
@@ -612,7 +851,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)
@@ -680,11 +919,45 @@ 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
+         * 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
@@ -700,8 +973,8 @@ export class PyAI {
         /**
          * 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
+         * 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.
@@ -724,7 +997,7 @@ export class PyAI {
         const q = new URLSearchParams(opts.query ?? {});
         if ((opts.product ?? "omni") === "omni") {
             // 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.
+            // 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)
@@ -766,6 +1039,17 @@ export class PyAI {
         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.1",
-  "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.3",
+  "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",