@agent-cards/checkout 0.19.0 → 0.21.0

package/dist/client.d.ts

@@ -1,849 +0,0 @@
-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';
-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;
-}
-/**
- * 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;
-    /** 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[];
-    /**
-     * 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[];
-}
-export declare class VaultClient {
-    private readonly opts;
-    private readonly baseUrl;
-    private readonly fetch;
-    private readonly pollIntervalMs;
-    private readonly unverifiableRetryDelaysMs;
-    private registry;
-    /**
-     * 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;
-    constructor(opts: VaultClientOptions);
-    /** 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<{
-        id: string;
-        status: '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;
-}