@pyai/sdk 0.2.0 → 0.2.2

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;
 }
@@ -121,13 +119,52 @@ export interface CreateJobParams {
     webhook_url?: string;
 }
 export interface RealtimeOptions {
-    /** "omni" (agentic, needs agentId) or "flow" (voice duplex). Default "omni". */
+    /** "omni" (agentic voice) or "flow" (legacy voice duplex). Default "omni". */
     product?: "omni" | "flow";
-    /** Required for omni: the agent to drive. */
+    /**
+     * Optional opaque tag echoed to your `kb_endpoint` and recorded on the call.
+     * Omni is zero-state: the session is authorized by the key's org, so there is
+     * nothing to create first and this tag is never required.
+     */
+    sessionLabel?: string;
+    /**
+     * @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.
+     */
     agentId?: string;
     /** Extra query params (e.g. format, rate). */
     query?: Record<string, string>;
 }
+/** Parameters for minting an ephemeral browser Omni session token (server-side). */
+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
+     * allowed.
+     */
+    allowedOrigins: string[];
+    /** Token lifetime in seconds. Default 60 server-side; max 600. Keep it short. */
+    ttlSeconds?: number;
+    /** Optional opaque tag echoed back to your `kb_endpoint` and recorded on the call. */
+    sessionLabel?: string;
+}
+/**
+ * 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}.
+ */
+export interface OmniSession {
+    object?: "omni.session";
+    /** The ephemeral session token. Short-lived + origin-locked; browser-safe. */
+    token: string;
+    /** Token expiry, Unix epoch milliseconds. */
+    expires_at: number;
+    /** The Omni realtime WebSocket URL to connect to. */
+    url: string;
+    /** Echoed back when supplied on the request. */
+    session_label?: string;
+}
 /** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
 export declare const HearFrameType: {
     /** Eager live hypothesis for the current utterance. */
@@ -138,6 +175,8 @@ export declare const HearFrameType: {
     readonly SpeechFinal: "speech_final";
     /** Corrected, full-context transcript following `speech_final`. */
     readonly Final: "final";
+    /** Final billed-usage summary, emitted just before a graceful close. */
+    readonly Usage: "usage";
     /** Server-side fault frame. */
     readonly Error: "error";
 };
