@pyai/sdk 0.2.2 → 0.3.1

package/dist/index.js

@@ -20,6 +20,10 @@ export class PyAIError extends Error {
         this.requestId = requestId;
     }
 }
+function normalizeVoice(value) {
+    const voiceId = String(value.voice_id ?? value.id ?? "");
+    return { ...value, voice_id: voiceId, id: voiceId };
+}
 /**
  * The runtime list of accepted `audio.speech` formats (mirrors {@link SpeechFormat}),
  * for building dropdowns / validating input before a request. Branch on the
@@ -28,6 +32,13 @@ export class PyAIError extends Error {
 export const SPEECH_FORMATS = ["wav", "mp3", "opus", "aac", "flac", "pcm", "g711_ulaw", "g711_alaw"];
 /** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
 export const SPEECH_SAMPLE_RATES = [8000, 16000, 24000, 48000];
+function assertActiveSpeechParams(params) {
+    for (const field of ["speed", "seed", "temperature"]) {
+        if (params[field] !== undefined) {
+            throw new Error(`${field} is reserved but not active on Speak`);
+        }
+    }
+}
 /* ------------------------------------------------------------------------- *
  * 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
@@ -36,6 +47,8 @@ export const SPEECH_SAMPLE_RATES = [8000, 16000, 24000, 48000];
  * ------------------------------------------------------------------------- */
 /** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
 export const HearFrameType = {
+    /** Applied endpointing configuration and validation warnings. */
+    ConfigAck: "config_ack",
     /** Eager live hypothesis for the current utterance. */
     Partial: "partial",
     /** Partial whose prefix has stabilized (won't be revised). */
@@ -69,7 +82,7 @@ export const ErrorCode = {
     Unauthorized: "unauthorized",
     Forbidden: "forbidden",
     OriginNotAllowed: "origin_not_allowed",
-    InvalidAgentId: "invalid_agent_id",
+    InvalidSessionLabel: "invalid_session_label",
     CreditExhausted: "credit_exhausted",
     KeyBudgetExceeded: "key_budget_exceeded",
     InsufficientQuota: "insufficient_quota",
@@ -83,8 +96,10 @@ export const ErrorCode = {
 /**
  * A live Hear streaming-STT session. Hides the frame protocol: stream audio
  * with {@link HearStream.sendAudio}, get `onPartial`/`onFinal`/`onError`
- * callbacks, force-finalize with {@link HearStream.commit}, and flush+close
- * with {@link HearStream.close}. Construct via `pyai.audio.transcriptions.stream()`.
+ * callbacks, update the silence floor with
+ * {@link HearStream.configureEndpointing}, force-finalize with
+ * {@link HearStream.commit}, and flush+close with {@link HearStream.close}.
+ * Construct via `pyai.audio.transcriptions.stream()`.
  */
 export class HearStream {
     ws;
@@ -92,27 +107,15 @@ export class HearStream {
     closed = false;
     constructor(url, subprotocol, opts) {
         this.opts = opts;
+        if (opts.grounding) {
+            throw new Error("Cue grounding is not active on the serving Hear stream; omit grounding until the API reference marks it active");
+        }
         const WS = opts.webSocket ?? globalThis.WebSocket;
         if (!WS) {
             throw new Error("No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to transcriptions.stream()");
         }
         this.ws = new WS(url, [subprotocol]);
         this.ws.onopen = () => {
-            if (opts.grounding) {
-                try {
-                    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 */
-                }
-            }
             opts.onOpen?.();
         };
         this.ws.onmessage = (ev) => this.handleMessage(ev.data);
@@ -135,6 +138,9 @@ export class HearStream {
             return;
         }
         switch (frame.type) {
+            case HearFrameType.ConfigAck:
+                this.opts.onConfigAck?.(frame);
+                break;
             case HearFrameType.Partial:
             case HearFrameType.PartialStable:
                 this.opts.onPartial?.(frame);
@@ -158,6 +164,10 @@ export class HearStream {
     sendAudio(chunk) {
         this.ws.send(chunk);
     }
+    /** Change the minimum trailing-pause floor without reconnecting. */
+    configureEndpointing(endpointingMs) {
+        this.ws.send(JSON.stringify({ type: "config", endpointing_ms: endpointingMs }));
+    }
     /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
     commit() {
         this.ws.send(JSON.stringify({ type: "commit" }));
@@ -272,6 +282,77 @@ export const OmniEvent = {
     /** Server fault frame. */
     Error: "error",
 };
+const OMNI_TRANSCRIPT_MAX_BYTES = 16_384;
+const OMNI_TRANSCRIPT_MAX_CHARS = 4_000;
+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;
+}
+function omniTranscriptRole(value) {
+    if (value === "user" || value === "caller" || value === "human")
+        return "user";
+    if (value === "assistant" || value === "agent")
+        return "assistant";
+    return null;
+}
+/** Normalize the live UTF-8 `0x02` text body and bounded legacy JSON bodies. */
+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;
+    }
+    // The serving engine's canonical payload is plain UTF-8 caller text, not
+    // JSON. Each frame is a delta for the current caller turn.
+    if (!decoded.trimStart().startsWith("{")) {
+        const text = omniTranscriptText(decoded);
+        return text
+            ? { event: "transcript", role: "user", text, final: false, mode: "delta" }
+            : null;
+    }
+    // Keep accepting a bounded direct object for older bridges and recordings.
+    let value;
+    try {
+        value = JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const payload = value;
+    if (payload.type !== undefined
+        || (payload.event !== undefined && payload.event !== "transcript"))
+        return null;
+    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) {
@@ -324,6 +405,8 @@ export class OmniConnection {
     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;
@@ -342,22 +425,34 @@ 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) {
+    async handleMessage(data) {
         // Server → client binary frames are TYPE-TAGGED by their first byte:
-        // 0x01 = agent audio (PCM16) · 0x02 = transcript JSON · 0x03 = control JSON.
+        // 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") {
-            const bytes = omniToBytes(data);
+            const bytes = typeof Blob !== "undefined" && data instanceof Blob
+                ? new Uint8Array(await data.arrayBuffer())
+                : omniToBytes(data);
             if (!bytes) {
-                this.opts.onAudio?.(data); // Blob/unknown, best-effort
+                this.opts.onError?.(new Error("Unsupported Omni binary frame"));
                 return;
             }
             const tag = bytes[0];
@@ -365,36 +460,41 @@ export class OmniConnection {
                 this.opts.onAudio?.(bytes.slice(1)); // copy → aligned PCM16
                 return;
             }
-            if (tag === 0x02 || tag === 0x03) {
+            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)));
-                    // The 0x02 tag is authoritative for transcript even if the JSON omits `event`.
-                    this.dispatchFrame(tag === 0x02 ? { ...parsed, event: "transcript" } : parsed);
+                    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(1)));
+                    if (parsed?.event === OmniEvent.Transcript) {
+                        this.opts.onError?.(new Error("Omni transcript events must use a binary 0x02 frame"));
+                        return;
+                    }
+                    this.dispatchFrame(parsed);
                 }
                 catch {
                     this.opts.onError?.(new Error("Unparseable Omni binary frame"));
                 }
                 return;
             }
-            this.opts.onAudio?.(data); // untagged, forward-compat as audio
+            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;
         }
-        // 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)}`));
-        }
+        this.opts.onError?.(new Error("Unexpected Omni text frame; server frames must use binary 0x01/0x02/0x03 tags"));
     }
     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 });
