@agent-cards/checkout 0.19.0 → 0.22.0

package/dist/client.js

@@ -1,1754 +0,0 @@
-import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, recognizerRequiresPreparation, } from './registry.js';
-import { armServedProfiles, classifyProfileRequest, declareSandboxMerchant, merchantProfileEnvironment, merchantProfileFor, merchantProfileUrlPatterns, } from './merchant-hosted.js';
-import { merchantAmountExchanges, merchantAmountFromResponses, merchantProfilePricedBySource, merchantTotalWire, MerchantTotalWait, } from './merchant-total.js';
-import { isMercadoTokenRequest, parseMercadoCheckoutContext, validateMercadoProcessorContext } from './mercado-checkout.generated.js';
-import { matchesPreparation, preparationMode, validPreparationEnvironment } from './prepared-processor.js';
-import { fiservKeyPinById, isFiservSubstitution, requiresFiservPreparation } from './fiserv.js';
-import { hasOwnedShopMarker, parseOwnedShopOrder, parseOwnedShopReceipt } from './owned-shop.generated.js';
-import { requestWithoutCard } from './card-fields.generated.js';
-import { classifyStripeCheckoutRequest, encodeStripeCheckoutContext, hasStripeCheckoutMarker, parseStripeCheckoutContext, parseStripeCheckoutResponse, STRIPE_CHECKOUT_CONTEXT_HEADER, } from './stripe-checkout.generated.js';
-/**
- * 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 const SUPPORTED_MODES = ['token', 'cse', 'hosted_form'];
-/**
- * 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 const SUPPORTED_REGISTRY_FEATURES = ['card_fields', 'checkout_sessions'];
-/**
- * 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 const SUPPORTED_CAPABILITIES = ['fiserv_card_capture'];
-/** An integer in the smallest unit, or a decimal string in normal units with a point; nothing else. */
-export function validAmountInput(amount) {
-    if (typeof amount === 'number')
-        return Number.isSafeInteger(amount) && amount >= 0;
-    return typeof amount === 'string' && /^\d{1,15}\.\d{1,3}$/.test(amount.trim());
-}
-const AMOUNT_AUTHORITIES = ['processor', 'agent', 'page', 'none'];
-export class CheckoutPreparationError extends Error {
-    preparationId;
-    reason;
-    constructor(preparationId, reason) {
-        super(`Checkout preparation unavailable: ${reason}`);
-        this.preparationId = preparationId;
-        this.reason = reason;
-        this.name = 'CheckoutPreparationError';
-    }
-}
-export class CardEncryptedError extends Error {
-    psp;
-    constructor(psp) {
-        super(`${psp} encrypts the card in-page; a paused request carries a blob, not a PAN. ` +
-            `Agentcard must run this PSP's client-side crypto in the vault.`);
-        this.psp = psp;
-        this.name = 'CardEncryptedError';
-    }
-}
-/**
- * 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 class UnsupportedModeError extends Error {
-    mode;
-    constructor(mode) {
-        super(`the checkout requests mode "${mode}", which this version of @agent-cards/checkout cannot complete; upgrade the SDK.`);
-        this.mode = mode;
-        this.name = 'UnsupportedModeError';
-    }
-}
-/**
- * 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 class PreparationRequiredError extends Error {
-    psp;
-    constructor(psp) {
-        super(`${psp} requires a prepared checkout: run prepareCheckout() and have the cardholder approve it before this request is taken over. Nothing was charged.`);
-        this.psp = psp;
-        this.name = 'PreparationRequiredError';
-    }
-}
-export class ApprovalTimeoutError extends Error {
-    constructor(ms) { super(`user did not approve within ${ms}ms`); this.name = 'ApprovalTimeoutError'; }
-}
-export class CheckoutCancelledError extends Error {
-    constructor() { super('checkout cancelled locally before authorization creation'); this.name = 'CheckoutCancelledError'; }
-}
-export const RUNTIME_CANCEL_REASONS = ['merchant_request_aborted', 'merchant_never_retried'];
-/** The payment may have reached the processor. Reconcile the merchant order before any new attempt. */
-export class PaymentOutcomeUnknownError extends Error {
-    authorizationId;
-    reason;
-    constructor(authorizationId, reason) {
-        super(`payment outcome unknown${authorizationId ? ` for ${authorizationId}` : ''}: ${reason}; check the merchant order before retrying`);
-        this.authorizationId = authorizationId;
-        this.reason = reason;
-        this.name = 'PaymentOutcomeUnknownError';
-    }
-}
-export class ApprovalDeclinedError extends Error {
-    constructor(reason) { super(`user declined: ${reason}`); this.name = 'ApprovalDeclinedError'; }
-}
-/**
- * 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 class AmountMismatchError extends ApprovalDeclinedError {
-    authorizationId;
-    expectedCents;
-    actualCents;
-    currency;
-    actualCurrency;
-    stage;
-    amountSource;
-    code = 'amount_mismatch';
-    constructor(
-    /** The declined authorization, or null for a create-time refusal (no row exists). */
-    authorizationId, 
-    /** What the user was asked to approve, smallest currency unit. */
-    expectedCents, 
-    /** What the processor (or the merchant, see `amountSource`) reported at the last check. */
-    actualCents, 
-    /** ISO 4217 of the approved amount. */
-    currency, 
-    /** ISO 4217 the processor reported (differs only on a currency change). */
-    actualCurrency = currency, 
-    /** Which check refused it. */
-    stage = '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') {
-        super('amount_mismatch');
-        this.authorizationId = authorizationId;
-        this.expectedCents = expectedCents;
-        this.actualCents = actualCents;
-        this.currency = currency;
-        this.actualCurrency = actualCurrency;
-        this.stage = stage;
-        this.amountSource = amountSource;
-        this.name = 'AmountMismatchError';
-        const reported = amountSource === 'merchant_total' ? 'the merchant\'s own checkout total is'
-            : amountSource === 'merchant_request' ? 'the merchant\'s card request names' : 'the processor reports';
-        this.message = `amount mismatch${authorizationId ? ` on ${authorizationId}` : ' at create'}: `
-            + `the user was asked to approve ${expectedCents} ${currency}, ${reported} ${actualCents} ${actualCurrency}. Nothing was charged.`;
-    }
-}
-/**
- * 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 class IntentNotConfirmableError extends ApprovalDeclinedError {
-    authorizationId;
-    code = 'intent_not_confirmable';
-    constructor(authorizationId) {
-        super('intent_not_confirmable');
-        this.authorizationId = authorizationId;
-        this.name = 'IntentNotConfirmableError';
-        this.message = `the PaymentIntent behind ${authorizationId} was already charged, is processing, or is on hold; `
-            + 'it cannot be confirmed again. Check the intent at Stripe before retrying.';
-    }
-}
-function parseProcessorError(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return null;
-    const fields = value;
-    const result = {};
-    const exact = (pattern, field) => pattern.exec(field)?.[0] === field;
-    for (const [key, field] of Object.entries(fields)) {
-        if (typeof field !== 'string')
-            return null;
-        if (key === 'reason' || key === 'source' || key === 'step') {
-            if (!exact(/^[a-z][a-z_]{0,63}$/, field))
-                return null;
-            result[key] = field;
-        }
-        else if (key === 'payment_id' || key === 'order_id') {
-            if (!exact(key === 'payment_id' ? /^pay_[A-Za-z0-9]{1,128}$/ : /^order_[A-Za-z0-9]{1,128}$/, field))
-                return null;
-            result[key] = field;
-        }
-        else
-            return null;
-    }
-    return Object.keys(result).length ? result : null;
-}
-/**
- * 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 class ProcessorRefusedError extends ApprovalDeclinedError {
-    authorizationId;
-    pspErrorCode;
-    code = 'processor_refused';
-    processorError;
-    constructor(authorizationId, pspErrorCode, processorError = null) {
-        super('processor_refused');
-        this.authorizationId = authorizationId;
-        this.pspErrorCode = pspErrorCode;
-        this.name = 'ProcessorRefusedError';
-        this.processorError = parseProcessorError(processorError);
-        this.message = `the processor rejected the payment request on ${authorizationId}${pspErrorCode ? ` (${pspErrorCode})` : ''}. Check the merchant payment status before retrying.`;
-    }
-}
-const ADYEN_TEST_PLATFORM_REFUSALS = ['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 class AdyenTestPlatformRefusedError extends ApprovalDeclinedError {
-    authorizationId;
-    code;
-    stage;
-    constructor(authorizationId, code, stage) {
-        super(code);
-        this.authorizationId = authorizationId;
-        this.code = code;
-        this.stage = stage;
-        this.name = 'AdyenTestPlatformRefusedError';
-        this.message = code === 'adyen_test_environment_refused'
-            ? `Adyen's test platform cannot take this live payment${authorizationId ? ` (${authorizationId} was declined)` : '; no authorization was created'}: the checkout names Adyen's test host or a test_ client key. Nothing was encrypted or charged.`
-            : `this checkout is on Adyen's test platform, which takes only Adyen's documented test cards${authorizationId ? ` (${authorizationId} was declined)` : ''}. Nothing was encrypted or charged.`;
-    }
-}
-/**
- * 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 class MerchantTotalError extends ApprovalDeclinedError {
-    authorizationId;
-    code;
-    stage;
-    reasonCode;
-    constructor(authorizationId, code, stage, reasonCode, reason) {
-        super(code);
-        this.authorizationId = authorizationId;
-        this.code = code;
-        this.stage = stage;
-        this.reasonCode = reasonCode;
-        this.name = 'MerchantTotalError';
-        this.message = `${reason}${authorizationId ? ` (${authorizationId})` : ''}. Nothing was charged.`;
-    }
-}
-/**
- * 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 class PresetRefusedError extends ApprovalDeclinedError {
-    authorizationId;
-    code;
-    detail;
-    preset;
-    rule;
-    stage;
-    attachment;
-    /** The preset's name. */
-    presetName;
-    /** Every preset that refused, each with its attachment, rule, code and statement; one entry when one refused. */
-    refusals;
-    constructor(authorizationId, code, detail, preset, rule, stage, 
-    /** The stored card the preset that refused is attached to, with its last four digits. */
-    attachment = null, refusals = []) {
-        super(code);
-        this.authorizationId = authorizationId;
-        this.code = code;
-        this.detail = detail;
-        this.preset = preset;
-        this.rule = rule;
-        this.stage = stage;
-        this.attachment = attachment;
-        this.name = 'PresetRefusedError';
-        this.presetName = preset?.name ?? null;
-        this.refusals = refusals.length ? refusals : preset ? [{ preset, attachment, rule, code, detail }] : [];
-        const others = this.refusals.slice(1).map((r) => `"${r.preset.name}"`);
-        const also = others.length ? ` Also refused by ${others.length === 1 ? 'preset' : 'presets'} ${others.join(', ')}.` : '';
-        this.message = `refused by the company preset${preset ? ` "${preset.name}"` : ''} (${code}${stage === 'create' ? ', before any authorization was created' : ''}): ${detail ?? 'this purchase is outside the rules the company set'}${also}`;
-    }
-}
-/** A decline reason only the company presets stamp (see PresetRefusedError). */
-export const PRESET_REFUSAL_REASONS = new Set([
-    'spend_total_exceeded', 'spend_rate_exceeded', 'spend_rate_unknown', 'amount_unknown', 'rate_unavailable',
-    'category_denied', 'category_unknown', 'merchant_denied', 'merchant_unknown',
-    'geo_denied', 'geo_unknown', 'currency_denied', 'currency_unknown',
-    'time_window_denied', 'surface_denied', 'surface_unknown',
-]);
-function presetOf(v) {
-    if (!v || typeof v !== 'object')
-        return null;
-    const p = v;
-    if (typeof p.id !== 'string' || typeof p.version !== 'number' || typeof p.name !== 'string')
-        return null;
-    return { id: p.id, version: p.version, name: p.name };
-}
-function attachmentOf(v) {
-    if (!v || typeof v !== 'object')
-        return null;
-    const a = v;
-    if (a.kind !== 'card')
-        return null;
-    return { kind: a.kind, targetId: typeof a.target_id === 'string' ? a.target_id : null, last4: typeof a.last4 === 'string' ? a.last4 : null };
-}
-/** The `refusals` list of a refusal envelope: every entry that names a preset. */
-function refusalsOf(v) {
-    if (!Array.isArray(v))
-        return [];
-    const out = [];
-    for (const item of v) {
-        if (!item || typeof item !== 'object')
-            continue;
-        const r = item;
-        const preset = presetOf(r.preset);
-        if (!preset || typeof r.reason !== 'string')
-            continue;
-        out.push({ preset, attachment: attachmentOf(r.attachment), rule: typeof r.rule === 'string' ? r.rule : null, code: r.reason, detail: typeof r.message === 'string' ? r.message : null });
-    }
-    return out;
-}
-export class CheckoutApiError extends Error {
-    status;
-    path;
-    bodyText;
-    /** The API's stable error code (`{ error: { code } }`), or null when the body carried none. */
-    code;
-    /**
-     * 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`.
-     */
-    details;
-    constructor(status, path, bodyText) {
-        super(`agentcard ${path} -> ${status} ${bodyText}`);
-        this.status = status;
-        this.path = path;
-        this.bodyText = bodyText;
-        this.name = 'CheckoutApiError';
-        const envelope = parseErrorEnvelope(bodyText);
-        this.code = envelope.code;
-        this.details = envelope.details;
-    }
-    /**
-     * 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() {
-        if (this.code === 'amount_mismatch' || this.code === 'duplicate_submission')
-            return false;
-        // Nor a refusal by the company preset (a 403 carrying `preset` in the
-        // envelope): the company's rules refused THIS purchase, at this merchant,
-        // for this amount, at this hour. The next one on the same page may pass,
-        // so the page is quieted like a decline, never latched.
-        if (this.details.preset && typeof this.details.preset === 'object')
-            return false;
-        return this.status >= 400 && this.status < 500 && this.status !== 429;
-    }
-}
-function parseErrorEnvelope(bodyText) {
-    try {
-        const parsed = JSON.parse(bodyText);
-        const err = parsed && typeof parsed === 'object' ? parsed.error : null;
-        if (err && typeof err === 'object') {
-            const { code, ...details } = err;
-            return { code: typeof code === 'string' ? code : null, details };
-        }
-    }
-    catch {
-        // Not a JSON envelope (a proxy page, an empty body): no code to carry.
-    }
-    return { code: null, details: {} };
-}
-/**
- * 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 function redactUrl(raw) {
-    try {
-        const u = new URL(raw);
-        return `${u.origin}${u.pathname}`;
-    }
-    catch {
-        return raw.split(/[?#]/)[0];
-    }
-}
-/**
- * Refusals a preparation create answers before any preparation exists, surfaced
- * as CheckoutPreparationError reasons: Adyen's test platform on a live client, and
- * a merchant profile Agentcard has not turned on, does not offer this account, or
- * whose key or checkout page is not the one it reviewed.
- */
-const PREPARATION_REFUSALS = [
-    'adyen_test_environment_refused', 'unsupported_checkout', 'merchant_profile_unavailable',
-    'merchant_profile_key_changed', 'unknown_merchant_profile', 'unsupported_payment_endpoint',
-    // A sandbox declaration from a live client or an org without declarations turned on,
-    // or one the API cannot pay (sandboxMerchants).
-    'sandbox_declaration_refused', 'sandbox_declaration_invalid',
-];
-/**
- * Refusals a Fiserv preparation create answers (4xx) before any preparation exists, surfaced as
- * the CheckoutPreparationError reason so the caller can tell them apart: the processor is
- * not turned on for this company (`processor_unavailable`), Agentcard has not turned on
- * payments to the merchant the key belongs to (`unsupported_checkout`), the merchant's
- * published key is no longer the one Agentcard reviewed (`merchant_profile_key_changed`),
- * or the key or environment named does not fit the request or the client's test or live
- * mode. A 502 `cse_key_unavailable` (the merchant's published key could not be read just
- * now; a new prepare() may pass) is surfaced the same way. Only for a Fiserv checkout;
- * any other failure, and every other processor's refusal that PREPARATION_REFUSALS does
- * not name, stays `preparation_unconfirmed`.
- */
-const FISERV_PREPARATION_REFUSALS = [
-    'processor_unavailable', 'unsupported_checkout', 'merchant_profile_required', 'unknown_merchant_profile',
-    'merchant_profile_key_changed', 'fiserv_key_refused', 'sandbox_host_on_live_row', 'live_host_on_sandbox_row',
-];
-/** Default backoff for a 502 amount_unverifiable at create: two retries, then give up. */
-const UNVERIFIABLE_RETRY_DELAYS_MS = [500, 1500];
-const PREPARATION_READ_RETRY_DELAYS_MS = [250, 500];
-const TRANSIENT_READ_NETWORK_CODES = new Set([
-    'ECONNRESET', 'ECONNREFUSED', 'EPIPE', 'ETIMEDOUT', 'EAI_AGAIN',
-    'UND_ERR_SOCKET', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT',
-]);
-function transientReadNetworkError(error) {
-    if (!(error instanceof Error) || error.name === 'AbortError' || error.name === 'TimeoutError' || error instanceof SyntaxError)
-        return false;
-    const code = error.cause?.code ?? error.code;
-    return typeof code === 'string' && TRANSIENT_READ_NETWORK_CODES.has(code);
-}
-export class VaultClient {
-    opts;
-    baseUrl;
-    fetch;
-    pollIntervalMs;
-    unverifiableRetryDelaysMs;
-    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).
-     */
-    merchantProfiles = armServedProfiles();
-    /** This client's own sandbox declarations (sandboxMerchants), armed at construction, one per profile. */
-    declaredProfiles;
-    preparations = new WeakSet();
-    usedPreparations = new WeakSet();
-    constructor(opts) {
-        this.opts = opts;
-        this.baseUrl = (opts.baseUrl ?? 'https://api.agentcard.sh').replace(/\/$/, '');
-        this.fetch = opts.fetchImpl ?? globalThis.fetch;
-        this.registry = opts.registry ?? BUILTIN_REGISTRY;
-        this.pollIntervalMs = opts.pollIntervalMs ?? 2000;
-        this.unverifiableRetryDelaysMs = opts.unverifiableRetryDelaysMs ?? UNVERIFIABLE_RETRY_DELAYS_MS;
-        const declared = (opts.sandboxMerchants ?? []).map(declareSandboxMerchant);
-        if (new Set(declared.map((profile) => profile.id)).size !== declared.length) {
-            throw new TypeError('sandboxMerchants: declare each profile at most once.');
-        }
-        this.declaredProfiles = Object.freeze(declared);
-    }
-    /** Refresh recognizers from the API so new PSPs work without a redeploy. */
-    async syncRegistry() {
-        // Never break checkout over a registry fetch — an auth blip or a bad
-        // response leaves the built-in recognizers in place.
-        //
-        // ?modes= is capability negotiation: the API serves only recognizers in
-        // the modes this build can finish, so a processor whose flow this SDK
-        // does not speak is never armed (a pause it cannot complete becomes an
-        // abort, which would dead-end the checkout). `mode` rides through the
-        // spread verbatim.
-        let raw;
-        // ?capabilities= is the dark-launch half of the same negotiation: a
-        // processor gated behind a capability is served only when this build lists
-        // it. This build lists fiserv_card_capture, so it arms Fiserv's card capture
-        // for a company Agentcard turned Fiserv on for; an older build, and every
-        // other company's, never sees that recognizer.
-        const capabilities = SUPPORTED_CAPABILITIES.length ? `&capabilities=${SUPPORTED_CAPABILITIES.join(',')}` : '';
-        // merchant_profiles=1 asks for the reviewed Adyen merchant profiles too, each
-        // as a `{ merchant_profile }` entry after the recognizers; an API that
-        // predates them serves none. Every profile this build reviewed stays armed in
-        // 'observe' through a failed sync or an answer without profiles, and turns
-        // 'enabled' only when the API serves it enabled with this build's own rules
-        // (merchant-hosted.ts armServedProfiles).
-        try {
-            raw = await this.get(`/v2/checkout/recognizers?modes=${SUPPORTED_MODES.join(',')}&features=${SUPPORTED_REGISTRY_FEATURES.join(',')}${capabilities}&merchant_profiles=1`);
-        }
-        catch {
-            return;
-        }
-        if (!Array.isArray(raw))
-            return;
-        const isProfile = (e) => !!e && typeof e === 'object' && 'merchant_profile' in e;
-        this.registry = raw.filter((e) => !isProfile(e)).map((e) => ({
-            ...e,
-            match: new RegExp(e.match, 'i'),
-            passthroughHeaders: e.passthroughHeaders.map((h) => new RegExp(h, 'i')),
-        }));
-        this.merchantProfiles = armServedProfiles(raw.filter(isProfile));
-    }
-    /**
-     * 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) {
-        return merchantProfileFor([...this.declaredProfiles, ...this.merchantProfiles], url);
-    }
-    /** 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) {
-        return this.declaredProfiles.find((profile) => profile.id === id)
-            ?? this.merchantProfiles.find((profile) => profile.id === id) ?? 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() {
-        return merchantProfileUrlPatterns([...this.declaredProfiles, ...this.merchantProfiles]);
-    }
-    /** True when this request is a card tokenization we can take over. */
-    isCardRequest(url, method = 'POST') {
-        return method.toUpperCase() === 'POST' && findRecognizer(url, this.registry) !== null;
-    }
-    /**
-     * 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, body) {
-        if (body == null)
-            return null;
-        const rec = findRecognizer(url, this.registry);
-        return rec ? requestWithoutCard(rec, url, body) : 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, method = 'POST') {
-        if (method.toUpperCase() !== 'POST')
-            return null;
-        const rec = findRecognizer(url, this.registry);
-        return rec ? rec.mode ?? 'token' : 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() {
-        return deriveCardUrlPatterns(this.registry);
-    }
-    /** Wait for real device approval before the caller starts native tokenization. */
-    async prepareCheckout(input) {
-        input = { ...input };
-        const fail = (reason, id = null) => new CheckoutPreparationError(id, reason);
-        if (!validPreparationEnvironment(input.psp, input.environment))
-            throw fail('unsupported_processor');
-        // A merchant-hosted preparation pays one reviewed profile's card request: the
-        // profile must be armed here, enabled, and paid in its own environment.
-        // A Fiserv checkout names the key Agentcard pinned for its merchant, in that key's own
-        // environment. The API then names that key's merchant on the approval, and the capture
-        // this preparation pays must carry an envelope under that key (matchesPreparation).
-        let profile = null;
-        let fiservPin = null;
-        if (input.psp === 'fiserv') {
-            if (input.merchantProfile === undefined)
-                throw fail('merchant_profile_required');
-            fiservPin = fiservKeyPinById(input.merchantProfile);
-            if (!fiservPin)
-                throw fail('unknown_merchant_profile');
-            if (fiservPin.environment !== input.environment)
-                throw fail('unsupported_processor');
-        }
-        else if (input.merchantProfile !== undefined) {
-            profile = typeof input.merchantProfile === 'string' ? this.merchantProfile(input.merchantProfile) : null;
-            if (input.psp !== 'adyen')
-                throw fail('unsupported_processor');
-            if (!profile)
-                throw fail('processor_interception_unavailable');
-            if (profile.status !== 'enabled')
-                throw fail('unsupported_checkout');
-            // A declared test endpoint pays on Adyen's TEST platform: a sandbox preparation.
-            if ((profile.sandboxDeclaration ? 'sandbox' : merchantProfileEnvironment(profile.id)) !== input.environment)
-                throw fail('unsupported_processor');
-        }
-        const declaration = profile?.sandboxDeclaration;
-        if (!validAmountInput(input.amount) || typeof input.currency !== 'string' || !/^[a-z]{3}$/i.test(input.currency))
-            throw fail('amount_required');
-        const origin = new URL(input.merchantOrigin);
-        if (!(origin.protocol === 'https:' || (origin.protocol === 'http:' && origin.hostname === 'localhost')) || origin.origin !== input.merchantOrigin)
-            throw fail('merchant_origin_invalid');
-        if (!input.checkoutKey || !input.user || !input.merchant)
-            throw fail('checkout_context_required');
-        // The cardholder approves a payment to the merchant the key pin belongs to, so a Fiserv
-        // checkout names that merchant as well: the approval, the handle this returns and every
-        // authorization it pays then name one merchant, never a label the caller chose.
-        if (fiservPin && input.merchant !== fiservPin.merchant)
-            throw fail('merchant_profile_mismatch');
-        const timeoutMs = input.timeoutMs ?? 15 * 60_000;
-        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
-            throw fail('timeout_invalid');
-        const signal = input.signal ? AbortSignal.any([input.signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs);
-        if (signal.aborted)
-            throw fail('cancelled');
-        let id = null;
-        let ready = false;
-        try {
-            // Drain a sent creation even after caller cancellation to retire its ID.
-            // The separate stop signal prevents dispatch after a slow OAuth exchange.
-            const created = await this.post('/v2/checkout/preparations', {
-                user: input.user, merchant: input.merchant, amount: input.amount, currency: input.currency.toLowerCase(),
-                ...(input.cardId ? { card_id: input.cardId } : {}), psp: input.psp, mode: preparationMode(input.psp),
-                environment: input.environment, checkout_key: input.checkoutKey, merchant_origin: input.merchantOrigin,
-                ...(profile ? { merchant_profile: profile.id } : {}),
-                ...(fiservPin ? { merchant_profile: fiservPin.id } : {}),
-                ...(declaration ? { sandbox_declaration: { endpoint: declaration.endpoint, client_key: declaration.clientKey, environment: 'test' } } : {}),
-            }, AbortSignal.timeout(30_000), signal);
-            if (!created || typeof created.id !== 'string' || !/^cprep_[A-Za-z0-9_-]{1,128}$/.test(created.id))
-                throw fail('create_unconfirmed');
-            const preparationId = created.id;
-            id = preparationId;
-            try {
-                Promise.resolve(input.onPreparationCreated?.(preparationId)).catch(() => { });
-            }
-            catch { /* observer only */ }
-            if (signal.aborted)
-                throw fail('cancelled', id);
-            if (typeof created.approvalUrl !== 'string')
-                throw fail('approval_url_missing', id);
-            try {
-                Promise.resolve(input.onApprovalUrl?.(created.approvalUrl)).catch(() => { });
-            }
-            catch { /* observer only */ }
-            while (!signal.aborted) {
-                const state = await this.readPreparation(id, signal);
-                if (signal.aborted)
-                    throw fail('cancelled', id);
-                if (state?.id !== id)
-                    throw fail('status_unconfirmed', id);
-                if (state.status === 'ready') {
-                    const expiry = Date.parse(state.ready_expires_at);
-                    if (!Number.isFinite(expiry) || expiry <= Date.now() || typeof state.card_id !== 'string' || !state.card_id
-                        || state.payment_status !== 'not_started' || state.amount_authority !== 'agent'
-                        // A merchant-hosted preparation names the merchant its reviewed profile names, and
-                        // a declared test endpoint names its host (declareSandboxMerchant), never the caller's label.
-                        // A Fiserv preparation names the merchant its key pin belongs to (input.merchant, checked above), and that pin.
-                        || state.user !== input.user || state.merchant !== (profile ? profile.merchant : input.merchant) || state.merchant_origin !== input.merchantOrigin
-                        || state.merchant_profile !== (profile ? profile.id : fiservPin ? fiservPin.id : undefined)
-                        || !servesDeclaration(state.sandbox_declaration, declaration)
-                        || !Number.isSafeInteger(state.amount) || (typeof input.amount === 'number' && state.amount !== input.amount) || state.currency !== input.currency.toLowerCase()
-                        || state.psp !== input.psp || state.mode !== preparationMode(input.psp) || state.environment !== input.environment
-                        || state.checkout_key !== input.checkoutKey)
-                        throw fail('ready_unconfirmed', id);
-                    const prepared = Object.freeze({
-                        id: preparationId, status: 'ready', psp: input.psp, environment: input.environment, mode: preparationMode(input.psp), expiresAt: state.ready_expires_at,
-                        cardId: state.card_id, user: input.user, merchant: input.merchant, amount: state.amount,
-                        amountDisplay: typeof state.amount_display === 'string' ? state.amount_display : null,
-                        currency: input.currency.toLowerCase(), merchantOrigin: input.merchantOrigin, checkoutKey: input.checkoutKey,
-                        paymentStatus: 'not_started', amountAuthority: 'agent',
-                        ...(profile ? { merchantProfile: profile.id } : {}),
-                        ...(fiservPin ? { merchantProfile: fiservPin.id } : {}),
-                        ...(declaration ? { sandboxDeclaration: declaration } : {}),
-                    });
-                    this.preparations.add(prepared);
-                    ready = true;
-                    return prepared;
-                }
-                if (state.status !== 'awaiting_approval')
-                    throw fail(['cancelled', 'expired', 'bound'].includes(state.status) ? state.status : 'status_unconfirmed', id);
-                await interruptibleSleep(this.pollIntervalMs, signal);
-            }
-            throw fail('cancelled', id);
-        }
-        catch (error) {
-            if (error instanceof CheckoutPreparationError)
-                throw error;
-            // A refusal the API answered before any preparation existed names its rule: one
-            // PREPARATION_REFUSALS names for any checkout, and, for a Fiserv checkout only, one
-            // FISERV_PREPARATION_REFUSALS names or a 502 cse_key_unavailable. Every other
-            // processor's other refusals stay preparation_unconfirmed, as before.
-            if (!id && !signal.aborted && error instanceof CheckoutApiError && error.code
-                && ((error.status >= 400 && error.status < 500 && (PREPARATION_REFUSALS.includes(error.code)
-                    || (input.psp === 'fiserv' && FISERV_PREPARATION_REFUSALS.includes(error.code))))
-                    || (input.psp === 'fiserv' && error.status === 502 && error.code === 'cse_key_unavailable')))
-                throw fail(error.code);
-            throw fail(signal.aborted ? 'cancelled' : 'preparation_unconfirmed', id);
-        }
-        finally {
-            if (id && !ready)
-                await this.cancelPreparation(id).catch(() => { });
-        }
-    }
-    /** Cancel only an unconsumed preparation; a bound request is reconciled separately. */
-    async cancelPreparation(id) {
-        if (!/^cprep_[A-Za-z0-9_-]{1,128}$/.test(id))
-            throw new CheckoutPreparationError(null, 'id_invalid');
-        const state = await this.post(`/v2/checkout/preparations/${id}/cancel`, {}, AbortSignal.timeout(5_000));
-        if (state?.id !== id || !['cancelled', 'expired'].includes(state.status))
-            throw new CheckoutPreparationError(id, 'cancel_unconfirmed');
-    }
-    async observePreparation(id, guidance, reason) {
-        try {
-            await this.post(`/v2/checkout/preparations/${id}/observe`, {
-                form_guidance: guidance, ...(reason ? { reason } : {}),
-            }, AbortSignal.timeout(5_000));
-        }
-        catch {
-            this.opts.onEvent?.({ type: 'telemetry_skipped', detail: 'form_guidance' });
-        }
-    }
-    async reportDuplicateGuard(authorizationId) {
-        try {
-            await this.post(`/v2/checkout/authorizations/${authorizationId}/duplicate-guard`, {
-                guard: 'hosted_form_repeat',
-            }, AbortSignal.timeout(5_000));
-        }
-        catch {
-            this.opts.onEvent?.({ type: 'telemetry_skipped', detail: 'duplicate_guard' });
-        }
-    }
-    /**
-     * 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.
-     */
-    async authorize(input) {
-        const mercadoContext = input.request.mercado_checkout === undefined ? undefined : parseMercadoCheckoutContext(input.request.mercado_checkout);
-        if (mercadoContext && (!isMercadoTokenRequest(input.request.url, input.request.method)
-            || input.executionMode === 'autopilot' || input.grantId))
-            throw new Error('mercado_checkout_context_invalid');
-        const nativeCheckout = hasStripeCheckoutMarker(input.request);
-        if (input.stripeCheckoutEnvironment !== undefined && !nativeCheckout)
-            throw new Error('Native Stripe Checkout environment requires its bound request.');
-        const checkoutContext = nativeCheckout ? parseStripeCheckoutContext(input.request) : null;
-        if (nativeCheckout) {
-            if (!checkoutContext || input.preparation || input.executionMode !== 'autopilot' || !input.grantId
-                || !Number.isSafeInteger(input.amount) || Number(input.amount) <= 0 || input.currency !== 'usd'
-                || input.merchantOrigin !== 'https://checkout.stripe.com')
-                throw new Error('Native Stripe Checkout requires an explicit mode-bound autopilot configuration.');
-            const phase = classifyStripeCheckoutRequest(input.request, {
-                environment: input.stripeCheckoutEnvironment, sessionId: checkoutContext.session_id, syntheticPaymentMethodId: checkoutContext.synthetic_payment_method_id,
-                amountCents: input.amount,
-            });
-            if (phase?.phase !== 'final')
-                throw new Error('Native Stripe Checkout request is not prepared.');
-        }
-        const ownedShop = hasOwnedShopMarker(input.request);
-        const shopOrder = ownedShop ? parseOwnedShopOrder(input.request) : null;
-        if (ownedShop) {
-            if (!shopOrder || input.preparation || input.executionMode === 'user_approval' ||
-                !input.merchantOrigin || (input.amount != null && input.amount !== shopOrder.amount &&
-                !(typeof input.amount === 'string' && Number(input.amount) * 100 === shopOrder.amount)) ||
-                (input.currency !== undefined && input.currency.toLowerCase() !== shopOrder.currency))
-                throw new Error('The shop order cannot use this checkout configuration.');
-            input = { ...input, amount: shopOrder.amount, currency: shopOrder.currency };
-        }
-        if (input.executionMode !== undefined && !['user_approval', 'autopilot'].includes(input.executionMode))
-            throw new Error('Unsupported checkout execution mode.');
-        if (input.grantId !== undefined && !/^apg_[A-Za-z0-9_-]{1,128}$/.test(input.grantId))
-            throw new Error('Invalid autopilot grant ID.');
-        if (input.preparation && (input.executionMode === 'autopilot' || input.grantId))
-            throw new Error('A device preparation cannot also select autopilot.');
-        if (input.merchantOrigin !== undefined && !input.preparation) {
-            const merchantUrl = new URL(input.merchantOrigin);
-            if (merchantUrl.protocol !== 'https:' || merchantUrl.origin !== input.merchantOrigin)
-                throw new Error('merchantOrigin must be an exact HTTPS origin.');
-        }
-        const preparation = input.preparation;
-        if (preparation) {
-            if (!this.preparations.has(preparation) || this.usedPreparations.has(preparation))
-                throw new CheckoutPreparationError(preparation.id ?? null, 'already_used_or_foreign');
-            // Consume locally before any await, including OAuth, and never recycle it.
-            this.usedPreparations.add(preparation);
-            if (Date.parse(preparation.expiresAt) <= Date.now())
-                throw new CheckoutPreparationError(preparation.id, 'expired');
-            if (input.user !== preparation.user || input.merchant !== preparation.merchant || (typeof input.amount === 'number' && input.amount !== preparation.amount) || (typeof input.amount === 'string' && !validAmountInput(input.amount))
-                || input.currency?.toLowerCase() !== preparation.currency || input.cardId !== preparation.cardId
-                || !matchesPreparation(preparation, input.request.url, input.request.method ?? 'POST', input.request.body, input.request.headers))
-                throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
-        }
-        if (input.signal?.aborted)
-            throw new CheckoutCancelledError();
-        if (input.merchantSignal?.aborted)
-            throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-        // An armed merchant profile's endpoint (merchant-hosted.ts): the reviewed
-        // merchant's own server, never a processor host, so no recognizer matches it.
-        const merchantProfile = nativeCheckout || ownedShop || mercadoContext ? null : this.merchantProfileOf(input.request.url);
-        // A preparation pays the profile it was made for and nothing else: a
-        // merchant-hosted one never a processor's request or another profile's (two
-        // profiles could share an endpoint), and a processor-hosted one never a
-        // merchant's own endpoint. Checked here, not left to the matcher above, so the
-        // create below can only ever name the profile the cardholder prepared. A Fiserv
-        // preparation names a key pin, not a reviewed profile (matchesPreparation binds it).
-        if (preparation && (((preparation.psp === 'fiserv' ? null : preparation.merchantProfile) ?? null) !== (merchantProfile?.id ?? null)
-            || (preparation.sandboxDeclaration?.endpoint ?? null) !== (merchantProfile?.sandboxDeclaration?.endpoint ?? null))) {
-            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
-        }
-        // A profile a later sync holds in 'observe' no longer pays the preparation made for it.
-        if (preparation && merchantProfile && merchantProfile.status !== 'enabled') {
-            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
-        }
-        if (merchantProfile)
-            assertMerchantHostedRequest(input, merchantProfile);
-        const rec = merchantProfile ? MERCHANT_HOSTED_RECOGNIZER : nativeCheckout ? this.registry.find(entry => entry.psp === 'stripe' && (entry.mode ?? 'token') === 'token')
-            : findRecognizer(input.request.url, this.registry);
-        if (!rec)
-            throw new Error(`not a known tokenization endpoint: ${redactUrl(input.request.url)}`);
-        // A client-side-encrypted processor is only takeable when its entry says
-        // the vault produces that ciphertext itself (mode cse); a bare
-        // clientSideEncrypted entry (an older registry, a hand-built one) still
-        // refuses here, exactly as before.
-        const mode = rec.mode ?? 'token';
-        if (preparation && (rec.psp !== preparation.psp || mode !== preparationMode(preparation.psp)))
-            throw new CheckoutPreparationError(preparation.id, 'checkout_changed');
-        // A preparation-required processor may not be taken over on an ordinary
-        // authorization: the cardholder must have approved a prepare() first. Refuse
-        // locally, before any create or prompt, when none is active, through the
-        // same strict rule the API applies (recognizerRequiresPreparation). Fiserv
-        // sets it; the API serves Fiserv only on a sync that declares its capability,
-        // and only to a company Agentcard turned Fiserv on for. This build carries
-        // Fiserv's own rules, so it also requires the preparation for a Fiserv
-        // request whatever the served entry says (requiresFiservPreparation): a
-        // registry that dropped the flag never opens an ordinary Fiserv authorization.
-        if ((recognizerRequiresPreparation(rec) || requiresFiservPreparation(rec.psp, input.request.url)) && !preparation)
-            throw new PreparationRequiredError(rec.psp);
-        // The merchant's server picks what it charges Adyen, so the agent's amount is
-        // what the API holds the body's own amount to: a merchant-hosted payment names one.
-        if (merchantProfile && input.amount == null) {
-            throw new Error(`A payment to ${merchantProfile.merchant} names its amount: pass amount and currency, the amount the cardholder approves.`);
-        }
-        if (rec.clientSideEncrypted && mode !== 'cse')
-            throw new CardEncryptedError(rec.psp);
-        if (!SUPPORTED_MODES.includes(mode))
-            throw new UnsupportedModeError(mode);
-        // Say no rather than coerce. isCardRequest only ever pauses a POST, and the
-        // service stores the replay template with method 'POST' hardcoded — so a
-        // caller handing in a PUT or GET would get it silently rewritten and the
-        // cardholder's device would replay something the caller never asked for.
-        // A direct caller deserves to be told, not surprised.
-        const method = (input.request.method ?? 'POST').toUpperCase();
-        if (method !== 'POST') {
-            throw new Error(`checkout authorization is POST-only; got ${method} for ${redactUrl(input.request.url)}. ` +
-                'A non-POST tokenizer needs recognizer support before it can be intercepted.');
-        }
-        // The amount is a hint: a pair or nothing. Refuse half a pair here, before
-        // a network call: the API would too, and a retry loop cannot fix a
-        // missing field. The processor's own amount is read by Agentcard.
-        const hasAmount = input.amount != null;
-        const hasCurrency = typeof input.currency === 'string' && input.currency.length > 0;
-        if (hasAmount !== hasCurrency) {
-            throw new Error('amount and currency go together: pass both or neither.');
-        }
-        if (hasAmount && !validAmountInput(input.amount)) {
-            throw new Error('amount is an integer in the currency\'s smallest unit (2306 for $23.06), or a decimal string in normal units ("23.06").');
-        }
-        const timeoutMs = input.timeoutMs ?? 15 * 60_000;
-        if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647)
-            throw new Error('timeoutMs must be a positive integer no larger than 2147483647.');
-        const deadline = Date.now() + timeoutMs;
-        const timeoutSignal = AbortSignal.timeout(timeoutMs);
-        const operationSignal = input.signal ? AbortSignal.any([input.signal, timeoutSignal]) : timeoutSignal;
-        // A reviewed profile priced by the merchant's own total: read it from what this browser
-        // recorded, and refuse before any create when it cannot stand behind this payment.
-        const priced = merchantProfile && merchantProfilePricedBySource(merchantProfile.id)
-            ? await this.readMerchantTotal(input, merchantProfile, preparation, operationSignal) : null;
-        let created;
-        const payload = {
-            user: input.user,
-            merchant: input.merchant,
-            // snake_case on the wire; camelCase is this SDK's convention.
-            ...(hasAmount ? { amount: input.amount, currency: input.currency } : {}),
-            ...(input.pageAmount ? { page_amount: input.pageAmount.amount, page_currency: input.pageAmount.currency } : {}),
-            ...(Number.isInteger(input.payToInterceptMs) && input.payToInterceptMs >= 0
-                ? { pay_to_intercept_ms: input.payToInterceptMs }
-                : {}),
-            psp: rec.psp,
-            // The mode this request will be finished in. The API checks it against
-            // the recognizer and refuses a disagreement before a row exists.
-            mode,
-            ...(input.cardId ? { cardId: input.cardId } : {}),
-            ...(input.executionMode ? { execution_mode: input.executionMode } : {}),
-            ...(input.grantId ? { grant_id: input.grantId } : {}),
-            ...(input.merchantOrigin && !preparation ? { merchant_origin: input.merchantOrigin } : {}),
-            // Only the profile's id: the API takes the key, its environment and where
-            // the card goes from the profile Agentcard reviewed, never from the caller.
-            ...(merchantProfile ? { merchant_hosted: { profile: merchantProfile.id, ...(merchantProfile.sandboxDeclaration ? { sandbox_declaration: {
-                            endpoint: merchantProfile.sandboxDeclaration.endpoint, client_key: merchantProfile.sandboxDeclaration.clientKey, environment: 'test'
-                        } } : {}),
-                    ...(priced ? { merchant_total: priced.wire } : {}) } } : {}),
-            // A prepared checkout already carries the page origin as merchant_origin.
-            ...(preparation
-                ? { preparation_id: preparation.id, checkout_key: preparation.checkoutKey, merchant_origin: preparation.merchantOrigin, form_guidance: 'filled' }
-                : input.pageOrigin ? { checkout_origin: input.pageOrigin } : {}),
-            request: {
-                url: input.request.url,
-                method: input.request.method,
-                headers: { ...pickHeaders(input.request.headers, rec.passthroughHeaders),
-                    ...(checkoutContext ? { [STRIPE_CHECKOUT_CONTEXT_HEADER]: encodeStripeCheckoutContext(checkoutContext) } : {}) },
-                body: input.request.body,
-                ...(mercadoContext ? { mercado_checkout: mercadoContext } : {}),
-            },
-        };
-        try {
-            created = await this.createAuthorization(payload, input.currency, AbortSignal.any([operationSignal, AbortSignal.timeout(30_000)]), input.merchantSignal);
-        }
-        catch (error) {
-            if (error instanceof PaymentOutcomeUnknownError) {
-                if (preparation && !error.authorizationId)
-                    throw new PaymentOutcomeUnknownError(await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated), error.reason);
-                throw error;
-            }
-            if (preparation && error instanceof CheckoutApiError && error.code === 'preparation_bound') {
-                const id = typeof error.details.authorization_id === 'string' && /^cauth_[A-Za-z0-9_-]+$/.test(error.details.authorization_id) ? error.details.authorization_id : null;
-                if (id) {
-                    try {
-                        Promise.resolve(input.onAuthorizationCreated?.(id)).catch(() => { });
-                    }
-                    catch { /* observer only */ }
-                }
-                throw new PaymentOutcomeUnknownError(id, 'preparation_already_bound');
-            }
-            // A missing answer or generic 5xx can hide a committed row and a delivered approval link.
-            // Only the documented pre-create read-back errors prove it is safe to retry.
-            const safeReadFailure = error instanceof CheckoutApiError
-                && error.status === 502 && (error.code === 'amount_unverifiable' || error.code === 'cse_key_unavailable');
-            if ((error instanceof CheckoutApiError && error.status >= 500 && !safeReadFailure)
-                || (!(error instanceof CheckoutApiError) && !(error instanceof ApprovalDeclinedError))) {
-                throw new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_unanswered');
-            }
-            throw error;
-        }
-        if (!created || typeof created.id !== 'string' || !created.id)
-            throw new PaymentOutcomeUnknownError(preparation ? await this.retireUncertainPreparation(preparation, input.onAuthorizationCreated) : null, 'authorization_create_malformed');
-        const authorizationId = created.id;
-        // A prepared Mercado token already has the person's approval. Poll its
-        // result promptly while the native SDK waits: at the default interval,
-        // 10 seconds has at most 20 reads instead of 5 (15 additional reads).
-        // Then restore the caller's interval. Human approval waiting, cancellation,
-        // merchant deadlines, and the single processor request remain unchanged.
-        const preparedMercadoPollUntil = preparation?.psp === 'mercado_pago' ? Date.now() + 10_000 : 0;
-        let execution = {};
-        let approvalDelivered = false;
-        const deliverApproval = (state) => {
-            if (ownedShop || nativeCheckout || preparation || approvalDelivered || execution.executionMode === 'autopilot')
-                return;
-            const url = state.approvalUrl ?? state.approval_url;
-            if (typeof url !== 'string' || !url)
-                return;
-            approvalDelivered = true;
-            try {
-                Promise.resolve(input.onApprovalUrl?.(url)).catch(() => { });
-            }
-            catch { /* observer only */ }
-        };
-        let failed = false;
-        let actionRequired = false;
-        const checkAutopilotAction = (state) => {
-            if (state.autopilot_status !== 'action_required')
-                return;
-            // The authenticated API reports only a verified completion category.
-            // Retain this authorization without returning its processor payload or
-            // inferring whether the required action is 3DS, a redirect, or another step.
-            if (state.id !== authorizationId || state.status !== 'awaiting_approval' || state.mode !== 'token'
-                || state.execution_mode !== 'autopilot' || execution.executionMode !== 'autopilot'
-                || state.grant_id !== execution.grantId || (input.grantId && state.grant_id !== input.grantId)) {
-                throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_action_unconfirmed');
-            }
-            actionRequired = true;
-            throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_action_required');
-        };
-        const stopSignal = input.merchantSignal
-            ? AbortSignal.any([input.merchantSignal, ...(input.signal ? [input.signal] : [])]) : input.signal;
-        try {
-            try {
-                Promise.resolve(input.onAuthorizationCreated?.(authorizationId)).catch(() => { });
-            }
-            catch { /* observer only */ }
-            if (input.merchantSignal?.aborted)
-                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
-            execution = executionMetadata(created, authorizationId);
-            checkAutopilotAction(created);
-            deliverApproval(created);
-            while (Date.now() < deadline) {
-                if (stopSignal?.aborted)
-                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
-                const pollInterval = Date.now() < preparedMercadoPollUntil ? Math.min(this.pollIntervalMs, 500) : this.pollIntervalMs;
-                await interruptibleSleep(Math.min(pollInterval, Math.max(0, deadline - Date.now())), stopSignal);
-                if (stopSignal?.aborted)
-                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'local_cancel');
-                let s;
-                const deadlineSignal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
-                const pollSignal = stopSignal ? AbortSignal.any([stopSignal, deadlineSignal]) : deadlineSignal;
-                try {
-                    s = await this.get(`/v2/checkout/authorizations/${authorizationId}`, pollSignal);
-                }
-                catch {
-                    throw new PaymentOutcomeUnknownError(authorizationId, input.merchantSignal?.aborted ? 'merchant_request_aborted' : 'authorization_poll_failed');
-                }
-                if (input.merchantSignal?.aborted)
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
-                if (!s || typeof s !== 'object' || Array.isArray(s) || typeof s.status !== 'string') {
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_malformed');
-                }
-                execution = executionMetadata(s, authorizationId, execution);
-                checkAutopilotAction(s);
-                if (nativeCheckout && (s.status === 'submitted_on_device' ||
-                    (s.status === 'approved' && (s.mode !== 'token' || execution.executionMode !== 'autopilot'
-                        || execution.grantId !== input.grantId))))
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'checkout_receipt_unconfirmed');
-                if (shopOrder && (s.status === 'submitted_on_device' ||
-                    (s.status === 'approved' && (s.mode !== 'token' || execution.executionMode !== 'autopilot'))))
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'shop_receipt_unconfirmed');
-                deliverApproval(s);
-                const amountAuthority = typeof s.amount_authority === 'string' && AMOUNT_AUTHORITIES.includes(s.amount_authority)
-                    ? { amountAuthority: s.amount_authority }
-                    : {};
-                // A merchant-hosted create finishes only as a cse approval: the API's
-                // database forces these rows to cse. A finished read in any other mode
-                // (token, a missing mode, a hosted form) is not one to act on, and never
-                // reaches the code that would answer the merchant's paused request with it.
-                if (merchantProfile && (s.status === 'approved' || s.status === 'submitted_on_device') && s.mode !== 'cse') {
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_hosted_mode_invalid');
-                }
-                if (s.status === 'submitted_on_device') {
-                    // The device attested that the processor's form left it; the stamp
-                    // is the whole fact and it is NOT an approval (see HostedFormReplay).
-                    // Only a hosted_form row may carry this status; a stamp without its
-                    // time is not one this SDK can act on. The device may already have paid,
-                    // so the adapter holds the attempt until the merchant is reconciled.
-                    const mode = typeof s.mode === 'string' ? s.mode : 'token';
-                    if (mode !== 'hosted_form')
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'submission_mode_mismatch');
-                    if (typeof s.submitted_at !== 'string' || !s.submitted_at) {
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'submission_timestamp_missing');
-                    }
-                    if (execution.executionMode === 'autopilot')
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_submission_mode_invalid');
-                    return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority, ...execution };
-                }
-                if (s.status === 'approved') {
-                    const approvedMode = typeof s.mode === 'string' ? s.mode : 'token';
-                    if (approvedMode === 'hosted_form') {
-                        // Never: the API finishes a hosted form as submitted_on_device, and
-                        // its database refuses `approved` on that mode. An answer that says
-                        // otherwise is not one to act on as a payment.
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'hosted_form_approval_malformed');
-                    }
-                    if (approvedMode === 'cse') {
-                        if (execution.executionMode === 'autopilot')
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_submission_mode_invalid');
-                        // A merchant-hosted create reads back only a merchant-hosted approval,
-                        // and a processor-hosted one never does.
-                        if (merchantProfile || (s.substitutions && typeof s.substitutions === 'object' && 'kind' in s.substitutions)) {
-                            return { ...merchantHostedApproval(s, authorizationId, merchantProfile), ...(priced ? { merchantTotal: priced.approved } : {}),
-                                ...amountAuthority, ...execution };
-                        }
-                        // The API serves a Fiserv envelope only briefly after the approval (it carries
-                        // no timestamp, so whoever holds it could resubmit it). A read after that
-                        // window says so instead of serving it; the capture was never continued here.
-                        if (s.substitutions_expired === true)
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_expired');
-                        const sub = s.substitutions;
-                        const fieldsOk = sub && typeof sub === 'object' && sub.encoding === 'json' && typeof sub.at === 'string' && sub.at
-                            && sub.fields && typeof sub.fields === 'object' && !Array.isArray(sub.fields)
-                            && Object.values(sub.fields).every((v) => typeof v === 'string' && v.length > 0);
-                        if (!fieldsOk)
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
-                        // A Fiserv approval carries exactly its envelope's four members at
-                        // source.encryptionData and removes nothing (fiserv.ts); any other shape is not one to act on.
-                        if (rec.psp === 'fiserv' && !isFiservSubstitution(sub))
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
-                        // `remove`: sibling keys the API says to drop with the swap (Adyen's
-                        // `brand`, stamped by adyen-web from the agent's dummy digits). Absent
-                        // on an older API; anything but a list of names is refused, since a
-                        // half-understood instruction would continue a body Adyen refuses.
-                        const removeRaw = sub.remove;
-                        if (removeRaw !== undefined && !(Array.isArray(removeRaw) && removeRaw.every((k) => typeof k === 'string' && k.length > 0))) {
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'cse_remove_malformed');
-                        }
-                        return {
-                            mode: 'cse',
-                            authorizationId,
-                            substitutions: {
-                                encoding: 'json',
-                                at: sub.at,
-                                fields: { ...sub.fields },
-                                ...(removeRaw ? { remove: [...removeRaw] } : {}),
-                            },
-                            ...amountAuthority,
-                            ...execution,
-                        };
-                    }
-                    if (approvedMode !== 'token')
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'approved_mode_unsupported');
-                    const response = s.response;
-                    if (!response || !Number.isInteger(response.status) || response.status < 100 || response.status > 599
-                        || typeof response.body !== 'string' || !response.headers || typeof response.headers !== 'object' || Array.isArray(response.headers)) {
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'approved_response_malformed');
-                    }
-                    if (shopOrder) {
-                        let receipt;
-                        try {
-                            receipt = parseOwnedShopReceipt(JSON.parse(response.body), shopOrder);
-                        }
-                        catch { /* No raw error or token replay. */ }
-                        if (execution.executionMode !== 'autopilot' || response.status !== 200 || !receipt)
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'shop_receipt_unconfirmed');
-                        // Only canonical receipt fields and our content type enter the page.
-                        response.body = JSON.stringify(receipt);
-                        response.headers = { 'content-type': 'application/json' };
-                    }
-                    if (checkoutContext) {
-                        let receipt;
-                        try {
-                            receipt = parseStripeCheckoutResponse(JSON.parse(response.body), { environment: input.stripeCheckoutEnvironment, sessionId: checkoutContext.session_id });
-                        }
-                        catch { /* Never return an unvalidated processor body to the page. */ }
-                        if (response.status !== 200 || !receipt || s.amount_verified !== true
-                            || s.charged_amount !== input.amount || s.charged_currency !== 'usd' || s.charged_kind !== 'captured')
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'checkout_receipt_unconfirmed');
-                        response.body = JSON.stringify(receipt);
-                        response.headers = { 'content-type': 'application/json' };
-                    }
-                    let processorContext;
-                    if (mercadoContext) {
-                        try {
-                            processorContext = await validateMercadoProcessorContext(s.processor_context, mercadoContext, input.request.url, response.body);
-                        }
-                        catch {
-                            throw new PaymentOutcomeUnknownError(authorizationId, 'mercado_checkout_metadata_invalid');
-                        }
-                    }
-                    else if (s.processor_context !== undefined)
-                        throw new PaymentOutcomeUnknownError(authorizationId, 'unexpected_processor_context');
-                    return {
-                        mode: 'token',
-                        authorizationId,
-                        ...(shopOrder ? { shopOrderId: shopOrder.order_id } : {}),
-                        ...(checkoutContext ? { checkoutSessionId: checkoutContext.session_id } : {}),
-                        ...response,
-                        ...(processorContext ? { processorContext } : {}),
-                        amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
-                        chargedAmount: typeof s.charged_amount === 'number' ? s.charged_amount : null,
-                        chargedCurrency: typeof s.charged_currency === 'string' ? s.charged_currency : null,
-                        chargedKind: s.charged_kind === 'captured' || s.charged_kind === 'authorized' || s.charged_kind === 'none' ? s.charged_kind : null,
-                        ...amountAuthority,
-                        ...execution,
-                    };
-                }
-                if (s.status === 'declined') {
-                    // The pre-replay checks declined it: typed, with the numbers, so the
-                    // caller can say what happened rather than "the user said no".
-                    if (s.reason === 'amount_mismatch') {
-                        throw new AmountMismatchError(String(created.id), Number(s.expected_cents), Number(s.actual_cents), String(s.currency ?? input.currency ?? ''), s.actual_currency != null ? String(s.actual_currency) : undefined, 'pre_replay');
-                    }
-                    if (s.reason === 'intent_not_confirmable')
-                        throw new IntentNotConfirmableError(String(created.id));
-                    if (typeof s.reason === 'string' && ADYEN_TEST_PLATFORM_REFUSALS.includes(s.reason)) {
-                        throw new AdyenTestPlatformRefusedError(String(created.id), s.reason, 'pre_replay');
-                    }
-                    if (typeof s.reason === 'string' && PRESET_REFUSAL_REASONS.has(s.reason)) {
-                        throw new PresetRefusedError(String(created.id), s.reason, typeof s.message === 'string' ? s.message : null, presetOf(s.preset), typeof s.rule === 'string' ? s.rule : null, 'pre_replay', attachmentOf(s.attachment), refusalsOf(s.refusals));
-                    }
-                    if (s.reason === 'processor_refused') {
-                        throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null, s.psp === 'razorpay' ? parseProcessorError(s.processor_error) : null);
-                    }
-                    throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
-                }
-                if (s.status === 'expired') {
-                    if (s.replay_attempted === false)
-                        throw new ApprovalTimeoutError(timeoutMs);
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'expired_after_possible_replay');
-                }
-                if (s.status !== 'awaiting_approval')
-                    throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_status_unrecognized');
-            }
-            // A local deadline is not server-side expiry; the person may still use the approval link.
-            throw new PaymentOutcomeUnknownError(authorizationId, 'local_approval_timeout');
-        }
-        catch (error) {
-            failed = true;
-            if (input.merchantSignal?.aborted)
-                throw new PaymentOutcomeUnknownError(authorizationId, 'merchant_request_aborted');
-            throw error;
-        }
-        finally {
-            // An attested action-required result retains its claim and reservation.
-            // Reporting that state must not request cancellation of the same attempt.
-            if (!actionRequired && (input.merchantSignal?.aborted || ((preparation || nativeCheckout) && failed))) {
-                // Drain a create acknowledgement even after the merchant aborts so its
-                // known ID can be retired. An unacknowledged create remains unknown.
-                // A started/finalized replay or failed cleanup never becomes a claimed
-                // cancellation, and this best-effort cleanup never retries a payment.
-                await this.cancelAuthorization(authorizationId).catch(() => { });
-            }
-        }
-    }
-    /** A lost bind acknowledgement must never resume the request. Recover metadata only for safe cleanup. */
-    async retireUncertainPreparation(preparation, onCreated) {
-        // Race cancellation atomically against a create still arriving at the API.
-        // A bound preparation refuses cancellation; resolve its ID exactly once below.
-        await this.cancelPreparation(preparation.id).catch(() => { });
-        let state;
-        try {
-            state = await this.get(`/v2/checkout/preparations/${preparation.id}`, AbortSignal.timeout(3_000));
-        }
-        catch {
-            return null;
-        }
-        if (state?.id !== preparation.id || state.status !== 'bound' || typeof state.authorization_id !== 'string'
-            || !/^cauth_[A-Za-z0-9_-]{1,128}$/.test(state.authorization_id))
-            return null;
-        const id = state.authorization_id;
-        try {
-            Promise.resolve(onCreated?.(id)).catch(() => { });
-        }
-        catch { /* observer only */ }
-        await this.cancelAuthorization(id).catch(() => { });
-        return id;
-    }
-    /**
-     * 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.
-     */
-    async cancelAuthorization(authorizationId, reason = 'merchant_request_aborted') {
-        if (!/^cauth_[A-Za-z0-9_-]{1,128}$/.test(authorizationId))
-            throw new Error('Invalid authorization ID.');
-        if (!RUNTIME_CANCEL_REASONS.includes(reason))
-            throw new Error('Unsupported cancellation reason.');
-        const result = await this.post(`/v2/checkout/authorizations/${authorizationId}/cancel`, reason === 'merchant_request_aborted' ? {} : { reason }, AbortSignal.timeout(5_000));
-        const recorded = result?.reason;
-        if (result?.id !== authorizationId || result.status !== 'declined' || result.cancelled !== true
-            || typeof recorded !== 'string' || !RUNTIME_CANCEL_REASONS.includes(recorded)
-            || typeof result.processor_request_started !== 'boolean'
-            // The plain cancellation is only ever confirmed before the card moved.
-            || (recorded === 'merchant_request_aborted' && result.processor_request_started !== false)) {
-            throw new PaymentOutcomeUnknownError(authorizationId, 'authorization_cancel_unconfirmed');
-        }
-        return { id: authorizationId, status: 'declined', reason: recorded,
-            cancelled: true, processor_request_started: result.processor_request_started };
-    }
-    /**
-     * 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.
-     */
-    async checkStripeContinuation(authorizationId, request) {
-        if (!/^cauth_[A-Za-z0-9_-]{1,128}$/.test(authorizationId))
-            throw new Error('Invalid authorization ID.');
-        const rec = findRecognizer(request.url, this.registry);
-        if (rec?.psp !== 'stripe')
-            throw new Error('Only a Stripe request can continue an approved Stripe token.');
-        const result = await this.post(`/v2/checkout/authorizations/${authorizationId}/continuations`, {
-            request: { url: request.url, method: request.method, headers: pickHeaders(request.headers, rec.passthroughHeaders), body: request.body },
-        }, AbortSignal.timeout(15_000));
-        const pi = result?.payment_intent;
-        if (result?.object !== 'checkout_continuation' || result.continuation !== 'allowed' || result.authorization !== authorizationId
-            || !pi || typeof pi.id !== 'string' || !Number.isSafeInteger(pi.amount) || typeof pi.currency !== 'string') {
-            throw new Error('The continuation answer was not recognized.');
-        }
-        return { paymentIntentId: pi.id, amount: pi.amount, currency: pi.currency };
-    }
-    /**
-     * 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.
-     */
-    async reportMerchantCharge(authorizationId, report) {
-        if (!/^cauth_[A-Za-z0-9_-]{1,128}$/.test(authorizationId))
-            throw new Error('Invalid authorization ID.');
-        const result = await this.post(`/v2/checkout/authorizations/${authorizationId}/merchant_charge`, report, AbortSignal.timeout(10_000));
-        const verdict = result?.verdict;
-        if (result?.authorization_id !== authorizationId || !['equal', 'lower', 'higher', 'currency_mismatch', 'unread'].includes(verdict)) {
-            throw new Error('The merchant charge report was not acknowledged.');
-        }
-        return { verdict, alerted: result.alerted === true };
-    }
-    /**
-     * 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.
-     */
-    async readMerchantTotal(input, profile, preparation, signal) {
-        const refuse = (code, reasonCode, reason) => new MerchantTotalError(null, code, 'sdk', reasonCode, reason);
-        const capture = input.merchantTotal;
-        if (!capture || typeof capture.exchanges !== 'function' || typeof capture.pausedAt !== 'number' || !Number.isFinite(capture.pausedAt)) {
-            throw refuse('merchant_total_required', null, `${profile.merchant}'s own total is read from its checkout's responses, and this runtime recorded none`);
-        }
-        const checkoutOrigin = preparation?.merchantOrigin ?? input.pageOrigin;
-        const card = {
-            url: input.request.url, method: (input.request.method ?? 'POST').toUpperCase(), body: input.request.body, pausedAt: capture.pausedAt,
-            ...(checkoutOrigin ? { checkoutOrigin } : {}), ...(capture.page ? { page: capture.page } : {}),
-            ...(profile.sandboxDeclaration ? { declaredEndpoint: profile.sandboxDeclaration.endpoint } : {}),
-        };
-        let seen;
-        try {
-            seen = await capture.exchanges(profile.id, 'source', card, signal);
-        }
-        catch (error) {
-            if (error instanceof MerchantTotalWait)
-                throw refuse('merchant_total_refused', 'stale', `${profile.merchant}'s total is not known: ${error.message}`);
-            throw error;
-        }
-        const sent = merchantAmountExchanges(profile.id, 'source', { card, responses: seen });
-        if (!sent.ok)
-            throw refuse('merchant_total_refused', sent.code, `Refusing to pay ${profile.merchant}: ${sent.reason}`);
-        const read = merchantAmountFromResponses(profile.id, { card, responses: sent.responses });
-        if (!read.ok)
-            throw refuse('merchant_total_refused', read.code, `Refusing to pay ${profile.merchant}: ${read.reason}`);
-        // The agent's number is held to the merchant's before anyone is asked. An integer amount is
-        // compared here; a decimal string is left to the API, which reads it in the currency's units.
-        if (typeof input.amount === 'number' && typeof input.currency === 'string'
-            && (input.amount !== read.amount.amount || input.currency.toLowerCase() !== read.amount.currency.toLowerCase())) {
-            // The same typed refusal the API's 409 amount_mismatch becomes, naming the merchant's total.
-            throw new AmountMismatchError(null, input.amount, read.amount.amount, input.currency.toLowerCase(), read.amount.currency, 'create', 'merchant_total');
-        }
-        return { wire: merchantTotalWire(capture.pausedAt, capture.page, sent.responses), approved: { card, amount: read.amount } };
-    }
-    /**
-     * 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.
-     */
-    async createAuthorization(payload, currency, signal, stopRetries) {
-        for (let attempt = 0;; attempt++) {
-            if (stopRetries?.aborted)
-                throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-            try {
-                return await this.post('/v2/checkout/authorizations', payload, signal, stopRetries);
-            }
-            catch (err) {
-                if (err instanceof CheckoutApiError && err.code && err.status === 403 && presetOf(err.details.preset)) {
-                    // A company preset refused this purchase before a row existed.
-                    const d = err.details;
-                    throw new PresetRefusedError(null, err.code, typeof d.message === 'string' ? d.message : null, presetOf(d.preset), typeof d.rule === 'string' ? d.rule : null, 'create', attachmentOf(d.attachment), refusalsOf(d.refusals));
-                }
-                if (err instanceof CheckoutApiError && err.status === 400 && err.code === 'adyen_test_environment_refused') {
-                    // A live checkout named Adyen's test host or a test_ key: refused before anyone was asked.
-                    throw new AdyenTestPlatformRefusedError(null, 'adyen_test_environment_refused', 'create');
-                }
-                if (err instanceof CheckoutApiError && err.code === 'amount_mismatch') {
-                    const d = err.details;
-                    throw new AmountMismatchError(null, Number(d.expected_cents), Number(d.actual_cents), String(d.currency ?? currency ?? ''), d.actual_currency != null ? String(d.actual_currency) : undefined, 'create', 
-                    // A merchant-hosted refusal names the merchant amount it held the agent's to:
-                    // its card request's own ('body') or its checkout total (an amount source's id).
-                    typeof d.amount_source === 'string' ? (d.amount_source === 'body' ? 'merchant_request' : 'merchant_total') : 'processor');
-                }
-                if (err instanceof CheckoutApiError && err.status === 409 && (err.code === 'merchant_total_required' || err.code === 'merchant_total_refused')) {
-                    // The API could not confirm the merchant's own total for this order: no row exists.
-                    const d = err.details;
-                    throw new MerchantTotalError(null, err.code, 'create', typeof d.reason_code === 'string' ? d.reason_code : null, typeof d.reason === 'string' ? `Agentcard could not confirm the merchant's own total: ${d.reason}` : err.message);
-                }
-                // Two 502s the API asks to be retried: Stripe did not answer the
-                // amount read-back, or Adyen did not answer the public-key fetch.
-                const retryable = !payload.preparation_id && err instanceof CheckoutApiError && err.status === 502
-                    && (err.code === 'amount_unverifiable' || err.code === 'cse_key_unavailable');
-                if (!retryable || attempt >= this.unverifiableRetryDelaysMs.length)
-                    throw err;
-                await interruptibleSleep(this.unverifiableRetryDelaysMs[attempt], stopRetries ? AbortSignal.any([stopRetries, ...(signal ? [signal] : [])]) : signal);
-                if (signal?.aborted)
-                    throw signal.reason;
-            }
-        }
-    }
-    // --- auth: client_credentials, cached until just before it expires --------
-    token = null;
-    inflight = null;
-    /**
-     * 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.
-     */
-    async accessToken(force = false) {
-        if (!force && this.token && Date.now() < this.token.expiresAt)
-            return this.token.value;
-        if (!force && this.inflight)
-            return this.inflight;
-        this.inflight = (async () => {
-            const body = new URLSearchParams({
-                grant_type: 'client_credentials',
-                client_id: this.opts.clientId,
-                client_secret: this.opts.clientSecret,
-            });
-            const r = await this.fetch(`${this.baseUrl}/api/v1/oauth/token`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/x-www-form-urlencoded' },
-                body: body.toString(),
-                signal: AbortSignal.timeout(30_000),
-            });
-            if (!r.ok) {
-                // RFC 6749 error shape, which real OAuth clients expect verbatim.
-                const d = await r.json().catch(() => ({}));
-                throw new Error(`agentcard auth failed: ${d.error ?? r.status} ${d.error_description ?? ''}`.trim());
-            }
-            const d = (await r.json());
-            // Renew a minute early so a token never expires mid-checkout.
-            const ttl = Math.max(60, (d.expires_in ?? 3600) - 60);
-            this.token = { value: d.access_token, expiresAt: Date.now() + ttl * 1000 };
-            return this.token.value;
-        })().finally(() => { this.inflight = null; });
-        return this.inflight;
-    }
-    /**
-     * 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.
-     */
-    async call(path, init = {}, retried = false, stopNewRequests, preparationReadAttempt) {
-        const signal = init.signal ?? AbortSignal.timeout(30_000);
-        const token = await withSignal(this.accessToken(), signal);
-        // Auth can outlive the merchant request. Stop a create that has not left
-        // yet, while preserving the response of one already sent for cleanup.
-        if (stopNewRequests?.aborted)
-            throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-        for (;;) {
-            signal.throwIfAborted();
-            let r;
-            try {
-                r = await withSignal(this.fetch(`${this.baseUrl}${path}`, {
-                    ...init,
-                    signal,
-                    headers: { ...(init.headers ?? {}), authorization: `Bearer ${token}`, 'content-type': 'application/json' },
-                }), signal);
-                if (r.ok)
-                    return await withSignal(r.json(), signal);
-            }
-            catch (error) {
-                const delay = preparationReadAttempt === undefined ? undefined : PREPARATION_READ_RETRY_DELAYS_MS[preparationReadAttempt];
-                if (signal.aborted || preparationReadAttempt === undefined || delay === undefined || !transientReadNetworkError(error))
-                    throw error;
-                preparationReadAttempt++;
-                await interruptibleSleep(delay, signal);
-                continue;
-            }
-            // A token can be revoked or expire early; one forced refresh, then give up.
-            if (r.status === 401 && !retried) {
-                if (stopNewRequests?.aborted)
-                    throw new PaymentOutcomeUnknownError(null, 'merchant_request_aborted');
-                await withSignal(this.accessToken(true), signal);
-                return this.call(path, { ...init, signal }, true, stopNewRequests, preparationReadAttempt);
-            }
-            throw new CheckoutApiError(r.status, path, await withSignal(r.text(), signal));
-        }
-    }
-    post(path, body, signal, stopNewRequests) {
-        return this.call(path, { method: 'POST', body: JSON.stringify(body), signal }, false, stopNewRequests);
-    }
-    get(path, signal) {
-        return this.call(path, { signal });
-    }
-    readPreparation(id, signal) {
-        return this.call(`/v2/checkout/preparations/${id}`, { signal }, false, undefined, 0);
-    }
-}
-function executionMetadata(state, authorizationId, previous = {}) {
-    if (state.execution_mode === undefined)
-        return previous;
-    if (state.execution_mode !== 'user_approval' && state.execution_mode !== 'autopilot')
-        throw new PaymentOutcomeUnknownError(authorizationId, 'execution_mode_unrecognized');
-    if (state.execution_mode === 'user_approval')
-        return { executionMode: 'user_approval' };
-    if (typeof state.grant_id !== 'string' || !/^apg_[A-Za-z0-9_-]{1,128}$/.test(state.grant_id))
-        throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_grant_unconfirmed');
-    if (previous.grantId && previous.grantId !== state.grant_id)
-        throw new PaymentOutcomeUnknownError(authorizationId, 'autopilot_grant_changed');
-    return { executionMode: 'autopilot', grantId: state.grant_id };
-}
-/**
- * What authorize() creates a merchant-hosted authorization as: an Adyen cse
- * payment that only a prepared checkout may make (so an unprepared request is
- * refused locally with PreparationRequiredError, before any create), forwarding
- * no header but content-type. Never matched against a URL: authorize() uses it
- * only for an armed profile's endpoint.
- */
-const MERCHANT_HOSTED_RECOGNIZER = Object.freeze({
-    psp: 'adyen', match: /(?!)/, encoding: 'json', passthroughHeaders: [],
-    clientSideEncrypted: true, mode: 'cse', preparationRequired: true,
-});
-/**
- * Refuse, before any create or prompt, a merchant-hosted request this client
- * cannot pay: a profile Agentcard has not turned on (observe), Autopilot (the
- * cardholder approves every one), or a request the profile's rules do not pause
- * (anything but its reviewed card request).
- */
-function assertMerchantHostedRequest(input, profile) {
-    if (profile.status !== 'enabled') {
-        throw new Error(`Agentcard has not turned on payments to ${profile.merchant} yet. Nothing was charged.`);
-    }
-    if (input.executionMode === 'autopilot' || input.grantId !== undefined) {
-        throw new Error(`A payment to ${profile.merchant} needs the cardholder's approval every time; Autopilot cannot pay it.`);
-    }
-    const verdict = classifyProfileRequest(profile, input.request.url, input.request.method ?? 'POST', input.request.body);
-    if (verdict.verdict === 'abort')
-        throw new Error(`Refusing to pay ${profile.merchant}: ${verdict.reason}. Nothing was charged.`);
-    if (verdict.verdict === 'pass')
-        throw new Error(`not a card request Agentcard reviewed for ${profile.merchant}.`);
-}
-const isRecord = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
-const FORBIDDEN_STEPS = new Set(['__proto__', 'constructor', 'prototype']);
-/**
- * Whether a served preparation names the sandbox declaration this client sent:
- * its endpoint, client key and the test environment, with the public key's
- * SHA-256 the API read. Neither side naming one also matches.
- */
-function servesDeclaration(served, declaration) {
-    if (!declaration)
-        return served === undefined;
-    return isRecord(served) && served.endpoint === declaration.endpoint && served.client_key === declaration.clientKey
-        && served.environment === 'test' && typeof served.public_key_sha256 === 'string' && /^[0-9a-f]{64}$/.test(served.public_key_sha256);
-}
-/** A served JSON path: object keys and array indices, `[]` for the body root; null for anything else. */
-function jsonPathOf(value) {
-    if (!Array.isArray(value) || value.length > 16)
-        return null;
-    const ok = value.every((step) => (typeof step === 'string' && step.length > 0 && !FORBIDDEN_STEPS.has(step))
-        || (typeof step === 'number' && Number.isSafeInteger(step) && step >= 0));
-    return ok ? [...value] : null;
-}
-/** Served card facts: a list of {path, value}; null when anything in it is not one. */
-function factsOf(value) {
-    if (!Array.isArray(value))
-        return null;
-    const facts = [];
-    for (const fact of value) {
-        if (!isRecord(fact) || Object.keys(fact).some((key) => key !== 'path' && key !== 'value'))
-            return null;
-        const path = jsonPathOf(fact.path);
-        if (!path || typeof fact.value !== 'string')
-            return null;
-        facts.push({ path, value: fact.value });
-    }
-    return facts;
-}
-const MERCHANT_HOSTED_SUBSTITUTION_MEMBERS = new Set(['encoding', 'kind', 'profile', 'path', 'fields', 'remove', 'set']);
-/**
- * The approved read of a merchant-hosted authorization, as the replay the
- * adapters continue: the profile's substitution (`kind: 'merchant_hosted'`, a
- * holder path that may be the root `[]`, the merchant's four field names with
- * their ciphertext, the keys to drop and any card facts to `set`), and beside it
- * the profile and the SHA-256 of the body the API checked at create. Anything
- * else, a create that was not merchant-hosted, another profile, or a set the API
- * no longer serves (`substitutions_expired`) is an unknown outcome: the device may
- * already have encrypted the card, and nothing here can pay with it.
- */
-function merchantHostedApproval(s, authorizationId, profile) {
-    const malformed = () => new PaymentOutcomeUnknownError(authorizationId, 'cse_substitutions_malformed');
-    if (!profile)
-        throw malformed();
-    // The API withheld the card because the merchant's total was too old when the cardholder
-    // approved: nothing was encrypted into any request, so this is a refusal, not an unknown.
-    if (s.merchant_total_stale === true) {
-        throw new MerchantTotalError(authorizationId, 'merchant_total_stale', 'runtime', 'stale', `The approval came after ${profile.merchant}'s total was too old for its profile, so Agentcard withheld the card`);
-    }
-    if (s.substitutions_expired === true)
-        throw new PaymentOutcomeUnknownError(authorizationId, 'substitutions_expired');
-    const sub = s.substitutions;
-    const served = s.merchant_hosted;
-    if (!isRecord(sub) || sub.encoding !== 'json' || sub.kind !== 'merchant_hosted' || sub.profile !== profile.id
-        || Object.keys(sub).some((member) => !MERCHANT_HOSTED_SUBSTITUTION_MEMBERS.has(member)))
-        throw malformed();
-    if (!isRecord(served) || served.profile !== profile.id || typeof served.body_sha256 !== 'string'
-        || !/^[0-9a-f]{64}$/.test(served.body_sha256))
-        throw malformed();
-    const path = jsonPathOf(sub.path);
-    const fields = isRecord(sub.fields) && Object.keys(sub.fields).length > 0
-        && Object.values(sub.fields).every((value) => typeof value === 'string' && value.length > 0) ? { ...sub.fields } : null;
-    const remove = sub.remove === undefined ? [] : Array.isArray(sub.remove) && sub.remove.every((key) => typeof key === 'string' && key.length > 0)
-        ? [...sub.remove] : null;
-    const set = sub.set === undefined ? [] : factsOf(sub.set);
-    if (!path || !fields || !remove || !set)
-        throw malformed();
-    return {
-        mode: 'cse',
-        kind: 'merchant_hosted',
-        authorizationId,
-        profile: profile.id,
-        substitutions: { encoding: 'json', kind: 'merchant_hosted', profile: profile.id, path, fields, remove, ...(set.length ? { set } : {}) },
-        bodySha256: served.body_sha256,
-        substitutionsExpiresAt: typeof s.substitutions_expires_at === 'string' ? s.substitutions_expires_at : null,
-        ...(profile.sandboxDeclaration ? { sandboxDeclaration: profile.sandboxDeclaration } : {}),
-    };
-}
-/**
- * Forward only the headers the merchant needs to accept the replay. Everything
- * else (cookies, UA, tracing) is dropped so we transmit as little as possible.
- */
-function pickHeaders(headers, allow) {
-    const out = {};
-    for (const [k, v] of Object.entries(headers)) {
-        const lk = k.toLowerCase();
-        if (lk === 'content-type' || allow.some((re) => re.test(lk)))
-            out[lk] = v;
-    }
-    if (!out['content-type'])
-        out['content-type'] = 'application/json';
-    return out;
-}
-/** Settle local work even if a custom fetch implementation ignores AbortSignal. */
-function withSignal(operation, signal) {
-    return new Promise((resolve, reject) => {
-        const aborted = () => { signal.removeEventListener('abort', aborted); reject(signal.reason); };
-        if (signal.aborted) {
-            operation.catch(() => { });
-            aborted();
-            return;
-        }
-        signal.addEventListener('abort', aborted, { once: true });
-        operation.then(value => { signal.removeEventListener('abort', aborted); resolve(value); }, error => { signal.removeEventListener('abort', aborted); reject(error); });
-    });
-}
-function interruptibleSleep(ms, signal) {
-    if (signal?.aborted)
-        return Promise.resolve();
-    return new Promise((resolve) => {
-        const done = () => { clearTimeout(timer); signal?.removeEventListener('abort', done); resolve(); };
-        const timer = setTimeout(done, ms);
-        signal?.addEventListener('abort', done, { once: true });
-    });
-}