@@ -156,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: {
@@ -203,15 +242,30 @@ export interface HearFinalFrame {
     /** Present only with Cue grounding enabled (top KB passages). */
     grounding?: HearGroundingPassage[];
 }
+/** Final billed-usage summary (`usage`), emitted just before a graceful close
+ * so realtime spend can be reconciled in-band (a realtime WS carries no
+ * `x-pyai-units` response header). Best-effort: absent if there was no billable
+ * audio or the close was abnormal. */
+export interface HearUsageFrame {
+    type: "usage";
+    /** `hear` for plain streaming, `cue` when grounding was enabled. */
+    product: "hear" | "cue";
+    /** The billed meter (`hear.requests` or `cue.minutes`). */
+    meter: string;
+    /** Summed active-speech audio billed for the session, in seconds. */
+    audio_seconds: number;
+    /** The same quantity in minutes. */
+    minutes: number;
+}
 /** Server fault frame (`error`). */
 export interface HearErrorFrame {
     type: "error";
     code?: string;
     message: string;
 }
-export type HearFrame = HearPartialFrame | HearFinalFrame | 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 {
@@ -240,12 +294,32 @@ export interface HearStreamOptions {
     encoding?: "pcm16" | "opus";
     /** 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.
+     */
+    numerals?: boolean;
+    /**
+     * 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.
+     */
+    endpointingMs?: number;
     /**
      * Enable Cue knowledge-base grounding: sends `{type:"config",grounding:true}`
      * on open, after which `speech_final`/`final` frames carry a `grounding`
      * 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). */
+    groundingK?: number;
+    /** 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). */
+    groundingTimeoutMs?: number;
     /** Extra query params merged onto the connect URL. */
     query?: Record<string, string>;
     /** Fired once the socket opens (after the optional grounding config). */
@@ -254,6 +328,8 @@ export interface HearStreamOptions {
     onPartial?: (frame: HearPartialFrame) => void;
     /** Fired on `speech_final` / `final`. */
     onFinal?: (frame: HearFinalFrame) => void;
+    /** Fired on the final `usage` summary (in-band realtime reconciliation). */
+    onUsage?: (frame: HearUsageFrame) => void;
     /** Fired on an `error` frame or a transport-level error. */
     onError?: (err: HearErrorFrame | Error) => void;
     /** Fired when the socket closes (code per `WSCloseCode`). */
@@ -284,6 +360,220 @@ 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
+ * (`configure`, `dtmf`, …) are keyed on `type`. {@link OmniConnection} handles
+ * both sides for you; this map is for matching frames in `onEvent`.
+ */
+export declare const OmniEvent: {
+    /** Handshake; advertises protocol version + audio formats. */
+    readonly Hello: "hello";
+    /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
+    readonly Configured: "configured";
+    /** Session is live; includes the resolved agent + audio caps. */
+    readonly SessionStarted: "session_started";
+    /** Turn boundary (user/assistant speaking). */
+    readonly Turn: "turn";
+    /** Incremental/final transcript text. */
+    readonly Transcript: "transcript";
+    /** User interrupted; assistant audio is being cut. */
+    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. */
+    readonly Error: "error";
+};
+export type OmniEvent = (typeof OmniEvent)[keyof typeof OmniEvent];
+/** A server → client Omni frame. Keyed on `event` (not `type`); open for forward-compat. */
+export interface OmniServerFrame {
+    event: string;
+    [k: string]: unknown;
+}
+/** 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`, 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). */
+    voice_id?: string;
+    /** System prompt / role + instructions for the agent. */
+    persona?: string;
+    /** Customer-hosted URL the engine calls per turn for grounding. */
+    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;
+}
+export interface OmniConnectOptions {
+    /** Optional opaque per-session tag echoed to your `kb_endpoint`. Omni is zero-state. */
+    sessionLabel?: string;
+    /**
+     * Ephemeral browser token from `omni.createSession`. When set it is used as
+     * the WS subprotocol (`pyai-key.<token>`) instead of the client's secret key,
+     * so a page never holds a secret key.
+     */
+    token?: string;
+    /** Connect-URL sample rate: 24000 browser, 16000 wideband telephony, 8000 G.711/Twilio. */
+    rate?: 24000 | 16000 | 8000;
+    /** Connect-URL audio format. Default `pcm16`. */
+    format?: "pcm16";
+    /**
+     * Agent config sent as `{"type":"configure",...}` the instant the socket
+     * opens. Omit to send it yourself later via {@link OmniConnection.configure}.
+     */
+    configure?: OmniConfigure;
+    /** Extra query params merged onto the connect URL. */
+    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. */
+    onAudio?: (chunk: OmniAudioChunk) => void;
+    /** Fired on the `hello` handshake frame. */
+    onHello?: (frame: OmniServerFrame) => void;
+    /** Fired on the `configured` ack. */
+    onConfigured?: (frame: OmniServerFrame) => void;
+    /** Fired on `session_started`. */
+    onSessionStarted?: (frame: OmniServerFrame) => void;
+    /** Fired on `turn` boundaries. */
+    onTurn?: (frame: OmniServerFrame) => void;
+    /** Fired on `transcript` text frames. */
+    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). */
+    onEvent?: (frame: OmniServerFrame) => void;
+    /** Fired on an `error` frame or a transport-level error. */
+    onError?: (err: OmniServerFrame | Error) => void;
+    /** Fired when the socket closes (code per {@link WSCloseCode}). */
+    onClose?: (code: number, reason: string) => void;
+    /** Injectable WebSocket constructor (defaults to the global). */
+    webSocket?: WebSocketCtor;
+}
+/**
+ * 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 declare class OmniConnection {
+    private readonly ws;
+    private readonly opts;
+    private closed;
+    /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
+    private blobTail;
+    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
+     * `{"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) 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`,
+     * never `event`.
+     */
+    send(frame: Record<string, unknown>): void;
+    /** Close the session. */
+    close(code?: number, reason?: string): void;
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket(): WebSocketLike;
+    /** Current WebSocket readyState. */
+    get readyState(): number;
+}
 /** Shape of `GET /v1/me`. Fields are best-effort / forward-compatible. */
 export interface MeResponse {
     object?: string;
@@ -378,7 +668,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). */
@@ -402,18 +692,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;
@@ -551,6 +841,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;
@@ -628,7 +988,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: {
@@ -695,7 +1055,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";
@@ -744,12 +1104,61 @@ 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
+         * 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: OmniSessionParams) => Promise<OmniSession>;
+        /**
+         * 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?: OmniConnectOptions) => OmniConnection;
+    };
     /** Build the realtime WebSocket URL for the chosen product. */
     realtimeURL(opts?: RealtimeOptions): string;
     /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
     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