@pyai/sdk 0.1.2 → 0.2.1

package/dist/index.d.ts

@@ -46,18 +46,70 @@ export interface TranscriptionJob {
     result_url?: string;
     error?: string;
 }
+/**
+ * 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
+ * `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).
+ *
+ * | format | rates (Hz) | Content-Type |
+ * |---|---|---|
+ * | `mp3` (default) | 8000/16000/24000/48000 | `audio/mpeg` |
+ * | `wav` | 8000/16000/24000/48000 | `audio/wav` |
+ * | `opus` | 8000/16000/24000/48000 | `audio/ogg` |
+ * | `aac` | 8000/16000/24000/48000 | `audio/aac` |
+ * | `flac` | 8000/16000/24000/48000 | `audio/flac` |
+ * | `pcm` | 8000/16000/24000/48000 | `audio/pcm` (raw int16 LE mono, no header) |
+ * | `g711_ulaw` | 8000 (forced) | `audio/basic` |
+ * | `g711_alaw` | 8000 (forced) | `audio/basic` |
+ */
+export type SpeechFormat = "wav" | "mp3" | "opus" | "aac" | "flac" | "pcm" | "g711_ulaw" | "g711_alaw";
+/**
+ * The runtime list of accepted `audio.speech` formats (mirrors {@link SpeechFormat}),
+ * for building dropdowns / validating input before a request. Branch on the
+ * named values; the order matches the contract doc.
+ */
+export declare const SPEECH_FORMATS: readonly ["wav", "mp3", "opus", "aac", "flac", "pcm", "g711_ulaw", "g711_alaw"];
+/** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
+export declare const SPEECH_SAMPLE_RATES: readonly [8000, 16000, 24000, 48000];
+export type SpeechSampleRate = (typeof SPEECH_SAMPLE_RATES)[number];
 export interface SpeechParams {
     input: string;
     voice?: string;
     model?: string;
-    response_format?: "wav" | "mp3" | "opus" | "aac" | "flac" | "pcm";
     /**
-     * Output sample rate in Hz (8000-48000). Omit for the native 24 kHz. Most
-     * useful with `response_format: "pcm"` (raw 16-bit mono samples), e.g. set
-     * `8000`/`16000` for telephony pipelines.
+     * Output container/codec, resampled+encoded server-side. One of
+     * {@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
+     * 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`.
      */
-    sample_rate?: number;
+    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
+     * native 24 kHz; `g711_*` is always 8000 (forced). Set `8000`/`16000` for
+     * telephony pipelines, most often with `response_format: "pcm"`.
+     */
+    sample_rate?: SpeechSampleRate;
     speed?: number;
