@agent-cards/sdk 0.20.0

package/dist/client.d.ts

@@ -0,0 +1,929 @@
+import { type CheckoutMode, type Recognizer } from './registry.js';
+import type { Substitutions } from './substitute.js';
+import { type MerchantHostedSubstitutions, type MerchantProfile, type SandboxMerchantDeclaration } from './merchant-hosted.js';
+import { type MerchantTotalApproved, type MerchantTotalCapture } from './merchant-total.js';
+import { type PreparationMode, type PreparationProcessor } from './prepared-processor.js';
+import { VoiceModule, type VoiceOptions } from './voice.js';
+import { BuyModule } from './buy.js';
+import { RequestRegistry } from './requests.js';
+import type { ApiTransport } from './api-module.js';
+export interface PausedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    /** Captured native Checkout Pro initialization, validated before use. */
+    mercado_checkout?: unknown;
+}
+/**
+ * The modes this SDK can finish. Asked for on syncRegistry (the API serves
+ * only recognizers in these modes, so a request this build cannot complete
+ * is never paused) and sent on every create.
+ */
+export declare const SUPPORTED_MODES: readonly CheckoutMode[];
+/**
+ * Registry features this SDK honours, asked for on syncRegistry next to the
+ * modes. `card_fields`: it reads a recognizer's cardFields and claims only a
+ * request whose body carries the card, so the API may serve it recognizers
+ * whose endpoints also run without a card. `checkout_sessions`: it lets a
+ * request the recognizer marks as routine without a card (passWithoutCard)
+ * through ahead of its holds, so the API may serve Stripe's Checkout Session
+ * confirm, which hosted Checkout sends after an approval.
+ */
+export declare const SUPPORTED_REGISTRY_FEATURES: readonly string[];
+/**
+ * Dark-launch capabilities this build can finish. Sent on syncRegistry as
+ * ?capabilities= so the API also serves the recognizers gated behind one of
+ * these. `fiserv_card_capture`: Fiserv Commerce Hub's Secure Data Capture card
+ * capture, which this build pauses and pays only through a prepared checkout
+ * (pre-claim.ts, fiserv.ts). The API serves Fiserv's recognizer only to a build
+ * that lists it and only for a company Agentcard turned Fiserv on for, so an older
+ * SDK never pauses a capture it cannot finish and no SDK pauses one for a company
+ * Fiserv is off for; the API also refuses a Fiserv payment for every such company.
+ */
+export declare const SUPPORTED_CAPABILITIES: readonly string[];
+/**
+ * What the amount on an authorization IS: held to a Stripe PaymentIntent
+ * (read back at create and before the replay), the parked form's own sum
+ * (hosted_form: the bytes the device submits name the amount), or a display
+ * fact on a template that carries no amount.
+ */
+/**
+ * Who named the amount an authorization carries: `processor` (the paused
+ * request's own bytes, or the Stripe intent it names, read back by Agentcard),
+ * `agent` (the `amount` you passed), `page` (the total read off the checkout
+ * page), or `none` (nobody yet; the processor is read right before the card
+ * is sent).
+ */
+export type AmountAuthority = 'processor' | 'agent' | 'page' | 'none';
+/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
+export declare function validAmountInput(amount: unknown): amount is number | string;
+/** How an existing authorization is being handled; omitted by older APIs. */
+export interface ExecutionMetadata {
+    executionMode?: 'user_approval' | 'autopilot';
+    grantId?: string;
+}
+/**
+ * The token flow: the cardholder's device called the processor itself, and
+ * this is the processor's answer to replay into the paused request.
+ */
+export interface TokenReplay extends ExecutionMetadata {
+    /** Authenticated selected-card metadata; the processor response body stays unchanged. */
+    processorContext?: unknown;
+    /** Present only after validating the native TEST Checkout completion. */
+    checkoutSessionId?: string;
+    /** Present only after validating the explicit owned-shop purchase receipt. */
+    shopOrderId?: string;
+    /** Absent on older API versions; always 'token' here. */
+    mode?: 'token';
+    /** The approved authorization (`cauth_…`). */
+    authorizationId: string;
+    status: number;
+    headers: Record<string, string>;
+    /** Body to hand back to the browser, verbatim. */
+    body: string;
+    /**
+     * Post-replay reconciliation, when the API has it: whether the amount the
+     * processor reported charging equals the amount the user approved (null
+     * when there was nothing to compare, e.g. a tokenization request), and the
+     * charged pair itself. A `false` here means the approval stood (money had
+     * moved) and Agentcard also sent your server checkout_authorization.amount_mismatch.
+     */
+    amountVerified?: boolean | null;
+    /** What the processor collected, an integer in the currency's smallest unit (Stripe's `amount`). */
+    chargedAmount?: number | null;
+    chargedCurrency?: string | null;
+    /**
+     * What `chargedAmount` is: 'captured' (the intent succeeded; this is
+     * amount_received), 'authorized' (requires_capture; amount_capturable, the
+     * merchant captures later), 'none' (a PaymentIntent was reported but
+     * nothing is collected yet: processing, requires_action), or null when no
+     * PaymentIntent was reported at all (a tokenization request).
+     */
+    chargedKind?: 'captured' | 'authorized' | 'none' | null;
+    /** Who named the amount the person approved. */
+    amountAuthority?: AmountAuthority;
+}
+/**
+ * The cse flow (Adyen): the cardholder's device encrypted the card under the
+ * processor's public key and reported the ciphertext. Nothing was sent to the
+ * processor yet: write `substitutions` into the paused body
+ * (substituteEncryptedFields) and let the request CONTINUE from the browser
+ * that paused it, so its session data, risk data and cookies stay its own.
+ * The processor's answer then reaches the page as it normally would; the
+ * merchant's order state is where the outcome shows up. A Fiserv card capture
+ * (a prepared checkout only) carries its envelope at `source.encryptionData`:
+ * write it with substituteFiservEnvelope, never substituteEncryptedFields.
+ */
+export interface CseReplay extends ExecutionMetadata {
+    mode: 'cse';
+    /** Absent on a processor-hosted cse approval; see MerchantHostedReplay. */
+    kind?: undefined;
+    authorizationId: string;
+    substitutions: Substitutions;
+    amountAuthority?: AmountAuthority;
+}
+/**
+ * The cse flow at an Adyen merchant's OWN endpoint (a reviewed merchant
+ * profile, see merchant-hosted.ts): the cardholder's device encrypted the card
+ * under the key Agentcard reviewed for that merchant, and nothing was sent. The
+ * paused request continues from this browser with the ciphertext written where
+ * the profile holds it (substituteMerchantHostedBody), and only when the live
+ * body still hashes to `bodySha256`, the body the API checked at create. The
+ * merchant's server charges the card and answers its own page; its order state is
+ * the outcome. Only a prepared checkout pays one, never Autopilot.
+ */
+export interface MerchantHostedReplay extends ExecutionMetadata {
+    mode: 'cse';
+    kind: 'merchant_hosted';
+    authorizationId: string;
+    /** The reviewed merchant profile the approval pays. */
+    profile: string;
+    substitutions: MerchantHostedSubstitutions;
+    /** SHA-256 (lowercase hex) of the paused body the API checked at create. */
+    bodySha256: string;
+    /** When the API stops serving this ciphertext, if it said. */
+    substitutionsExpiresAt: string | null;
+    /** Present when the approval pays this client's own sandbox declaration (VaultClientOptions.sandboxMerchants). */
+    sandboxDeclaration?: Readonly<{
+        endpoint: string;
+        clientKey: string;
+    }>;
+    /**
+     * The merchant's own total this approval was created at, when its profile is priced by
+     * one: the adapters read it again at release (merchantTotalAtRelease) and hold the card
+     * request unless it is still this amount, then report what the merchant says it charged.
+     */
+    merchantTotal?: MerchantTotalApproved;
+    amountAuthority?: AmountAuthority;
+}
+/**
+ * The hosted_form flow (Tranzila): the cardholder's device rebuilt the
+ * processor's own form with the real card and submitted it itself, top-level,
+ * at `submittedAt`. The processor answered THE DEVICE, not the browser that
+ * paused the navigation, so there is no response to replay and no outcome
+ * here: resolve the paused navigation with hostedFormSubmittedPage() (the
+ * adapters do), never resubmit the form, and confirm the order with the
+ * merchant, which learns the outcome from the processor.
+ *
+ * THIS IS NOT AN APPROVED PAYMENT. `kind` and `outcome` say so in words so
+ * no caller mistakes it for one: the API finishes such an authorization as
+ * `submitted_on_device` (never `approved`) and sends your server
+ * `checkout_authorization.submitted` (never `.approved`). The stamp is the
+ * cardholder's device attesting that the form left it; Agentcard holds no
+ * processor evidence on this mode and cannot obtain any. Treat it as "the
+ * person paid, or tried to, on their own device" and confirm with the merchant.
+ */
+export interface HostedFormReplay extends ExecutionMetadata {
+    mode: 'hosted_form';
+    /** What this resolution is: a device-attested submission, not a processor answer. */
+    kind: 'submitted_on_device';
+    /** Always 'unverified': no processor evidence exists for a hosted form. */
+    outcome: 'unverified';
+    authorizationId: string;
+    /** When the device reported the form left it (ISO 8601). */
+    submittedAt: string;
+    amountAuthority?: AmountAuthority;
+}
+/** What authorize() resolves with; branch on `mode` (absent means token). */
+export type ReplayResponse = TokenReplay | CseReplay | MerchantHostedReplay | HostedFormReplay;
+export interface PrepareCheckoutOptions {
+    psp: PreparationProcessor;
+    /** The processor environment, independent of your Agentcard client's mode. */
+    environment: 'production' | 'sandbox' | 'shared';
+    /**
+     * An Adyen merchant that takes the card on its own server: the id of the
+     * profile Agentcard reviewed for it (psp 'adyen'; the environment is the
+     * profile's). The profile must be enabled on this client (syncRegistry); its
+     * card request is then the one request this preparation pays.
+     *
+     * A Fiserv checkout (psp 'fiserv'): the id of the key Agentcard pinned for the
+     * merchant, `agentcard_sandbox` in the sandbox environment. Required for Fiserv,
+     * and refused for every processor but Adyen and Fiserv. The cardholder is asked to
+     * approve a payment to the merchant that key belongs to, so the checkout's `merchant`
+     * must be that merchant's name (`Agentcard sandbox` for `agentcard_sandbox`), and the
+     * one card capture this preparation pays must carry an envelope under that key.
+     */
+    merchantProfile?: string;
+    signal?: AbortSignal;
+}
+export interface PrepareCheckoutInput extends PrepareCheckoutOptions {
+    user: string;
+    merchant: string;
+    /** An integer in the currency's smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06"). */
+    amount: number | string;
+    currency: string;
+    cardId?: string;
+    merchantOrigin: string;
+    checkoutKey: string;
+    timeoutMs?: number;
+    onPreparationCreated?: (id: string) => void;
+    onApprovalUrl?: (url: string) => void;
+}
+/** Real user consent and an unlocked device; no processor request or payment yet. */
+export interface PreparedCheckout {
+    readonly id: string;
+    readonly status: 'ready';
+    readonly psp: PreparationProcessor;
+    readonly environment: 'production' | 'sandbox' | 'shared';
+    /** How the approved card reaches the processor: ciphertext the device produces (Adyen, `cse`) or the device's own request (`token`). */
+    readonly mode: PreparationMode;
+    readonly expiresAt: string;
+    readonly cardId: string;
+    readonly user: string;
+    readonly merchant: string;
+    /** The approved amount, an integer in the currency's smallest unit, as the API confirmed it. */
+    readonly amount: number;
+    readonly amountDisplay: string | null;
+    readonly currency: string;
+    readonly merchantOrigin: string;
+    readonly checkoutKey: string;
+    readonly paymentStatus: 'not_started';
+    readonly amountAuthority: 'agent';
+    /** The reviewed merchant profile this preparation pays, or the Fiserv key pin it pays under; absent for a processor-hosted checkout. */
+    readonly merchantProfile?: string;
+    /** The declared test endpoint and key this preparation pays instead of the profile's (VaultClientOptions.sandboxMerchants). */
+    readonly sandboxDeclaration?: Readonly<{
+        endpoint: string;
+        clientKey: string;
+    }>;
+}
+export declare class CheckoutPreparationError extends Error {
+    preparationId: string | null;
+    reason: string;
+    constructor(preparationId: string | null, reason: string);
+}
+export interface AuthorizeInput extends ExecutionMetadata {
+    /** Native Checkout defaults to TEST; LIVE requires this explicit opt-in. */
+    stripeCheckoutEnvironment?: 'test' | 'production';
+    /** Observed top-level HTTPS merchant origin; a routing hint, never payment authority. */
+    merchantOrigin?: string;
+    /** Your identifier for the person whose card should pay. */
+    user: string;
+    /** Shown to the user on the approval screen. Judged by nothing: the merchant comes from the checkout page. */
+    merchant: string;
+    /**
+     * Your hint at the amount: an integer in the currency's smallest unit (2306
+     * for $23.06), or a decimal string in normal units ("23.06"), with its ISO
+     * 4217 code ("usd"). Optional: the processor's own amount is the higher
+     * authority, read from the paused request or from the Stripe intent it
+     * names right before the cardholder's device replays, and the company's
+     * caps are judged on it. A hint lets a bad purchase be refused the moment
+     * you open it, and a hint that disagrees with the processor beyond one
+     * smallest unit is refused with nothing charged (an AmountMismatchError;
+     * `stage` says which check). Agentcard derives the display string; you
+     * never send one. Both or neither: one without the other is refused.
+     */
+    amount?: number | string;
+    currency?: string;
+    /**
+     * The total read off the checkout page, the lowest authority: used only
+     * when neither the processor's request nor your hint names an amount. The
+     * adapters fill it from `[data-agentcard-amount]` when a page carries one.
+     */
+    pageAmount?: {
+        amount: number;
+        currency: string;
+    };
+    /** Milliseconds from the caller's pay click until the SDK caught the card request, measured on one clock. */
+    payToInterceptMs?: number;
+    /**
+     * WHICH stored card should pay — a vault card id from
+     * GET /api/v2/vault_cards. The approval page preselects it (the human can
+     * still override). Omitted: the page defaults to the most recently added
+     * card. An id that isn't in this user's vault fails the create with a 404
+     * `card_not_found`.
+     */
+    cardId?: string;
+    /**
+     * The origin of the checkout page the payment form was on
+     * (https://shop.example.com). The adapters read it from the page; pass it
+     * yourself when you run your own interception. With the processor identity
+     * in the paused request this is what names the merchant for the company's
+     * presets; `merchant` above is shown to the person and judged by nothing.
+     */
+    pageOrigin?: string;
+    request: PausedRequest;
+    /** Abort if the user has not approved within this many ms. Default 15 min. */
+    timeoutMs?: number;
+    /** Stops local polling; it does not revoke a pending approval or undo a payment. */
+    signal?: AbortSignal;
+    /** Adapter-owned merchant request lifetime. A failed request retires a pending approval before replay when possible. */
+    merchantSignal?: AbortSignal;
+    /** Called before onApprovalUrl; lets a runtime reconcile an interrupted authorization. */
+    onAuthorizationCreated?: (authorizationId: string) => void;
+    /** Called once with the URL to surface to the user, if you deliver it yourself. */
+    onApprovalUrl?: (url: string) => void;
+    /** One-use preparation returned by this client. Never resumes an older request. */
+    preparation?: PreparedCheckout;
+    /**
+     * For a reviewed merchant profile priced by the merchant's own total: when the card
+     * request paused and the merchant responses this browser recorded (see
+     * merchant-total.ts). The adapters pass it; a runtime that intercepts on its own builds
+     * one from its network events, or the payment is refused before any create.
+     */
+    merchantTotal?: MerchantTotalCapture;
+}
+export declare class CardEncryptedError extends Error {
+    psp: string;
+    constructor(psp: string);
+}
+/**
+ * The registry requests a mode this SDK build cannot finish, before creation.
+ * A response in an unexpected mode after creation has an unknown payment
+ * outcome instead and raises PaymentOutcomeUnknownError.
+ */
+export declare class UnsupportedModeError extends Error {
+    mode: string;
+    constructor(mode: string);
+}
+/**
+ * The recognizer says this processor is preparation-required, and no preparation
+ * was passed. Its card may be sent only after the cardholder approved a
+ * prepare(): call prepareCheckout() (or the adapters' preparation gate) before
+ * this request is intercepted. Thrown locally before any create or prompt, and
+ * terminal (retrying the same paused request without preparing fails the same
+ * way). The API answers 409 preparation_required for the same case.
+ */
+export declare class PreparationRequiredError extends Error {
+    psp: string;
+    constructor(psp: string);
+}
+export declare class ApprovalTimeoutError extends Error {
+    constructor(ms: number);
+}
+export declare class CheckoutCancelledError extends Error {
+    constructor();
+}
+/** The reasons an org runtime may stamp when it retires an authorization; see VaultClient.cancelAuthorization. */
+export type RuntimeCancelReason = 'merchant_request_aborted' | 'merchant_never_retried';
+export declare const RUNTIME_CANCEL_REASONS: readonly RuntimeCancelReason[];
+/** The payment may have reached the processor. Reconcile the merchant order before any new attempt. */
+export declare class PaymentOutcomeUnknownError extends Error {
+    authorizationId: string | null;
+    reason: string;
+    constructor(authorizationId: string | null, reason: string);
+}
+export declare class ApprovalDeclinedError extends Error {
+    constructor(reason: string);
+}
+/**
+ * Agentcard refused the payment because the processor's amount did not match
+ * the amount the user was (or would have been) asked to approve. Nothing was
+ * charged. Two stages:
+ *   - 'create': the intent already disagreed when the request was parked. No
+ *     authorization exists (`authorizationId` is null). Per request, not per
+ *     page: the merchant can still update the intent before confirmation, so
+ *     the adapters keep intercepting and the next attempt is judged afresh.
+ *   - 'pre_replay': the intent moved between create and the moment the
+ *     cardholder's device would have sent the card. The authorization is
+ *     `declined` with reason `amount_mismatch`.
+ *
+ * A decline in every structural sense (the adapters abort the paused request
+ * and quiet the page's retry exactly as for a person's "no"), so it extends
+ * ApprovalDeclinedError: code that already handles declines keeps working,
+ * and code that wants the numbers reads them here or branches on `code`.
+ *
+ * A merchant-hosted checkout (an Adyen merchant whose own server charges the card)
+ * has no processor read-back: its agent amount is held to the merchant's own
+ * checkout total, as the agent's browser read it, at stage 'create'. The SDK refuses
+ * that before any create, and the API refuses the same with 409 `amount_mismatch`, so a
+ * caller catches this one class either way; `amountSource` says whose number
+ * `actualCents` is, and the message names it.
+ */
+export declare class AmountMismatchError extends ApprovalDeclinedError {
+    /** The declined authorization, or null for a create-time refusal (no row exists). */
+    authorizationId: string | null;
+    /** What the user was asked to approve, smallest currency unit. */
+    expectedCents: number;
+    /** What the processor (or the merchant, see `amountSource`) reported at the last check. */
+    actualCents: number;
+    /** ISO 4217 of the approved amount. */
+    currency: string;
+    /** ISO 4217 the processor reported (differs only on a currency change). */
+    actualCurrency: string;
+    /** Which check refused it. */
+    stage: 'create' | 'pre_replay';
+    /**
+     * Whose number `actualCents` is: the processor's ('processor'), a merchant-hosted
+     * merchant's own checkout total ('merchant_total'), or the amount its card request
+     * names ('merchant_request').
+     */
+    readonly amountSource: 'processor' | 'merchant_total' | 'merchant_request';
+    readonly code: "amount_mismatch";
+    constructor(
+    /** The declined authorization, or null for a create-time refusal (no row exists). */
+    authorizationId: string | null, 
+    /** What the user was asked to approve, smallest currency unit. */
+    expectedCents: number, 
+    /** What the processor (or the merchant, see `amountSource`) reported at the last check. */
+    actualCents: number, 
+    /** ISO 4217 of the approved amount. */
+    currency: string, 
+    /** ISO 4217 the processor reported (differs only on a currency change). */
+    actualCurrency?: string, 
+    /** Which check refused it. */
+    stage?: 'create' | 'pre_replay', 
+    /**
+     * Whose number `actualCents` is: the processor's ('processor'), a merchant-hosted
+     * merchant's own checkout total ('merchant_total'), or the amount its card request
+     * names ('merchant_request').
+     */
+    amountSource?: 'processor' | 'merchant_total' | 'merchant_request');
+}
+/**
+ * The PaymentIntent behind this checkout can no longer be confirmed: it was
+ * already charged (succeeded), is being charged (processing), is authorized
+ * and on hold for the merchant to capture (requires_capture), or was
+ * canceled. Agentcard refused rather than replay a confirm at it; the
+ * authorization is `declined` with reason `intent_not_confirmable`.
+ * Deliberately NOT "nothing was charged": for three of those four, money has
+ * moved or is moving. Check the intent at Stripe before retrying.
+ */
+export declare class IntentNotConfirmableError extends ApprovalDeclinedError {
+    authorizationId: string;
+    readonly code: "intent_not_confirmable";
+    constructor(authorizationId: string);
+}
+/** Bounded processor identifiers, never a raw response or free-form description. */
+export interface RazorpayProcessorError {
+    reason?: string;
+    source?: string;
+    step?: string;
+    payment_id?: string;
+    order_id?: string;
+}
+/**
+ * The device reported a processor request rejection. A generic processor
+ * code does not establish an issuer decline or prove no money moved. Read
+ * the bounded processor evidence and reconcile the merchant before retrying.
+ * The authorization remains `declined` with reason `processor_refused` for
+ * compatibility; no successful processor response is handed to the merchant.
+ */
+export declare class ProcessorRefusedError extends ApprovalDeclinedError {
+    authorizationId: string;
+    pspErrorCode: string | null;
+    readonly code: "processor_refused";
+    readonly processorError: RazorpayProcessorError | null;
+    constructor(authorizationId: string, pspErrorCode: string | null, processorError?: RazorpayProcessorError | null);
+}
+/** Why Agentcard refused a payment on Adyen's TEST platform; see AdyenTestPlatformRefusedError. */
+export type AdyenTestPlatformRefusal = 'adyen_test_environment_refused' | 'adyen_test_platform_requires_documented_test_card';
+/**
+ * Agentcard refused a payment on Adyen's TEST platform, where a test account can
+ * read whatever is encrypted under its key. Nothing was encrypted and nothing was
+ * charged. `code` says which rule:
+ *   - 'adyen_test_environment_refused': a live checkout names Adyen's test host or
+ *     a `test_` client key. Stage 'create': the API refused it before anyone was
+ *     asked (`authorizationId` is null) and the page's next request is refused the
+ *     same way, so the adapters stop intercepting. Stage 'pre_replay': the
+ *     authorization was declined right before the card would have been encrypted.
+ *   - 'adyen_test_platform_requires_documented_test_card': a test-mode checkout on
+ *     Adyen's test platform, where the approval page encrypts only Adyen's
+ *     documented test cards and the cardholder's card is not one.
+ * A decline in every structural sense, so it extends ApprovalDeclinedError.
+ */
+export declare class AdyenTestPlatformRefusedError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: AdyenTestPlatformRefusal;
+    readonly stage: 'create' | 'pre_replay';
+    constructor(authorizationId: string | null, code: AdyenTestPlatformRefusal, stage: 'create' | 'pre_replay');
+}
+/** Why a merchant-hosted payment priced by the merchant's own total was refused; see MerchantTotalError. */
+export type MerchantTotalRefusal = 'merchant_total_required' | 'merchant_total_refused' | 'merchant_total_changed' | 'merchant_total_stale';
+/**
+ * A reviewed merchant's own checkout total could not stand behind this payment, so the
+ * card request was held and nothing was charged. The merchant's server picks what it
+ * charges, so a merchant-hosted payment is priced by the total the merchant's own
+ * checkout responses named in this browser (the profile's amount source), never by the
+ * agent's number alone. `code`:
+ *   - 'merchant_total_required': no total was sent (stage 'sdk': this runtime recorded no
+ *     merchant responses; stage 'create': the API got none);
+ *   - 'merchant_total_refused': the responses do not confirm one total for this order
+ *     (`reasonCode`: no_source when none was seen, stale, refused, unreadable,
+ *     mismatch, unbound, invalid); stage 'sdk' before any create, 'create' by the API;
+ *   - 'merchant_total_changed': stage 'release': between the approval and the moment the
+ *     card would have gone out, the merchant's total moved, or a request that could move
+ *     it had not answered. The approval is retired; the card never left this browser;
+ *   - 'merchant_total_stale': stage 'runtime': the approval came after the total was too
+ *     old for its profile, so the API withheld the card.
+ * A decline in every structural sense, so it extends ApprovalDeclinedError.
+ */
+export declare class MerchantTotalError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: MerchantTotalRefusal;
+    readonly stage: 'sdk' | 'create' | 'release' | 'runtime';
+    readonly reasonCode: string | null;
+    constructor(authorizationId: string | null, code: MerchantTotalRefusal, stage: 'sdk' | 'create' | 'release' | 'runtime', reasonCode: string | null, reason: string);
+}
+/**
+ * A non-2xx from the Agentcard API, carrying the status so callers can tell a
+ * misconfiguration from a blip. The adapters use this to decide whether
+ * retrying is worth anything: a 404 `connection_not_found` will answer the same
+ * way forever, while a 429 or a 502 will not.
+ */
+/**
+ * The company's preset refused the purchase. The company that runs this
+ * integration put rules on its users' Vault purchases (a merchant list, a
+ * currency, a spend cap, a time window); this purchase is outside them.
+ * Nothing was charged. Two stages:
+ *   - 'create': refused before any authorization existed (`authorizationId`
+ *     is null); nobody was asked to approve. Per purchase, not per page: the
+ *     next request on the same page is judged afresh.
+ *   - 'pre_replay': refused right before the cardholder's device would have
+ *     sent the card; the authorization is `declined` with `code` as reason.
+ * `code` is the rule's reason (merchant_denied, currency_denied,
+ * spend_rate_exceeded, time_window_denied, ...), `message` the rule's own
+ * statement with the company's next step, `preset` the version that judged
+ * it. When several presets refused the same purchase, `code`, `preset`,
+ * `rule` and `attachment` are the first, and `refusals` names every one. A
+ * decline in every structural sense (the adapters quiet the page's retry as
+ * for a person's "no"), so it extends ApprovalDeclinedError.
+ */
+export declare class PresetRefusedError extends ApprovalDeclinedError {
+    readonly authorizationId: string | null;
+    readonly code: string;
+    readonly detail: string | null;
+    readonly preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null;
+    readonly rule: string | null;
+    readonly stage: 'create' | 'pre_replay';
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    readonly attachment: PresetAttachment | null;
+    /** The preset's name. */
+    readonly presetName: string | null;
+    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
+    readonly refusals: readonly PresetRefusal[];
+    constructor(authorizationId: string | null, code: string, detail: string | null, preset: {
+        id: string;
+        version: number;
+        name: string;
+    } | null, rule: string | null, stage: 'create' | 'pre_replay', 
+    /** The stored card the preset that refused is attached to, with its last four digits. */
+    attachment?: PresetAttachment | null, refusals?: readonly PresetRefusal[]);
+}
+/** The stored card a preset is attached to, with its last four digits. */
+export interface PresetAttachment {
+    kind: 'card';
+    targetId: string | null;
+    last4: string | null;
+}
+/** One preset's refusal of a purchase. */
+export interface PresetRefusal {
+    preset: {
+        id: string;
+        version: number;
+        name: string;
+    };
+    attachment: PresetAttachment | null;
+    rule: string | null;
+    code: string;
+    detail: string | null;
+}
+/** A decline reason only the company presets stamp (see PresetRefusedError). */
+export declare const PRESET_REFUSAL_REASONS: ReadonlySet<string>;
+export declare class CheckoutApiError extends Error {
+    status: number;
+    path: string;
+    bodyText: string;
+    /** The API's stable error code (`{ error: { code } }`), or null when the body carried none. */
+    readonly code: string | null;
+    /**
+     * The rest of the error envelope. A 409 `amount_mismatch` from create
+     * carries `expected_cents`, `actual_cents`, `currency`, `actual_currency`;
+     * an `amount_unverifiable` carries `reason`; an `intent_not_confirmable`
+     * carries `intent_status`.
+     */
+    readonly details: Record<string, unknown>;
+    constructor(status: number, path: string, bodyText: string);
+    /**
+     * True when repeating this exact call cannot succeed: a misconfiguration
+     * (4xx other than 429). NOT a 409 `amount_mismatch`: Stripe lets a merchant
+     * update an intent's amount until it is confirmed, so the next request on
+     * the same page may well agree. That one is a per-request failure, and
+     * authorize() surfaces it as AmountMismatchError before an adapter ever
+     * sees it here. NOT a 409 `duplicate_submission` either: the household
+     * already has, or already answered, the prompt for this submission, and
+     * once that prior authorization is declined or expired the same form is a
+     * new question. The adapters quiet the page's re-post the way they quiet a
+     * decline instead of latching the attachment.
+     */
+    get permanent(): boolean;
+}
+/** The client-credentials exchange was refused: the RFC 6749 error, with the status the token endpoint answered. */
+export declare class CheckoutAuthError extends Error {
+    status: number;
+    code: string | null;
+    constructor(status: number, code: string | null, description: string | null);
+}
+/**
+ * A URL as it may appear in an error message: origin + path only. A paused
+ * request's URL can carry a client secret in its query string, and error
+ * messages travel further than anyone intends (onEvent, logs, crash reports).
+ */
+export declare function redactUrl(raw: string): string;
+export interface VaultClientOptions {
+    /**
+     * Your Agentcard OAuth client credentials. The SDK exchanges them for a
+     * short-lived access token and refreshes it when it expires.
+     *
+     * NOT an `sk_` API key: those are retired, and the checkout endpoints reject
+     * them with `client_credentials_required` because an authorization has to be
+     * bound to the confidential client that created it.
+     */
+    clientId: string;
+    clientSecret: string;
+    baseUrl?: string;
+    /**
+     * The credentials are a sandbox client's. Sandbox and live share one base URL, and the
+     * client's mode lives on Agentcard's side, so name it here when you want the sandbox recogniser: a
+     * fixture store on `http://127.0.0.1[:port]` or `http://localhost[:port]` is then recognised by its path
+     * against each processor's endpoints and paused as the processor's request would be. An `sk_test_`
+     * credential reads as sandbox on its own. Production never admits loopback, whatever this says about a
+     * production client: Agentcard refuses the create.
+     */
+    sandbox?: boolean;
+    /** Override the PSP registry (tests, or pinning). Defaults to the hosted list. */
+    registry?: Recognizer[];
+    fetchImpl?: typeof fetch;
+    /** Receives contained reporting failures that do not change checkout behavior. */
+    onEvent?: (event: {
+        type: string;
+        detail?: unknown;
+    }) => void;
+    pollIntervalMs?: number;
+    /**
+     * Waits before retrying a create the API answered 502 `amount_unverifiable`
+     * (Stripe did not answer the amount read-back) or 502 `cse_key_unavailable`
+     * (Adyen did not answer the public-key fetch). One retry per entry, then
+     * the error is thrown. Default [500, 1500]; [] disables retries.
+     */
+    unverifiableRetryDelaysMs?: number[];
+    /**
+     * The voice module: how this product approves purchases by voice, named
+     * once per business, with the Vault return link and the verifier address
+     * beside it. Leave it out for a client that approves no purchase by voice;
+     * `agentcard.voice.*` then throws `missing_approval_posture`. See `VoiceOptions`.
+     */
+    voice?: VoiceOptions;
+    /**
+     * Test mode only: run a merchant-hosted checkout against your own Adyen TEST
+     * account. Each entry arms your own endpoint as taking the card request of a
+     * profile Agentcard reviewed (its body rules), encrypted under your own Adyen
+     * TEST client key; prepare({ psp: 'adyen', environment: 'sandbox',
+     * merchantProfile: <that profile> }) then pays it. Declare them here, before any
+     * attach, so every adapter pauses the endpoint. The API accepts a declaration
+     * only from a test-mode client of an org Agentcard turned declarations on for,
+     * and the Vault encrypts only Adyen's documented test cards under a test_ key.
+     * Throws a TypeError at construction for a profile this build did not review, an
+     * endpoint the API would refuse (see declareSandboxMerchant) or a non-test key.
+     *
+     * On this client a declared profile id takes the place of the reviewed profile
+     * with that id: merchantProfile(id) and prepare({ merchantProfile: id }) name
+     * the declaration, so this client never prepares the reviewed merchant's own
+     * checkout. Nothing is lost on a test-mode client, which can never pay a
+     * reviewed profile on Adyen's live platform; use a separate client for that.
+     */
+    sandboxMerchants?: SandboxMerchantDeclaration[];
+}
+/** The options `new Agentcard({ … })` takes; `VaultClientOptions` is the same type under its older name. */
+export type AgentcardOptions = VaultClientOptions;
+export declare class VaultClient {
+    private readonly opts;
+    private readonly baseUrl;
+    private readonly fetch;
+    private readonly pollIntervalMs;
+    private readonly unverifiableRetryDelaysMs;
+    /** The recognisers the API serves (or the built-in list), before yours are merged in. */
+    private registry;
+    /** The recognisers you registered at runtime; they win over the served list on the same processor. */
+    private extraRecognizers;
+    /**
+     * The reviewed merchant profiles this client arms: every one this build reviewed,
+     * in 'observe' until a sync reads that the API enabled it (armServedProfiles).
+     */
+    private merchantProfiles;
+    /** This client's own sandbox declarations (sandboxMerchants), armed at construction, one per profile. */
+    private readonly declaredProfiles;
+    private readonly preparations;
+    private readonly usedPreparations;
+    /** Named at construction, or read off an `sk_test_` credential. */
+    private readonly sandboxNamed;
+    /** What the token exchange said about the client's mode, when it said anything (`livemode` or `sandbox` on the answer). */
+    private sandboxLearned;
+    /**
+     * The credentials are a sandbox client's: named at construction (`sandbox: true`), read off an `sk_test_`
+     * credential, or learned from the token exchange on an API that says the client's mode. Until one of those,
+     * false: a live client.
+     */
+    get sandbox(): boolean;
+    /** What every module shares: the token, the HTTP path, the poll settings and the language list. */
+    protected readonly transport: ApiTransport;
+    /**
+     * Approve purchases by voice inside your own product: connect a person once,
+     * create the purchase, ask for the key word, read the result. Same
+     * credentials, same token as the checkout calls. Needs `voice: { approval }`
+     * at construction; without it every verb throws `missing_approval_posture`.
+     */
+    readonly voice: VoiceModule;
+    /**
+     * The Purchase API from the same client: ask for a cart on behalf of a
+     * person you connected, confirm it by its hash, and name an approval the
+     * person already gave by voice so the API places against it and asks for
+     * nothing a second time. Same credentials, same token as the voice calls.
+     */
+    readonly buy: BuyModule;
+    /**
+     * The request builders: the processor requests a purchase pauses on, the
+     * shipped ones and yours (`requests.register`, `requests.build`).
+     */
+    readonly requests: RequestRegistry;
+    constructor(opts: VaultClientOptions);
+    /**
+     * The browser recognisers: the list the API serves (after `syncRegistry`)
+     * or the built-in one, plus the entries you register at runtime, so a store
+     * or a processor Agentcard does not know yet needs no release. `find(url)`
+     * reads the merged list, as every pause does.
+     */
+    readonly recognizers: {
+        /** Adds a recogniser, or replaces yours with the same `psp`. Refused (`invalid_recognizer`) without `psp`, `match`, `hosts` and `encoding`. */
+        register: (entry: Recognizer) => void;
+        /** Every recogniser a pause is judged against: yours first, then the served or built-in list. */
+        list: () => Recognizer[];
+        /** The recogniser that claims a URL, or null. */
+        find: (url: string) => Recognizer | null;
+    };
+    private mergedRegistry;
+    /** The recogniser that claims a card request (`POST` to a recognised endpoint), or null; what a paused request names as `recognizer`. */
+    recognizerOf(url: string, method?: string): Recognizer | null;
+    /** Refresh recognizers from the API so new PSPs work without a redeploy. */
+    syncRegistry(): Promise<void>;
+    /**
+     * The reviewed Adyen merchant profile whose card endpoint (or a sibling of it,
+     * the same path under another query) this URL is, with its status on this
+     * client; null for any other URL. Every profile this build reviewed is armed,
+     * in 'observe' until a sync reads that the API enabled it. The adapters pause
+     * these requests and judge them with classifyMerchantRequest. A raw runtime
+     * that pauses one must never continue a card body there unless authorize()
+     * paid it.
+     */
+    merchantProfileOf(url: string): MerchantProfile | null;
+    /** The armed profile with this id, or null. A profile id this client declared (sandboxMerchants) names its declaration, in place of the reviewed profile. */
+    merchantProfile(id: string): MerchantProfile | null;
+    /**
+     * Fetch.enable globs for every armed merchant profile's endpoint and its
+     * siblings, for a raw CDP runtime to arm beside cardUrlPatterns(). Every profile
+     * this build reviewed is armed from the start, so these are the same before and
+     * after syncRegistry; a sync changes only a profile's status.
+     */
+    merchantProfileUrlPatterns(): string[];
+    /** True when this request is a card tokenization we can take over. */
+    isCardRequest(url: string, method?: string): boolean;
+    /**
+     * What happens to a card request (by URL) whose body carries no card: null
+     * when it carries one, so it is a card request as usual; 'continue' when the
+     * recognizer marks the endpoint as one where such requests are routine and
+     * never ours; 'refuse' otherwise, such as a Stripe confirmation paying with
+     * a method this checkout never approved. The adapters ask only after their
+     * holds, so a request that would reuse an approved token is refused there
+     * first. A body that could not be read is not judged here.
+     */
+    withoutCard(url: string, body: string | null | undefined): 'continue' | 'refuse' | null;
+    /**
+     * How the card would reach the processor on this request (`token`, `cse`
+     * or `hosted_form`; absent on the entry means `token`), or null when the
+     * registry does not recognize it. The adapters read it to decide whether an
+     * approval outlives the page's own request: a hosted form is a navigation
+     * and cannot.
+     */
+    checkoutModeOf(url: string, method?: string): CheckoutMode | null;
+    /**
+     * Glob url patterns covering every host the CURRENT registry can send a card
+     * to — what a raw CDP connection has to hand `Fetch.enable` before any card
+     * request can be paused. attachToCdp calls this for you.
+     *
+     * Call syncRegistry() FIRST: without it these cover only the built-in PSPs,
+     * and a request the API knows about is never paused at all. Deliberately
+     * WIDER than the recognizers themselves (a glob cannot express an anchored
+     * host regex); isCardRequest is the exact check and runs on every request
+     * these patterns pause.
+     */
+    cardUrlPatterns(): string[];
+    /** Wait for real device approval before the caller starts native tokenization. */
+    prepareCheckout(input: PrepareCheckoutInput): Promise<PreparedCheckout>;
+    /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
+    cancelPreparation(id: string): Promise<void>;
+    observePreparation(id: string, guidance: 'presented_not_filled' | 'not_presented', reason?: string): Promise<void>;
+    reportDuplicateGuard(authorizationId: string): Promise<void>;
+    /**
+     * Hand us a paused tokenization request. We ask the cardholder to approve,
+     * their device supplies the card and calls the merchant, and you get back the
+     * response to replay into the browser. Your process never sees a card.
+     */
+    authorize(input: AuthorizeInput): Promise<ReplayResponse>;
+    /** A lost bind acknowledgement must never resume the request. Recover metadata only for safe cleanup. */
+    private retireUncertainPreparation;
+    /**
+     * Retire an authorization the runtime is done with. A 409 or missing
+     * response remains unknown.
+     *
+     * `merchant_request_aborted` (the default): the merchant request is gone
+     * and the row must still be awaiting the person with no replay started; the
+     * acknowledgement carries `processor_request_started: false`.
+     *
+     * `merchant_never_retried`: the page abandoned its request while the person
+     * decided, the adapter kept the approval for the page's retry, and none
+     * came. The row may already be `approved` (a token or ciphertext minted on
+     * the device that this runtime handed to no request), so
+     * `processor_request_started` says whether the processor was asked; the API
+     * stamps this reason only where no charge can have been made and answers
+     * 409 otherwise. The acknowledgement echoes the reason the row actually
+     * carries: a row retired earlier under the other runtime reason answers
+     * with that one.
+     */
+    cancelAuthorization(authorizationId: string, reason?: RuntimeCancelReason): Promise<{
+        /** `cancelled`, the API's own status for a withdrawn purchase since 2026-09-25; `declined` from an API before that date. */
+        id: string;
+        status: 'cancelled' | 'declined';
+        reason: RuntimeCancelReason;
+        cancelled: true;
+        processor_request_started: boolean;
+    }>;
+    /**
+     * Ask whether the page may pay with the Stripe card token an approval
+     * produced: a PaymentIntent confirm that carries no card and pays with
+     * exactly the approved payment method, card token, confirmation token or
+     * source. The API reads the payment from Stripe and answers only for the
+     * approved amount and currency on the same Stripe account; any other answer
+     * rejects with a CheckoutApiError whose code says why (for example
+     * `continuation_not_bound`, `amount_mismatch`). Nothing is charged here:
+     * the adapters continue the page's own request once this resolves.
+     */
+    checkStripeContinuation(authorizationId: string, request: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+        body: string;
+    }): Promise<{
+        paymentIntentId: string;
+        amount: number;
+        currency: string;
+    }>;
+    /**
+     * After a merchant-hosted payment priced by the merchant's own total: what the merchant's
+     * confirmation says it charged (merchant-total.ts merchantChargeReport builds `report`
+     * from the responses this browser recorded after the card request). The API compares it
+     * with the approved amount and alerts Agentcard once when the merchant charged more, or
+     * in another currency. The adapters send it on their own; the verdict is 'equal',
+     * 'lower', 'higher', 'currency_mismatch', or 'unread' when no response read.
+     */
+    reportMerchantCharge(authorizationId: string, report: {
+        request: {
+            url: string;
+            method: string;
+            body: string;
+        };
+        responses: unknown[];
+    }): Promise<{
+        verdict: 'equal' | 'lower' | 'higher' | 'currency_mismatch' | 'unread';
+        alerted: boolean;
+    }>;
+    /**
+     * The merchant's own total for a paused card request whose reviewed profile is priced by
+     * one: the exchanges the adapter recorded (once every request that can move the total has
+     * answered), cut to what the profile's rules read, and the same reading the API makes.
+     * Refused with a MerchantTotalError before any create when nothing recorded them, one is
+     * still unanswered, or they do not confirm one total for this order.
+     */
+    private readMerchantTotal;
+    /**
+     * POST the create, with two typed twists: a 502 `amount_unverifiable`
+     * (Stripe did not answer the read-back) is retried on a short backoff
+     * instead of being left to the page's own retry loop, and a 409
+     * `amount_mismatch` becomes an AmountMismatchError at stage 'create' so the
+     * adapters treat it as an answered request, not a dead page.
+     */
+    private createAuthorization;
+    private token;
+    private inflight;
+    /**
+     * Exchange client credentials for an access token, reusing the cached one
+     * until it is nearly expired. Concurrent callers share a single in-flight
+     * exchange rather than each minting their own token.
+     */
+    private accessToken;
+    /**
+     * A preparation status read may retry two known connection failures, after
+     * 250ms and 500ms, while keeping its original approval deadline and signal.
+     * Only fetch and a successful response's body read belong to that retry:
+     * OAuth, HTTP errors, invalid JSON and every mutation remain outside it.
+     * The existing one-time 401 refresh carries the remaining read budget.
+     */
+    private call;
+    private post;
+    private get;
+    private readPreparation;
+}