@agent-cards/checkout 0.18.0 → 0.21.0

package/dist/client.js

@@ -1,1251 +0,0 @@
-import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.js';
-import { isMercadoTokenRequest, parseMercadoCheckoutContext, validateMercadoProcessorContext } from './mercado-checkout.generated.js';
-import { matchesPreparedRequest, preparationMode, validPreparationEnvironment } from './prepared-processor.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'];
-/** 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';
-    }
-}
-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`.
- */
-export class AmountMismatchError extends ApprovalDeclinedError {
-    authorizationId;
-    expectedCents;
-    actualCents;
-    currency;
-    actualCurrency;
-    stage;
-    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 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') {
-        super('amount_mismatch');
-        this.authorizationId = authorizationId;
-        this.expectedCents = expectedCents;
-        this.actualCents = actualCents;
-        this.currency = currency;
-        this.actualCurrency = actualCurrency;
-        this.stage = stage;
-        this.name = 'AmountMismatchError';
-        this.message = `amount mismatch${authorizationId ? ` on ${authorizationId}` : ' at create'}: `
-            + `the user was asked to approve ${expectedCents} ${currency}, the processor reports ${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.`;
-    }
-}
-/**
- * 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];
-    }
-}
-/** 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;
-    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;
-    }
-    /** 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;
-        try {
-            raw = await this.get(`/v2/checkout/recognizers?modes=${SUPPORTED_MODES.join(',')}&features=${SUPPORTED_REGISTRY_FEATURES.join(',')}`);
-        }
-        catch {
-            return;
-        }
-        if (!Array.isArray(raw))
-            return;
-        this.registry = raw.map((e) => ({
-            ...e,
-            match: new RegExp(e.match, 'i'),
-            passthroughHeaders: e.passthroughHeaders.map((h) => new RegExp(h, 'i')),
-        }));
-    }
-    /** 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');
-        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');
-        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,
-            }, 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'
-                        || state.user !== input.user || state.merchant !== input.merchant || state.merchant_origin !== input.merchantOrigin
-                        || !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',
-                    });
-                    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;
-            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
-                || !matchesPreparedRequest(preparation.psp, preparation.environment, 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');
-        const rec = 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');
-        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;
-        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 } : {}),
-            // 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 }
-                    : {};
-                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');
-                        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');
-                        // `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' && 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 };
-    }
-    /**
-     * 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.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');
-                }
-                // 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 };
-}
-/**
- * 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 });
-    });
-}