+    /**
+     * Deterministic sampling seed for reproducible eval runs. Forward-compatible:
+     * honored once the engine supports it (otherwise ignored server-side), so it's
+     * always safe to send.
+     */
+    seed?: number;
+    /**
+     * Sampling temperature (lower = more deterministic). Forward-compatible —
+     * honored once the engine supports it, otherwise ignored.
+     */
+    temperature?: number;
 }
 export interface CreateJobParams {
     audio_url: string;
@@ -69,13 +121,660 @@ 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. */
+    readonly Partial: "partial";
+    /** Partial whose prefix has stabilized (won't be revised). */
+    readonly PartialStable: "partial_stable";
+    /** Stable transcript at end-of-utterance (endpoint or commit). */
+    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";
+};
+export type HearFrameType = (typeof HearFrameType)[keyof typeof HearFrameType];
+/** WebSocket close codes used across the PyAI realtime/streaming surfaces. */
+export declare const WSCloseCode: {
+    /** Normal closure. */
+    readonly Normal: 1000;
+    /** Auth/policy: bad key, missing scope, or revoked token. */
+    readonly PolicyViolation: 1008;
+    /** Engine/internal error. */
+    readonly InternalError: 1011;
+    /** Over the concurrency cap (PyAI-specific; mirrors HTTP 429). */
+    readonly OverCapacity: 4429;
+};
+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
+ * new server code never breaks the build, but the known ones are named here.
+ */
+export declare const ErrorCode: {
+    readonly Unauthorized: "unauthorized";
+    readonly Forbidden: "forbidden";
+    readonly OriginNotAllowed: "origin_not_allowed";
+    readonly InvalidAgentId: "invalid_agent_id";
+    readonly CreditExhausted: "credit_exhausted";
+    readonly KeyBudgetExceeded: "key_budget_exceeded";
+    readonly InsufficientQuota: "insufficient_quota";
+    readonly RateLimitExceeded: "rate_limit_exceeded";
+    readonly ConcurrencyLimitExceeded: "concurrency_limit_exceeded";
+    readonly DailyCapExceeded: "daily_cap_exceeded";
+    readonly IdempotencyConflict: "idempotency_conflict";
+    readonly NotFound: "not_found";
+    readonly NumberInUse: "number_in_use";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** A top-3 knowledge-base passage attached to Cue (grounded) finals. */
+export interface HearGroundingPassage {
+    content: string;
+    score: number;
+}
+/** Live hypothesis frame (`partial` / `partial_stable`). */
+export interface HearPartialFrame {
+    type: "partial" | "partial_stable";
+    text: string;
+    /** Prefix that has stabilized (won't change). */
+    stable_text?: string;
+    /** The still-changing tail. */
+    active_text?: string;
+    utterance_id: string;
+    /** Audio-timeline position of the hypothesis, ms. */
+    t_ms: number;
+}
+/** Finalized-utterance frame (`speech_final` / `final`). */
+export interface HearFinalFrame {
+    type: "speech_final" | "final";
+    text: string;
+    utterance_id: string;
+    t_ms: number;
+    /** Active-speech length of the utterance (the billed signal), ms. */
+    audio_ms: number;
+    /** 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 | HearUsageFrame | HearErrorFrame;
+/**
+ * Minimal structural WebSocket — matches both the browser/Node global
+ * `WebSocket` and the `ws` package, and lets tests inject a mock.
+ */
+export interface WebSocketLike {
+    send(data: string | ArrayBufferLike | ArrayBufferView | Blob): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    onopen: ((ev: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((ev: unknown) => void) | null;
+    onclose: ((ev: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+}
+export type WebSocketCtor = new (url: string, protocols?: string | string[]) => WebSocketLike;
+export interface HearStreamOptions {
+    /** Streaming STT model. Server default `pyai-hear`. */
+    model?: string;
+    /** ISO-639-1 hint, e.g. "en". */
+    language?: string;
+    /** Input PCM sample rate in Hz. Default 16000 server-side. */
+    sampleRate?: number;
+    /** Audio frame encoding. Default "pcm16". */
+    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). */
+    onOpen?: () => void;
+    /** Fired on `partial` / `partial_stable`. */
+    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`). */
+    onClose?: (code: number, reason: string) => void;
+    /** Injectable WebSocket constructor (defaults to the global). */
+    webSocket?: WebSocketCtor;
+}
+/**
+ * A live Hear streaming-STT session. Hides the frame protocol: stream audio
+ * with {@link HearStream.sendAudio}, get `onPartial`/`onFinal`/`onError`
+ * callbacks, force-finalize with {@link HearStream.commit}, and flush+close
+ * with {@link HearStream.close}. Construct via `pyai.audio.transcriptions.stream()`.
+ */
+export declare class HearStream {
+    private readonly ws;
+    private readonly opts;
+    private closed;
+    constructor(url: string, subprotocol: string, opts: HearStreamOptions);
+    private handleMessage;
+    /** Send a chunk of audio (PCM16 or opus per `encoding`). */
+    sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void;
+    /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
+    commit(): void;
+    /** Close the socket; the server flushes a final for any buffered audio. */
+    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";
+    /** 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;
+/**
+ * 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.
+ */
+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;
+    /** 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 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;
+    constructor(url: string, subprotocol: string, opts: OmniConnectOptions);
+    private handleMessage;
+    /**
+     * 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). */
+    sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void;
+    /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
+    sendDtmf(digits: 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;
+    key_id?: string;
+    org_id?: string;
+    /** "live" | "test" (a.k.a. environment). */
+    environment?: string;
+    env?: string;
+    scopes?: string[];
+    limits?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface TelephonyCapabilities {
+    voice?: boolean;
+    sms?: boolean;
+}
+export interface TelephonyAvailableNumber {
+    object?: "telephony.available_number";
+    /** E.164. */
+    phone_number: string;
+    country?: string;
+    area_code?: string | null;
+    locality?: string | null;
+    region?: string | null;
+    capabilities?: TelephonyCapabilities;
+    monthly_cost_cents?: number;
+}
+export interface TelephonyNumber {
+    object?: "telephony.number";
+    id: string;
+    /** E.164. */
+    phone_number: string;
+    country?: string;
+    area_code?: string | null;
+    capabilities?: TelephonyCapabilities;
+    /** Agent that answers inbound calls to this number. */
+    agent_id?: string | null;
+    recording?: boolean;
+    monthly_cost_cents?: number;
+    status?: "active" | "released";
+    created_at?: number;
+    released_at?: number | null;
+}
+export type TraceVerdict = "PASS" | "WARN" | "FAIL";
+export type TraceSeverity = "low" | "medium" | "high" | "critical";
+export interface TraceInteraction {
+    object?: "trace.interaction";
+    /** call_id */
+    id: string;
+    agent_id?: string | null;
+    product?: string | null;
+    verdict: TraceVerdict;
+    findings?: number;
+    blocked_turns?: number;
+    modified_turns?: number;
+    packs_enforced?: string;
+    scored_at?: number;
+}
+export interface TraceFinding {
+    object?: "trace.finding";
+    id: string;
+    /** call_id */
+    interaction_id: string;
+    agent_id?: string | null;
+    check_id: string;
+    severity: TraceSeverity;
+    verdict?: string;
+    confidence?: number;
+    action?: "flag" | "preempt_next" | "escalate";
+    speaker?: "agent" | "caller" | "any" | null;
+    reason?: string;
+    preempt_instruction?: string | null;
+    at_t?: number | null;
+    tier?: number;
+}
+/** A tool invocation recorded on a timeline turn. */
+export interface TraceToolCall {
+    name: string;
+    /** Arguments the agent passed (engine-shaped JSON). */
+    args?: unknown;
+    /** Tool result returned to the agent (engine-shaped JSON). */
+    result?: unknown;
+    /** Audio-timeline position of the call, ms. */
+    t_ms?: number;
+}
+/** Barge-in timing for a timeline turn. */
+export interface TraceBargeMetrics {
+    /** Time from caller speech onset to barge-in detection, ms. */
+    detect_ms?: number;
+    /** Whether the agent cleanly recovered after the barge-in. */
+    recovered?: boolean;
+}
+/**
+ * Known timeline-turn roles. Left open (see {@link TraceTimelineTurn.role}) so a
+ * 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). */
+export interface TraceTimelineTurn {
+    /** Monotonic turn index within the call. */
+    seq: number;
+    /** Audio-timeline position of the turn, ms. */
+    t_ms: number;
+    /** Who spoke/acted this turn. Open-ended for forward-compat. */
+    role: TraceTimelineRole | (string & {});
+    /** Transcript/text for the turn, when available. */
+    text?: string;
+    /** Time-to-first-audio for the turn (latency scoring), ms. */
+    ttfb_ms?: number;
+    /** Turn-detection (endpointing) latency, ms. */
+    endpointing_ms?: number;
+    /** Barge-in detect/recovery timing for the turn. */
+    barge?: TraceBargeMetrics;
+    /** Tool calls made during the turn (tool-use scoring). */
+    tool_calls?: TraceToolCall[];
+}
+/**
+ * Aggregate per-call quality metrics (eval scorecard-v1). All optional and
+ * forward-compatible — present once the engine emits them.
+ */
+export interface QualityMetrics {
+    /** 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_recovery?: number;
+    /** Task-success score, 0–1. */
+    task_success?: number;
+    /** Composite voice-agent quality index (engine-defined scale). */
+    vaqi?: number;
+    [k: string]: unknown;
+}
+export interface TraceInteractionDetail extends TraceInteraction {
+    /** Hash-chain link proving the record is unaltered. */
+    audit_hash?: string;
+    scorecard?: Record<string, unknown>;
+    tier2_findings?: TraceFinding[];
+    /**
+     * Scorecard schema version, e.g. `"trace-scorecard-v1"`. Present once the
+     * engine emits the eval block below.
+     */
+    scorecard_version?: string;
+    /**
+     * Per-call operational timeline. Forward-compatible: empty/undefined until
+     * the engine emits per-turn timing (Ask 1 of the evals engine plan).
+     */
+    timeline?: TraceTimelineTurn[];
+    /** Aggregate per-call quality metrics. Forward-compatible (see above). */
+    quality_metrics?: QualityMetrics;
+}
+export interface TraceViolation {
+    object?: "trace.violation";
+    id: string;
+    /** call_id */
+    interaction_id: string;
+    agent_id?: string | null;
+    rule_id: string;
+    pack_id?: string | null;
+    severity: TraceSeverity;
+    action_taken?: "pass" | "flag" | "modify" | "block";
+    citation?: string;
+    reason?: string;
+    at_t?: number | null;
+}
+export interface TraceConfigInput {
+    agent_id?: string;
+    enabled?: boolean;
+    channels?: Array<"voice" | "text">;
+    /** Map of pack_id → { enabled, version }. */
+    rule_packs?: Record<string, {
+        enabled?: boolean;
+        version?: string | null;
+    }>;
+    guardrails?: Record<string, unknown>;
+    [k: string]: unknown;
+}
+export interface TraceConfig {
+    object?: "trace.config";
+    agent_id?: string | null;
+    enabled?: boolean;
+    mode?: "warn" | "modify" | "block" | "human_handoff";
+    etag?: string;
+    updated_at?: number;
+    config?: TraceConfigInput;
+}
+export interface TraceRulePackSpec {
+    pack_id: string;
+    version: string;
+    jurisdiction?: string;
+    legal_status?: string;
+    rules: Array<Record<string, unknown>>;
+}
+export interface TraceRulePack {
+    object?: "trace.rule_pack";
+    id?: string;
+    pack_id: string;
+    version?: string;
+    builtin?: boolean;
+    jurisdiction?: string | null;
+    legal_status?: string | null;
+    etag?: string;
+    status?: "active" | "deprecated";
+    created_at?: number;
+    /** The authored DSL (only on the single-pack GET). */
+    spec?: Record<string, unknown>;
+}
+export interface TraceExposure {
+    object?: "trace.exposure";
+    window_days?: number;
+    interactions_scanned?: number;
+    with_a_gap?: number;
+    gap_rate?: number;
+    by_rule?: Array<{
+        rule_id: string;
+        pack_id?: string | null;
+        count: number;
+        rate: number;
+    }>;
+    by_verdict?: {
+        PASS?: number;
+        WARN?: number;
+        FAIL?: number;
+    };
+    top_exposure?: string | null;
+}
+export interface RecapConfigInput {
+    enabled?: boolean;
+    webhook_url?: string | null;
+    default_pack_id?: string;
+}
+export interface RecapConfig {
+    object?: "recap.config";
+    enabled?: boolean;
+    webhook_url?: string | null;
+    default_pack_id?: string;
+    updated_at?: number;
+}
+export interface RecapCallSummary {
+    object?: "recap.call";
+    call_id: string;
+    pack_id?: string;
+    status?: "pending" | "processing" | "complete" | "failed";
+    call_duration_s?: number | null;
+    created_at?: number;
+    completed_at?: number | null;
+}
+export interface RecapCall extends RecapCallSummary {
+    record?: unknown;
+    error?: string | null;
+    crm_write_status?: string | null;
+}
+export interface RecapCallTriggerInput {
+    utterances: Array<{
+        speaker_role?: "agent" | "customer";
+        text: string;
+        offset_s?: number;
+        duration_s?: number;
+    }>;
+    pack_id?: string;
+    call_duration_s?: number;
+    call_direction?: "inbound" | "outbound";
+    customer_name?: string;
+    crm_fields?: Record<string, unknown>;
+}
 export declare class PyAI {
     private readonly apiKey;
     private readonly baseURL;
@@ -86,6 +785,9 @@ export declare class PyAI {
     private request;
     private toError;
     private getJson;
+    private postJson;
+    private putJson;
+    private deleteReq;
     models: {
         list: () => Promise<ListResponse<{
             id: string;
@@ -116,10 +818,26 @@ export declare class PyAI {
                 file: Blob;
                 filename?: string;
                 model?: string;
+                language?: string;
+                response_format?: "json" | "text" | "verbose_json";
+                /**
+                 * Deterministic seed for reproducible eval runs. Forward-compatible:
+                 * honored once the engine supports it, otherwise ignored.
+                 */
+                seed?: number;
+                /** Sampling temperature. Forward-compatible (honored when supported). */
+                temperature?: number;
             }) => Promise<{
                 text: string;
                 [k: string]: unknown;
             }>;
+            /**
+             * Open a live streaming-STT WebSocket (Hear). Hides the frame protocol
+             * behind `onPartial`/`onFinal`/`onError`; stream audio with `sendAudio`,
+             * force-finalize with `commit()`, flush+close with `close()`. Set
+             * `grounding: true` for Cue (turn detection + KB context).
+             */
+            stream: (opts?: HearStreamOptions) => HearStream;
         };
     };
     transcriptionJobs: {
@@ -132,10 +850,153 @@ export declare class PyAI {
             cursor?: string;
         }) => Promise<ListResponse<TranscriptionJob>>;
     };
+    /**
+     * Introspect the calling key: scopes, environment, and limits. Useful for a
+     * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+     */
+    me: () => Promise<MeResponse>;
+    clones: {
+        /** List the org's cloned voices. */
+        list: () => Promise<ListResponse<Voice>>;
+        /** Enroll a custom voice from reference audio (>= ~10s). Scope `voice:clone`. */
+        create: (params: {
+            name: string;
+            file: Blob;
+            filename?: string;
+        }) => Promise<Voice>;
+        /**
+         * Fetch a single cloned voice by id. The API exposes no GET-by-id for
+         * clones, so this filters `list()` client-side and throws a 404 `PyAIError`
+         * when the id isn't found.
+         */
+        get: (id: string) => Promise<Voice>;
+        /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+        delete: (id: string) => Promise<void>;
+    };
+    telephony: {
+        numbers: {
+            /** Search the carrier's available US local numbers. */
+            available: (params?: {
+                areaCode?: string;
+                contains?: string;
+                limit?: number;
+            }) => Promise<ListResponse<TelephonyAvailableNumber>>;
+            /** List the org's managed numbers (active only unless `includeReleased`). */
+            list: (params?: {
+                includeReleased?: boolean;
+            }) => Promise<ListResponse<TelephonyNumber>>;
+            /** Provision (buy) a specific available number, optionally bound to an agent. */
+            buy: (params: {
+                phone_number: string;
+                agent_id?: string | null;
+            }) => Promise<TelephonyNumber>;
+            /** Route a number to an agent (`agentId: null` to unassign). */
+            assign: (id: string, agentId: string | null) => Promise<TelephonyNumber>;
+            /** Release a number back to the carrier (idempotent). */
+            release: (id: string) => Promise<TelephonyNumber>;
+        };
+    };
+    trace: {
+        interactions: {
+            /** List scanned interactions (scorecards), newest first. Scope `trace:read`. */
+            list: (params?: {
+                verdict?: TraceVerdict;
+                agentId?: string;
+                limit?: number;
+                cursor?: string;
+            }) => Promise<ListResponse<TraceInteraction>>;
+            /** The full per-call evidence view (findings, redactions, audit hash). */
+            get: (id: string) => Promise<TraceInteractionDetail>;
+        };
+        violations: {
+            /** Drill-down of every fired Tier-0 rule across scorecards. Scope `trace:read`. */
+            list: (params?: {
+                ruleId?: string;
+                severity?: TraceSeverity;
+                interactionId?: string;
+                limit?: number;
+                cursor?: string;
+            }) => Promise<ListResponse<TraceViolation>>;
+        };
+        findings: {
+            /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+            list: (params?: {
+                checkId?: string;
+                action?: "flag" | "preempt_next" | "escalate";
+                severity?: TraceSeverity;
+                interactionId?: string;
+                limit?: number;
+                cursor?: string;
+            }) => Promise<ListResponse<TraceFinding>>;
+        };
+        config: {
+            /** Read per-agent Trace config (omit `agentId` for the org default). Scope `trace:configure`. */
+            get: (agentId?: string) => Promise<TraceConfig>;
+            /** Upsert per-agent Trace config. Scope `trace:configure`. */
+            set: (input: TraceConfigInput) => Promise<TraceConfig>;
+        };
+        rulePacks: {
+            /** List built-in + custom rule packs. Scope `trace:configure`. */
+            list: () => Promise<ListResponse<TraceRulePack>>;
+            /** Upload a custom rule pack (Trace DSL). Scope `trace:configure`. */
+            create: (spec: TraceRulePackSpec) => Promise<TraceRulePack>;
+            /** Resolve a rule pack by id (latest active, or pin `version`). */
+            get: (id: string, version?: string) => Promise<TraceRulePack>;
+        };
+        /** Compliance exposure summary over a trailing window. Scope `trace:read`. */
+        exposure: (windowDays?: number) => Promise<TraceExposure>;
+        /**
+         * Convenience: the per-call operational timeline (eval scorecard-v1). A thin
+         * wrapper over `interactions.get(id)` that returns the `timeline` array, or
+         * `[]` when the engine hasn't emitted one yet (forward-compatible). Scope
+         * `trace:read`.
+         */
+        callTimeline: (id: string) => Promise<TraceTimelineTurn[]>;
+    };
+    recap: {
+        config: {
+            get: () => Promise<RecapConfig>;
+            set: (input: RecapConfigInput) => Promise<RecapConfig>;
+        };
+        calls: {
+            list: (params?: {
+                limit?: number;
+                cursor?: string;
+                status?: string;
+            }) => Promise<ListResponse<RecapCallSummary>>;
+            get: (callId: string) => Promise<RecapCall>;
+            trigger: (callId: string, input: RecapCallTriggerInput) => Promise<RecapCallSummary>;
+        };
+    };
+    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;
     /**
      * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
      * The key travels as a subprotocol so it works from the browser without