@agent-cards/sdk 0.23.27 → 0.24.0

package/dist/voice-stream.generated.d.ts

@@ -1,118 +0,0 @@
-/**
- * The streaming door, from either side: the person's
- * answer goes to the verifier as it is spoken, over one WebSocket, and the
- * verifier says `hearing` the moment the key word is out and `verdict` when it
- * has closed the span. One call serves a live microphone and a finished
- * recording alike: a buffer pushed in one go and ended is a short stream.
- *
- * Uses the platform's WebSocket (Node 22, React Native, the browser). The
- * credential rides in the first frame, never in a header, so every platform
- * behaves the same.
- */
-import { AgentcardError, type Lang, type Verdict } from './voice-types.js';
-/**
- * How the bytes are encoded. `pcm16-16k`: little-endian 16-bit mono at
- * 16 kHz, judged live. `mulaw-8k`: a telephone band, judged on the words
- * only. `opus`: an Ogg or WebM Opus stream, judged live. A media type such
- * as `audio/m4a` or `audio/wav`: a finished recording pushed in one go, held
- * until `end`, then judged exactly as an upload of the same bytes.
- */
-export type StreamFormat = 'pcm16-16k' | 'mulaw-8k' | 'opus' | `audio/${string}`;
-/**
- * How the take is heard: the phone's own microphone, a wired headset, a Bluetooth one, or
- * unknown when the platform says nothing. The verifier scores the voice on that route's cohort when it has one
- * and records a change from the enrolment's route as evidence; only the kind travels, never a device name.
- */
-export type ChannelKind = 'builtin' | 'wired' | 'bluetooth' | 'unknown';
-export declare const CHANNEL_KINDS: readonly ChannelKind[];
-/** The key word (and, on a phone's stream, the price) is out: a bot may start its next line now. `heard_count` is how many words landed; the words themselves never cross (WP115). */
-export interface Hearing {
-    heard_count: number;
-}
-/** The verifier's verdict on the stream: the upload verdict plus what the live door knows. */
-/**
- * The verifier's signed word on a take (WP182): `payload` is the exact JSON string the signature covers (the challenge
- * id, `accepted`, the template hash it matched, `z`, `cos`, `spoof_bits`, `issued_at`), `signature` the raw ECDSA
- * `r || s` bytes base64url under the receipt key the Vault's page stamped on the listen, `kid` that key's name. The
- * host relays it to the frame as `host-judged` once the proof landed; the frame checks the signature itself.
- */
-export interface VerdictReceipt {
-    payload: string;
-    signature: string;
-    alg: string;
-    kid: string;
-}
-export interface StreamVerdict extends Verdict {
-    reason: string;
-    bits: {
-        words: number;
-        voice: number;
-        total: number;
-    };
-    cos: number | null;
-    z: number | null;
-    speech_s: number;
-    /** From the first byte to the verdict. */
-    ms: number;
-    /** From the caller's last byte (or `end`) to the verdict: what streaming saves. */
-    since_end_ms: number;
-    /** Why the verifier closed the span: `all_words`, `quiet`, `ended`, `stalled`, `span_cap`, `wall_cap`. */
-    closed_by: string;
-    /** The verifier's signed receipt for this take (WP182), when it sent one. */
-    receipt?: VerdictReceipt;
-}
-export interface StreamInput {
-    /** The verifier's streaming address, `wss://…/v1/stream` (`ws://` against a local verifier). */
-    stream_url: string;
-    authorization_id: string;
-    challenge_id: string;
-    lang: Lang;
-    format: StreamFormat;
-    /** The credential for this answer: the challenge's `answer_token` on the app side, the business's bearer on the server side. */
-    token: string;
-    /** The channel the take is heard on, when known at the open; `handle.channel(kind)` names it later. */
-    channel?: ChannelKind;
-    /** Test seam: the WebSocket constructor; defaults to the platform's. */
-    WebSocket?: typeof WebSocket;
-}
-type Listener<T> = (value: T) => void;
-export interface StreamHandle {
-    readonly format: StreamFormat;
-    /** Queue bytes; they go the moment the socket is open. */
-    push(chunk: ArrayBuffer | Uint8Array): void;
-    /** Nothing more is coming: the verifier closes the span with what it has. */
-    end(): void;
-    /** How the take is heard, once the microphone is open and the device is known; before the verdict. */
-    channel(kind: ChannelKind): void;
-    /**
-     * The audio that follows is sealed (WP115): the take's ephemeral key goes ahead of it as the stream's `sealed`
-     * frame, once, before the first push. The verifier opens every later chunk with it; this side reads none of them.
-     * `kid` names the verifier key the take was sealed to (the first sixteen hex characters of SHA-256 over its SPKI,
-     * as the frame computes it): after a key rotation the verifier opens the take under the key it names, inside the
-     * previous key's grace window, instead of assuming the current one and refusing. A head with no `kid` means the
-     * current key, as a frame from before the field sealed to it.
-     */
-    seal(head: {
-        alg: string;
-        eph: string;
-        kid?: string;
-    }): void;
-    on(event: 'hearing', fn: Listener<Hearing>): StreamHandle;
-    on(event: 'verdict', fn: Listener<StreamVerdict>): StreamHandle;
-    on(event: 'error', fn: Listener<AgentcardError>): StreamHandle;
-    /** Resolves with the verdict; rejects with an `AgentcardError` carrying the verifier's code. */
-    verdict(): Promise<StreamVerdict>;
-    /** Drops the socket without a verdict (the person walked away). */
-    close(): void;
-}
-/** Opens the door and hands back the handle. The first frame names the challenge; bytes follow. */
-export declare function openStream(input: StreamInput): StreamHandle;
-/**
- * A finished recording through the same door. For `pcm16-16k` with `chunkMs`
- * the bytes go in timed chunks, as a microphone would send them; otherwise
- * the whole buffer goes at once. Ends the stream and resolves the verdict.
- */
-export declare function streamBuffer(handle: StreamHandle, bytes: ArrayBuffer | Uint8Array, chunkMs?: number): Promise<StreamVerdict>;
-/** The verifier's streaming address from its origin (`/v1/stream` appended) or a full address, as given. */
-export declare function streamAddress(verifierUrl: string): string;
-export {};

