@pyai/sdk 0.3.1 → 0.4.0

package/README.md

@@ -131,6 +131,7 @@ WS subprotocol, so it works in the browser), routes the wire frames to
 const hear = pyai.audio.transcriptions.stream({
   sampleRate: 16000,
   endpointingMs: 800, // minimum trailing pause; may wait up to max(800, 1500) ms
+  vocabulary: ["Nguyen", "SKU-99"],
   onConfigAck: (ack) => {
     if (ack.warnings.length) throw new Error(JSON.stringify(ack.warnings));
   },
@@ -145,6 +146,35 @@ vad.on("end", () => hear.commit());                     // optional forced final
 // hear.close() also flushes a final for any buffered audio
 ```
 
+Streaming uses up to five sanitized vocabulary terms. To store organization
+suggestions, use a key with `hear:configure` and set explicit activation
+profiles first:
+
+```ts
+await pyai.hear.vocabulary.set({
+  terms: ["Nguyen", "SKU-99"],
+  enabledFor: ["batch", "hear_stream"],
+});
+```
+
+Request-level terms come first. Stored suggestions fill remaining slots up to
+five. The effective list is fixed when a stream opens or a batch job is created.
+Organization Hear terms are not used by Omni and are not populated
+automatically from CRM or dialer data. A managed Agent can opt in with its own
+list:
+
+```ts
+const agent = await pyai.agents.create({
+  name: "Front desk",
+  vocabulary: ["Nguyen", "Acme Dental", "SKU-99"],
+});
+
+await pyai.agents.update(agent.agent_id, { vocabulary: [] });
+```
+
+The Agent list is sanitized to at most five effective terms and fixed when a
+new session starts. An empty list turns the feature off.
+
 Frame `type`s, WS close codes, and error `code`s are exported as named
 constants so you never hardcode a magic string:
 

package/dist/index.d.ts

@@ -31,6 +31,20 @@ export interface Voice {
     name?: string;
     gender?: string;
     region?: string;
+    language?: string;
+    /** Customer-facing quality tier. */
+    tier?: "standard" | "natural";
+    /** Permanent convenience inputs accepted on the advertised surfaces. */
+    aliases?: string[];
+    /** Product surfaces on which this stock voice can be selected. */
+    available_on?: Array<"speak" | "omni">;
+    /** Accepted Speak delivery modes. Empty means the voice has no Speak surface. */
+    synthesis_modes?: Array<"streaming" | "async">;
+    /** Voice-specific amount on top of the selected product's base rate. */
+    pricing?: {
+        included_in_base_price: boolean;
+        additional_price_usd_per_minute: number;
+    };
     [k: string]: unknown;
 }
 export interface ListResponse<T> {
@@ -82,6 +96,13 @@ export interface SpeechParams {
     input: string;
     voice?: string;
     model?: SpeakModel;
+    /**
+     * Delivery mode. The API defaults to true and every catalog voice accepts
+     * both values. Set false when you want one complete buffered body with a
+     * `Content-Length`. A voice whose serving fleet has no streaming lane is
+     * rendered buffered either way and says so with `x-pyai-stream: buffered`.
+     */
+    stream?: boolean;
     /**
      * Output container/codec, resampled+encoded server-side. One of
      * {@link SpeechFormat}, anything else is a `400 unsupported_format`. Omit for
@@ -119,8 +140,57 @@ export interface CreateJobParams {
     diarize?: boolean;
     channel?: boolean;
     numerals?: boolean;
+    smart_format?: boolean;
+    dictation?: boolean;
+    drop_fillers?: boolean;
+    /**
+     * Per-job names, brands, products, or distinctive terms. PyAI keeps up to
+     * five valid entries after trimming, deduplication, and common-word
+     * filtering.
+     */
+    vocabulary?: string[];
     output_formats?: Array<"json" | "srt" | "vtt">;
     webhook_url?: string;
+    call_id?: string;
+    pack_id?: string;
+    call_direction?: "inbound" | "outbound";
+    customer_name?: string;
+}
+export type HearVocabularyProfile = "batch" | "hear_stream";
+export interface HearVocabularyInput {
+    /** Organization-owned names, brands, products, or distinctive terms. */
+    terms: string[];
+    /** Stored terms remain inert unless a use case is selected here. */
+    enabledFor: HearVocabularyProfile[];
+}
+export interface HearVocabulary {
+    object: "hear.vocabulary";
+    /** Sanitized stored list, at most five terms. */
+    terms: string[];
+    /** Use cases that may add stored suggestions. */
+    enabled_for: HearVocabularyProfile[];
+    /** Unix milliseconds, or null before the first save. */
+    updated_at: number | null;
+}
+export interface AgentConfig {
+    name?: string;
+    persona_system_prompt?: string | null;
+    greeting?: string | null;
+    voice_id?: string | null;
+    language?: "en" | "fr" | "es" | "de" | "hi" | null;
+    /**
+     * Opt-in speech-recognition vocabulary. PyAI sanitizes and keeps at most
+     * five terms. An empty list or null turns it off.
+     */
+    vocabulary?: string[] | null;
+    [key: string]: unknown;
+}
+export interface Agent {
+    object: "agent";
+    agent_id: string;
+    name: string;
+    vocabulary: string[];
+    [key: string]: unknown;
 }
 export interface RealtimeOptions {
     /**
@@ -183,10 +253,16 @@ export declare const HearFrameType: {
     readonly Error: "error";
 };
 export type HearFrameType = (typeof HearFrameType)[keyof typeof HearFrameType];
-/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+/**
+ * WebSocket close codes used across the PyAI realtime/streaming surfaces.
+ * Browser callers may initiate only Normal or values in 3000-4999; the
+ * standards-reserved values below are server close observations.
+ */
 export declare const WSCloseCode: {
     /** Normal closure. */
     readonly Normal: 1000;
+    /** Browser-safe private application code for a malformed peer protocol frame. */
+    readonly ProtocolViolation: 4002;
     /** Auth/policy: bad key, missing scope, or revoked token. */
     readonly PolicyViolation: 1008;
     /** Engine/internal error. */
@@ -214,6 +290,7 @@ export declare const ErrorCode: {
     readonly IdempotencyConflict: "idempotency_conflict";
     readonly NotFound: "not_found";
     readonly NumberInUse: "number_in_use";
+    readonly UnsupportedToolTransport: "unsupported_tool_transport";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** A top-3 knowledge-base passage attached to Cue (grounded) finals. */
@@ -303,28 +380,59 @@ export interface WebSocketLike {
         reason: string;
     }) => void) | null;
 }
+/**
+ * The non-secret marker every PyAI realtime client offers ALONGSIDE its
+ * `pyai-key.<KEY>` credential token.
+ *
+ * A browser cannot set `Authorization` on a WebSocket, so the key rides in
+ * `Sec-WebSocket-Protocol`. RFC 6455 makes the server echo the subprotocol it
+ * SELECTS, so a server that selects the credential publishes the credential —
+ * which api.pyai.com did until 2026-09-07. The edge now echoes only this
+ * marker. Offering it is not optional for Node clients: `ws` throws
+ * "Server sent no subprotocol" when it offered subprotocols and the 101
+ * selected none, and RFC 6455 lets the server select only a value the client
+ * actually offered.
+ */
+export declare const REALTIME_SUBPROTOCOL_MARKER = "pyai.v1";
 export type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
 export interface HearStreamOptions {
     /** Streaming STT model. Server default `pyai-hear`. */
     model?: string;
-    /**
-     * Hear is English-only. Set `"en"` explicitly; omission also means English
-     * and does not enable language detection. Other values receive
-     * `400 unsupported_language`.
-     */
-    language?: "en";
+    /** Omit or use auto for automatic detection; an explicit code pins recognition. */
+    language?: "auto" | "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl";
     /** Input PCM sample rate in Hz. Default 16000 server-side. */
     sampleRate?: number;
     /** Audio frame encoding. Default "pcm16". */
-    encoding?: "pcm16" | "opus";
+    encoding?: "pcm16";
     /** Emit eager partial hypotheses. Default true server-side. */
     interimResults?: boolean;
     /**
-     * Format spoken numbers as digits in the transcript (e.g. "one two three" →
-     * "123"). Useful for voice agents that read back phone numbers, codes, and
-     * amounts. Default false (spoken form). Forwards `?numerals=true` on the URL.
+     * Tri-state number formatting on **final** transcripts. `true` forces digits,
+     * `false` keeps spoken form, omitted keeps the live engine default (ITN on).
+     * Never applied to interim partials. Independent of `smartFormat`.
      */
     numerals?: boolean;
+    /**
+     * Opt-in English punctuation and sentence capitalization on **final**
+     * transcripts only. Interim partials are never formatted. Default false.
+     */
+    smartFormat?: boolean;
+    /**
+     * Spoken punctuation commands (`period`, `comma`, `new paragraph`,
+     * `question mark`) on finals only. Separate from `smartFormat`. Off by default.
+     */
+    dictation?: boolean;
+    /**
+     * Strip `um` / `uh` / `umm` / `uhh` / `er` on finals. Off by default.
+     * Do not enable on legal or compliance audio by default.
+     */
+    dropFillers?: boolean;
+    /**
+     * Per-session names, brands, products, or other distinctive terms. PyAI
+     * sanitizes up to five effective terms. Request terms come first, then stored
+     * `hear_stream` suggestions fill remaining slots. The list is fixed at open.
+     */
+    vocabulary?: string[];
     /**
      * Minimum trailing-pause length before an utterance may end (50-5000 ms).
      * Turn detection may wait longer, bounded at `max(endpointingMs, 1500)`.
@@ -439,6 +547,8 @@ export declare const OmniEvent: {
     readonly Flush: "flush";
     /** Engine requests a client-loop tool invocation. */
     readonly ToolCall: "tool_call";
+    /** A write tool is waiting for the caller to confirm; it has not run. */
+    readonly ToolConfirmationRequired: "tool_confirmation_required";
     /** Session is closing; see close code. */
     readonly SessionEnd: "session_end";
     /** Server fault frame. */
@@ -471,8 +581,6 @@ export interface OmniToolDef {
     name: string;
     description?: string;
     parameters?: Record<string, unknown>;
-    /** When set, engine-POST mode. Omit for client-loop (default). */
-    endpoint?: string;
 }
 export interface OmniToolCallFrame {
     event: "tool_call";
@@ -508,7 +616,9 @@ export interface OmniConfigure {
      * staged, see the Language support reference.
      */
     language?: "en" | "fr" | "es" | "de" | "hi";
-    /** Function calling definitions (client-loop when `endpoint` is omitted). */
+    /** Function calling: hosted catalog names, client-loop schemas, or names of
+     * server tools already registered with POST /v1/tools. An inline `endpoint`
+     * is rejected with `unsupported_tool_transport`. */
     tools?: OmniToolDef[];
     /** Forward-compatible: any other key the engine honors. */
     [k: string]: unknown;
@@ -874,8 +984,45 @@ export interface RecapCallSummary {
     created_at?: number;
     completed_at?: number | null;
 }
+export interface RecapActionItem {
+    owner?: string | null;
+    task: string;
+    due?: string | null;
+}
+export interface RecapTalkRatio {
+    agent: number;
+    customer: number;
+}
+export interface RecapSignal {
+    kind: string;
+    text: string;
+    at_s?: number | null;
+}
+export interface RecapRecord {
+    format: "recap.record.v1";
+    tldr: string | null;
+    summary: string | null;
+    action_items: RecapActionItem[];
+    disposition: string | null;
+    next_steps: string | null;
+    talk_ratio: RecapTalkRatio | null;
+    signals: RecapSignal[];
+    fields: Record<string, unknown>;
+    rep?: Record<string, unknown>;
+    manager?: Record<string, unknown>;
+    ops?: Record<string, unknown>;
+}
 export interface RecapCall extends RecapCallSummary {
-    record?: unknown;
+    record?: RecapRecord;
+    transcript?: {
+        format: "utterances.v1";
+        utterances: Array<{
+            speaker_role: "agent" | "customer";
+            text: string;
+            offset_s: number;
+            duration_s: number;
+        }>;
+    };
     error?: string | null;
     crm_write_status?: string | null;
 }
@@ -994,19 +1141,43 @@ export declare class PyAI {
         list: (params?: {
             gender?: string;
             region?: string;
+            language?: string;
+            tier?: "standard" | "natural";
+            q?: string;
         }) => Promise<ListResponse<Voice>>;
         get: (id: string) => Promise<Voice>;
     };
+    hear: {
+        vocabulary: {
+            /** Read organization-owned vocabulary. Scope `hear:configure`. */
+            get: () => Promise<HearVocabulary>;
+            /** Replace vocabulary and activation profiles. Scope `hear:configure`. */
+            set: (input: HearVocabularyInput) => Promise<HearVocabulary>;
+        };
+    };
+    agents: {
+        list: () => Promise<ListResponse<Agent>>;
+        get: (agentId: string) => Promise<Agent>;
+        create: (input: AgentConfig & {
+            name: string;
+        }) => Promise<Agent>;
+        update: (agentId: string, patch: AgentConfig) => Promise<Agent>;
+        delete: (agentId: string) => Promise<{
+            object: "agent.deleted";
+            agent_id: string;
+            deleted: boolean;
+        }>;
+    };
     audio: {
         /** Text-to-speech. Returns the raw audio bytes (default WAV). */
         speech: (params: SpeechParams) => Promise<ArrayBuffer>;
         /**
          * Text-to-speech, streamed. Resolves as soon as the response headers arrive
          * with the body as a `ReadableStream` of audio bytes, so you can start
-         * playback or forward the audio at the first chunk (the engine's
-         * time-to-first-byte is tens of ms) instead of buffering the whole clip.
-         * Use `mp3` for the smoothest progressive playback. Returns an async
-         * iterable of Uint8Array chunks.
+         * playback or forward the audio at the first chunk. Use `pcm`, `wav`,
+         * or G.711 for streaming; `mp3` and `opus` are buffered server-side.
+         * Consume the stream immediately and cancel its reader when stopping early.
+         * HTTP connection reuse and protocol negotiation are controlled by fetch.
          */
         speechStream: (params: SpeechParams) => Promise<ReadableStream<Uint8Array>>;
         /** Synchronous speech-to-text (multipart upload). */
@@ -1015,11 +1186,13 @@ export declare class PyAI {
                 file: Blob;
                 filename?: string;
                 model?: string;
-                /**
-                 * Hear is English-only. Omission means English, not auto-detect; other
-                 * values receive `400 unsupported_language`.
-                 */
-                language?: "en";
+                /** Optional language hint. Omission enables automatic detection. */
+                language?: "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl";
+                numerals?: boolean;
+                smart_format?: boolean;
+                dictation?: boolean;
+                drop_fillers?: boolean;
+                vocabulary?: string[];
                 response_format?: "json" | "text" | "verbose_json";
                 /**
                  * Deterministic seed for reproducible eval runs. Forward-compatible:
@@ -1200,7 +1373,7 @@ export declare class PyAI {
          * 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
+         * `new WebSocket(session.url, ["pyai.v1", "pyai-key." + session.token])`. The token
          * expires after `ttlSeconds` (default 60s) and only works from
          * `allowedOrigins`. Scope `omni:session`.
          */
@@ -1218,8 +1391,15 @@ export declare class PyAI {
     };
     /** Build the canonical Omni WebSocket URL. */
     realtimeURL(opts?: RealtimeOptions): string;
-    /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
+    /** The subprotocol token that carries the key on a WS upgrade. */
     realtimeSubprotocol(): string;
+    /**
+     * The full subprotocol list to open a PyAI WebSocket with:
+     * `[marker, credential]`. Always pass BOTH — see
+     * {@link REALTIME_SUBPROTOCOL_MARKER}. Pass `token` to use an ephemeral
+     * session token (from `omni.createSession`) instead of the secret key.
+     */
+    realtimeSubprotocols(token?: string): string[];
     /** Build the Hear streaming-STT WebSocket URL (`/v1/audio/transcriptions/stream`). */
     hearStreamURL(opts?: HearStreamOptions): string;
     /** Build the AMD detection WebSocket URL (`/v1/amd/stream`). */

package/dist/index.js

@@ -62,10 +62,16 @@ export const HearFrameType = {
     /** Server-side fault frame. */
     Error: "error",
 };
-/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+/**
+ * WebSocket close codes used across the PyAI realtime/streaming surfaces.
+ * Browser callers may initiate only Normal or values in 3000-4999; the
+ * standards-reserved values below are server close observations.
+ */
 export const WSCloseCode = {
     /** Normal closure. */
     Normal: 1000,
+    /** Browser-safe private application code for a malformed peer protocol frame. */
+    ProtocolViolation: 4002,
     /** Auth/policy: bad key, missing scope, or revoked token. */
     PolicyViolation: 1008,
     /** Engine/internal error. */
@@ -92,7 +98,22 @@ export const ErrorCode = {
     IdempotencyConflict: "idempotency_conflict",
     NotFound: "not_found",
     NumberInUse: "number_in_use",
+    UnsupportedToolTransport: "unsupported_tool_transport",
 };
+/**
+ * The non-secret marker every PyAI realtime client offers ALONGSIDE its
+ * `pyai-key.<KEY>` credential token.
+ *
+ * A browser cannot set `Authorization` on a WebSocket, so the key rides in
+ * `Sec-WebSocket-Protocol`. RFC 6455 makes the server echo the subprotocol it
+ * SELECTS, so a server that selects the credential publishes the credential —
+ * which api.pyai.com did until 2026-09-07. The edge now echoes only this
+ * marker. Offering it is not optional for Node clients: `ws` throws
+ * "Server sent no subprotocol" when it offered subprotocols and the 101
+ * selected none, and RFC 6455 lets the server select only a value the client
+ * actually offered.
+ */
+export const REALTIME_SUBPROTOCOL_MARKER = "pyai.v1";
 /**
  * A live Hear streaming-STT session. Hides the frame protocol: stream audio
  * with {@link HearStream.sendAudio}, get `onPartial`/`onFinal`/`onError`
@@ -114,7 +135,7 @@ export class HearStream {
         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 = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, subprotocol]);
         this.ws.onopen = () => {
             opts.onOpen?.();
         };
@@ -205,7 +226,7 @@ export class AmdStream {
         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 = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, 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"));
@@ -277,6 +298,8 @@ export const OmniEvent = {
     Flush: "flush",
     /** Engine requests a client-loop tool invocation. */
     ToolCall: "tool_call",
+    /** A write tool is waiting for the caller to confirm; it has not run. */
+    ToolConfirmationRequired: "tool_confirmation_required",
     /** Session is closing; see close code. */
     SessionEnd: "session_end",
     /** Server fault frame. */
@@ -413,7 +436,7 @@ export class OmniConnection {
         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 = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, subprotocol]);
         this.ws.onopen = () => {
             if (opts.configure) {
                 try {
@@ -679,12 +702,41 @@ export class PyAI {
                 q.set("gender", params.gender);
             if (params.region)
                 q.set("region", params.region);
+            if (params.language)
+                q.set("language", params.language);
+            if (params.tier)
+                q.set("tier", params.tier);
+            if (params.q)
+                q.set("q", params.q);
             const qs = q.toString();
             const page = await this.getJson(`/v1/voices${qs ? `?${qs}` : ""}`);
             return { ...page, data: page.data.map(normalizeVoice) };
         },
         get: async (id) => normalizeVoice(await this.getJson(`/v1/voices/${encodeURIComponent(id)}`)),
     };
+    // --- Hear organization settings ----------------------------------------
+    hear = {
+        vocabulary: {
+            /** Read organization-owned vocabulary. Scope `hear:configure`. */
+            get: () => this.getJson("/v1/hear/vocabulary"),
+            /** Replace vocabulary and activation profiles. Scope `hear:configure`. */
+            set: (input) => this.putJson("/v1/hear/vocabulary", {
+                terms: input.terms,
+                enabled_for: input.enabledFor,
+            }),
+        },
+    };
+    // --- managed Agents ----------------------------------------------------
+    agents = {
+        list: () => this.getJson("/v1/agents"),
+        get: (agentId) => this.getJson(`/v1/agents/${encodeURIComponent(agentId)}`),
+        create: (input) => this.postJson("/v1/agents", input),
+        update: (agentId, patch) => this.postJson(`/v1/agents/${encodeURIComponent(agentId)}`, patch),
+        delete: async (agentId) => {
+            const response = await this.deleteReq(`/v1/agents/${encodeURIComponent(agentId)}`);
+            return (await response.json());
+        },
+    };
     // --- audio --------------------------------------------------------------
     audio = {
         /** Text-to-speech. Returns the raw audio bytes (default WAV). */
@@ -700,10 +752,10 @@ export class PyAI {
         /**
          * Text-to-speech, streamed. Resolves as soon as the response headers arrive
          * with the body as a `ReadableStream` of audio bytes, so you can start
-         * playback or forward the audio at the first chunk (the engine's
-         * time-to-first-byte is tens of ms) instead of buffering the whole clip.
-         * Use `mp3` for the smoothest progressive playback. Returns an async
-         * iterable of Uint8Array chunks.
+         * playback or forward the audio at the first chunk. Use `pcm`, `wav`,
+         * or G.711 for streaming; `mp3` and `opus` are buffered server-side.
+         * Consume the stream immediately and cancel its reader when stopping early.
+         * HTTP connection reuse and protocol negotiation are controlled by fetch.
          */
         speechStream: async (params) => {
             assertActiveSpeechParams(params);
@@ -724,6 +776,16 @@ export class PyAI {
                 form.set("model", params.model ?? "pyai-hear");
                 if (params.language)
                     form.set("language", params.language);
+                if (params.numerals !== undefined)
+                    form.set("numerals", String(params.numerals));
+                if (params.smart_format !== undefined)
+                    form.set("smart_format", String(params.smart_format));
+                if (params.dictation !== undefined)
+                    form.set("dictation", String(params.dictation));
+                if (params.drop_fillers !== undefined)
+                    form.set("drop_fillers", String(params.drop_fillers));
+                if (params.vocabulary?.length)
+                    form.set("vocabulary", params.vocabulary.join(","));
                 if (params.response_format)
                     form.set("response_format", params.response_format);
                 if (params.seed !== undefined)
@@ -985,7 +1047,7 @@ export class PyAI {
          * 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
+         * `new WebSocket(session.url, ["pyai.v1", "pyai-key." + session.token])`. The token
          * expires after `ttlSeconds` (default 60s) and only works from
          * `allowedOrigins`. Scope `omni:session`.
          */
@@ -1035,14 +1097,29 @@ export class PyAI {
         const qs = q.toString();
         return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
     }
-    /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
+    /** The subprotocol token that carries the key on a WS upgrade. */
     realtimeSubprotocol() {
         return `pyai-key.${this.apiKey}`;
     }
+    /**
+     * The full subprotocol list to open a PyAI WebSocket with:
+     * `[marker, credential]`. Always pass BOTH — see
+     * {@link REALTIME_SUBPROTOCOL_MARKER}. Pass `token` to use an ephemeral
+     * session token (from `omni.createSession`) instead of the secret key.
+     */
+    realtimeSubprotocols(token) {
+        return [
+            REALTIME_SUBPROTOCOL_MARKER,
+            token ? `pyai-key.${token}` : this.realtimeSubprotocol(),
+        ];
+    }
     /** 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 ?? {});
+        // `context` is private to PyAI's adapter-to-server hop. Never expose or
+        // forward it from the public SDK escape hatch.
+        q.delete("context");
         q.set("protocol", "pyai-hear-v1");
         if (opts.model)
             q.set("model", opts.model);
@@ -1056,6 +1133,15 @@ export class PyAI {
             q.set("interim_results", String(opts.interimResults));
         if (opts.numerals !== undefined)
             q.set("numerals", String(opts.numerals));
+        if (opts.smartFormat !== undefined)
+            q.set("smart_format", String(opts.smartFormat));
+        if (opts.dictation !== undefined)
+            q.set("dictation", String(opts.dictation));
+        if (opts.dropFillers !== undefined)
+            q.set("drop_fillers", String(opts.dropFillers));
+        if (opts.vocabulary?.length) {
+            q.set("vocabulary", JSON.stringify(opts.vocabulary));
+        }
         if (opts.endpointingMs !== undefined)
             q.set("endpointing_ms", String(opts.endpointingMs));
         const qs = q.toString();
@@ -1080,8 +1166,8 @@ export class PyAI {
     connectRealtime(opts = {}) {
         const WS = globalThis.WebSocket;
         if (!WS)
-            throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocol() with a WS library");
-        return new WS(this.realtimeURL(opts), [this.realtimeSubprotocol()]);
+            throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocols() with a WS library");
+        return new WS(this.realtimeURL(opts), this.realtimeSubprotocols());
     }
 }
 export default PyAI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",

package/src/index.ts

@@ -41,6 +41,20 @@ export interface Voice {
   name?: string;
   gender?: string;
   region?: string;
+  language?: string;
+  /** Customer-facing quality tier. */
+  tier?: "standard" | "natural";
+  /** Permanent convenience inputs accepted on the advertised surfaces. */
+  aliases?: string[];
+  /** Product surfaces on which this stock voice can be selected. */
+  available_on?: Array<"speak" | "omni">;
+  /** Accepted Speak delivery modes. Empty means the voice has no Speak surface. */
+  synthesis_modes?: Array<"streaming" | "async">;
+  /** Voice-specific amount on top of the selected product's base rate. */
+  pricing?: {
+    included_in_base_price: boolean;
+    additional_price_usd_per_minute: number;
+  };
   [k: string]: unknown;
 }
 
@@ -104,6 +118,13 @@ export interface SpeechParams {
   input: string;
   voice?: string;
   model?: SpeakModel;
+  /**
+   * Delivery mode. The API defaults to true and every catalog voice accepts
+   * both values. Set false when you want one complete buffered body with a
+   * `Content-Length`. A voice whose serving fleet has no streaming lane is
+   * rendered buffered either way and says so with `x-pyai-stream: buffered`.
+   */
+  stream?: boolean;
   /**
    * Output container/codec, resampled+encoded server-side. One of
    * {@link SpeechFormat}, anything else is a `400 unsupported_format`. Omit for
@@ -150,8 +171,62 @@ export interface CreateJobParams {
   diarize?: boolean;
   channel?: boolean;
   numerals?: boolean;
+  smart_format?: boolean;
+  dictation?: boolean;
+  drop_fillers?: boolean;
+  /**
+   * Per-job names, brands, products, or distinctive terms. PyAI keeps up to
+   * five valid entries after trimming, deduplication, and common-word
+   * filtering.
+   */
+  vocabulary?: string[];
   output_formats?: Array<"json" | "srt" | "vtt">;
   webhook_url?: string;
+  call_id?: string;
+  pack_id?: string;
+  call_direction?: "inbound" | "outbound";
+  customer_name?: string;
+}
+
+export type HearVocabularyProfile = "batch" | "hear_stream";
+
+export interface HearVocabularyInput {
+  /** Organization-owned names, brands, products, or distinctive terms. */
+  terms: string[];
+  /** Stored terms remain inert unless a use case is selected here. */
+  enabledFor: HearVocabularyProfile[];
+}
+
+export interface HearVocabulary {
+  object: "hear.vocabulary";
+  /** Sanitized stored list, at most five terms. */
+  terms: string[];
+  /** Use cases that may add stored suggestions. */
+  enabled_for: HearVocabularyProfile[];
+  /** Unix milliseconds, or null before the first save. */
+  updated_at: number | null;
+}
+
+export interface AgentConfig {
+  name?: string;
+  persona_system_prompt?: string | null;
+  greeting?: string | null;
+  voice_id?: string | null;
+  language?: "en" | "fr" | "es" | "de" | "hi" | null;
+  /**
+   * Opt-in speech-recognition vocabulary. PyAI sanitizes and keeps at most
+   * five terms. An empty list or null turns it off.
+   */
+  vocabulary?: string[] | null;
+  [key: string]: unknown;
+}
+
+export interface Agent {
+  object: "agent";
+  agent_id: string;
+  name: string;
+  vocabulary: string[];
+  [key: string]: unknown;
 }
 
 export interface RealtimeOptions {
@@ -226,10 +301,16 @@ export const HearFrameType = {
 } as const;
 export type HearFrameType = (typeof HearFrameType)[keyof typeof HearFrameType];
 
-/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+/**
+ * WebSocket close codes used across the PyAI realtime/streaming surfaces.
+ * Browser callers may initiate only Normal or values in 3000-4999; the
+ * standards-reserved values below are server close observations.
+ */
 export const WSCloseCode = {
   /** Normal closure. */
   Normal: 1000,
+  /** Browser-safe private application code for a malformed peer protocol frame. */
+  ProtocolViolation: 4002,
   /** Auth/policy: bad key, missing scope, or revoked token. */
   PolicyViolation: 1008,
   /** Engine/internal error. */
@@ -258,6 +339,7 @@ export const ErrorCode = {
   IdempotencyConflict: "idempotency_conflict",
   NotFound: "not_found",
   NumberInUse: "number_in_use",
+  UnsupportedToolTransport: "unsupported_tool_transport",
 } as const;
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 
@@ -366,29 +448,61 @@ export interface WebSocketLike {
   onclose: ((ev: { code: number; reason: string }) => void) | null;
 }
 
+/**
+ * The non-secret marker every PyAI realtime client offers ALONGSIDE its
+ * `pyai-key.<KEY>` credential token.
+ *
+ * A browser cannot set `Authorization` on a WebSocket, so the key rides in
+ * `Sec-WebSocket-Protocol`. RFC 6455 makes the server echo the subprotocol it
+ * SELECTS, so a server that selects the credential publishes the credential —
+ * which api.pyai.com did until 2026-09-07. The edge now echoes only this
+ * marker. Offering it is not optional for Node clients: `ws` throws
+ * "Server sent no subprotocol" when it offered subprotocols and the 101
+ * selected none, and RFC 6455 lets the server select only a value the client
+ * actually offered.
+ */
+export const REALTIME_SUBPROTOCOL_MARKER = "pyai.v1";
+
 export type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
 
 export interface HearStreamOptions {
   /** Streaming STT model. Server default `pyai-hear`. */
   model?: string;
-  /**
-   * Hear is English-only. Set `"en"` explicitly; omission also means English
-   * and does not enable language detection. Other values receive
-   * `400 unsupported_language`.
-   */
-  language?: "en";
+  /** Omit or use auto for automatic detection; an explicit code pins recognition. */
+  language?: "auto" | "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl";
   /** Input PCM sample rate in Hz. Default 16000 server-side. */
   sampleRate?: number;
   /** Audio frame encoding. Default "pcm16". */
-  encoding?: "pcm16" | "opus";
+  encoding?: "pcm16";
   /** Emit eager partial hypotheses. Default true server-side. */
   interimResults?: boolean;
   /**
-   * Format spoken numbers as digits in the transcript (e.g. "one two three" →
-   * "123"). Useful for voice agents that read back phone numbers, codes, and
-   * amounts. Default false (spoken form). Forwards `?numerals=true` on the URL.
+   * Tri-state number formatting on **final** transcripts. `true` forces digits,
+   * `false` keeps spoken form, omitted keeps the live engine default (ITN on).
+   * Never applied to interim partials. Independent of `smartFormat`.
    */
   numerals?: boolean;
+  /**
+   * Opt-in English punctuation and sentence capitalization on **final**
+   * transcripts only. Interim partials are never formatted. Default false.
+   */
+  smartFormat?: boolean;
+  /**
+   * Spoken punctuation commands (`period`, `comma`, `new paragraph`,
+   * `question mark`) on finals only. Separate from `smartFormat`. Off by default.
+   */
+  dictation?: boolean;
+  /**
+   * Strip `um` / `uh` / `umm` / `uhh` / `er` on finals. Off by default.
+   * Do not enable on legal or compliance audio by default.
+   */
+  dropFillers?: boolean;
+  /**
+   * Per-session names, brands, products, or other distinctive terms. PyAI
+   * sanitizes up to five effective terms. Request terms come first, then stored
+   * `hear_stream` suggestions fill remaining slots. The list is fixed at open.
+   */
+  vocabulary?: string[];
   /**
    * Minimum trailing-pause length before an utterance may end (50-5000 ms).
    * Turn detection may wait longer, bounded at `max(endpointingMs, 1500)`.
@@ -454,7 +568,7 @@ export class HearStream {
         "No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to transcriptions.stream()",
       );
     }
-    this.ws = new WS(url, [subprotocol]);
+    this.ws = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, subprotocol]);
     this.ws.onopen = () => {
       opts.onOpen?.();
     };
@@ -553,7 +667,7 @@ export class AmdStream {
         "No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to amd.stream()",
       );
     }
-    this.ws = new WS(url, [subprotocol]);
+    this.ws = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, 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"));
@@ -629,6 +743,8 @@ export const OmniEvent = {
   Flush: "flush",
   /** Engine requests a client-loop tool invocation. */
   ToolCall: "tool_call",
+  /** A write tool is waiting for the caller to confirm; it has not run. */
+  ToolConfirmationRequired: "tool_confirmation_required",
   /** Session is closing; see close code. */
   SessionEnd: "session_end",
   /** Server fault frame. */
@@ -762,8 +878,6 @@ export interface OmniToolDef {
   name: string;
   description?: string;
   parameters?: Record<string, unknown>;
-  /** When set, engine-POST mode. Omit for client-loop (default). */
-  endpoint?: string;
 }
 
 export interface OmniToolCallFrame {
@@ -801,7 +915,9 @@ export interface OmniConfigure {
    * staged, see the Language support reference.
    */
   language?: "en" | "fr" | "es" | "de" | "hi";
-  /** Function calling definitions (client-loop when `endpoint` is omitted). */
+  /** Function calling: hosted catalog names, client-loop schemas, or names of
+   * server tools already registered with POST /v1/tools. An inline `endpoint`
+   * is rejected with `unsupported_tool_transport`. */
   tools?: OmniToolDef[];
   /** Forward-compatible: any other key the engine honors. */
   [k: string]: unknown;
@@ -894,7 +1010,7 @@ export class OmniConnection {
         "No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to omni.connect()",
       );
     }
-    this.ws = new WS(url, [subprotocol]);
+    this.ws = new WS(url, [REALTIME_SUBPROTOCOL_MARKER, subprotocol]);
     this.ws.onopen = () => {
       if (opts.configure) {
         try {
@@ -1359,8 +1475,41 @@ export interface RecapCallSummary {
   completed_at?: number | null;
 }
 
+export interface RecapActionItem {
+  owner?: string | null;
+  task: string;
+  due?: string | null;
+}
+
+export interface RecapTalkRatio {
+  agent: number;
+  customer: number;
+}
+
+export interface RecapSignal {
+  kind: string;
+  text: string;
+  at_s?: number | null;
+}
+
+export interface RecapRecord {
+  format: "recap.record.v1";
+  tldr: string | null;
+  summary: string | null;
+  action_items: RecapActionItem[];
+  disposition: string | null;
+  next_steps: string | null;
+  talk_ratio: RecapTalkRatio | null;
+  signals: RecapSignal[];
+  fields: Record<string, unknown>;
+  rep?: Record<string, unknown>;
+  manager?: Record<string, unknown>;
+  ops?: Record<string, unknown>;
+}
+
 export interface RecapCall extends RecapCallSummary {
-  record?: unknown;
+  record?: RecapRecord;
+  transcript?: { format: "utterances.v1"; utterances: Array<{ speaker_role: "agent" | "customer"; text: string; offset_s: number; duration_s: number }> };
   error?: string | null;
   crm_write_status?: string | null;
 }
@@ -1574,10 +1723,19 @@ export class PyAI {
   // --- voices -------------------------------------------------------------
 
   voices = {
-    list: async (params: { gender?: string; region?: string } = {}): Promise<ListResponse<Voice>> => {
+    list: async (params: {
+      gender?: string;
+      region?: string;
+      language?: string;
+      tier?: "standard" | "natural";
+      q?: string;
+    } = {}): Promise<ListResponse<Voice>> => {
       const q = new URLSearchParams();
       if (params.gender) q.set("gender", params.gender);
       if (params.region) q.set("region", params.region);
+      if (params.language) q.set("language", params.language);
+      if (params.tier) q.set("tier", params.tier);
+      if (params.q) q.set("q", params.q);
       const qs = q.toString();
       const page = await this.getJson<ListResponse<Record<string, unknown>>>(
         `/v1/voices${qs ? `?${qs}` : ""}`,
@@ -1592,6 +1750,46 @@ export class PyAI {
       ),
   };
 
+  // --- Hear organization settings ----------------------------------------
+
+  hear = {
+    vocabulary: {
+      /** Read organization-owned vocabulary. Scope `hear:configure`. */
+      get: (): Promise<HearVocabulary> =>
+        this.getJson("/v1/hear/vocabulary"),
+      /** Replace vocabulary and activation profiles. Scope `hear:configure`. */
+      set: (input: HearVocabularyInput): Promise<HearVocabulary> =>
+        this.putJson("/v1/hear/vocabulary", {
+          terms: input.terms,
+          enabled_for: input.enabledFor,
+        }),
+    },
+  };
+
+  // --- managed Agents ----------------------------------------------------
+
+  agents = {
+    list: (): Promise<ListResponse<Agent>> => this.getJson("/v1/agents"),
+    get: (agentId: string): Promise<Agent> =>
+      this.getJson(`/v1/agents/${encodeURIComponent(agentId)}`),
+    create: (input: AgentConfig & { name: string }): Promise<Agent> =>
+      this.postJson("/v1/agents", input),
+    update: (agentId: string, patch: AgentConfig): Promise<Agent> =>
+      this.postJson(`/v1/agents/${encodeURIComponent(agentId)}`, patch),
+    delete: async (
+      agentId: string,
+    ): Promise<{ object: "agent.deleted"; agent_id: string; deleted: boolean }> => {
+      const response = await this.deleteReq(
+        `/v1/agents/${encodeURIComponent(agentId)}`,
+      );
+      return (await response.json()) as {
+        object: "agent.deleted";
+        agent_id: string;
+        deleted: boolean;
+      };
+    },
+  };
+
   // --- audio --------------------------------------------------------------
 
   audio = {
@@ -1608,10 +1806,10 @@ export class PyAI {
     /**
      * Text-to-speech, streamed. Resolves as soon as the response headers arrive
      * with the body as a `ReadableStream` of audio bytes, so you can start
-     * playback or forward the audio at the first chunk (the engine's
-     * time-to-first-byte is tens of ms) instead of buffering the whole clip.
-     * Use `mp3` for the smoothest progressive playback. Returns an async
-     * iterable of Uint8Array chunks.
+     * playback or forward the audio at the first chunk. Use `pcm`, `wav`,
+     * or G.711 for streaming; `mp3` and `opus` are buffered server-side.
+     * Consume the stream immediately and cancel its reader when stopping early.
+     * HTTP connection reuse and protocol negotiation are controlled by fetch.
      */
     speechStream: async (params: SpeechParams): Promise<ReadableStream<Uint8Array>> => {
       assertActiveSpeechParams(params);
@@ -1629,11 +1827,13 @@ export class PyAI {
         file: Blob;
         filename?: string;
         model?: string;
-        /**
-         * Hear is English-only. Omission means English, not auto-detect; other
-         * values receive `400 unsupported_language`.
-         */
-        language?: "en";
+        /** Optional language hint. Omission enables automatic detection. */
+        language?: "en" | "es" | "fr" | "de" | "hi" | "it" | "pt" | "nl";
+        numerals?: boolean;
+        smart_format?: boolean;
+        dictation?: boolean;
+        drop_fillers?: boolean;
+        vocabulary?: string[];
         response_format?: "json" | "text" | "verbose_json";
         /**
          * Deterministic seed for reproducible eval runs. Forward-compatible:
@@ -1647,6 +1847,11 @@ export class PyAI {
         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.numerals !== undefined) form.set("numerals", String(params.numerals));
+        if (params.smart_format !== undefined) form.set("smart_format", String(params.smart_format));
+        if (params.dictation !== undefined) form.set("dictation", String(params.dictation));
+        if (params.drop_fillers !== undefined) form.set("drop_fillers", String(params.drop_fillers));
+        if (params.vocabulary?.length) form.set("vocabulary", params.vocabulary.join(","));
         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));
@@ -1921,7 +2126,7 @@ export class PyAI {
      * 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
+     * `new WebSocket(session.url, ["pyai.v1", "pyai-key." + session.token])`. The token
      * expires after `ttlSeconds` (default 60s) and only works from
      * `allowedOrigins`. Scope `omni:session`.
      */
@@ -1973,15 +2178,31 @@ export class PyAI {
     return `${wsBase}/v1/omni${qs ? `?${qs}` : ""}`;
   }
 
-  /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
+  /** The subprotocol token that carries the key on a WS upgrade. */
   realtimeSubprotocol(): string {
     return `pyai-key.${this.apiKey}`;
   }
 
+  /**
+   * The full subprotocol list to open a PyAI WebSocket with:
+   * `[marker, credential]`. Always pass BOTH — see
+   * {@link REALTIME_SUBPROTOCOL_MARKER}. Pass `token` to use an ephemeral
+   * session token (from `omni.createSession`) instead of the secret key.
+   */
+  realtimeSubprotocols(token?: string): string[] {
+    return [
+      REALTIME_SUBPROTOCOL_MARKER,
+      token ? `pyai-key.${token}` : this.realtimeSubprotocol(),
+    ];
+  }
+
   /** Build the Hear streaming-STT WebSocket URL (`/v1/audio/transcriptions/stream`). */
   hearStreamURL(opts: HearStreamOptions = {}): string {
     const wsBase = this.baseURL.replace(/^http/, "ws");
     const q = new URLSearchParams(opts.query ?? {});
+    // `context` is private to PyAI's adapter-to-server hop. Never expose or
+    // forward it from the public SDK escape hatch.
+    q.delete("context");
     q.set("protocol", "pyai-hear-v1");
     if (opts.model) q.set("model", opts.model);
     if (opts.language) q.set("language", opts.language);
@@ -1989,6 +2210,12 @@ export class PyAI {
     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.smartFormat !== undefined) q.set("smart_format", String(opts.smartFormat));
+    if (opts.dictation !== undefined) q.set("dictation", String(opts.dictation));
+    if (opts.dropFillers !== undefined) q.set("drop_fillers", String(opts.dropFillers));
+    if (opts.vocabulary?.length) {
+      q.set("vocabulary", JSON.stringify(opts.vocabulary));
+    }
     if (opts.endpointingMs !== undefined) q.set("endpointing_ms", String(opts.endpointingMs));
     const qs = q.toString();
     return `${wsBase}/v1/audio/transcriptions/stream${qs ? `?${qs}` : ""}`;
@@ -2011,8 +2238,8 @@ export class PyAI {
    */
   connectRealtime(opts: RealtimeOptions = {}): WebSocket {
     const WS = (globalThis as { WebSocket?: typeof WebSocket }).WebSocket;
-    if (!WS) throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocol() with a WS library");
-    return new WS(this.realtimeURL(opts), [this.realtimeSubprotocol()]);
+    if (!WS) throw new Error("No global WebSocket; use realtimeURL()/realtimeSubprotocols() with a WS library");
+    return new WS(this.realtimeURL(opts), this.realtimeSubprotocols());
   }
 }