@agent-cards/sdk 0.23.28 → 0.24.1

package/dist/voice-types.d.ts

@@ -1,735 +0,0 @@
-/**
- * Wire shapes of the voice and vault modules. Spellings are the API's
- * (snake_case), so a response can be handed through untouched.
- * `@agent-cards/voice` keeps a structurally identical copy for the phone;
- * `PausedRequest` is the checkout client's own.
- */
-import type { PausedRequest } from './client.js';
-import type { Substitutions } from './substitute.js';
-import type { Language } from './languages.js';
-export type { Language } from './languages.js';
-/** @deprecated A language is a BCP 47 tag (`Language`); this name stays for one release. */
-export type Lang = Language;
-/**
- * How the Vault treats voice set-up on a connect link: `required` makes it a
- * step the person cannot skip; `offered` shows it and lets them pass. An app
- * that approves purchases by voice asks for `required`.
- */
-export type VoiceAsk = 'required' | 'offered';
-/**
- * How purchases are approved inside your product, chosen once per customer.
- * `sheet`: the person approves on Agentcard's own page,
- * opened in the in-app browser for one moment, with a credential Agentcard
- * verifies (the voice key or the passkey); a browser your app cannot script or
- * read. `in_app`: hold-to-talk in your app, judged on the phone and by
- * Agentcard, signed by a key in your app (`VoiceHost` in
- * `@agent-cards/voice`). Named in the server constructor; no default.
- */
-export type ApprovalPosture = 'sheet' | 'in_app';
-/**
- * One structured action the app's bot drafted from what the person said.
- * Agentcard takes the numbers, never the words: its voice reads the action
- * back in full, the person confirms it with the secure passphrase and the
- * one-time key word, and the endpoint that already exists for it runs.
- * `amount` is an integer in the currency's smallest unit (2000 for $20).
- */
-export type Action = {
-    kind: 'rule.on';
-    amount: number;
-    days: number;
-} | {
-    kind: 'rule.off';
-} | {
-    kind: 'rule.change';
-    amount: number;
-    days: number;
-};
-/**
- * What a business asks to be allowed on a connect link, in the shape of OAuth's
- * `authorization_details` (RFC 9396): the card, the voice, the rule. Stored at
- * mint and enforced from then on: `agentcard_card` for the exchange's
- * connection credential, purchases and the card read; `rule` for action links;
- * each term also decides whether `card`, `voice` and `rule` are read back (a
- * term not asked for reads null at the API, `false` / `[]` here). The SDK asks
- * for all three unless you name fewer.
- */
-export type AuthorizationDetail = {
-    type: 'agentcard_card' | 'voice' | 'rule';
-    [key: string]: unknown;
-};
-export interface ConnectInput {
-    /** `required` for an app that approves by voice; `offered` otherwise. */
-    voice?: VoiceAsk;
-    /**
-     * The link is an OAuth authorization grant by default: the
-     * client mints `state` and a PKCE challenge, the return link carries
-     * `code` and `state`, and the result is collected once with `exchange` (or
-     * `completeConnect`). `pkce: false` mints the older polling shape, read with
-     * `awaitConnected`; deprecated, kept for one release. A call with no return
-     * link (a messaging bot) polls whatever this says: there is no link to carry
-     * the code.
-     */
-    pkce?: boolean;
-    /**
-     * The terms this link asks to be allowed (`[{ type: 'agentcard_card' }, { type: 'voice' }]`), enforced
-     * from then on (see `AuthorizationDetail`). On a grant, absent means all three, sent explicitly.
-     */
-    authorization_details?: AuthorizationDetail[];
-    /** Where the Vault sends the person back: an app link (`yourapp://connected`) or https. Must be exactly one of your registered redirect links; a prefix or a bare scheme is not registered. */
-    return_url?: string;
-    /** Your own id for the person; comes back on the linked session. */
-    external_user_id?: string;
-    /** Pre-fill the person's email on the sign-in step. */
-    email?: string;
-    /** The language your app speaks, a BCP 47 tag Agentcard lists (`voice.languages()`). The Vault opens in it and the voice key it sets up is the one for that language. */
-    lang?: Language;
-    /**
-     * Where the signed-in person lands instead of the connect steps. `voice_options`: the Vault's Voice
-     * options page (the voice key, its reset, the language, the passkey it rests on, the devices), for an
-     * app's own settings row. Nothing is collected: the link polls (`grant: 'poll'`), and the person closes
-     * the sheet when done; read `vault.people.get` afterwards for what changed.
-     */
-    landing?: 'voice_options';
-}
-export interface ConnectResult {
-    /** Open this in the in-app browser sheet. */
-    url: string;
-    /** The session: `completeConnect` and `exchange` name it; with `grant: 'poll'`, `awaitConnected` polls it. */
-    session_id: string;
-    voice?: VoiceAsk;
-    /** The customer's approval posture, as the server was constructed; the app half learns where the passphrase is spoken from here. Absent on a client built without `voice`. */
-    approval?: ApprovalPosture;
-    /**
-     * How the result is collected. `exchange`: the return link carries `code`
-     * and `state`; hand it to `completeConnect`, or its parts to `exchange`,
-     * once, within 60 seconds. `poll`: read it with `awaitConnected`.
-     */
-    grant: 'exchange' | 'poll';
-    /** The request handle Agentcard answers this link under (`areq_…`); on the webhooks too. */
-    request_id: string | null;
-    /** The opaque value the client minted; the return link carries it back and `exchange` checks it. */
-    state?: string;
-    /**
-     * The PKCE verifier behind the challenge this link was minted with. The
-     * client keeps it for `exchange`; it is here only so a server with several
-     * instances can persist it and pass it back as `code_verifier` from the
-     * instance the return link reaches. Never send it to the app.
-     */
-    code_verifier?: string;
-    /** As asked at mint; echoed at exchange. */
-    authorization_details?: AuthorizationDetail[] | null;
-}
-/**
- * The linked session: who connected and what the app may use. Each of `card`,
- * `voice` and `rule` is read only where the grant asked for its term
- * (`authorization_details`); a term not asked for reads `false` / `[]` here.
- */
-export interface Connected {
-    user_id: string;
-    /** A card is stored and this app may charge it. */
-    card: boolean;
-    /** Languages with a voice key (`['en']`); empty when none. */
-    voice: string[];
-    /** An auto-approval rule covers the card: purchases under it need no passphrase. */
-    rule: boolean;
-    /** A live Vault passkey on the account: what a voice reset needs. Read with the `voice` term. */
-    passkey: boolean;
-    /** Your own id for the person, as `connect` named it; null when it named none. */
-    external_user_id?: string | null;
-    /**
-     * The link's diary: the last step the Vault's page reached (`opened`, `signed_in`, `voice_refused`,
-     * `stopped`, `left`, `reset_done`, …) and the last reason it recorded (`rejected`, `no_voice_key`,
-     * `skipped`, …), so a link that came back with `voice: []` says why. Null when the page reported none;
-     * absent from an API older than the diary.
-     */
-    last_step?: VaultSessionStep | null;
-    reason?: string | null;
-}
-/** What `exchange` (or `completeConnect`) returns: the connected person, plus the grant's own fields. */
-export interface Exchanged extends Connected {
-    session_id: string;
-    request_id: string | null;
-    /** The `state` as minted, echoed by Agentcard. */
-    state: string | null;
-    authorization_details: AuthorizationDetail[] | null;
-    /** The action the link carried, when it carried one (see `actions.propose`). */
-    action: {
-        kind: Action['kind'];
-        confirmed: boolean;
-        done: boolean;
-    } | null;
-    linked_at: string | null;
-    /**
-     * What the return link said about a voice reset, when it carried `voice_reset` (the Vault appends
-     * `voice_reset=done|unchanged|failed` when the visit reset the person's voice key): `done`, the key was
-     * cleared and set up again; `unchanged`, nothing was reset; `failed`, the reset did not go through. Only
-     * `completeConnect` fills it, from the link; `exchange` with the parts in hand leaves it null.
-     */
-    voice_reset?: VoiceResetOutcome | null;
-    /**
-     * The grant's connection credential, when the grant asked for
-     * `agentcard_card` and the ceremony verified the person's own contact; null
-     * otherwise. Access-only: `refresh_token` is always null, it lives
-     * `expires_in` seconds (an hour), and `scope` names the terms it is good for
-     * (`vault_grant agentcard_card voice`). `disconnect` revokes it. Most
-     * products need nothing from it: the client-credentials token already serves
-     * every call in this module.
-     */
-    connection: {
-        access_token: string;
-        refresh_token: null;
-        token_type: 'Bearer';
-        expires_in: number;
-        scope: string;
-    } | null;
-}
-export interface ExchangeInput {
-    /** From the return link. */
-    code: string;
-    /** From the return link; must equal the `state` the client minted for this session (or `expected_state`). */
-    state?: string;
-    /** The session `connect` returned; finds the verifier and the state the client holds. */
-    session_id?: string;
-    /** Only when another instance minted the link: the `code_verifier` that `connect` returned there. */
-    code_verifier?: string;
-    /**
-     * Only when another instance minted the link: the `state` that `connect`
-     * returned there, persisted beside the verifier. Compared with the link's
-     * `state` here, before any call; without it a cross-instance exchange is
-     * refused (`state_mismatch`).
-     */
-    expected_state?: string;
-}
-/** `disconnect`: the connection this session made is revoked. */
-export interface Revoked {
-    session_id: string;
-    revoked: boolean;
-    revoked_at: string;
-    /** Whether a token minted by the exchange was revoked with it. */
-    token_revoked: boolean;
-}
-/**
- * A returning person, read before any link is minted: what they already have
- * with this business. Store `user_id` after the first `awaitConnected`; on a
- * later launch ask here, and open the Vault only for what is missing.
- */
-export interface Person {
-    user_id: string;
-    /** A card is stored and this app may charge it. */
-    card: boolean;
-    /** Languages with a voice key this app may use (`['en']`); empty when none. */
-    voice: string[];
-    /** An auto-approval rule covers the card: purchases under it need no passphrase. */
-    rule: boolean;
-    /**
-     * A live Vault passkey on the account. A voice reset (`voice.reset`) needs one: with
-     * `passkey: false` the Vault's reset page asks the person to add one first, so a bot can say so before
-     * it opens the link. Read with the `voice` term.
-     */
-    passkey: boolean;
-    /**
-     * One of your own team: the person's Agentcard account email is a member's or an admin's of your organization.
-     * The email itself is never returned.
-     */
-    team_member: boolean;
-}
-/** A proposed action: the Vault link, the session to await, and the hash the read-back is bound to. */
-export interface Proposed {
-    url: string;
-    session_id: string;
-    /** sha256 of the action's canonical form: what Agentcard's voice reads back and what the key word challenge is bound to. */
-    action_hash: string | null;
-}
-/** Where an action stands once the sheet closes. */
-export interface Done {
-    /** The world agrees with the action (a rule is on for rule.on, none for rule.off). */
-    done: boolean;
-    /** The person's voice confirmed the action; the endpoint may still be running. */
-    confirmed: boolean;
-    /** A rule covers the card now. */
-    rule: boolean;
-    /**
-     * The last step the Vault's page reached on the link: `opened`, `signed_in`, `challenge_minted`,
-     * `voice_refused`, `confirmed`, `stopped`, `left`; null when the page never reported one (the link
-     * was not opened). With `done: false`, where the handover ended.
-     */
-    last_step: VaultSessionStep | null;
-    /**
-     * The last reason the page recorded, a plain code: the judge's refusal (`rejected`, `need_more`,
-     * `resting`, `cancelled`, `stale_challenge`, `verification_failed`), or why the page could go no
-     * further (`no_voice_key`, `no_card`, `unavailable`, `already`, `none`, `no_rule`). Null when none.
-     */
-    reason: string | null;
-}
-/** One read of an action's link (`voice.actions.get`): where it stands, with no wait. */
-export interface ActionState extends Done {
-    session_id: string;
-    status: 'pending' | 'linked' | 'expired';
-    /** The action the link carries, when the read says. */
-    kind: Action['kind'] | string | null;
-}
-/** The steps a Vault link's page reports (`Done.last_step`). */
-export type VaultSessionStep = 'opened' | 'signed_in' | 'challenge_minted' | 'voice_refused' | 'confirmed' | 'stopped' | 'left' | 'reset_done';
-/** What a return link says about a voice reset made on the visit (`voice_reset=` on the link). */
-export type VoiceResetOutcome = 'done' | 'unchanged' | 'failed';
-/**
- * A return link, read: the grant's `code` and `state` (null on a link minted to poll: a reset, an action) and the
- * `voice_reset` outcome when the visit reset the person's voice key. `readReturnLink(url)` fills it, from the
- * query alone; the scheme may be an app's own (`yourapp://connected?code=…`).
- */
-export interface ReturnLink {
-    code: string | null;
-    state: string | null;
-    voice_reset: VoiceResetOutcome | null;
-}
-/**
- * A Vault session as the business reads it (`voice.sessions.get`), without exchanging anything: where the
- * link stands, how its result is collected, and the diary. On a linked grant the connected result (`user_id`,
- * `card`, `voice`, `rule`, `passkey`, `action`) is withheld until `completeConnect`/`exchange` and reads null
- * here with `exchange_required: true`; on a polling mint it reads as `awaitConnected` would give it.
- */
-export interface SessionState {
-    session_id: string;
-    request_id: string | null;
-    status: 'pending' | 'linked' | 'expired';
-    /** `exchange`: the return link carries the code; `poll`: this read is the result. */
-    grant: 'exchange' | 'poll';
-    /** True on a linked grant this read did not disclose; hand the return link to `completeConnect`. */
-    exchange_required: boolean;
-    /** The diary: the last step the page reached and the last reason it recorded; null when none. */
-    last_step: VaultSessionStep | null;
-    reason: string | null;
-    /** Your own id for the person, as the mint named it; null when it named none. */
-    external_user_id: string | null;
-    user_id: string | null;
-    card: boolean | null;
-    voice: string[] | null;
-    rule: boolean | null;
-    passkey: boolean | null;
-    action: {
-        kind: Action['kind'];
-        confirmed: boolean;
-        done: boolean;
-    } | null;
-    linked_at: string | null;
-    expires_at: string | null;
-}
-export interface CreateAuthorizationInput {
-    /** The person who approves: the `user_id` the connect exchange returned. Required, so a server serving many people never charges the wrong one. */
-    user_id: string;
-    merchant: string;
-    /** An integer in the currency's smallest unit (599 for $5.99), the one word the checkout client's `authorizations.create` uses too. */
-    amount: number;
-    /** Lowercase ISO code, `usd`. */
-    currency: string;
-    /**
-     * The processor's card request the purchase pauses on: one a browser purchase paused on, one
-     * `checkout.requests.build` made, or `'sandbox'`, the first-run form that names no processor and that
-     * only a sandbox client may send (`sandbox_request_in_live` otherwise).
-     */
-    request: PausedRequest | 'sandbox';
-    /** The processor the request belongs to, as the recognisers name it (`stripe`, `braintree`, `mercado_pago`, …). Default `stripe`. */
-    psp?: string;
-    /** How the card reaches the processor. Absent means `token`; `cse` and `hosted_form` are checked against the recogniser by the API. */
-    mode?: 'token' | 'cse' | 'hosted_form';
-    /** Your own key for this create; the same key creates once. The SDK sends a fresh one when you name none. */
-    idempotency_key?: string;
-    /** The link the approval page sends the person back to, sent with the create and stored on the request; defaults to the client's `returnUrl`. Exactly one of your registered links. */
-    return_url?: string;
-    /**
-     * The exact https origin your app or checkout page pays from (`https://yourapp.example`): what an
-     * auto-approval rule the person confirmed needs to take the purchase. Agentcard stores no `origin` header
-     * from the paused request, so without this a rule never applies and the create answers
-     * `execution_reason: 'unverified_origin'`. Absent, the SDK sends the paused request's `origin` header when
-     * it is such an origin (`stripePaymentIntentConfirm(origin, …)` sets one).
-     */
-    checkout_origin?: string;
-    /**
-     * Pins the card that pays: one of the person's stored cards (`voice.authorizations.get(id).cards`, or the
-     * card list). Absent, the person's recommended card pays under their smart routing, else their only card,
-     * and `card` on the answer says which (decision 213).
-     */
-    card_id?: string;
-}
-export type AuthorizationStatus = 'awaiting_approval' | 'approved' | 'declined' | 'expired' | 'cancelled' | 'completed' | 'timeout';
-/**
- * The business's own words for withdrawing a purchase it watches, while the person is still deciding: the person
- * closed the sheet, the person changed their mind, or a reason of the business's own. `voice.authorizations.cancel`
- * stamps one; it is the request's `terminal_reason` from then on.
- */
-export type CancelReason = 'person_closed_sheet' | 'person_changed_mind' | 'business_cancelled';
-/**
- * How the approval request ended, as CIBA names it. Null while it awaits the person. `cancelled` is the runtime's
- * withdrawal or a processor refusal; the three `CancelReason` words are the business's own withdrawal. A purchase
- * withdrawn before a decision reads `status: 'cancelled'` (since 2026-09-25); its terminal reason says who withdrew it.
- */
-export type TerminalReason = 'approved' | 'declined_by_person' | 'expired' | 'refused_by_rule' | 'approval_changed' | 'cancelled' | CancelReason;
-/** What `voice.authorizations.cancel` answers: the purchase is withdrawn, and how the request reads from now on. */
-export interface Cancelled {
-    id: string;
-    status: 'cancelled';
-    /** The reason as stamped; `terminal_reason` is the same word on every later read and on the `checkout_authorization.cancelled` webhook. */
-    reason: CancelReason;
-    terminal_reason: TerminalReason;
-    request_id: string | null;
-}
-/** Where the approval reached the person: the approval link, the app's sheet, the app-held approval, or (reserved) a push. */
-export type DeliveryChannel = 'app_sheet' | 'in_app' | 'link' | 'push';
-/** One piece of what approved the request: its kind, when, and an internal id. Never the material itself. */
-export interface InteractionEvidence {
-    type: 'voice_proof' | 'passkey_assertion' | 'rescoring' | 'rule' | 'platform_interaction';
-    at: string;
-    ref: string;
-}
-/** The portable rendering of what the person approves; the field names are Agentcard's, versioned beside it. */
-export interface Intent {
-    who: string;
-    what: string;
-    how_much: {
-        amount: number | null;
-        currency: string | null;
-    };
-    for_whom: string | null;
-    until: string;
-    request_hash: string;
-    nonce: string;
-    version: string;
-}
-/** The approval request's fields, on the create and on every read. */
-export interface ApprovalRequestFields {
-    /** The request handle (`areq_…`); the webhooks carry it too. */
-    request_id?: string | null;
-    /** Your own id for the person, as the connect named it; on every event for them too. */
-    external_user_id?: string | null;
-    /** Seconds between two reads; `awaitResult` polls no faster. */
-    interval?: number;
-    /** The same interval in milliseconds, exactly as the request was configured. */
-    poll_interval_ms?: number;
-    /** The canonical hash the voice proof binds: the authorization's id, merchant, amount and currency with the intent's request hash, nonce and version. */
-    intent_hash?: string | null;
-    expires_at?: string;
-    delivery_channel?: DeliveryChannel | null;
-    /** How the request ended; null while it awaits the person. */
-    terminal_reason?: TerminalReason | null;
-    /** What approved it, typed and capped at eight entries. */
-    interaction_evidence?: InteractionEvidence[];
-    /** The portable rendering of what the person approves; null on rows written before it existed. */
-    intent?: Intent | null;
-    intent_version?: string | null;
-}
-export interface Authorization extends ApprovalRequestFields {
-    id: string;
-    status: AuthorizationStatus;
-    /** `user_approval`: the person approves, by voice here. `autopilot`: the person's rule took it, no approval step. */
-    execution_mode?: 'user_approval' | 'autopilot' | string;
-    /**
-     * Why no rule took the purchase when the business could mend it: `unverified_origin`, the create named no
-     * `checkout_origin`. `execution_detail` says so in a sentence. Absent otherwise.
-     */
-    execution_reason?: 'unverified_origin' | string;
-    execution_detail?: string;
-    /**
-     * The purchase's own approval page on the Vault, while it awaits a person.
-     * It offers whichever doors the device has: voice, Face ID, Touch ID, the
-     * master password. Open it in the sheet (`approve` from the app half), or
-     * send it to a person with no microphone or no screen in front of your bot.
-     * The link is id-only; where the page sends the person afterwards is the
-     * `return_url` stored on the request (`return_url` on the create, or the
-     * client's `returnUrl`), which the page reads from Agentcard, never from
-     * the link.
-     */
-    approval_url?: string;
-    /** The registered link the approval page ends on, as stored on the request. */
-    return_url?: string;
-    /**
-     * The card that pays (decision 213): the one your create pinned, else the person's recommended card under
-     * their smart routing, else their only card; null when several could pay and none is chosen yet. Absent from
-     * an API older than the field.
-     */
-    card?: PayingCard | null;
-    /** Every card the person may pay with instead, while the purchase awaits a decision; `authorizations.setCard` picks one. */
-    cards?: ChoosableCard[];
-}
-/** A voice-only link: the Vault runs voice set-up alone; with `reset`, it forgets the device key and revokes the enrolment first. */
-export interface VoiceResetInput {
-    return_url?: string;
-    /** The language your app speaks; the Vault opens in it (see `ConnectInput.lang`). */
-    lang?: Language;
-}
-/**
- * The card a purchase pays with, as every read and every key word challenge names it (decision 213). Under the
- * person's smart routing the recommended card pays when your app pinned none, and `reason` is the
- * recommendation's sentence for it ("American Express Gold: 4x on food delivery, about $2.20 in points on
- * this order."); `reason` is null when your app pinned the card or the person chose another. Null when the
- * person has several cards and none is chosen yet.
- */
-export interface PayingCard {
-    id: string;
-    /** How the card is named on screen and out loud: its product, else its label, else "Visa ····4242". */
-    name: string;
-    last4: string | null;
-    brand: string | null;
-    reason: string | null;
-}
-/**
- * One of the cards the person may pay with instead, for "another card": the recommendation's reason where it
- * scored the card, whether it is the recommended one, and whether an auto-approval rule on it pays without
- * asking. `voice.authorizations.setCard(id, card.id)` makes it the paying card.
- */
-export interface ChoosableCard extends PayingCard {
-    recommended: boolean;
-    auto_approve?: boolean;
-}
-/**
- * The key word challenge as `voice.challenge` returns it, every field typed. `word`, `say` and `say_private`
- * are what the bot says and shows; `challenge` and `intent` are what the app's hosted frame signs its proof
- * over; `verifier_url` and `answer_token` are where and with what the phone streams the answer. The four host
- * fields are typed as the API returns them and read as optional until the API release that mints them;
- * `challengeForHost` refuses a challenge that lacks the nonce or the intent.
- */
-export interface VoiceChallenge {
-    id: string;
-    /** The purchase this key word belongs to; set by `voice.challenge`, so the challenge alone can open a stream. */
-    authorization_id?: string;
-    /** The one-time key word the person says after their secure passphrase. */
-    word: string;
-    /** The language the challenge was minted in, as asked. */
-    lang?: Language;
-    /** The sentence your bot says, by language tag, with the key word in it: for a person wearing headphones. */
-    say: Record<Language, string>;
-    /**
-     * The same sentence without the word, pointing at the screen: for a phone playing through its speaker, or
-     * a route the app cannot read. Show the word on the screen in every case; the route decides only which of
-     * the two lines is spoken. Absent from an API older than this field.
-     */
-    say_private?: Record<Language, string>;
-    /**
-     * The card that pays, with the recommendation's reason when it picked it (decision 213). Both lines name it
-     * before the key word: hearing the card and the reason, then speaking the passphrase, is the confirmation.
-     * Null when no card is known yet; absent from an API older than the field.
-     */
-    card?: PayingCard | null;
-    /** Agentcard's own voice saying the line, when your organisation turned that on; `audio_delivery` says which form the link carries. */
-    audio_url?: string;
-    audio_delivery?: 'spoken' | 'screen';
-    /**
-     * The nonce the app's hosted frame signs its proof over. Present on every challenge the API mints;
-     * `VoiceHost.approve` needs it.
-     */
-    challenge?: string;
-    /** The payment's canonical hash and its kind, signed with the nonce. */
-    intent?: {
-        kind: string;
-        hash: string;
-    };
-    /**
-     * The verifier's address for this answer: the phone streams there itself, and a business hosts no door.
-     * Absent from an API older than the field; the app half then needs the deprecated `stream_url`.
-     */
-    verifier_url?: string;
-    /**
-     * A short-lived credential scoped to this one challenge, for the verifier's stream. The app hands it on the
-     * first frame and never carries your bearer. Absent from an API older than the field.
-     */
-    answer_token?: string;
-    /**
-     * The verifier's sealing key, P-256 SPKI as base64url (WP115): the hosted frame seals the take's audio to it and the
-     * app relays ciphertext it cannot read. Absent from an API older than the field, or when the API could not read the
-     * verifier; the frame then refuses the take and the app takes the approval page.
-     */
-    verifier_public_key?: string;
-    /**
-     * The authorization's price in the currency's smallest unit (3999 for $39.99) and its ISO code, lower case, for
-     * the app's screen. Nobody says it: the approval is the passphrase and the key word (2026-10-01, reversing
-     * decision 245). Absent from an API older than the fields, or on a template that carries no amount.
-     */
-    amount_minor?: number;
-    currency?: string;
-    expires_at: string;
-}
-/**
- * What the business forwards to the app, unread, for `VoiceHost.approve`: one sealed object from
- * `voice.challengeForHost`, so a business cannot assemble it wrong. The frame signs over `challenge` and
- * `intent`; the phone streams to `verifier_url` with `answer_token` when the API minted them.
- */
-export interface HostApprovalBundle {
-    /** The challenge's own id (`vch_…`): named on the stream's first frame and on the frame's verdict. */
-    challenge_id: string;
-    authorization_id: string;
-    word: string;
-    /** The language the challenge was minted in. */
-    lang?: Language;
-    say: Record<Language, string>;
-    say_private?: Record<Language, string>;
-    /** The card that pays and why, as the lines say it (decision 213); the app shows it beside the word. */
-    card?: PayingCard | null;
-    audio_url?: string;
-    audio_delivery?: 'spoken' | 'screen';
-    /** The nonce the hosted frame signs over. */
-    challenge: string;
-    intent: {
-        kind: string;
-        hash: string;
-    };
-    /** Where the phone streams; absent until the API release that mints it. */
-    verifier_url?: string;
-    /** The credential for that stream; absent until the API release that mints it. */
-    answer_token?: string;
-    /** The verifier's sealing key the frame seals the audio to (WP115); absent until the API release that carries it. */
-    verifier_public_key?: string;
-    /** The authorization's price for the app's screen, smallest unit and ISO code; nobody says it (2026-10-01, reversing decision 245); absent until the API release that carries them. */
-    amount_minor?: number;
-    currency?: string;
-    expires_at: string;
-}
-/** What the frame says its app voice key is, relayed by `VoiceHost` for `voice.appKeys.register`. */
-export interface AppVoiceKeyDescription {
-    credential_id: string;
-    /** The signing half, P-256 SPKI as base64url. The agreement half the app copy is sealed for is never registered here (WP115): the person's vault proves it during the set-up inside the app. */
-    public_key: string;
-    kind: 'app_voice_key';
-    alg: 'ES256';
-    proof_version: 1;
-    lang?: Language;
-    device_label?: string;
-    /**
-     * The phone's hardware key, attested for this app voice key (WP199): `VoiceHost` 1.9.8 puts it on the description it
-     * hands your `register` when the phone attested one, and `voice.appKeys.register` sends it on as `hardware`. Absent
-     * from a phone that registered a software key.
-     */
-    hardware?: HardwareAttestation;
-}
-/**
- * The hardware key the phone binds to its app voice key at registration (WP199): the key's id, the platform's
- * attestation of it (Android's certificate chain as base64url DER, one string a certificate, or iOS App Attest's
- * attestation object as one base64url string), the challenge the attestation answers (`SHA-256(credential_id + "." +
- * public_key)`, as the phone computed it; Agentcard recomputes and compares), and on iOS the App ID the build runs
- * under (`<team id>.<bundle id>`), which Agentcard checks the attestation's `rpIdHash` against. Opaque to the SDK: it
- * is sent as `hardware` on the registration and Agentcard checks it.
- */
-export interface HardwareAttestation {
-    platform: 'android' | 'ios';
-    key_id: string;
-    attestation: string[] | string;
-    challenge: string;
-    app_id?: string;
-}
-/** The registered app voice key, with the phone's scoped credential (one hour; register again for a fresh one). */
-export interface RegisteredAppVoiceKey {
-    id: string;
-    credential_id: string;
-    kind: 'app_voice_key';
-    alg: 'ES256';
-    proof_version: 1;
-    lang?: string;
-    device_label?: string;
-    created_at: string;
-    revoked: boolean;
-    /** The phone's bearer for its two calls (the sealed copy and the proof). Hand it to `VoiceHost`'s `register`; nothing else goes to the phone. */
-    credential: {
-        token: string;
-        token_type: 'Bearer';
-        expires_in: number;
-    };
-    /** Whether Agentcard verified a hardware key bound to this app voice key (WP199); absent from an API from before it. */
-    hardware_proven?: boolean;
-    /** Where the proven hardware key lives: Android StrongBox or TEE, or Apple's Secure Enclave. */
-    hardware_level?: 'strongbox' | 'tee' | 'secure_enclave';
-    /** Which hardware key is proven, by its id, so the phone compares it with the key it holds (WP199). Present only when proven. */
-    hardware_key_id?: string;
-}
-/** `voice.appKeys.revoke`: the key is revoked and nothing else is. */
-export interface RevokedAppVoiceKey {
-    id: string;
-    revoked: boolean;
-    revoked_at: string | null;
-}
-/**
- * Whether the charge settled, read back from the processor by Agentcard itself after the purchase finished: the
- * same object the `checkout_authorization.approved` webhook carries at finish and the `settled` /
- * `settlement_unconfirmed` webhook carries once the read lands. `status` is `settled` (the processor holds a
- * succeeded payment), `not_settled` (no charge was made: `reason` says why), or `unknown` (`reason` names what
- * was seen last, `check_pending` while Agentcard is still reading). `final: false` means one of the two
- * settlement webhooks follows; `true` means Agentcard will not check again. `settled_amount` and
- * `settled_currency` are what the processor reports collected, in the currency's smallest unit; `message` is
- * the answer in one sentence.
- */
-export interface Settlement {
-    status: 'settled' | 'not_settled' | 'unknown';
-    reason: string;
-    final: boolean;
-    processor_reference: string | null;
-    processor_status: string | null;
-    processor_error_code: string | null;
-    settled_amount: number | null;
-    settled_currency: string | null;
-    checked_at: string | null;
-    resolved_at: string | null;
-    message: string;
-}
-export interface AuthorizationResult extends ApprovalRequestFields {
-    /** The purchase's id (`cauth_…`), as read; absent only on `timeout`, which is the SDK's own answer. */
-    id?: string;
-    /**
-     * `approved`, `declined` (the person said no: `terminal_reason: 'declined_by_person'`, or a rule or the
-     * processor refused), `cancelled` (withdrawn before a decision: the business's `voice.authorizations.cancel`
-     * with its `CancelReason` as `terminal_reason`, or the runtime's `cancelled`), `expired`, or `timeout` at the
-     * deadline. `cancelled` is the API's own status for a withdrawn purchase (since 2026-09-25); the SDK reads it as
-     * the API says it.
-     */
-    status: AuthorizationStatus;
-    /** The purchase's approval page while it awaits a person (see `Authorization.approval_url`); absent otherwise. */
-    approval_url?: string;
-    /**
-     * Whether the charge settled, on a finished purchase: present on `approved` (and on an `expired` purchase a
-     * device may have paid), `null` when there is nothing to read back (the request tokenized a card the merchant
-     * charges itself), absent while the purchase is open or on `timeout`. `final: false` means the
-     * `checkout_authorization.settled` or `settlement_unconfirmed` webhook follows; read the purchase again later
-     * for the answer without waiting on it.
-     */
-    settlement?: Settlement | null;
-    /** `voice` after a challenge; `passkey` or `bearer` otherwise; empty when a rule took the purchase. */
-    approved_with?: 'voice' | 'passkey' | 'bearer' | string;
-    execution_mode?: 'user_approval' | 'autopilot' | string;
-    /** Why no rule took it, when the business can mend that (`unverified_origin`); see `Authorization`. */
-    execution_reason?: 'unverified_origin' | string;
-    execution_detail?: string;
-    /**
-     * How the card reached the processor (`token`, `cse`, `hosted_form`), and the processor's answer on an
-     * approved `token` purchase: what `controller.resume(result)` replays into a browser purchase that
-     * `attachToCdp(…, { pauseOnly: true })` paused. `substitutions` is the ciphertext of a `cse`
-     * purchase, `submitted_at` the device's stamp on a `hosted_form` one. Absent while the purchase is open.
-     */
-    mode?: 'token' | 'cse' | 'hosted_form' | string;
-    response?: {
-        status: number;
-        headers: Record<string, string>;
-        body: string;
-    };
-    substitutions?: Substitutions;
-    submitted_at?: string;
-    /** The card that pays, or paid (decision 213); see `Authorization.card`. */
-    card?: PayingCard | null;
-    /** Every card the person may pay with instead, while the purchase awaits a decision; absent once it is decided. */
-    cards?: ChoosableCard[];
-}
-/** The verifier's answer to one recording. */
-export interface Verdict {
-    /** The passphrase, the key word and the voice all held: the purchase is approved. */
-    accepted: boolean;
-    /** The challenge is used up; ask for a fresh key word before the next try. False when nothing was heard. */
-    spent: boolean;
-    approved_with: string | null;
-}
-export declare class AgentcardError extends Error {
-    /** The API's error code (`invalid_return_url`, `action_unavailable`, `voice_not_enrolled`, `slow_down`, `invalid_grant`), or the client's own (`unreachable`, `connect_timeout`, `oauth_failed`, `state_mismatch`). */
-    readonly code: string;
-    readonly status?: number | undefined;
-    /** The rest of the API's error envelope: `slow_down` carries `interval`, `grant_requires_exchange` carries `request_id`. */
-    readonly details: Record<string, unknown>;
-    constructor(
-    /** The API's error code (`invalid_return_url`, `action_unavailable`, `voice_not_enrolled`, `slow_down`, `invalid_grant`), or the client's own (`unreachable`, `connect_timeout`, `oauth_failed`, `state_mismatch`). */
-    code: string, message: string, status?: number | undefined, 
-    /** The rest of the API's error envelope: `slow_down` carries `interval`, `grant_requires_exchange` carries `request_id`. */
-    details?: Record<string, unknown>);
-}