@pyai/sdk 0.2.1 → 0.2.3

package/dist/index.d.ts

@@ -1,10 +1,9 @@
 /**
- * @pyai/sdk — official TypeScript/JavaScript client for the PyAI API.
+ * @pyai/sdk, official TypeScript/JavaScript client for the PyAI API.
  *
  * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
  * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
- * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque —
- * never parsed.
+ * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque, * never parsed.
  */
 export interface PyAIOptions {
     /** A pyai_live_ or pyai_test_ key. */
@@ -48,7 +47,7 @@ export interface TranscriptionJob {
 }
 /**
  * Output container/codec for `audio.speech`. This is the **exact** set the
- * server accepts on `POST /v1/audio/speech` — any other value is rejected with
+ * server accepts on `POST /v1/audio/speech`, any other value is rejected with
  * `400 unsupported_format`. The default (when `response_format` is omitted) is
  * `mp3`. Omit `sample_rate` for the engine's native 24 kHz (`g711_*` is always
  * 8 kHz).
@@ -80,20 +79,20 @@ export interface SpeechParams {
     model?: string;
     /**
      * Output container/codec, resampled+encoded server-side. One of
-     * {@link SpeechFormat} — anything else is a `400 unsupported_format`. Omit for
+     * {@link SpeechFormat}, anything else is a `400 unsupported_format`. Omit for
      * the default of `mp3`.
      *
-     * `g711_ulaw`/`g711_alaw` return raw 8 kHz mono G.711 — the bytes Twilio/SIP
+     * `g711_ulaw`/`g711_alaw` return raw 8 kHz mono G.711, the bytes Twilio/SIP
      * media streams expect, so you can hand the response straight to a telephony
      * frame without a client-side resampler or μ-law encoder. `sample_rate` is
      * forced to 8000 for those (omit it, or set exactly 8000). `pcm` is raw,
      * headerless int16 LE mono at `sample_rate`. `mp3`/`opus` are buffered (not
-     * chunk-streamed) — use them with `speech`, not `speechStream`.
+     * chunk-streamed), use them with `speech`, not `speechStream`.
      */
     response_format?: SpeechFormat;
     /**
      * Output sample rate in Hz. One of {@link SpeechSampleRate}
-     * (8000/16000/24000/48000) — anything else is a `400`. Omit for the engine's
+     * (8000/16000/24000/48000), anything else is a `400`. Omit for the engine's
      * native 24 kHz; `g711_*` is always 8000 (forced). Set `8000`/`16000` for
      * telephony pipelines, most often with `response_format: "pcm"`.
      */
@@ -106,8 +105,7 @@ export interface SpeechParams {
      */
     seed?: number;
     /**
-     * Sampling temperature (lower = more deterministic). Forward-compatible —
-     * honored once the engine supports it, otherwise ignored.
+     * Sampling temperature (lower = more deterministic). Forward-compatible, * honored once the engine supports it, otherwise ignored.
      */
     temperature?: number;
 }
@@ -130,7 +128,7 @@ export interface RealtimeOptions {
      */
     sessionLabel?: string;
     /**
-     * @deprecated Use {@link sessionLabel}. Kept for back-compat — emitted as the
+     * @deprecated Use {@link sessionLabel}. Kept for back-compat, emitted as the
      * `agent_id` query alias, which the gateway still accepts. Ignored if
      * `sessionLabel` is set.
      */
@@ -142,7 +140,7 @@ export interface RealtimeOptions {
 export interface OmniSessionParams {
     /**
      * Browser origins (scheme://host[:port]) the minted token may connect from.
-     * Required and non-empty — a browser token must be origin-locked. `*` is not
+     * Required and non-empty, a browser token must be origin-locked. `*` is not
      * allowed.
      */
     allowedOrigins: string[];
@@ -152,7 +150,7 @@ export interface OmniSessionParams {
     sessionLabel?: string;
 }
 /**
- * The result of {@link PyAI.omni}.createSession — a short-lived credential safe
+ * The result of {@link PyAI.omni}.createSession, a short-lived credential safe
  * to hand to the browser. Use {@link OmniSession.token} as the WebSocket
  * subprotocol `pyai-key.<token>` against {@link OmniSession.url}.
  */
@@ -197,7 +195,7 @@ export declare const WSCloseCode: {
 export type WSCloseCode = (typeof WSCloseCode)[keyof typeof WSCloseCode];
 /**
  * Stable, machine-readable error `code`s (the documented contract). Branch on
- * these. The set is treated as open — `PyAIError.code` stays `string` — so a
+ * these. The set is treated as open, `PyAIError.code` stays `string`, so a
  * new server code never breaks the build, but the known ones are named here.
  */
 export declare const ErrorCode: {
@@ -267,7 +265,7 @@ export interface HearErrorFrame {
 }
 export type HearFrame = HearPartialFrame | HearFinalFrame | HearUsageFrame | HearErrorFrame;
 /**
- * Minimal structural WebSocket — matches both the browser/Node global
+ * Minimal structural WebSocket, matches both the browser/Node global
  * `WebSocket` and the `ws` package, and lets tests inject a mock.
  */
 export interface WebSocketLike {
@@ -303,8 +301,8 @@ export interface HearStreamOptions {
      */
     numerals?: boolean;
     /**
-     * Turn-segmentation tuning: trailing-pause (ms, 50–2000) that ends an
-     * utterance. Forwards `?endpointing_ms=` — clamped + honored once the engine
+     * Turn-segmentation tuning: trailing-pause (ms, 50-2000) that ends an
+     * utterance. Forwards `?endpointing_ms=`, clamped + honored once the engine
      * supports it; a no-op when omitted. Drive end-of-turn yourself with
      * {@link HearStream.commit} for full control today.
      */
@@ -315,12 +313,12 @@ export interface HearStreamOptions {
      * array. Bills a single `cue.minutes` line instead of the Hear rate.
      */
     grounding?: boolean;
-    /** Cue: number of KB passages to retrieve per turn (1–20, default 3). */
+    /** Cue: number of KB passages to retrieve per turn (1-20, default 3). */
     groundingK?: number;
-    /** Cue: drop passages scoring below this (0–1, default 0 = keep all). */
+    /** Cue: drop passages scoring below this (0-1, default 0 = keep all). */
     groundingMinScore?: number;
     /** Cue: max ms to wait for retrieval at the final before failing open to
-     * `grounding: []` (50–2000, default 450). */
+     * `grounding: []` (50-2000, default 450). */
     groundingTimeoutMs?: number;
     /** Extra query params merged onto the connect URL. */
     query?: Record<string, string>;
@@ -362,6 +360,32 @@ export declare class HearStream {
     /** Current WebSocket readyState. */
     get readyState(): number;
 }
+/**
+ * A live AMD (answering-machine-detection) stream. The wire is Twilio's Media
+ * Streams protocol, so if you're already on Twilio the usual path is one line of
+ * TwiML pointing `<Stream url="wss://api.pyai.com/v1/amd/stream">` at PyAI, no
+ * SDK needed. This helper is for server-side clients that fork the media
+ * themselves: send Twilio `start`/`media`/`stop` frames with {@link AmdStream.send}
+ * (or raw μ-law audio with {@link AmdStream.sendAudio}) and receive the `amd`
+ * decision via `onDecision`. Construct via `pyai.amd.stream()`.
+ */
+export declare class AmdStream {
+    private readonly ws;
+    private readonly opts;
+    private closed;
+    constructor(url: string, subprotocol: string, opts: AmdStreamOptions);
+    private handleMessage;
+    /** Send a Twilio Media Streams control/media frame (JSON) or a raw string. */
+    send(frame: string | Record<string, unknown>): void;
+    /** Send a raw audio chunk (G.711 μ-law 8 kHz for the Twilio-native path). */
+    sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void;
+    /** Close the socket. */
+    close(code?: number, reason?: string): void;
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket(): WebSocketLike;
+    /** Current WebSocket readyState. */
+    get readyState(): number;
+}
 /**
  * Event names on Omni **server → client** frames. ⚠️ Note the asymmetry:
  * inbound frames are keyed on `event`, but your **outbound** control frames
@@ -383,6 +407,8 @@ export declare const OmniEvent: {
     readonly BargeIn: "barge_in";
     /** Alias for barge-in on some engine builds. */
     readonly Flush: "flush";
+    /** Engine requests a client-loop tool invocation. */
+    readonly ToolCall: "tool_call";
     /** Session is closing; see close code. */
     readonly SessionEnd: "session_end";
     /** Server fault frame. */
@@ -394,15 +420,39 @@ export interface OmniServerFrame {
     event: string;
     [k: string]: unknown;
 }
+/** Canonical, sanitized transcript delivered by the native Omni demux. */
+export interface OmniTranscriptFrame extends OmniServerFrame {
+    event: "transcript";
+    role: "user" | "assistant";
+    text: string;
+    final: boolean;
+    mode: "delta" | "replace";
+    sequence?: number;
+}
+/** Normalize the live UTF-8 0x02 body and the documented direct-object legacy shape. */
+export declare function normalizeOmniTranscriptBody(bytes: Uint8Array): OmniTranscriptFrame | null;
 /** A binary agent-audio chunk delivered to {@link OmniConnectOptions.onAudio}. */
 export type OmniAudioChunk = ArrayBuffer | ArrayBufferView | Blob;
+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 {
+    type: "tool_call";
+    call_id: string;
+    name: string;
+    arguments?: Record<string, unknown>;
+}
 /**
  * The agent config sent as the `configure` control frame. These are the wire
  * (snake_case) fields the engine reads; it's an **open bag**, so forward-compat
- * fields (e.g. `greeting` / `language` once the engine acks them) pass straight
- * through. The SDK supplies the `{"type":"configure"}` envelope for you — which
- * is the whole point: a hand-rolled `{"event":"configure"}` is acked but
- * silently dropped, leaving the agent with no brain and zero turns.
+ * fields (e.g. `greeting`, or `model_tier` once the engine acks it) pass
+ * straight through. The SDK supplies the `{"type":"configure"}` envelope for
+ * you, which is the whole point: a hand-rolled `{"event":"configure"}` is
+ * acked but silently dropped, leaving the agent with no brain and zero turns.
  */
 export interface OmniConfigure {
     /** Voice to speak with (stock / clone / designed id). */
@@ -413,6 +463,19 @@ export interface OmniConfigure {
     kb_endpoint?: string;
     /** Bearer the engine presents to `kb_endpoint`. */
     kb_token?: string;
+    /**
+     * Session language, end to end (recognition, reasoning, voice). Also
+     * settable on the agent profile (`language` on `POST /v1/agents`), which
+     * applies automatically when connecting with `session_label={agent_id}`;
+     * an inline value here wins for the session. Default `en`. Fail-safe: an
+     * unknown/not-yet-enabled language falls back to `en` (the `configured`
+     * ack carries `language_active` + `language_fallback: true`), the call
+     * proceeds and bills as what was served. Per-language availability is
+     * staged, see the Language support reference.
+     */
+    language?: "en" | "fr" | "es" | "de" | "hi";
+    /** Function calling definitions (client-loop when `endpoint` is omitted). */
+    tools?: OmniToolDef[];
     /** Forward-compatible: any other key the engine honors. */
     [k: string]: unknown;
 }
@@ -438,7 +501,7 @@ export interface OmniConnectOptions {
     query?: Record<string, string>;
     /** Fired once the socket opens (after the optional auto-configure). */
     onOpen?: () => void;
-    /** Fired for each binary agent-audio chunk — play it out as it arrives. */
+    /** Fired for each binary agent-audio chunk, play it out as it arrives. */
     onAudio?: (chunk: OmniAudioChunk) => void;
     /** Fired on the `hello` handshake frame. */
     onHello?: (frame: OmniServerFrame) => void;
@@ -452,6 +515,8 @@ export interface OmniConnectOptions {
     onTranscript?: (frame: OmniServerFrame) => void;
     /** Fired on `barge_in` / `flush` (user interrupted). */
     onBargeIn?: (frame: OmniServerFrame) => void;
+    /** Fired when the engine requests a client-loop tool invocation. */
+    onToolCall?: (frame: OmniToolCallFrame) => void;
     /** Fired on `session_end`. */
     onSessionEnd?: (frame: OmniServerFrame) => void;
     /** Fired on EVERY JSON frame (including unknown/forward-compat ones). */
@@ -483,18 +548,32 @@ export declare class OmniConnection {
     private readonly ws;
     private readonly opts;
     private closed;
+    /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
+    private blobTail;
+    /** Serializes inbound Blob decoding so browser frames stay ordered. */
+    private inboundTail;
     constructor(url: string, subprotocol: string, opts: OmniConnectOptions);
     private handleMessage;
+    private dispatchFrame;
     /**
      * Send (or update) the agent config. Always emitted as
-     * `{"type":"configure", ...}` — the correct key. (A hand-rolled
+     * `{"type":"configure", ...}`, the correct key. (A hand-rolled
      * `{"event":"configure"}` is acked but silently dropped by the engine.)
      */
     configure(cfg: OmniConfigure): void;
-    /** Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate). */
+    /**
+     * Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate) as a
+     * `0x01`-prefixed frame. The engine demuxes on the first byte and has no
+     * default branch, so an untagged chunk is dropped with no error.
+     */
     sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void;
     /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
     sendDtmf(digits: string): void;
+    /** Reply to a client-loop {@link OmniEvent.ToolCall}. */
+    toolResult(callId: string, payload: {
+        result?: unknown;
+        error?: string;
+    }): void;
     /**
      * Send an arbitrary control frame for forward-compat control types the SDK
      * does not model yet. Reminder: client → server frames are keyed on `type`,
@@ -602,7 +681,7 @@ export interface TraceBargeMetrics {
 }
 /**
  * Known timeline-turn roles. Left open (see {@link TraceTimelineTurn.role}) so a
- * new server-side role never breaks the build — branch defensively.
+ * new server-side role never breaks the build, branch defensively.
  */
 export type TraceTimelineRole = "agent" | "caller" | "system" | "tool";
 /** One turn of a per-call operational timeline (eval scorecard-v1). */
@@ -626,18 +705,18 @@ export interface TraceTimelineTurn {
 }
 /**
  * Aggregate per-call quality metrics (eval scorecard-v1). All optional and
- * forward-compatible — present once the engine emits them.
+ * forward-compatible, present once the engine emits them.
  */
 export interface QualityMetrics {
-    /** Word error rate vs. reference transcript, 0–1 (lower is better). */
+    /** Word error rate vs. reference transcript, 0-1 (lower is better). */
     wer?: number;
     /** Representative time-to-first-audio across turns, ms. */
     ttfb_ms?: number;
     /** 95th-percentile end-to-end turn latency, ms. */
     turn_p95_ms?: number;
-    /** Barge-in recovery rate, 0–1. */
+    /** Barge-in recovery rate, 0-1. */
     barge_recovery?: number;
-    /** Task-success score, 0–1. */
+    /** Task-success score, 0-1. */
     task_success?: number;
     /** Composite voice-agent quality index (engine-defined scale). */
     vaqi?: number;
@@ -775,6 +854,76 @@ export interface RecapCallTriggerInput {
     customer_name?: string;
     crm_fields?: Record<string, unknown>;
 }
+/** PyAI's richer answered-by vocabulary (superset of Twilio's enum). */
+export type AmdAnsweredBy = "human" | "voicemail" | "live_voicemail" | "screening" | "ivr" | "human_gatekeeper" | "sit_invalid" | "fax" | "silence" | "unknown";
+/** Twilio's `AnsweredBy` enum, echoed for drop-in migration parity. */
+export type AmdTwilioAnsweredBy = "human" | "machine_start" | "machine_end_beep" | "machine_end_silence" | "machine_end_other" | "fax" | "unknown";
+export interface AmdConfigInput {
+    /** Operating point on the ROC curve, [0,1]. Near 0 = human-safe (never hang up
+     * on a person); near 1 = fire `machine` fast. A per-call TwiML `<Parameter>`
+     * overrides this. */
+    aggressiveness?: number;
+    /** Signed POST target for `amd.call.completed` events (https). */
+    webhookUrl?: string | null;
+}
+export interface AmdConfig {
+    object?: "amd.config";
+    aggressiveness?: number;
+    webhook_url?: string | null;
+    updated_at?: number;
+}
+export interface AmdCallSummary {
+    object?: "amd.call";
+    call_id: string;
+    session_label?: string | null;
+    status?: "completed" | "failed";
+    answered_by?: AmdAnsweredBy;
+    /** Twilio-enum projection of `answered_by` for drop-in routing parity. */
+    answered_by_twilio?: string | null;
+    confidence?: number | null;
+    /** Latency from answer to decision, in ms. */
+    decision_ms?: number | null;
+    created_at?: number;
+}
+export interface AmdCall extends AmdCallSummary {
+    /** Human-readable evidence, e.g. "machine phrase: 'leave a message' @1.2s". */
+    reason?: string | null;
+    aggressiveness?: number | null;
+    started_at?: number | null;
+    meta?: Record<string, unknown> | null;
+    error?: string | null;
+}
+/** A mid-call AMD decision event pushed on the stream (and to the webhook). */
+export interface AmdDecisionEvent {
+    event?: "amd";
+    call_id?: string;
+    answered_by?: AmdAnsweredBy;
+    answered_by_twilio?: string | null;
+    confidence?: number | null;
+    decision_ms?: number | null;
+    reason?: string | null;
+    [k: string]: unknown;
+}
+export interface AmdStreamOptions {
+    /** Per-call operating point override (0-1), sent on the connect URL. */
+    aggressiveness?: number;
+    /** Opaque per-call tag, echoed back on the decision. */
+    sessionLabel?: string;
+    /** Extra query params merged onto the connect URL. */
+    query?: Record<string, string>;
+    /** Fired once the socket opens. */
+    onOpen?: () => void;
+    /** Fired when PyAI emits the `amd` decision event mid-call. */
+    onDecision?: (event: AmdDecisionEvent) => void;
+    /** Fired on any other JSON frame (forward-compatible). */
+    onMessage?: (frame: Record<string, unknown>) => void;
+    /** Fired on a transport-level error. */
+    onError?: (err: Error) => void;
+    /** Fired when the socket closes. */
+    onClose?: (code: number, reason: string) => void;
+    /** Injectable WebSocket constructor (defaults to the global). */
+    webSocket?: WebSocketCtor;
+}
 export declare class PyAI {
     private readonly apiKey;
     private readonly baseURL;
@@ -852,7 +1001,7 @@ export declare class PyAI {
     };
     /**
      * Introspect the calling key: scopes, environment, and limits. Useful for a
-     * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+     * preflight/doctor check. (New route; older deployments may 404, handle it.)
      */
     me: () => Promise<MeResponse>;
     clones: {
@@ -919,7 +1068,7 @@ export declare class PyAI {
             }) => Promise<ListResponse<TraceViolation>>;
         };
         findings: {
-            /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+            /** List Tier-2 (async semantic) findings, advisory, non-blocking. Scope `trace:read`. */
             list: (params?: {
                 checkId?: string;
                 action?: "flag" | "preempt_next" | "escalate";
@@ -968,10 +1117,34 @@ export declare class PyAI {
             trigger: (callId: string, input: RecapCallTriggerInput) => Promise<RecapCallSummary>;
         };
     };
+    amd: {
+        config: {
+            /** The org's AMD operating point + webhook. Scope `amd:configure`. */
+            get: () => Promise<AmdConfig>;
+            /** Set the account-default `aggressiveness` (0-1) and webhook. Scope `amd:configure`. */
+            set: (input: AmdConfigInput) => Promise<AmdConfig>;
+        };
+        calls: {
+            /** Recent AMD decisions, newest first. Scope `amd:read`. */
+            list: (params?: {
+                limit?: number;
+                cursor?: string;
+                sessionLabel?: string;
+            }) => Promise<ListResponse<AmdCallSummary>>;
+            /** The full decision (answered_by, reason, …) for one call. Scope `amd:read`. */
+            get: (callId: string) => Promise<AmdCall>;
+        };
+        /**
+         * Open a live AMD stream over `/v1/amd/stream` (Twilio Media Streams
+         * protocol). Server-side helper for forking media yourself; the common
+         * Twilio path is one line of TwiML, no SDK. Scope `amd:detect`.
+         */
+        stream: (opts?: AmdStreamOptions) => AmdStream;
+    };
     omni: {
         /**
          * Mint an ephemeral, origin-locked Omni session token a browser can use to
-         * open ONE realtime session **directly** — the public/private split for
+         * open ONE realtime session **directly**, the public/private split for
          * realtime. **Call this from your server** with a secret key holding
          * `omni:session`; never ship the secret key to a page. Hand the returned
          * `token` to the browser, which connects with
@@ -983,8 +1156,8 @@ export declare class PyAI {
         /**
          * Open a live Omni agentic-voice session over `/v1/omni`. Returns an
          * {@link OmniConnection} that handles the wire protocol's frame-key
-         * asymmetry for you — it sends `type`-keyed control frames (`configure`,
-         * `dtmf`) and parses `event`-keyed server frames — so you can't trip the #1
+         * asymmetry for you, it sends `type`-keyed control frames (`configure`,
+         * `dtmf`) and parses `event`-keyed server frames, so you can't trip the #1
          * Omni integration bug. Omni is zero-state: nothing to create first; the
          * agent's behavior travels in the `configure` frame. Pass `token` (from
          * `createSession`) to connect from a browser without the secret key.
@@ -997,6 +1170,8 @@ export declare class PyAI {
     realtimeSubprotocol(): 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`). */
+    amdStreamURL(opts?: AmdStreamOptions): string;
     /**
      * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
      * The key travels as a subprotocol so it works from the browser without