package/dist/voice-stream.generated.js

@@ -1,170 +0,0 @@
-// GENERATED by scripts/generate-voice-stream.mjs from packages/voice/src/core/stream.ts. Do not edit; edit the source and rebuild.
-/**
- * The streaming door, from either side: the person's
- * answer goes to the verifier as it is spoken, over one WebSocket, and the
- * verifier says `hearing` the moment the key word is out and `verdict` when it
- * has closed the span. One call serves a live microphone and a finished
- * recording alike: a buffer pushed in one go and ended is a short stream.
- *
- * Uses the platform's WebSocket (Node 22, React Native, the browser). The
- * credential rides in the first frame, never in a header, so every platform
- * behaves the same.
- */
-import { AgentcardError } from './voice-types.js';
-export const CHANNEL_KINDS = ['builtin', 'wired', 'bluetooth', 'unknown'];
-/** The receipt as the verifier sends it, every field a string, or null for anything else: a receipt with a piece missing cannot be checked, so it is not carried. */
-function receiptOf(r) {
-    if (!r || typeof r !== 'object')
-        return null;
-    const { payload, signature, alg, kid } = r;
-    return typeof payload === 'string' && typeof signature === 'string' && typeof alg === 'string' && typeof kid === 'string' ? { payload, signature, alg, kid } : null;
-}
-function toArrayBuffer(chunk) {
-    if (chunk instanceof ArrayBuffer)
-        return chunk;
-    return chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength);
-}
-/** Opens the door and hands back the handle. The first frame names the challenge; bytes follow. */
-export function openStream(input) {
-    const WS = input.WebSocket ?? globalThis.WebSocket;
-    if (!WS)
-        throw new AgentcardError('no_websocket', 'This runtime has no WebSocket; the streaming door needs one.');
-    const ws = new WS(input.stream_url);
-    ws.binaryType = 'arraybuffer';
-    const listeners = { hearing: [], verdict: [], error: [] };
-    // Audio chunks and, ahead of the first sealed chunk, the `sealed` text frame: sent in the order they were queued.
-    const queue = [];
-    let open = false, ended = false, settled = false, sealed = false;
-    let channelKind = input.channel && CHANNEL_KINDS.includes(input.channel) ? input.channel : undefined;
-    // A channel named after the open goes as its own text frame; one named before rides the first frame.
-    let channelPending = null;
-    let resolveVerdict, rejectVerdict;
-    const verdictPromise = new Promise((resolve, reject) => { resolveVerdict = resolve; rejectVerdict = reject; });
-    verdictPromise.catch(() => { });
-    const fail = (err) => {
-        if (settled)
-            return;
-        settled = true;
-        for (const fn of listeners.error)
-            fn(err);
-        rejectVerdict(err);
-    };
-    const flush = () => { while (open && queue.length)
-        ws.send(queue.shift()); };
-    ws.onopen = () => {
-        // No token on the frame when the caller has none: a fronting door may carry the credential on the upgrade instead.
-        ws.send(JSON.stringify({ authorization_id: input.authorization_id, challenge_id: input.challenge_id, lang: input.lang, format: input.format, ...(input.token ? { token: input.token } : {}), ...(channelKind ? { channel: channelKind } : {}) }));
-        open = true;
-        if (channelPending) {
-            ws.send(JSON.stringify({ type: 'channel', kind: channelPending }));
-            channelPending = null;
-        }
-        flush();
-        if (ended)
-            ws.send(JSON.stringify({ type: 'end' }));
-    };
-    ws.onmessage = (ev) => {
-        if (typeof ev.data !== 'string')
-            return;
-        let msg;
-        try {
-            msg = JSON.parse(ev.data);
-        }
-        catch {
-            return;
-        }
-        if (msg.type === 'hearing') {
-            const h = { heard_count: Math.max(0, Math.floor(Number(msg.heard_count)) || 0) };
-            for (const fn of listeners.hearing)
-                fn(h);
-        }
-        else if (msg.type === 'verdict') {
-            if (settled)
-                return;
-            settled = true;
-            const receipt = receiptOf(msg.receipt);
-            const v = {
-                accepted: msg.accepted === true, spent: true,
-                approved_with: typeof msg.approved_with === 'string' ? msg.approved_with : null,
-                reason: String(msg.reason ?? ''), bits: msg.bits ?? { words: 0, voice: 0, total: 0 },
-                cos: typeof msg.cos === 'number' ? msg.cos : null, z: typeof msg.z === 'number' ? msg.z : null,
-                speech_s: Number(msg.speech_s ?? 0), ms: Number(msg.ms ?? 0), since_end_ms: Number(msg.since_end_ms ?? 0), closed_by: String(msg.closed_by ?? ''),
-                ...(receipt ? { receipt } : {}),
-            };
-            for (const fn of listeners.verdict)
-                fn(v);
-            resolveVerdict(v);
-        }
-        else if (msg.type === 'error') {
-            fail(new AgentcardError(String(msg.code ?? 'verifier_error'), String(msg.message ?? 'The verifier refused the stream.')));
-        }
-    };
-    ws.onerror = () => fail(new AgentcardError('unreachable', 'The verifier could not be reached.'));
-    ws.onclose = () => fail(new AgentcardError('stream_closed', 'The verifier closed the stream without a verdict.'));
-    const handle = {
-        format: input.format,
-        push(chunk) { if (ended || settled)
-            return; queue.push(toArrayBuffer(chunk)); flush(); },
-        end() { if (ended)
-            return; ended = true; if (open) {
-            flush();
-            ws.send(JSON.stringify({ type: 'end' }));
-        } },
-        channel(kind) {
-            if (settled || ended || !CHANNEL_KINDS.includes(kind))
-                return;
-            if (!open) {
-                channelKind = kind;
-                channelPending = null;
-                return;
-            }
-            channelKind = kind;
-            ws.send(JSON.stringify({ type: 'channel', kind }));
-        },
-        seal(head) {
-            if (settled || ended || sealed || typeof head.eph !== 'string' || !head.eph)
-                return;
-            sealed = true;
-            const kid = typeof head.kid === 'string' && head.kid ? head.kid : null;
-            queue.push(JSON.stringify({ type: 'sealed', alg: head.alg, eph: head.eph, ...(kid ? { kid } : {}) }));
-            flush();
-        },
-        on(event, fn) { listeners[event].push(fn); return handle; },
-        verdict: () => verdictPromise,
-        close() { if (!settled) {
-            settled = true;
-            rejectVerdict(new AgentcardError('stream_closed', 'The stream was closed before a verdict.'));
-        } try {
-            ws.close();
-        }
-        catch { /* already closed */ } },
-    };
-    return handle;
-}
-const PCM16_16K_BYTES_PER_MS = 32;
-/**
- * A finished recording through the same door. For `pcm16-16k` with `chunkMs`
- * the bytes go in timed chunks, as a microphone would send them; otherwise
- * the whole buffer goes at once. Ends the stream and resolves the verdict.
- */
-export async function streamBuffer(handle, bytes, chunkMs) {
-    const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-    if (chunkMs && chunkMs > 0 && handle.format === 'pcm16-16k') {
-        const step = PCM16_16K_BYTES_PER_MS * chunkMs;
-        for (let i = 0; i < u8.length; i += step) {
-            handle.push(u8.subarray(i, Math.min(u8.length, i + step)));
-            if (i + step < u8.length)
-                await new Promise((r) => setTimeout(r, chunkMs));
-        }
-    }
-    else {
-        handle.push(u8);
-    }
-    handle.end();
-    return handle.verdict();
-}
-/** The verifier's streaming address from its origin (`/v1/stream` appended) or a full address, as given. */
-export function streamAddress(verifierUrl) {
-    const trimmed = verifierUrl.replace(/\/+$/, '');
-    return /\/v1\/stream$/.test(trimmed) ? trimmed : trimmed + '/v1/stream';
-}