@pyai/sdk 0.1.2 → 0.2.1

package/dist/index.js

@@ -21,6 +21,320 @@ export class PyAIError extends Error {
         this.requestId = requestId;
     }
 }
+/**
+ * The runtime list of accepted `audio.speech` formats (mirrors {@link SpeechFormat}),
+ * for building dropdowns / validating input before a request. Branch on the
+ * named values; the order matches the contract doc.
+ */
+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];
+/* ------------------------------------------------------------------------- *
+ * 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.
+ * ------------------------------------------------------------------------- */
+/** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
+export const HearFrameType = {
+    /** Eager live hypothesis for the current utterance. */
+    Partial: "partial",
+    /** Partial whose prefix has stabilized (won't be revised). */
+    PartialStable: "partial_stable",
+    /** Stable transcript at end-of-utterance (endpoint or commit). */
+    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",
+};
+/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+export const WSCloseCode = {
+    /** Normal closure. */
+    Normal: 1000,
+    /** Auth/policy: bad key, missing scope, or revoked token. */
+    PolicyViolation: 1008,
+    /** Engine/internal error. */
+    InternalError: 1011,
+    /** Over the concurrency cap (PyAI-specific; mirrors HTTP 429). */
+    OverCapacity: 4429,
+};
+/**
+ * Stable, machine-readable error `code`s (the documented contract). Branch on
+ * 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 = {
+    Unauthorized: "unauthorized",
+    Forbidden: "forbidden",
+    OriginNotAllowed: "origin_not_allowed",
+    InvalidAgentId: "invalid_agent_id",
+    CreditExhausted: "credit_exhausted",
+    KeyBudgetExceeded: "key_budget_exceeded",
+    InsufficientQuota: "insufficient_quota",
+    RateLimitExceeded: "rate_limit_exceeded",
+    ConcurrencyLimitExceeded: "concurrency_limit_exceeded",
+    DailyCapExceeded: "daily_cap_exceeded",
+    IdempotencyConflict: "idempotency_conflict",
+    NotFound: "not_found",
+    NumberInUse: "number_in_use",
+};
+/**
+ * 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()`.
+ */
+export class HearStream {
+    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 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);
+        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) {
+        // Hear emits JSON text frames; ignore any unexpected binary.
+        if (typeof data !== "string")
+            return;
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            this.opts.onError?.(new Error(`Unparseable Hear frame: ${data.slice(0, 120)}`));
+            return;
+        }
+        switch (frame.type) {
+            case HearFrameType.Partial:
+            case HearFrameType.PartialStable:
+                this.opts.onPartial?.(frame);
+                break;
+            case HearFrameType.SpeechFinal:
+            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.
+                break;
+        }
+    }
+    /** Send a chunk of audio (PCM16 or opus per `encoding`). */
+    sendAudio(chunk) {
+        this.ws.send(chunk);
+    }
+    /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
+    commit() {
+        this.ws.send(JSON.stringify({ type: "commit" }));
+    }
+    /** Close the socket; the server flushes a final for any buffered audio. */
+    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",
+    /** Session is closing; see close code. */
+    SessionEnd: "session_end",
+    /** Server fault frame. */
+    Error: "error",
+};
+/**
+ * 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;
+    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) {
+        // Binary = agent audio (play it out). JSON text = an `event`-keyed frame.
+        if (typeof data !== "string") {
+            this.opts.onAudio?.(data);
+            return;
+        }
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            this.opts.onError?.(new Error(`Unparseable Omni frame: ${data.slice(0, 120)}`));
+            return;
+        }
+        this.opts.onEvent?.(frame);
+        switch (frame.event) {
+            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.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(JSON.stringify({ type: "configure", ...cfg }));
+    }
+    /** Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate). */
+    sendAudio(chunk) {
+        this.ws.send(chunk);
+    }
+    /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
+    sendDtmf(digits) {
+        this.ws.send(JSON.stringify({ type: "dtmf", digits }));
+    }
+    /**
+     * 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(JSON.stringify(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;
@@ -74,6 +388,25 @@ export class PyAI {
         const res = await this.request(path, { headers: this.authHeaders() });
         return (await res.json());
     }
+    async postJson(path, payload, extraHeaders = {}) {
+        const res = await this.request(path, {
+            method: "POST",
+            headers: this.authHeaders({ "Content-Type": "application/json", ...extraHeaders }),
+            body: JSON.stringify(payload),
+        });
+        return (await res.json());
+    }
+    async putJson(path, payload) {
+        const res = await this.request(path, {
+            method: "PUT",
+            headers: this.authHeaders({ "Content-Type": "application/json" }),
+            body: JSON.stringify(payload),
+        });
+        return (await res.json());
+    }
+    deleteReq(path) {
+        return this.request(path, { method: "DELETE", headers: this.authHeaders() });
+    }
     // --- models -------------------------------------------------------------
     models = {
         list: () => this.getJson("/v1/models"),
@@ -126,6 +459,14 @@ export class PyAI {
                 const form = new FormData();
                 form.set("file", params.file, params.filename ?? "audio.wav");
                 form.set("model", params.model ?? "pyai-hear");
+                if (params.language)
+                    form.set("language", params.language);
+                if (params.response_format)
+                    form.set("response_format", params.response_format);
+                if (params.seed !== undefined)
+                    form.set("seed", String(params.seed));
+                if (params.temperature !== undefined)
+                    form.set("temperature", String(params.temperature));
                 const res = await this.request("/v1/audio/transcriptions", {
                     method: "POST",
                     headers: this.authHeaders(),
@@ -133,6 +474,13 @@ export class PyAI {
                 });
                 return (await res.json());
             },
+            /**
+             * Open a live streaming-STT WebSocket (Hear). Hides the frame protocol
+             * behind `onPartial`/`onFinal`/`onError`; stream audio with `sendAudio`,
+             * force-finalize with `commit()`, flush+close with `close()`. Set
+             * `grounding: true` for Cue (turn detection + KB context).
+             */
+            stream: (opts = {}) => new HearStream(this.hearStreamURL(opts), this.realtimeSubprotocol(), opts),
         },
     };
     // --- async transcription jobs ------------------------------------------
