@agent-cards/sdk 0.23.27 → 0.24.0

package/dist/voice.js

@@ -1,815 +0,0 @@
-import { ApiModule } from './api-module.js';
-import { withRetries } from './voice-retry.js';
-import { openStream, streamAddress } from './voice-stream.generated.js';
-import { mintPkce, readReturnLink } from './voice-pkce.js';
-import { stripePaymentIntentConfirmRequest } from './requests.js';
-import { AgentcardError, } from './voice-types.js';
-export { stripePaymentIntentConfirm } from './requests.js';
-export const GRANT_REQUIRES_EXCHANGE_MESSAGE = 'This session is an authorization grant: its result is not read by polling. Hand the return link to voice.completeConnect(url), or its code and state to voice.exchange({ code, state, session_id }).';
-/** How many minted grants the client remembers (verifier and state, by session); the oldest is forgotten past this. */
-const GRANTS_REMEMBERED = 5_000;
-/** The exchange refusals that end a grant for good; a `not_linked` leaves it open. */
-const TERMINAL_EXCHANGE_CODES = new Set(['invalid_grant', 'not_a_grant', 'code_expired', 'already_exchanged', 'revoked', 'expired', 'account_suspended']);
-/** The steps a Vault link's page reports, as the API spells them; anything else reads as null. */
-const SESSION_STEPS = new Set(['opened', 'signed_in', 'challenge_minted', 'voice_refused', 'confirmed', 'stopped', 'left', 'reset_done']);
-export function stepOf(v) { return typeof v === 'string' && SESSION_STEPS.has(v) ? v : null; }
-export function reasonOf(v) { return typeof v === 'string' && v ? v : null; }
-/** What a grant asks for when the caller names nothing: the three terms, so the row says what is enforced. */
-const ALL_AUTHORIZATION_DETAILS = [{ type: 'agentcard_card' }, { type: 'voice' }, { type: 'rule' }];
-/** The business's words for withdrawing a purchase (`authorizations.cancel`); anything else is refused before any call. */
-export const CANCEL_REASONS = ['person_closed_sheet', 'person_changed_mind', 'business_cancelled'];
-/** Why no rule took the purchase, when the API says so plainly (`unverified_origin`). */
-function executionReasonFields(a) {
-    return {
-        ...(typeof a.execution_reason === 'string' ? { execution_reason: a.execution_reason } : {}),
-        ...(typeof a.execution_detail === 'string' ? { execution_detail: a.execution_detail } : {}),
-    };
-}
-/**
- * The origin a paused request pays from, when its `origin` header is one Agentcard admits as `checkout_origin`
- * (an exact https origin, or http://localhost for a local run); null otherwise. The Stripe request builders
- * set that header, so a create that names no `checkout_origin` still carries the app's.
- */
-export function checkoutOriginOf(request) {
-    const header = Object.entries(request.headers ?? {}).find(([k]) => k.toLowerCase() === 'origin')?.[1];
-    if (typeof header !== 'string')
-        return null;
-    try {
-        const u = new URL(header);
-        return u.origin === header && !u.username && !u.password && (u.protocol === 'https:' || (u.protocol === 'http:' && u.hostname === 'localhost')) ? header : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** The approval request's fields as the API answers them, typed, and nothing the row does not carry. */
-function approvalRequestFields(a) {
-    const out = {};
-    if ('request_id' in a)
-        out.request_id = a.request_id ?? null;
-    if (typeof a.interval === 'number')
-        out.interval = a.interval;
-    if (typeof a.poll_interval_ms === 'number')
-        out.poll_interval_ms = a.poll_interval_ms;
-    if ('intent_hash' in a)
-        out.intent_hash = a.intent_hash ?? null;
-    if (typeof a.expires_at === 'string')
-        out.expires_at = a.expires_at;
-    if ('delivery_channel' in a)
-        out.delivery_channel = a.delivery_channel ?? null;
-    if ('terminal_reason' in a)
-        out.terminal_reason = a.terminal_reason ?? null;
-    if (Array.isArray(a.interaction_evidence))
-        out.interaction_evidence = a.interaction_evidence;
-    if ('intent' in a)
-        out.intent = a.intent ?? null;
-    if ('intent_version' in a)
-        out.intent_version = a.intent_version ?? null;
-    if ('external_user_id' in a)
-        out.external_user_id = a.external_user_id ?? null;
-    return out;
-}
-export const MISSING_APPROVAL_POSTURE_MESSAGE = "Name how your product approves purchases: voice: { approval: 'sheet' } (the person approves on Agentcard's page with a credential Agentcard verifies; the default when approval is left out) or voice: { approval: 'in_app' } (hold-to-talk in your app, judged on the phone and by Agentcard, signed by a key in your app).";
-/** The default posture: the person approves on Agentcard's page. */
-export const DEFAULT_APPROVAL_POSTURE = 'sheet';
-/**
- * The posture as named, or `'sheet'` when none was: a client built without
- * `voice`, or with `voice` and no `approval`, approves on Agentcard's page.
- * Throws `missing_approval_posture` only for a posture that is neither.
- */
-export function approvalPostureOf(options) {
-    const posture = options?.approval;
-    if (posture === undefined)
-        return DEFAULT_APPROVAL_POSTURE;
-    if (posture === 'sheet' || posture === 'in_app')
-        return posture;
-    throw new AgentcardError('missing_approval_posture', MISSING_APPROVAL_POSTURE_MESSAGE);
-}
-export { streamAddress } from './voice-stream.generated.js';
-/**
- * The sandbox request: a first run's purchase, naming no processor. Under a
- * sandbox client `voice.authorizations.create({ request: 'sandbox' })` sends
- * this; the sandbox completes it without reaching any processor. A live
- * client refuses it before any call (`sandbox_request_in_live`).
- */
-export const SANDBOX_REQUEST = stripePaymentIntentConfirmRequest({
-    origin: 'https://sandbox.agentcard.sh',
-    intent: { id: 'pi_sandbox', client_secret: 'pi_sandbox_secret_sandbox', publishable_key: 'pk_test_sandbox' },
-});
-/** The paying card as the API names it (decision 213), read for its type; null for null or anything that is not one. */
-function cardOf(v) {
-    if (!v || typeof v !== 'object')
-        return null;
-    const c = v;
-    if (typeof c.id !== 'string' || !c.id)
-        return null;
-    return { id: c.id, name: typeof c.name === 'string' ? c.name : '', last4: typeof c.last4 === 'string' ? c.last4 : null, brand: typeof c.brand === 'string' ? c.brand : null, reason: typeof c.reason === 'string' ? c.reason : null };
-}
-/** The choosable cards as the API lists them; a list only, every entry a card. */
-function cardsOf(v) {
-    if (!Array.isArray(v))
-        return undefined;
-    const out = [];
-    for (const raw of v) {
-        const card = cardOf(raw);
-        if (!card)
-            continue;
-        const c = raw;
-        out.push({ ...card, recommended: c.recommended === true, ...(c.auto_approve === true ? { auto_approve: true } : {}) });
-    }
-    return out;
-}
-/** `card` and `cards` off a purchase read, as the API carries them; absent from an older API. */
-function cardFields(a) {
-    const cards = cardsOf(a.cards);
-    return { ...('card' in a ? { card: cardOf(a.card) } : {}), ...(cards ? { cards } : {}) };
-}
-/** A challenge as the API answers it, every field read for its type; the four host fields stay absent until the API mints them. */
-function challengeOf(ch, authorizationId) {
-    const str = (v) => (typeof v === 'string' && v ? v : undefined);
-    const minor = (v) => (typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : undefined);
-    const lines = (v) => (v && typeof v === 'object' ? v : undefined);
-    const intent = ch.intent && typeof ch.intent === 'object' && typeof ch.intent.hash === 'string'
-        ? { kind: String(ch.intent.kind ?? ''), hash: ch.intent.hash } : undefined;
-    const audioDelivery = ch.audio_delivery === 'spoken' || ch.audio_delivery === 'screen' ? ch.audio_delivery : undefined;
-    return {
-        id: String(ch.id ?? ''),
-        authorization_id: str(ch.authorization_id) ?? authorizationId,
-        word: String(ch.word ?? ''),
-        ...(str(ch.lang) ? { lang: str(ch.lang) } : {}),
-        say: lines(ch.say) ?? {},
-        ...(lines(ch.say_private) ? { say_private: lines(ch.say_private) } : {}),
-        ...('card' in ch ? { card: cardOf(ch.card) } : {}),
-        ...(str(ch.audio_url) ? { audio_url: str(ch.audio_url) } : {}),
-        ...(audioDelivery ? { audio_delivery: audioDelivery } : {}),
-        ...(str(ch.challenge) ? { challenge: str(ch.challenge) } : {}),
-        ...(intent ? { intent } : {}),
-        ...(str(ch.verifier_url) ? { verifier_url: str(ch.verifier_url) } : {}),
-        ...(str(ch.answer_token) ? { answer_token: str(ch.answer_token) } : {}),
-        ...(str(ch.verifier_public_key) ? { verifier_public_key: str(ch.verifier_public_key) } : {}),
-        ...(minor(ch.amount_minor) !== undefined ? { amount_minor: minor(ch.amount_minor) } : {}),
-        ...(str(ch.currency) ? { currency: str(ch.currency) } : {}),
-        expires_at: String(ch.expires_at ?? ''),
-    };
-}
-/** The sealed bundle for the host, from a typed challenge; refuses one the frame cannot sign for. */
-export function bundleOf(ch) {
-    if (!ch.challenge || !ch.intent || !ch.authorization_id)
-        throw new AgentcardError('challenge_incomplete', 'The API minted this challenge without the nonce or the intent the hosted frame signs over; an in-app approval needs both. Take the approval page this once.');
-    return {
-        challenge_id: ch.id,
-        authorization_id: ch.authorization_id,
-        word: ch.word,
-        ...(ch.lang ? { lang: ch.lang } : {}),
-        say: ch.say,
-        ...(ch.say_private ? { say_private: ch.say_private } : {}),
-        ...(ch.card !== undefined ? { card: ch.card } : {}),
-        ...(ch.audio_url ? { audio_url: ch.audio_url } : {}),
-        ...(ch.audio_delivery ? { audio_delivery: ch.audio_delivery } : {}),
-        challenge: ch.challenge,
-        intent: ch.intent,
-        ...(ch.verifier_url ? { verifier_url: ch.verifier_url } : {}),
-        ...(ch.answer_token ? { answer_token: ch.answer_token } : {}),
-        ...(ch.verifier_public_key ? { verifier_public_key: ch.verifier_public_key } : {}),
-        ...(ch.amount_minor !== undefined ? { amount_minor: ch.amount_minor } : {}),
-        ...(ch.currency ? { currency: ch.currency } : {}),
-        expires_at: ch.expires_at,
-    };
-}
-/** What a paused browser purchase resumes with: the mode and the processor's answer, ciphertext or device stamp, read for their types. */
-function replayFields(a) {
-    const out = {};
-    if (typeof a.mode === 'string')
-        out.mode = a.mode;
-    const r = a.response;
-    if (r && typeof r === 'object' && Number.isInteger(r.status) && typeof r.body === 'string' && r.headers && typeof r.headers === 'object' && !Array.isArray(r.headers)) {
-        out.response = { status: r.status, headers: r.headers, body: r.body };
-    }
-    const sub = a.substitutions;
-    if (sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.fields && typeof sub.fields === 'object') {
-        out.substitutions = { encoding: 'json', at: sub.at, fields: { ...sub.fields }, ...(Array.isArray(sub.remove) ? { remove: sub.remove } : {}) };
-    }
-    if (typeof a.submitted_at === 'string')
-        out.submitted_at = a.submitted_at;
-    return out;
-}
-/** A purchase as one read answers it: the status, what approved it, the request fields, the settlement and what a paused page resumes with. */
-function resultOf(a) {
-    const fields = approvalRequestFields(a);
-    // The settlement answer as the API carries it (the same object as on the finishing webhook), read defensively:
-    // an object with a status word, or null when there is nothing to read back; absent from an older API.
-    const settlement = 'settlement' in a
-        ? (a.settlement && typeof a.settlement === 'object' && typeof a.settlement.status === 'string' ? a.settlement : null)
-        : undefined;
-    const approvalUrl = typeof a.approval_url === 'string' ? a.approval_url : typeof a.approvalUrl === 'string' ? a.approvalUrl : undefined;
-    return { ...(typeof a.id === 'string' ? { id: a.id } : {}), status: a.status, approved_with: a.approved_with, execution_mode: a.execution_mode, ...executionReasonFields(a), ...fields, ...(settlement === undefined ? {} : { settlement }), ...(approvalUrl && a.status === 'awaiting_approval' ? { approval_url: approvalUrl } : {}), ...replayFields(a), ...cardFields(a) };
-}
-/** A random idempotency key for one create, so a retried call makes one purchase. */
-function idempotencyKey() {
-    const c = globalThis.crypto;
-    if (c?.randomUUID)
-        return c.randomUUID();
-    return 'ik_' + Math.random().toString(36).slice(2) + Date.now().toString(36);
-}
-/** `agentcard.voice`: constructed by the client, never on its own. */
-export class VoiceModule extends ApiModule {
-    options;
-    clientIsSandbox;
-    /** The approval posture the client was constructed with, one per business; `'sheet'` when the client named none. */
-    approval;
-    /** The grants this client minted, by session id: the verifier and the state, then the exchanged result. Memory only. */
-    grants = new Map();
-    /** Session id by minted `state`, so a return link finds its grant without naming the session. */
-    grantsByState = new Map();
-    constructor(t, options, clientIsSandbox) {
-        super(t);
-        this.options = options;
-        this.clientIsSandbox = clientIsSandbox;
-        this.approval = approvalPostureOf(options);
-    }
-    posture() {
-        return this.approval;
-    }
-    /** Where the Vault sends the person back when a call names nothing, as the client was constructed. */
-    get returnUrl() { return this.options?.returnUrl; }
-    /**
-     * The languages Agentcard speaks, as the API lists them (`{ tag, name }`),
-     * read once and kept for ten minutes. Every call that names a `lang` checks
-     * it against this list first and refuses one not on it with
-     * `unsupported_language` before anything is sent. `null` on an API that
-     * does not serve the list yet; tags then travel unchecked.
-     */
-    languages() { return this.t.languages.list(); }
-    // --- connecting a person --------------------------------------------------------------------------------
-    remember(grant) {
-        if (this.grants.size >= GRANTS_REMEMBERED) {
-            const oldest = this.grants.keys().next().value;
-            if (oldest !== undefined)
-                this.forget(oldest);
-        }
-        this.grants.set(grant.sessionId, grant);
-        this.grantsByState.set(grant.state, grant.sessionId);
-    }
-    forget(sessionId) {
-        const g = this.grants.get(sessionId);
-        if (!g)
-            return;
-        this.grants.delete(sessionId);
-        if (this.grantsByState.get(g.state) === sessionId)
-            this.grantsByState.delete(g.state);
-    }
-    /**
-     * Mints the connect link. The person signs in, stores a card if none, sets
-     * up their voice if the app requires it, and comes back. Open `url` in the
-     * in-app sheet. The link is an OAuth authorization grant: the client mints
-     * `state` and a PKCE challenge, keeps the verifier, and the return link
-     * comes back as `yourapp://connected?code=…&state=…`; hand it to
-     * `completeConnect(url)`, once, within 60 seconds. With no return link there
-     * is nothing to carry the code, so the mint polls (`grant: 'poll'`, then
-     * `awaitConnected`); `pkce: false` asks for that shape outright (deprecated).
-     * A grant asks for the terms it names in `authorization_details`, and for
-     * all three when it names none; the terms are enforced from then on. The
-     * result carries the client's approval posture as `approval`, for the app.
-     */
-    async connect(input = {}) {
-        const approval = this.posture();
-        await this.t.languages.check(input.lang);
-        const returnUrl = input.return_url ?? this.returnUrl;
-        if (input.pkce === true && !returnUrl)
-            throw new AgentcardError('missing_return_url', 'A grant rides the return link: name return_url on the call or returnUrl on the client.');
-        // A landing collects nothing, so it polls unless the caller asks for a grant outright.
-        const grant = input.pkce === true || (input.pkce !== false && !input.landing);
-        const pkce = grant && !!returnUrl ? await mintPkce(this.options?.pkce) : null;
-        const details = input.authorization_details ?? (pkce ? ALL_AUTHORIZATION_DETAILS : undefined);
-        const body = await this.request('/api/v2/vault_sessions', {
-            method: 'POST',
-            body: {
-                mode: 'open',
-                ...(returnUrl ? { return_url: returnUrl } : {}),
-                ...(input.voice ? { voice: input.voice } : {}),
-                ...(input.email ? { email: input.email } : {}),
-                ...(input.external_user_id ? { external_user_id: input.external_user_id } : {}),
-                ...(input.lang ? { lang: input.lang } : {}),
-                ...(input.landing ? { steps: [input.landing] } : {}),
-                ...(pkce ? { state: pkce.state, code_challenge: pkce.code_challenge, code_challenge_method: pkce.code_challenge_method } : {}),
-                ...(details ? { authorization_details: details } : {}),
-            },
-        });
-        if (pkce)
-            this.remember({ sessionId: body.id, state: pkce.state, verifier: pkce.code_verifier });
-        return {
-            url: body.url,
-            session_id: body.id,
-            voice: body.voice ?? input.voice,
-            approval,
-            grant: pkce ? 'exchange' : 'poll',
-            request_id: body.request_id ?? null,
-            ...(pkce ? { state: pkce.state, code_verifier: pkce.code_verifier } : {}),
-            ...(details ? { authorization_details: body.authorization_details ?? details } : {}),
-        };
-    }
-    /**
-     * The grant's exchange: the `code` from the return link, under this client's
-     * credentials, with the verifier the client kept for the session. Answers
-     * once, within 60 seconds of the link. A `state` that is not the one minted
-     * for the session is refused here, before any call (`state_mismatch`). When
-     * another instance minted the link, pass the `code_verifier` AND the
-     * `expected_state` that `connect` returned there: the link's `state` is
-     * compared with `expected_state` locally, and no exchange is made without
-     * that comparison. The API's refusals come through verbatim: `invalid_grant`,
-     * `not_linked` (the person is not done; try again), `code_expired`,
-     * `already_exchanged`, `revoked`. `completeConnect(url)` reads the link and
-     * calls this.
-     */
-    async exchange(input) {
-        this.posture();
-        const bySession = input.session_id ? this.grants.get(input.session_id) : undefined;
-        const byState = !bySession && input.state ? this.grants.get(this.grantsByState.get(input.state) ?? '') : undefined;
-        const grant = bySession ?? byState;
-        if (grant && input.state !== grant.state) {
-            throw new AgentcardError('state_mismatch', input.state === undefined
-                ? 'The return link carries no state; this session was minted with one. Refused before any call.'
-                : 'The state on the return link is not the one minted for this session. Refused before any call.');
-        }
-        if (!grant && input.code_verifier) {
-            // Another instance minted the link: the persisted state must be given and must be the link's, or nothing is sent.
-            if (!input.expected_state)
-                throw new AgentcardError('state_mismatch', 'Another instance minted this link: pass expected_state (the state connect returned there, persisted with the code_verifier) so the return link can be checked before any call.');
-            if (input.state !== input.expected_state) {
-                throw new AgentcardError('state_mismatch', input.state === undefined
-                    ? 'The return link carries no state; this session was minted with one. Refused before any call.'
-                    : 'The state on the return link is not the one minted for this session. Refused before any call.');
-            }
-        }
-        if (!grant && input.state !== undefined && !input.code_verifier) {
-            throw new AgentcardError('state_mismatch', 'No session minted by this client carries that state. Pass session_id, and the code_verifier and expected_state connect returned, when another instance minted the link.');
-        }
-        const verifier = input.code_verifier ?? grant?.verifier;
-        if (!verifier)
-            throw new AgentcardError('unknown_grant', 'This client did not mint that session, or has restarted since. Pass the code_verifier and expected_state connect returned, or connect again.');
-        let body;
-        try {
-            body = await this.request('/api/v2/vault_sessions/exchange', { method: 'POST', body: { code: input.code, code_verifier: verifier } });
-        }
-        catch (err) {
-            // A refusal that ends the grant is what awaitConnected answers from then on; a grant already exchanged keeps its result.
-            if (grant && !grant.result && err instanceof AgentcardError && TERMINAL_EXCHANGE_CODES.has(err.code))
-                grant.failure = err;
-            throw err;
-        }
-        const userId = typeof body.user_id === 'string' ? body.user_id : null;
-        if (!userId)
-            throw new AgentcardError('invalid_grant', 'The exchange answered without a person.');
-        const result = {
-            user_id: userId,
-            card: body.card === true,
-            voice: Array.isArray(body.voice) ? body.voice : [],
-            rule: body.rule === true,
-            passkey: body.passkey === true,
-            external_user_id: typeof body.external_user_id === 'string' ? body.external_user_id : null,
-            session_id: typeof body.session_id === 'string' ? body.session_id : (grant?.sessionId ?? input.session_id ?? ''),
-            request_id: typeof body.request_id === 'string' ? body.request_id : null,
-            state: typeof body.state === 'string' ? body.state : null,
-            authorization_details: Array.isArray(body.authorization_details) ? body.authorization_details : null,
-            action: body.action && typeof body.action === 'object' ? body.action : null,
-            linked_at: typeof body.linked_at === 'string' ? body.linked_at : null,
-            // The link's diary, as the exchange answers it: why a grant came back with `voice: []`.
-            last_step: stepOf(body.last_step),
-            reason: reasonOf(body.reason),
-            // Only the return link says this; `completeConnect` fills it from the link.
-            voice_reset: null,
-            connection: body.connection && typeof body.connection === 'object' ? body.connection : null,
-        };
-        if (grant)
-            grant.result = result;
-        return result;
-    }
-    /**
-     * The return link, as the sheet handed it back (`yourapp://connected?code=…&state=…`):
-     * finds the grant by its `state`, checks it, and exchanges the code. Throws
-     * `missing_code` when the link carries none (a session minted to poll, a
-     * reset or an action link: read those with `awaitConnected`).
-     */
-    async completeConnect(returnUrl, opts = {}) {
-        this.posture();
-        const { code, state, voice_reset } = readReturnLink(returnUrl);
-        // A link with no code is not a grant's: the error names what the link did say (`voice_reset` after a reset
-        // visit), so the caller reads the outcome from `details` and polls the session for the rest.
-        if (!code)
-            throw new AgentcardError('missing_code', 'The return link carries no code. A session minted to poll (pkce: false, reset, or an action) is read with awaitConnected.', undefined, { voice_reset });
-        const result = await this.exchange({ code, ...(state !== null ? { state } : {}), ...opts });
-        return { ...result, voice_reset };
-    }
-    /**
-     * Resolves once the session is linked: who, and what the app may use.
-     * For a grant this client minted it resolves when `exchange` (or
-     * `completeConnect`) has answered for that session, and reads nothing
-     * meanwhile; for a polling mint it polls the session. Throws
-     * `connect_timeout` at the deadline, and `grant_requires_exchange` when the
-     * API says the session is a grant this client does not hold the verifier for.
-     * For one read with no wait, `sessions.get(session_id)`.
-     */
-    async awaitConnected(sessionId, opts = {}) {
-        this.posture();
-        const grant = this.grants.get(sessionId);
-        if (grant) {
-            return this.poll(async () => {
-                if (grant.result)
-                    return grant.result;
-                if (grant.failure)
-                    throw grant.failure;
-                return undefined;
-            }, opts.timeout_ms, () => { throw new AgentcardError('connect_timeout', 'The Vault session was not exchanged in time. ' + GRANT_REQUIRES_EXCHANGE_MESSAGE); });
-        }
-        const deadline = Date.now() + (opts.timeout_ms ?? this.pollTimeoutMs);
-        return this.poll(async () => {
-            let s;
-            try {
-                s = await this.read(`/api/v2/vault_sessions/${encodeURIComponent(sessionId)}`, { deadline });
-            }
-            catch (err) {
-                if (err instanceof AgentcardError && err.code === 'grant_requires_exchange')
-                    throw new AgentcardError('grant_requires_exchange', GRANT_REQUIRES_EXCHANGE_MESSAGE, err.status, err.details);
-                throw err;
-            }
-            // A linked grant this client does not hold the verifier for: the API answers the diary and withholds the
-            // result (`exchange_required`); that is the refusal this call has always given, said plainly.
-            if (s.status === 'linked' && (s.exchange_required === true || (s.grant === 'exchange' && !s.user_id))) {
-                throw new AgentcardError('grant_requires_exchange', GRANT_REQUIRES_EXCHANGE_MESSAGE, 400, { request_id: s.request_id ?? null, last_step: stepOf(s.last_step), reason: reasonOf(s.reason) });
-            }
-            if (s.status === 'linked' && s.user_id) {
-                return { user_id: s.user_id, card: s.card === true, voice: Array.isArray(s.voice) ? s.voice : [], rule: s.rule === true, passkey: s.passkey === true, external_user_id: s.external_user_id ?? null, last_step: stepOf(s.last_step), reason: reasonOf(s.reason) };
-            }
-            if (s.status === 'expired' || s.status === 'consumed')
-                throw new AgentcardError('vault_session_' + s.status, 'The Vault link is no longer usable. Connect again.');
-            return undefined;
-        }, opts.timeout_ms, () => { throw new AgentcardError('connect_timeout', 'The Vault session was not linked in time.'); });
-    }
-    sessions = {
-        /**
-         * Where a link stands, in one read and with no wait: its status, how its result is collected (`grant`), and
-         * the diary (`last_step`, `reason`) that says why a link came back with nothing. On a linked grant the
-         * connected result stays behind the exchange (`exchange_required: true`, the person's fields null); a
-         * polling mint reads its result here as `awaitConnected` gives it. `slow_down` is waited out.
-         */
-        get: async (sessionId) => {
-            this.posture();
-            const s = await this.read(`/api/v2/vault_sessions/${encodeURIComponent(sessionId)}`);
-            const status = s.status === 'linked' ? 'linked' : s.status === 'expired' ? 'expired' : 'pending';
-            const grant = s.grant === 'exchange' ? 'exchange' : 'poll';
-            const withheld = status === 'linked' && (s.exchange_required === true || (grant === 'exchange' && !s.user_id));
-            return {
-                session_id: typeof s.id === 'string' ? s.id : sessionId,
-                request_id: typeof s.request_id === 'string' ? s.request_id : null,
-                status,
-                grant,
-                exchange_required: withheld,
-                last_step: stepOf(s.last_step),
-                reason: reasonOf(s.reason),
-                external_user_id: typeof s.external_user_id === 'string' ? s.external_user_id : null,
-                user_id: withheld || typeof s.user_id !== 'string' ? null : s.user_id,
-                card: withheld || typeof s.card !== 'boolean' ? null : s.card,
-                voice: withheld || !Array.isArray(s.voice) ? null : s.voice,
-                rule: withheld || typeof s.rule !== 'boolean' ? null : s.rule,
-                passkey: withheld || typeof s.passkey !== 'boolean' ? null : s.passkey,
-                action: withheld || !s.action || typeof s.action !== 'object' ? null : s.action,
-                linked_at: typeof s.linked_at === 'string' ? s.linked_at : null,
-                expires_at: typeof s.expires_at === 'string' ? s.expires_at : null,
-            };
-        },
-    };
-    /**
-     * Revokes the connection a session made: the token its exchange minted is
-     * revoked, and an unexchanged code refuses from then on. Idempotent.
-     */
-    async disconnect(sessionId) {
-        this.posture();
-        const body = await this.request(`/api/v2/vault_sessions/${encodeURIComponent(sessionId)}`, { method: 'DELETE' });
-        return { session_id: body.id ?? sessionId, revoked: body.revoked === true, revoked_at: body.revoked_at, token_revoked: body.token_revoked === true };
-    }
-    people = {
-        /**
-         * A returning person: what they already have with this business, without
-         * minting a link or sending them anywhere. Store `user_id` from the first
-         * exchange; on a later launch read here first, and `connect` only for what
-         * is missing (no card, or `voice: 'required'` and no voice for the bot's
-         * language). 404 `connection_not_found` when the person never connected
-         * through this client (or disconnected). The `user_id` in the answer is
-         * the effective one: a merged account answers with its survivor, worth
-         * storing from then on.
-         */
-        get: async (userId) => {
-            this.posture();
-            const p = await this.read(`/api/v2/vault_users/${encodeURIComponent(userId)}`);
-            return { user_id: p.user_id, card: p.card === true, voice: Array.isArray(p.voice) ? p.voice : [], rule: p.rule === true, passkey: p.passkey === true, team_member: p.team_member === true };
-        },
-    };
-    // --- the purchase ---------------------------------------------------------------------------------------
-    authorizations = {
-        /**
-         * Creates the purchase, paused for approval, for the person `user_id`
-         * names (the `user_id` the connect exchange returned; required, so a
-         * server serving many people never charges the wrong one).
-         * `execution_mode: 'autopilot'` means the person's rule took it and no
-         * voice step follows. The return link (the call's, else the client's
-         * `returnUrl`) goes in the create, so Agentcard stores it on the request
-         * and the approval page reads it from there; the `approval_url` returned
-         * is id-only. `request: 'sandbox'` is the first-run form: under a sandbox
-         * client (`sandbox: true`, an `sk_test_` credential, or a mode the token
-         * exchange named) it sends the sandbox request and names no processor; a
-         * live client refuses it before the create leaves (`sandbox_request_in_live`). Every
-         * create carries an idempotency key, so a retried call makes one purchase.
-         */
-        create: async (input) => {
-            this.posture();
-            const user = input.user_id;
-            if (typeof user !== 'string' || !user)
-                throw new AgentcardError('not_connected', 'Name user_id: the person the connect exchange returned. Refused before any call.');
-            let request;
-            if (input.request === 'sandbox') {
-                // A client that was not named sandbox may still learn it from the token exchange; the create itself has not left.
-                if (!this.clientIsSandbox())
-                    await this.t.bearer();
-                if (!this.clientIsSandbox())
-                    throw new AgentcardError('sandbox_request_in_live', "request: 'sandbox' is for a sandbox client. Under live credentials build the processor's request (checkout.requests.build) or hand over the request a browser purchase paused on. Refused before any call.");
-                request = SANDBOX_REQUEST;
-            }
-            else if (input.request && typeof input.request === 'object' && typeof input.request.url === 'string') {
-                request = input.request;
-            }
-            else {
-                throw new AgentcardError('invalid_request', "request must be a paused request ({ url, method, headers, body }) or 'sandbox'. Refused before any call.");
-            }
-            const returnUrl = input.return_url ?? this.returnUrl;
-            // The origin the purchase is paid from goes in the create (Agentcard keeps no `origin` header from the
-            // paused request), so a rule the person confirmed can take it; named on the call, else the paused
-            // request's own when it is an origin Agentcard admits.
-            const checkoutOrigin = input.checkout_origin ?? checkoutOriginOf(request);
-            const body = await this.request('/v2/checkout/authorizations', {
-                method: 'POST',
-                body: { user, merchant: input.merchant, amount: input.amount, currency: input.currency, psp: input.psp ?? 'stripe', mode: input.mode ?? 'token', request, ...(returnUrl ? { return_url: returnUrl } : {}), ...(checkoutOrigin ? { checkout_origin: checkoutOrigin } : {}), ...(input.card_id ? { card_id: input.card_id } : {}) },
-                headers: { 'idempotency-key': input.idempotency_key ?? idempotencyKey() },
-            });
-            const approvalUrl = body.approval_url ?? body.approvalUrl;
-            return { id: body.id, status: body.status, execution_mode: body.execution_mode, ...executionReasonFields(body), ...approvalRequestFields(body), ...(approvalUrl ? { approval_url: approvalUrl } : {}), ...(typeof body.return_url === 'string' ? { return_url: body.return_url } : {}), ...cardFields(body) };
-        },
-        /**
-         * Names the card that pays, before the approval (decision 213): the person said "another card", or chose
-         * one from `cards`. `cardId` is one of the person's stored cards as `cards` lists them; a card that is not
-         * theirs is `card_not_found`. Refused once the purchase is decided (`already_finalized`) or while the card is
-         * with the processor (`replay_in_progress`). Answers the purchase as `get` reads it, `card` and `cards`
-         * included. Ask for the key word after this, so the line names the card that will pay.
-         */
-        setCard: async (authorizationId, cardId) => {
-            this.posture();
-            if (typeof cardId !== 'string' || !cardId)
-                throw new AgentcardError('invalid_card', 'Name the card: one of the ids the purchase\'s `cards` lists. Refused before any call.');
-            const a = await this.request(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}/card`, { method: 'POST', body: { card_id: cardId } });
-            return resultOf(a);
-        },
-        /**
-         * One read of a purchase, with no wait: its status, what approved it, the
-         * request fields, the settlement once it finished, and what a paused
-         * page resumes with. The way to ask "is it decided yet?" from a handler
-         * that cannot wait; `awaitResult` is the way to wait. `slow_down` is
-         * waited out.
-         */
-        get: async (authorizationId) => {
-            this.posture();
-            const a = await this.read(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}`);
-            return resultOf(a);
-        },
-        /**
-         * Withdraws a purchase that still awaits the person, in the business's own words: the person closed the
-         * sheet (`person_closed_sheet`), the person changed their mind (`person_changed_mind`), or a reason of the
-         * business's own (`business_cancelled`). The purchase reads `status: 'cancelled'` from then on, the reason
-         * is its `terminal_reason` on every read and on the `checkout_authorization.cancelled` webhook, and
-         * `awaitResult` reads `status: 'cancelled'` at once. Idempotent: a purchase already
-         * withdrawn answers what it became. One that the person already approved cannot be withdrawn
-         * (`409 already_finalized` once it finished, `409 outcome_unknown` while the card is with the processor).
-         */
-        cancel: async (authorizationId, opts) => {
-            this.posture();
-            const reason = opts?.reason;
-            if (!CANCEL_REASONS.includes(reason))
-                throw new AgentcardError('invalid_cancel_reason', `reason must be one of ${CANCEL_REASONS.join(', ')}.`);
-            const body = await this.request(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}/cancel`, { method: 'POST', body: { reason } });
-            const stamped = CANCEL_REASONS.includes(body.reason) ? body.reason : reason;
-            return { id: body.id ?? authorizationId, status: 'cancelled', reason: stamped, terminal_reason: (typeof body.terminal_reason === 'string' ? body.terminal_reason : stamped), request_id: body.request_id ?? null };
-        },
-    };
-    approvals = {
-        /**
-         * The purchase's approval page on the Vault. It offers whichever doors the
-         * device has (voice, Face ID, Touch ID, the master password), so it is the
-         * way in for a person who forgot the passphrase, a bot with no microphone,
-         * or an agent with no screen, and it is the person-held tier of an in-app
-         * approval (`approve` from the app half opens it in the sheet). The read
-         * names the return link (this call's, else the client's `returnUrl`),
-         * the exact registered link the Vault sends the person back to once
-         * approved, and Agentcard stores it on the request, so the sheet closes on
-         * its own; the link returned is id-only, the page reads the return from
-         * Agentcard. Open it (or send it), then `awaitResult`. Null once the
-         * purchase no longer awaits a person.
-         */
-        approvalUrl: async (authorizationId, opts = {}) => {
-            this.posture();
-            const returnUrl = opts.return_url ?? this.returnUrl;
-            const a = await this.read(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}${returnUrl ? `?return_url=${encodeURIComponent(returnUrl)}` : ''}`);
-            return a.status === 'awaiting_approval' ? (a.approval_url ?? a.approvalUrl ?? null) : null;
-        },
-    };
-    /**
-     * Asks for the one-time key word. Your bot says `say[lang]` when the
-     * person wears headphones, `say_private[lang]` when the phone plays through
-     * its speaker or the route is unknown (the line then points at the screen,
-     * where your app shows `word`). With `voice: 'braxter'` the response also
-     * carries `audio_url`, Agentcard's own voice saying the line, when the
-     * deployment has it; `delivery: 'screen'` asks for the private form of that
-     * audio. Every field is typed: `challenge` and `intent` are what the app's
-     * hosted frame signs over, `verifier_url` and `answer_token` where and with
-     * what the phone streams. `lang` defaults to `en` and is checked against
-     * `languages()` first. 409 `voice_not_enrolled` when the person has no
-     * voice key for apps.
-     */
-    async challenge(authorizationId, opts = {}) {
-        this.posture();
-        const lang = opts.lang ?? 'en';
-        await this.t.languages.check(lang);
-        const ch = await this.request(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}/voice_challenge`, { method: 'POST', body: { lang, ...(opts.voice ? { voice: opts.voice } : {}), ...(opts.delivery ? { delivery: opts.delivery } : {}) } });
-        return { ...challengeOf(ch, authorizationId), lang: typeof ch.lang === 'string' && ch.lang ? ch.lang : lang };
-    }
-    /**
-     * The key word for an in-app approval, as one sealed bundle: mints the
-     * challenge and hands back the object your app forwards to
-     * `VoiceHost.approve` unread. It carries the word and both lines, Agentcard's
-     * audio when asked for, the nonce and the intent the frame signs over, and
-     * the verifier's address with the answer token the phone streams with (both
-     * absent from an API older than them). Refuses with `challenge_incomplete`
-     * when the API minted no nonce or intent, since the frame cannot sign
-     * without them.
-     */
-    async challengeForHost(authorizationId, opts = {}) {
-        const ch = await this.challenge(authorizationId, opts);
-        return bundleOf(ch);
-    }
-    appKeys = {
-        /**
-         * Registers the app voice key your app's hosted frame minted (`VoiceHost.provision` relays its description),
-         * under this client's credentials, against the person connected to your app. Hand the `credential` back to
-         * the phone and nothing else. `user_id` is the person the connect exchange returned; required. 404
-         * `connection_not_found` when the person never connected through this client; 409 `credential_exists`
-         * when the credential id already names a different key. The same key again answers with a fresh credential.
-         * `hardware` (WP199), when the phone minted a hardware key for this app voice key, is its attestation as the
-         * phone handed it over: on the key itself (`key.hardware`, where `VoiceHost` 1.9.8 puts it, so a server that
-         * forwards the key as it came needs no change) or in `opts.hardware`, which wins when both are given. It is sent
-         * on as is, and the answer's `hardware_proven` and `hardware_level` say what Agentcard made of it.
-         */
-        register: async (key, opts) => {
-            this.posture();
-            const user = opts?.user_id;
-            if (typeof user !== 'string' || !user)
-                throw new AgentcardError('not_connected', 'Name user_id: the person the connect exchange returned. Refused before any call.');
-            if (!key || typeof key.credential_id !== 'string' || typeof key.public_key !== 'string')
-                throw new AgentcardError('invalid_app_key', 'The app voice key needs credential_id and public_key, as VoiceHost describes it.');
-            await this.t.languages.check(key.lang);
-            const hardware = opts.hardware ?? key.hardware;
-            const body = { credential_id: key.credential_id, public_key: key.public_key, kind: 'app_voice_key', alg: 'ES256', proof_version: 1, ...(key.lang ? { lang: key.lang } : {}), ...(key.device_label ? { device_label: key.device_label } : {}), ...(hardware ? { hardware } : {}) };
-            const reg = await this.request(`/api/v2/vault_users/${encodeURIComponent(user)}/app_voice_keys`, { method: 'POST', body });
-            if (!reg || !reg.credential || typeof reg.credential.token !== 'string')
-                throw new AgentcardError('register_failed', 'Agentcard registered the key without a scoped credential.');
-            return reg;
-        },
-        /** Revokes one app voice key of the person `user_id` names; the person's other keys, the card and the connection stay. Idempotent. */
-        revoke: async (keyId, opts) => {
-            this.posture();
-            const user = opts?.user_id;
-            if (typeof user !== 'string' || !user)
-                throw new AgentcardError('not_connected', 'Name user_id: the person the connect exchange returned. Refused before any call.');
-            const r = await this.request(`/api/v2/vault_users/${encodeURIComponent(user)}/app_voice_keys/${encodeURIComponent(keyId)}`, { method: 'DELETE' });
-            return { id: r.id ?? keyId, revoked: r.revoked !== false, revoked_at: typeof r.revoked_at === 'string' ? r.revoked_at : null };
-        },
-    };
-    /**
-     * The streaming door from your server, the push direction: your pipeline
-     * already has the person's audio, so hand it to the verifier as it comes.
-     * `push` the bytes in `format`, `end` when the person is done (or let the
-     * verifier close the span itself), and read `hearing` and `verdict`. A
-     * finished recording is a short stream: see `streamBuffer`. The bearer is
-     * this client's token. The address is `stream_url` on the call, else the
-     * client's `voice.verifierUrl`, else the `verifier_url` the challenge
-     * itself carries. `lang` defaults to the challenge's language, else `en`.
-     */
-    async stream(challenge, opts) {
-        this.posture();
-        const authorizationId = opts.authorization_id ?? challenge.authorization_id;
-        if (!authorizationId)
-            throw new AgentcardError('missing_authorization', 'Name authorization_id, or pass the challenge voice.challenge returned.');
-        const challengeId = 'challenge_id' in challenge ? challenge.challenge_id : challenge.id;
-        const verifierUrl = this.options?.verifierUrl ?? challenge.verifier_url;
-        const base = opts.stream_url ?? (verifierUrl ? streamAddress(verifierUrl) : null);
-        if (!base)
-            throw new AgentcardError('missing_verifier_url', 'Name stream_url, or construct the client with voice.verifierUrl.');
-        const lang = opts.lang ?? challenge.lang ?? 'en';
-        await this.t.languages.check(lang);
-        const token = await withRetries(() => this.t.bearer(), this.backoff);
-        return openStream({ stream_url: base.replace(/^http/, 'ws'), authorization_id: authorizationId, challenge_id: challengeId, lang, format: opts.format, token, ...(opts.channel ? { channel: opts.channel } : {}) });
-    }
-    /**
-     * "I forgot my passphrase." Mints a voice-only link that starts the
-     * person's voice key over: the Vault forgets the device key, revokes the
-     * enrolment, and runs set-up again. Open `url` in the sheet, then
-     * `awaitConnected(session_id)`; `voice` reads `['en']` once it is done.
-     */
-    async reset(input = {}) {
-        const approval = this.posture();
-        await this.t.languages.check(input.lang);
-        const returnUrl = input.return_url ?? this.returnUrl;
-        const body = await this.request('/api/v2/vault_sessions', {
-            method: 'POST',
-            body: { mode: 'open', ...(returnUrl ? { return_url: returnUrl } : {}), steps: ['voice'], reset: true, voice: 'required', ...(input.lang ? { lang: input.lang } : {}) },
-        });
-        return { url: body.url, session_id: body.id, voice: 'required', approval, grant: 'poll', request_id: body.request_id ?? null };
-    }
-    /**
-     * Polls the purchase until it leaves `awaiting_approval`; `{ status: 'timeout' }`
-     * at the deadline. The first read's `interval` (seconds) is the least this
-     * waits between reads, and a `slow_down` answer backs off to the interval
-     * it names and keeps polling. The result carries `request_id`,
-     * `terminal_reason`, `interaction_evidence`, `intent` and the other request
-     * fields beside `status`, and on a finished purchase the `settlement`
-     * answer the finishing webhook carries. For one read with no wait,
-     * `authorizations.get(id)`.
-     */
-    async awaitResult(authorizationId, opts = {}) {
-        this.posture();
-        let intervalMs;
-        const deadline = Date.now() + (opts.timeout_ms ?? this.pollTimeoutMs);
-        return this.poll(async () => {
-            let a;
-            try {
-                // The shared read waits out slow_down up to this call's deadline; past it the refusal is the poll
-                // loop's cue to space its next read by the interval named, and the deadline reads `timeout`.
-                a = await this.read(`/v2/checkout/authorizations/${encodeURIComponent(authorizationId)}`, { deadline, onInterval: (ms) => { intervalMs = ms; } });
-            }
-            catch (err) {
-                if (err instanceof AgentcardError && err.code === 'slow_down')
-                    return undefined;
-                throw err;
-            }
-            if (typeof a.interval === 'number')
-                intervalMs = a.interval * 1000;
-            if (a.status === 'awaiting_approval')
-                return undefined;
-            return resultOf(a);
-        }, opts.timeout_ms, () => ({ status: 'timeout' }), () => intervalMs);
-    }
-    actions = {
-        /**
-         * Mints the link that carries one action. Open `url` in the sheet:
-         * Agentcard's voice reads the action back, the person confirms it with the
-         * secure passphrase and the key word, the Vault runs it and returns.
-         * Throws `action_unavailable` for a kind the Vault cannot carry out yet.
-         */
-        propose: async (action, input = {}) => {
-            this.posture();
-            await this.t.languages.check(input.lang);
-            const returnUrl = input.return_url ?? this.returnUrl;
-            const body = await this.request('/api/v2/vault_sessions', {
-                method: 'POST',
-                body: { mode: 'open', ...(returnUrl ? { return_url: returnUrl } : {}), steps: ['action'], action, ...(input.lang ? { lang: input.lang } : {}) },
-            });
-            return { url: body.url, session_id: body.id, action_hash: body.action_hash ?? null };
-        },
-        /**
-         * One read of an action's link, with no wait: whether the action is done and confirmed, whether a rule
-         * covers the card now, the link's status, and the last step and reason its page recorded.
-         */
-        get: async (sessionId) => {
-            this.posture();
-            const s = await this.read(`/api/v2/vault_sessions/${encodeURIComponent(sessionId)}`);
-            const status = s.status === 'linked' ? 'linked' : s.status === 'expired' ? 'expired' : 'pending';
-            return { session_id: typeof s.id === 'string' ? s.id : sessionId, status, done: s.action?.done === true, confirmed: s.action?.confirmed === true, rule: s.rule === true, kind: s.action?.kind ?? null, last_step: stepOf(s.last_step), reason: reasonOf(s.reason) };
-        },
-        /**
-         * Polls the action's session until it reads done, or the deadline; the last state comes back either
-         * way, with the last step the Vault's page reached and the last reason it recorded, so a bot that
-         * gets `done: false` can say why ("your voice didn't confirm it", "that browser holds no voice key").
-         * For one read with no wait, `actions.get(session_id)`.
-         */
-        awaitDone: async (sessionId, opts = {}) => {
-            this.posture();
-            const deadline = Date.now() + (opts.timeout_ms ?? this.pollTimeoutMs);
-            let last = { done: false, confirmed: false, rule: false, last_step: null, reason: null };
-            return this.poll(async () => {
-                const s = await this.read(`/api/v2/vault_sessions/${encodeURIComponent(sessionId)}`, { deadline });
-                last = { done: s.action?.done === true, confirmed: s.action?.confirmed === true, rule: s.rule === true, last_step: stepOf(s.last_step), reason: reasonOf(s.reason) };
-                if (last.done)
-                    return last;
-                if (s.status === 'expired')
-                    throw new AgentcardError('vault_session_expired', 'The Vault link is no longer usable.');
-                return undefined;
-            }, opts.timeout_ms, () => last);
-        },
-    };
-}