+        const eventName = frame.event;
+        if (typeof eventName !== "string" || !eventName) {
+            this.opts.onError?.(new Error("Omni server control frame is missing its event key"));
+            return;
+        }
+        this.opts.onEvent?.(frame);
         switch (eventName) {
             case OmniEvent.Hello:
                 this.opts.onHello?.(frame);
@@ -435,7 +535,10 @@ export class OmniConnection {
      * `{"event":"configure"}` is acked but silently dropped by the engine.)
      */
     configure(cfg) {
-        this.ws.send(omniControlFrame({ type: "configure", ...cfg }));
+        const payload = { ...cfg };
+        delete payload.type;
+        delete payload.event;
+        this.ws.send(omniControlFrame({ type: "configure", ...payload }));
     }
     /**
      * Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate) as a
@@ -471,7 +574,12 @@ export class OmniConnection {
      * never `event`.
      */
     send(frame) {
-        this.ws.send(omniControlFrame(frame));
+        if (typeof frame.type !== "string" || !frame.type) {
+            throw new TypeError("Omni client control frames must have a non-empty type key");
+        }
+        const payload = { ...frame };
+        delete payload.event;
+        this.ws.send(omniControlFrame(payload));
     }
     /** Close the session. */
     close(code = WSCloseCode.Normal, reason = "") {
@@ -565,25 +673,27 @@ export class PyAI {
     };
     // --- voices -------------------------------------------------------------
     voices = {
-        list: (params = {}) => {
+        list: async (params = {}) => {
             const q = new URLSearchParams();
             if (params.gender)
                 q.set("gender", params.gender);
             if (params.region)
                 q.set("region", params.region);
             const qs = q.toString();
-            return this.getJson(`/v1/voices${qs ? `?${qs}` : ""}`);
+            const page = await this.getJson(`/v1/voices${qs ? `?${qs}` : ""}`);
+            return { ...page, data: page.data.map(normalizeVoice) };
         },
-        get: (id) => this.getJson(`/v1/voices/${encodeURIComponent(id)}`),
+        get: async (id) => normalizeVoice(await this.getJson(`/v1/voices/${encodeURIComponent(id)}`)),
     };
     // --- audio --------------------------------------------------------------
     audio = {
         /** Text-to-speech. Returns the raw audio bytes (default WAV). */
         speech: async (params) => {
+            assertActiveSpeechParams(params);
             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-speak", ...params }),
             });
             return res.arrayBuffer();
         },
@@ -596,10 +706,11 @@ export class PyAI {
          * iterable of Uint8Array chunks.
          */
         speechStream: async (params) => {
+            assertActiveSpeechParams(params);
             const res = await this.request("/v1/audio/speech", {
                 method: "POST",
                 headers: this.authHeaders({ "Content-Type": "application/json" }),
-                body: JSON.stringify({ model: "pyai-voice", ...params, stream: true }),
+                body: JSON.stringify({ model: "pyai-speak", ...params, stream: true }),
             });
             if (!res.body)
                 throw new PyAIError(res.status, "Response had no body to stream");
@@ -669,7 +780,7 @@ export class PyAI {
     clones = {
         /** List the org's cloned voices. */
         list: () => this.getJson("/v1/voice/clones"),
-        /** Enroll a custom voice from reference audio (>= ~10s). Scope `voice:clone`. */
+        /** Enroll a custom voice from reference audio (>= ~10s). Scope `speak:clone`. */
         create: async (params) => {
             const form = new FormData();
             form.set("name", params.name);
@@ -689,7 +800,7 @@ export class PyAI {
                 throw new PyAIError(404, `No cloned voice ${id}`, ErrorCode.NotFound);
             return match;
         },
-        /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+        /** Delete a cloned voice (tenant-isolated). Scope `speak:clone`. */
         delete: async (id) => {
             await this.deleteReq(`/v1/voice/clones/${encodeURIComponent(id)}`);
         },
@@ -898,34 +1009,31 @@ export class PyAI {
                 query.format = opts.format;
             if (opts.rate)
                 query.rate = String(opts.rate);
-            const url = this.realtimeURL({ product: "omni", sessionLabel: opts.sessionLabel, query });
+            const url = this.realtimeURL({ 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. */
+    /** Build the canonical Omni WebSocket URL. */
     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. 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"))
-                q.set("rate", "24000");
-            const qs = q.toString();
-            return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
+        // format/rate are load-bearing on the connect URL, so default to
+        // browser-grade PCM16/24kHz.
+        for (const key of ["agent", "agent_id", "agentId", "model", "access_token"]) {
+            if (q.has(key)) {
+                throw new Error(`Omni query parameter "${key}" is not supported; use sessionLabel, format/rate, or api_key`);
+            }
         }
-        q.set("model", "pyai-flow-realtime");
-        return `${wsBase}/v1/realtime?${q.toString()}`;
+        if (opts.sessionLabel)
+            q.set("session_label", opts.sessionLabel);
+        if (!q.has("format"))
+            q.set("format", "pcm16");
+        if (!q.has("rate"))
+            q.set("rate", "24000");
+        const qs = q.toString();
+        return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
     }
     /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
     realtimeSubprotocol() {
@@ -935,6 +1043,7 @@ export class PyAI {
     hearStreamURL(opts = {}) {
         const wsBase = this.baseURL.replace(/^http/, "ws");
         const q = new URLSearchParams(opts.query ?? {});
+        q.set("protocol", "pyai-hear-v1");
         if (opts.model)
             q.set("model", opts.model);
         if (opts.language)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "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",
@@ -14,7 +14,11 @@
   "bin": {
     "pyai": "dist/cli.js"
   },
-  "files": ["dist", "src", "README.md"],
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/atomsai/pyai-platform-backend.git",
@@ -31,7 +35,18 @@
   "engines": {
     "node": ">=18"
   },
-  "keywords": ["pyai", "voice-ai", "tts", "stt", "speech", "voice-agents", "realtime", "transcription", "compliance", "openai-compatible"],
+  "keywords": [
+    "pyai",
+    "voice-ai",
+    "tts",
+    "stt",
+    "speech",
+    "voice-agents",
+    "realtime",
+    "transcription",
+    "compliance",
+    "openai-compatible"
+  ],
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^22.0.0",