@@ -159,17 +507,230 @@ export class PyAI {
             return this.getJson(`/v1/transcription/jobs${qs ? `?${qs}` : ""}`);
         },
     };
+    // --- key introspection --------------------------------------------------
+    /**
+     * Introspect the calling key: scopes, environment, and limits. Useful for a
+     * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+     */
+    me = () => this.getJson("/v1/me");
+    // --- voice clones -------------------------------------------------------
+    clones = {
+        /** List the org's cloned voices. */
+        list: () => this.getJson("/v1/voice/clones"),
+        /** Enroll a custom voice from reference audio (>= ~10s). Scope `voice:clone`. */
+        create: async (params) => {
+            const form = new FormData();
+            form.set("name", params.name);
+            form.set("file", params.file, params.filename ?? "sample.wav");
+            const res = await this.request("/v1/voice/clones", { method: "POST", headers: this.authHeaders(), body: form });
+            return (await res.json());
+        },
+        /**
+         * Fetch a single cloned voice by id. The API exposes no GET-by-id for
+         * clones, so this filters `list()` client-side and throws a 404 `PyAIError`
+         * when the id isn't found.
+         */
+        get: async (id) => {
+            const { data } = await this.clones.list();
+            const match = data.find((v) => v.id === id);
+            if (!match)
+                throw new PyAIError(404, `No cloned voice ${id}`, ErrorCode.NotFound);
+            return match;
+        },
+        /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+        delete: async (id) => {
+            await this.deleteReq(`/v1/voice/clones/${encodeURIComponent(id)}`);
+        },
+    };
+    // --- telephony (managed numbers) ---------------------------------------
+    telephony = {
+        numbers: {
+            /** Search the carrier's available US local numbers. */
+            available: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.areaCode)
+                    q.set("area_code", params.areaCode);
+                if (params.contains)
+                    q.set("contains", params.contains);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                const qs = q.toString();
+                return this.getJson(`/v1/telephony/available${qs ? `?${qs}` : ""}`);
+            },
+            /** List the org's managed numbers (active only unless `includeReleased`). */
+            list: (params = {}) => {
+                const qs = params.includeReleased ? "?include_released=true" : "";
+                return this.getJson(`/v1/telephony/numbers${qs}`);
+            },
+            /** Provision (buy) a specific available number, optionally bound to an agent. */
+            buy: (params) => this.postJson("/v1/telephony/numbers", params),
+            /** Route a number to an agent (`agentId: null` to unassign). */
+            assign: (id, agentId) => this.postJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/assign`, { agent_id: agentId }),
+            /** Release a number back to the carrier (idempotent). */
+            release: async (id) => {
+                const res = await this.deleteReq(`/v1/telephony/numbers/${encodeURIComponent(id)}`);
+                return (await res.json());
+            },
+        },
+    };
+    // --- trace (compliance) -------------------------------------------------
+    trace = {
+        interactions: {
+            /** List scanned interactions (scorecards), newest first. Scope `trace:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.verdict)
+                    q.set("verdict", params.verdict);
+                if (params.agentId)
+                    q.set("agent_id", params.agentId);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                const qs = q.toString();
+                return this.getJson(`/v1/trace/interactions${qs ? `?${qs}` : ""}`);
+            },
+            /** The full per-call evidence view (findings, redactions, audit hash). */
+            get: (id) => this.getJson(`/v1/trace/interactions/${encodeURIComponent(id)}`),
+        },
+        violations: {
+            /** Drill-down of every fired Tier-0 rule across scorecards. Scope `trace:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.ruleId)
+                    q.set("rule_id", params.ruleId);
+                if (params.severity)
+                    q.set("severity", params.severity);
+                if (params.interactionId)
+                    q.set("interaction_id", params.interactionId);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                const qs = q.toString();
+                return this.getJson(`/v1/trace/violations${qs ? `?${qs}` : ""}`);
+            },
+        },
+        findings: {
+            /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.checkId)
+                    q.set("check_id", params.checkId);
+                if (params.action)
+                    q.set("action", params.action);
+                if (params.severity)
+                    q.set("severity", params.severity);
+                if (params.interactionId)
+                    q.set("interaction_id", params.interactionId);
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                const qs = q.toString();
+                return this.getJson(`/v1/trace/findings${qs ? `?${qs}` : ""}`);
+            },
+        },
+        config: {
+            /** Read per-agent Trace config (omit `agentId` for the org default). Scope `trace:configure`. */
+            get: (agentId) => this.getJson(`/v1/trace/config${agentId ? `?agent_id=${encodeURIComponent(agentId)}` : ""}`),
+            /** Upsert per-agent Trace config. Scope `trace:configure`. */
+            set: (input) => this.putJson("/v1/trace/config", input),
+        },
+        rulePacks: {
+            /** List built-in + custom rule packs. Scope `trace:configure`. */
+            list: () => this.getJson("/v1/trace/rule-packs"),
+            /** Upload a custom rule pack (Trace DSL). Scope `trace:configure`. */
+            create: (spec) => this.postJson("/v1/trace/rule-packs", spec),
+            /** Resolve a rule pack by id (latest active, or pin `version`). */
+            get: (id, version) => this.getJson(`/v1/trace/rule-packs/${encodeURIComponent(id)}${version ? `?version=${encodeURIComponent(version)}` : ""}`),
+        },
+        /** Compliance exposure summary over a trailing window. Scope `trace:read`. */
+        exposure: (windowDays) => this.getJson(`/v1/trace/exposure${windowDays !== undefined ? `?window_days=${windowDays}` : ""}`),
+        /**
+         * Convenience: the per-call operational timeline (eval scorecard-v1). A thin
+         * wrapper over `interactions.get(id)` that returns the `timeline` array, or
+         * `[]` when the engine hasn't emitted one yet (forward-compatible). Scope
+         * `trace:read`.
+         */
+        callTimeline: async (id) => {
+            const detail = await this.trace.interactions.get(id);
+            return detail.timeline ?? [];
+        },
+    };
+    // --- recap (conversation intelligence) --------------------------------
+    recap = {
+        config: {
+            get: () => this.getJson("/v1/recap/config"),
+            set: (input) => this.putJson("/v1/recap/config", input),
+        },
+        calls: {
+            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.status)
+                    q.set("status", params.status);
+                const qs = q.toString();
+                return this.getJson(`/v1/recap/calls${qs ? `?${qs}` : ""}`);
+            },
+            get: (callId) => this.getJson(`/v1/recap/calls/${encodeURIComponent(callId)}`),
+            trigger: (callId, input) => this.postJson(`/v1/recap/calls/${encodeURIComponent(callId)}`, input),
+        },
+    };
+    // --- 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"))
@@ -184,6 +745,27 @@ export class PyAI {
     realtimeSubprotocol() {
         return `pyai-key.${this.apiKey}`;
     }
+    /** Build the Hear streaming-STT WebSocket URL (`/v1/audio/transcriptions/stream`). */
+    hearStreamURL(opts = {}) {
+        const wsBase = this.baseURL.replace(/^http/, "ws");
+        const q = new URLSearchParams(opts.query ?? {});
+        if (opts.model)
+            q.set("model", opts.model);
+        if (opts.language)
+            q.set("language", opts.language);
+        if (opts.sampleRate !== undefined)
+            q.set("sample_rate", String(opts.sampleRate));
+        if (opts.encoding)
+            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}` : ""}`;
+    }
     /**
      * 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,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.1.2",
+  "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).",
   "type": "module",
   "main": "dist/index.js",
@@ -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",