@agent-cards/checkout 0.17.0 → 0.19.0

package/dist/merchant-hosted.js

@@ -0,0 +1,170 @@
+/**
+ * Adyen merchant-hosted checkouts, as the agent's browser sees them.
+ *
+ * Some Adyen merchants (Dunelm, Cinemark) have adyen-web encrypt the card into
+ * four fields and post them to THEIR OWN server, which then charges the card
+ * through Adyen. No processor host is involved, so the processor registry can
+ * never recognize that request. Agentcard reviews each such merchant instead and
+ * pins its endpoint, body rules and Adyen key in a profile (payment-core
+ * merchant-profiles.js). This build carries those profiles as a generated
+ * projection (adyen-merchant-hosted.generated.ts) and arms every one of them from
+ * the start, in 'observe' until the API says this client may pay it
+ * (VaultClient.syncRegistry asks with merchant_profiles=1). A sync that has not run
+ * or failed, or an API that serves no profile, leaves each one in 'observe'.
+ *
+ * A profile's `status` keeps it dark: 'observe' pauses its card request, reports
+ * the request's shape (a hash of its key paths, never a value) and aborts it, so
+ * the agent's dummy card never reaches the merchant and nothing is charged;
+ * 'enabled' lets a prepared checkout pay it. The API can hold a profile in
+ * 'observe' for a client but never enable it past this build: a profile is
+ * 'enabled' only when both say so. Every profile ships in 'observe' today.
+ */
+import { MERCHANT_PROFILE_RECOGNIZERS as SHARED_PROFILES, classifyDeclaredMerchantRequest as sharedClassifyDeclared, declaredTemplatedUrl as sharedDeclaredTemplatedUrl, declaredUrlGlobs as sharedDeclaredUrlGlobs, declaredUrlRelation as sharedDeclaredUrlRelation, declaredEndpointRefusal as sharedDeclaredEndpointRefusal, classifyMerchantRequest as sharedClassify, merchantBodyKeyPathSha256 as sharedKeyPathSha256, merchantProfileEnvironment as sharedEnvironment, merchantProfileRulesMatch as sharedRulesMatch, merchantProfileTemplatedUrl as sharedTemplatedUrl, merchantProfileUrlGlobs as sharedUrlGlobs, merchantProfileUrlRelation as sharedUrlRelation, sha256Hex as sharedSha256Hex, } from './adyen-merchant-hosted.generated.js';
+import { SubstitutionError, substituteMerchantHosted as sharedSubstitute } from './substitutions.generated.js';
+import { BUILTIN_REGISTRY } from './registry.js';
+/**
+ * The profile's verdict on a paused request: pause (its reviewed card request),
+ * abort (encrypted card data it cannot finish, with the reason) or pass (no
+ * encrypted card data, or not its endpoint or a sibling of it). Reads only;
+ * throws for a profile id this build did not review.
+ */
+export const classifyMerchantRequest = sharedClassify;
+/** The endpoint origin, the path TEMPLATE and the profile's own query: what an event may name. */
+export const merchantProfileTemplatedUrl = sharedTemplatedUrl;
+/** SHA-256 of a JSON body's sorted key paths, no value in it; null for a body that is not JSON. */
+export const merchantBodyKeyPathSha256 = sharedKeyPathSha256;
+/** 'sandbox' for a profile on Adyen's TEST platform, 'production' for every live environment. */
+export const merchantProfileEnvironment = sharedEnvironment;
+const urlRelation = sharedUrlRelation;
+const urlGlobs = sharedUrlGlobs;
+const rulesMatch = sharedRulesMatch;
+const sha256Hex = sharedSha256Hex;
+const substitute = sharedSubstitute;
+/** classifyMerchantRequest for a sandbox declaration: the profile's body rules at the declared endpoint instead of the profile's. */
+export const classifyDeclaredMerchantRequest = sharedClassifyDeclared;
+const declaredRelation = sharedDeclaredUrlRelation;
+const declaredTemplated = sharedDeclaredTemplatedUrl;
+const declaredGlobs = sharedDeclaredUrlGlobs;
+/** payment-core's endpoint rule for a declaration, the part that needs no processor catalog: why an endpoint cannot be declared, or null. */
+const declaredEndpointRefusal = sharedDeclaredEndpointRefusal;
+const BUILT = SHARED_PROFILES;
+/**
+ * The profiles this client arms: every profile this build reviewed, once each, in
+ * this build's order. A served entry is `{ merchant_profile: <the profile's wire
+ * projection> }`, and the first one that names a profile with exactly this build's
+ * rules (endpoint, body rules, holder, fields, key: everything but `status`) and a
+ * status this build knows decides it: 'enabled' only when both that entry and this
+ * build say so. Every other profile stays in 'observe': one the API did not serve (no
+ * sync yet, a failed sync, an API that predates profiles) and one the API reviewed
+ * again after this build was cut, which this build cannot pay. In 'observe' its card
+ * request is still paused and aborted, so the agent's dummy card never reaches a
+ * reviewed merchant, whatever the API answered.
+ */
+export function armServedProfiles(entries = []) {
+    const decided = new Map();
+    for (const entry of entries) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const served = entry.merchant_profile;
+        if (!served || typeof served !== 'object' || Array.isArray(served))
+            continue;
+        const id = served.id;
+        const status = served.status;
+        const built = typeof id === 'string' ? BUILT.find((profile) => profile.id === id) : undefined;
+        if (!built || decided.has(built.id) || (status !== 'observe' && status !== 'enabled') || !rulesMatch(built.id, served))
+            continue;
+        decided.set(built.id, status === 'enabled' && built.status === 'enabled' ? 'enabled' : 'observe');
+    }
+    return BUILT.map((built) => Object.freeze({ id: built.id, merchant: built.merchant, status: decided.get(built.id) ?? 'observe' }));
+}
+const TEST_CLIENT_KEY = /^test_[A-Za-z0-9]{32}$/;
+/**
+ * Arms a sandbox declaration: the reviewed profile's card request at your own
+ * endpoint, under your own Adyen TEST key. Throws a TypeError for a profile this
+ * build did not review, an endpoint the API would refuse, or a key that is not a
+ * test_ key. The endpoint rule is the API's own (payment-core sandboxDeclarationRefusal):
+ * an HTTPS URL in the exact form the browser writes it (no port, credentials or
+ * fragment), on a public domain name outside Adyen's domains, Agentcard's and every
+ * reviewed merchant's domain (declaredEndpointRefusal), and on no host this build's
+ * processor registry names. The armed entry names its host as the merchant, and is
+ * 'enabled' whatever the reviewed profile's status: it never pays the reviewed
+ * merchant, the API refuses it from a live client and from an org it has not turned
+ * declarations on for, and the Vault encrypts only Adyen's documented test cards
+ * under a test_ key.
+ */
+export function declareSandboxMerchant(input) {
+    const built = input && typeof input.profile === 'string' ? BUILT.find((profile) => profile.id === input.profile) : undefined;
+    if (!built)
+        throw new TypeError('sandboxMerchants: profile is not a merchant profile this SDK build reviewed.');
+    const refusal = declaredEndpointRefusal(input.endpoint);
+    if (refusal)
+        throw new TypeError(`sandboxMerchants: ${refusal}.`);
+    const url = new URL(input.endpoint);
+    const host = url.hostname.replace(/\.$/, '');
+    if (BUILTIN_REGISTRY.some((rec) => (rec.hosts ?? []).some((source) => new RegExp(source, 'i').test(host)))) {
+        throw new TypeError(`sandboxMerchants: ${url.hostname} is a payment processor's host, not a merchant's own endpoint.`);
+    }
+    if (typeof input.clientKey !== 'string' || !TEST_CLIENT_KEY.test(input.clientKey)) {
+        throw new TypeError('sandboxMerchants: clientKey must be an Adyen TEST client key (test_ followed by 32 letters and digits).');
+    }
+    return Object.freeze({ id: built.id, merchant: url.hostname, status: 'enabled',
+        sandboxDeclaration: Object.freeze({ endpoint: input.endpoint, clientKey: input.clientKey }) });
+}
+/** How a URL relates to an armed profile: its declared endpoint when it has one, else the reviewed endpoint. */
+function relationTo(profile, url) {
+    return profile.sandboxDeclaration ? declaredRelation(profile.sandboxDeclaration.endpoint, url) : urlRelation(profile.id, url);
+}
+/** The armed profile whose endpoint, or a sibling of it (same origin and path shape), a URL is; null for any other URL. */
+export function merchantProfileFor(profiles, url) {
+    if (typeof url !== 'string')
+        return null;
+    return profiles.find((profile) => relationTo(profile, url) !== null) ?? null;
+}
+/** The Fetch.enable globs that pause every armed profile's endpoint and its siblings, a declared endpoint included. */
+export function merchantProfileUrlPatterns(profiles) {
+    return [...new Set(profiles.flatMap((profile) => (profile.sandboxDeclaration
+            ? declaredGlobs(profile.sandboxDeclaration.endpoint) : urlGlobs(profile.id))))];
+}
+/** classifyMerchantRequest for an armed profile: at its declared endpoint when it has one. */
+export function classifyProfileRequest(profile, url, method, body) {
+    return profile.sandboxDeclaration
+        ? classifyDeclaredMerchantRequest(profile.id, profile.sandboxDeclaration.endpoint, url, method, body)
+        : classifyMerchantRequest(profile.id, url, method, body);
+}
+/** merchantProfileTemplatedUrl for an armed profile: a declared endpoint's origin and path, never its query. */
+export function profileTemplatedUrl(profile, url) {
+    return profile.sandboxDeclaration ? declaredTemplated(profile.sandboxDeclaration.endpoint) : merchantProfileTemplatedUrl(profile.id, url);
+}
+/**
+ * The Fetch.enable globs for every profile this build reviewed. Every one of them is
+ * armed from the start (armServedProfiles), so attachToCdp arms all of them at attach
+ * and a syncRegistry() before or after it changes only a profile's status: its card
+ * request is paused and judged under CDP exactly as attachToPlaywright's per-request
+ * route judges it.
+ */
+export function reviewedMerchantProfileUrlPatterns() {
+    return [...new Set(BUILT.flatMap((profile) => urlGlobs(profile.id)))];
+}
+/**
+ * The continuation of a merchant-hosted approval: the live paused body with the
+ * Vault's ciphertext in place of the dummy fields. The API never sees the body the
+ * browser continues, so the live body must first hash to the one the API checked
+ * when the authorization was created (`bodySha256`); a page that rewrote its body
+ * while the cardholder decided is refused rather than paid. payment-core's
+ * substituteMerchantHosted then reads the profile's body rules again on the live
+ * body, writes only the profile's four fields, and refuses a profile that is not
+ * enabled, unless this client armed the endpoint from its own sandbox declaration
+ * (the replay carries `sandboxDeclaration`), where every body rule still applies.
+ * Throws SubstitutionError; nothing leaves the browser when it does.
+ */
+export function substituteMerchantHostedBody(body, replay) {
+    if (typeof body !== 'string' || sha256Hex(body) !== replay.bodySha256) {
+        throw new SubstitutionError('the paused body is not the one Agentcard checked when this checkout was created');
+    }
+    const { set, ...substitution } = replay.substitutions;
+    return substitute(body, set && set.length ? { ...substitution, set } : substitution, { sandboxDeclared: replay.sandboxDeclaration !== undefined });
+}
+/** The URL an event names for a merchant-hosted replay's request: its declared endpoint's origin and path, or the profile's template. */
+export function replayTemplatedUrl(replay, url) {
+    return replay.sandboxDeclaration ? declaredTemplated(replay.sandboxDeclaration.endpoint) : merchantProfileTemplatedUrl(replay.profile, url);
+}

package/dist/merchant-total-watch.d.ts

@@ -0,0 +1,115 @@
+import { type MerchantHostedReplay } from './client.js';
+import { MerchantExchangeLog, type MerchantRequestSeen, type MerchantTotalCapture } from './merchant-total.js';
+/** onEvent is ordinary integrator telemetry; the shape matches AttachOptions.onEvent. */
+type TotalEvent = {
+    type: string;
+    detail?: unknown;
+};
+type ChargeReporter = {
+    reportMerchantCharge?: (authorizationId: string, report: any) => Promise<{
+        verdict: string;
+        alerted: boolean;
+    }>;
+};
+type Canceller = {
+    cancelAuthorization?: (authorizationId: string, reason: 'merchant_never_retried') => Promise<unknown>;
+};
+/** What the watch reads from the adapter's VaultClient: the profile a URL pays, and this client's own declarations. */
+type ProfileSource = {
+    merchantProfile?: (id: string) => {
+        id: string;
+        sandboxDeclaration?: {
+            endpoint: string;
+        };
+    } | null;
+    merchantProfileOf?: (url: string) => {
+        id: string;
+    } | null;
+};
+/**
+ * How long a paused card request's page is waited for. Chromium can deliver a request's
+ * Network event (which names its document) after the Fetch pause; it follows within
+ * milliseconds, so this bound only matters when it never comes, and the read then has no page.
+ */
+export declare const MERCHANT_PAGE_WAIT_MS = 1000;
+/**
+ * The pauses before the after-payment report is tried again when it could not go out (no
+ * confirmation read yet, or the report request failed): a confirmation the page asks for
+ * after the card request's answer (Dick's order submit) still gets reported.
+ */
+export declare const MERCHANT_CHARGE_RETRY_DELAYS_MS: readonly number[];
+/** How long after the merchant answered a confirmation that arrives late is still reported. */
+export declare const MERCHANT_CHARGE_REPORT_WINDOW_MS: number;
+/**
+ * The merchant's own total around one attached page, shared by the CDP and Playwright
+ * adapters so both read it the same way (merchant-total.ts says what it proves). From
+ * attach on, the adapter tells it about every request that leaves, every answer and every
+ * failure; it keeps, read-only, the ones a priced profile's rules read at the origins they
+ * read (a client's sandbox declaration moves a profile's to its declared endpoint), and
+ * the page each request came from. At a pause it hands the client a capture; at release it
+ * reads the total again and holds the card request unless it is still the approved amount;
+ * once the merchant answered the continued request it reports what the merchant says it
+ * charged.
+ */
+export declare class MerchantTotalWatch {
+    private readonly onEvent?;
+    private readonly vault?;
+    private readonly waitMs;
+    private readonly settleMs;
+    private readonly retryDelaysMs;
+    readonly log: MerchantExchangeLog;
+    private readonly pages;
+    private readonly pageWaiters;
+    /** Approvals whose charge report the API took (the newest REPORTS_MAX). */
+    private readonly reported;
+    /** Approvals a report attempt is running or scheduled for. */
+    private readonly reporting;
+    /**
+     * Approvals still waiting for their report (the newest REPORTS_MAX), each with until when a
+     * confirmation that comes late reports it. One per approval, so a second payment on the
+     * same page never takes the first one's place.
+     */
+    private readonly awaiting;
+    constructor(onEvent?: ((event: TotalEvent) => void) | undefined, vault?: ProfileSource | undefined, waitMs?: number, settleMs?: number, retryDelaysMs?: readonly number[]);
+    /** A request left: remember its page, and record it when a priced profile's rules read it. */
+    sent(key: string, request: MerchantRequestSeen): void;
+    /** The page a request came from, when the adapter named one. */
+    pageOf(key: string): string | undefined;
+    /**
+     * The page a request came from, waiting up to `timeoutMs` for its own event to arrive when
+     * the adapter has not seen it yet; undefined when that event names none or never comes.
+     */
+    pageFor(key: string, timeoutMs: number, signal?: AbortSignal): Promise<string | undefined>;
+    /** Whether a paused request is the card request of an armed profile the merchant's own total prices. */
+    priced(url: string): boolean;
+    /** The capture the client reads for a card request that paused at `pausedAt`. */
+    capture(pausedAt: number, page: string | undefined): MerchantTotalCapture;
+    /**
+     * The read at release. Resolves when the card request may go out; otherwise retires the
+     * approval (the card never left this browser, so merchant_never_retried, which stops the
+     * API serving its ciphertext) and throws. The retirement is awaited: once the API confirms
+     * it, a MerchantTotalError at stage 'release'; when it does not (or this vault cannot
+     * retire), the approved row may still serve its ciphertext, so a PaymentOutcomeUnknownError
+     * ('authorization_cancel_unconfirmed') the application must reconcile, as every retirement
+     * the API did not confirm ends. `merchant_total_held` says which (`retired`).
+     */
+    release(replay: MerchantHostedReplay, vault: Canceller | undefined, signal?: AbortSignal): Promise<void>;
+    /**
+     * The merchant answered the continued card request (both adapters call this when its
+     * final answer arrives, whatever the profile's after-payment rules read): after a short
+     * settle for the rest of its confirmation, report what it says it charged, once per
+     * approval. The approval counts as reported only once the API took the report. One that
+     * could not go out (no confirmation read yet, or the report request failed) is tried again
+     * after each of MERCHANT_CHARGE_RETRY_DELAYS_MS; after the last, a confirmation the log reads
+     * within MERCHANT_CHARGE_REPORT_WINDOW_MS of the answer is still reported (lateConfirmation).
+     * The first attempt keeps a Node process alive, since the confirmation may already be read;
+     * later ones do not. Never throws; each outcome is an event, and `merchant_charge_unreported`
+     * says whether another attempt follows (`retrying`).
+     */
+    answered(replay: MerchantHostedReplay, vault: ChargeReporter | undefined): void;
+    /** A newly read answer: each approval's confirmation that came after its last attempt is reported now, under that approval. */
+    private lateConfirmation;
+    /** One report attempt, `tries` into its retries; never rejects. */
+    private attempt;
+}
+export {};

package/dist/merchant-total-watch.js

@@ -0,0 +1,268 @@
+import { MerchantTotalError, PaymentOutcomeUnknownError } from './client.js';
+import { MERCHANT_CHARGE_SETTLE_MS, MERCHANT_LOG_TEXT_MAX, MERCHANT_TOTAL_WAIT_MS, MerchantExchangeLog, merchantChargeReport, merchantProfilePricedBySource, merchantTotalAtRelease, } from './merchant-total.js';
+import { MERCHANT_PROFILE_RECOGNIZERS } from './adyen-merchant-hosted.generated.js';
+/** Every profile this build reviewed that the merchant's own responses price. */
+const PRICED_IDS = MERCHANT_PROFILE_RECOGNIZERS
+    .map((profile) => profile.id).filter((id) => merchantProfilePricedBySource(id));
+/** How many request pages are remembered, oldest dropped first. */
+const PAGES_MAX = 512;
+/**
+ * How long a paused card request's page is waited for. Chromium can deliver a request's
+ * Network event (which names its document) after the Fetch pause; it follows within
+ * milliseconds, so this bound only matters when it never comes, and the read then has no page.
+ */
+export const MERCHANT_PAGE_WAIT_MS = 1_000;
+/**
+ * The pauses before the after-payment report is tried again when it could not go out (no
+ * confirmation read yet, or the report request failed): a confirmation the page asks for
+ * after the card request's answer (Dick's order submit) still gets reported.
+ */
+export const MERCHANT_CHARGE_RETRY_DELAYS_MS = [1_000, 3_000, 10_000];
+/** How long after the merchant answered a confirmation that arrives late is still reported. */
+export const MERCHANT_CHARGE_REPORT_WINDOW_MS = 10 * 60_000;
+/** How many approvals the watch remembers as reported, or as waiting for a late confirmation. */
+const REPORTS_MAX = 16;
+/**
+ * The merchant's own total around one attached page, shared by the CDP and Playwright
+ * adapters so both read it the same way (merchant-total.ts says what it proves). From
+ * attach on, the adapter tells it about every request that leaves, every answer and every
+ * failure; it keeps, read-only, the ones a priced profile's rules read at the origins they
+ * read (a client's sandbox declaration moves a profile's to its declared endpoint), and
+ * the page each request came from. At a pause it hands the client a capture; at release it
+ * reads the total again and holds the card request unless it is still the approved amount;
+ * once the merchant answered the continued request it reports what the merchant says it
+ * charged.
+ */
+export class MerchantTotalWatch {
+    onEvent;
+    vault;
+    waitMs;
+    settleMs;
+    retryDelaysMs;
+    log;
+    pages = new Map();
+    pageWaiters = new Map();
+    /** Approvals whose charge report the API took (the newest REPORTS_MAX). */
+    reported = new Set();
+    /** Approvals a report attempt is running or scheduled for. */
+    reporting = new Set();
+    /**
+     * Approvals still waiting for their report (the newest REPORTS_MAX), each with until when a
+     * confirmation that comes late reports it. One per approval, so a second payment on the
+     * same page never takes the first one's place.
+     */
+    awaiting = new Map();
+    constructor(onEvent, vault, waitMs = MERCHANT_TOTAL_WAIT_MS, settleMs = MERCHANT_CHARGE_SETTLE_MS, retryDelaysMs = MERCHANT_CHARGE_RETRY_DELAYS_MS) {
+        this.onEvent = onEvent;
+        this.vault = vault;
+        this.waitMs = waitMs;
+        this.settleMs = settleMs;
+        this.retryDelaysMs = retryDelaysMs;
+        // A client's declarations are fixed when it is built (VaultClientOptions.sandboxMerchants),
+        // so where each priced profile is read is settled once, here.
+        const scopes = PRICED_IDS.map((id) => {
+            let endpoint;
+            try {
+                endpoint = typeof vault?.merchantProfile === 'function' ? vault.merchantProfile(id)?.sandboxDeclaration?.endpoint : undefined;
+            }
+            catch {
+                endpoint = undefined;
+            }
+            return typeof endpoint === 'string' ? { id, declaredEndpoint: endpoint } : id;
+        });
+        // Every answer the log reads can be a confirmation that came after the report's last attempt.
+        this.log = new MerchantExchangeLog(() => scopes, Date.now, MERCHANT_LOG_TEXT_MAX, () => this.lateConfirmation());
+    }
+    /** A request left: remember its page, and record it when a priced profile's rules read it. */
+    sent(key, request) {
+        if (request.page) {
+            this.pages.delete(key);
+            this.pages.set(key, request.page);
+            while (this.pages.size > PAGES_MAX)
+                this.pages.delete(this.pages.keys().next().value);
+        }
+        this.log.sent(key, request);
+        // A pause waiting for this request's page learns it now (or that its event names none).
+        for (const waiter of [...(this.pageWaiters.get(key) ?? [])])
+            waiter();
+    }
+    /** The page a request came from, when the adapter named one. */
+    pageOf(key) {
+        return this.pages.get(key);
+    }
+    /**
+     * The page a request came from, waiting up to `timeoutMs` for its own event to arrive when
+     * the adapter has not seen it yet; undefined when that event names none or never comes.
+     */
+    async pageFor(key, timeoutMs, signal) {
+        const known = this.pages.get(key);
+        if (known !== undefined || timeoutMs <= 0 || signal?.aborted)
+            return known;
+        await new Promise((resolve) => {
+            const waiters = this.pageWaiters.get(key) ?? new Set();
+            const done = () => {
+                clearTimeout(timer);
+                waiters.delete(done);
+                if (waiters.size === 0 && this.pageWaiters.get(key) === waiters)
+                    this.pageWaiters.delete(key);
+                signal?.removeEventListener('abort', done);
+                resolve();
+            };
+            const timer = setTimeout(done, timeoutMs);
+            waiters.add(done);
+            this.pageWaiters.set(key, waiters);
+            signal?.addEventListener('abort', done, { once: true });
+        });
+        return this.pages.get(key);
+    }
+    /** Whether a paused request is the card request of an armed profile the merchant's own total prices. */
+    priced(url) {
+        try {
+            const profile = typeof this.vault?.merchantProfileOf === 'function' ? this.vault.merchantProfileOf(url) : null;
+            return !!profile && merchantProfilePricedBySource(profile.id);
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The capture the client reads for a card request that paused at `pausedAt`. */
+    capture(pausedAt, page) {
+        return this.log.capture(pausedAt, page, this.waitMs);
+    }
+    /**
+     * The read at release. Resolves when the card request may go out; otherwise retires the
+     * approval (the card never left this browser, so merchant_never_retried, which stops the
+     * API serving its ciphertext) and throws. The retirement is awaited: once the API confirms
+     * it, a MerchantTotalError at stage 'release'; when it does not (or this vault cannot
+     * retire), the approved row may still serve its ciphertext, so a PaymentOutcomeUnknownError
+     * ('authorization_cancel_unconfirmed') the application must reconcile, as every retirement
+     * the API did not confirm ends. `merchant_total_held` says which (`retired`).
+     */
+    async release(replay, vault, signal) {
+        if (!replay.merchantTotal)
+            return;
+        const refusal = await merchantTotalAtRelease(this.log, replay.profile, replay.merchantTotal, Date.now(), this.waitMs, signal);
+        if (!refusal)
+            return;
+        let retired = false;
+        if (typeof vault?.cancelAuthorization === 'function') {
+            try {
+                await vault.cancelAuthorization(replay.authorizationId, 'merchant_never_retried');
+                retired = true;
+            }
+            catch {
+                retired = false;
+            }
+        }
+        this.onEvent?.({ type: 'merchant_total_held', detail: { authorizationId: replay.authorizationId, profile: replay.profile, reason: refusal.code, retired } });
+        if (!retired)
+            throw new PaymentOutcomeUnknownError(replay.authorizationId, 'authorization_cancel_unconfirmed');
+        throw new MerchantTotalError(replay.authorizationId, 'merchant_total_changed', 'release', refusal.code, `The card request was held: ${refusal.reason}`);
+    }
+    /**
+     * The merchant answered the continued card request (both adapters call this when its
+     * final answer arrives, whatever the profile's after-payment rules read): after a short
+     * settle for the rest of its confirmation, report what it says it charged, once per
+     * approval. The approval counts as reported only once the API took the report. One that
+     * could not go out (no confirmation read yet, or the report request failed) is tried again
+     * after each of MERCHANT_CHARGE_RETRY_DELAYS_MS; after the last, a confirmation the log reads
+     * within MERCHANT_CHARGE_REPORT_WINDOW_MS of the answer is still reported (lateConfirmation).
+     * The first attempt keeps a Node process alive, since the confirmation may already be read;
+     * later ones do not. Never throws; each outcome is an event, and `merchant_charge_unreported`
+     * says whether another attempt follows (`retrying`).
+     */
+    answered(replay, vault) {
+        const id = replay.authorizationId;
+        if (!replay.merchantTotal || this.reported.has(id) || this.reporting.has(id))
+            return;
+        this.awaiting.delete(id);
+        this.awaiting.set(id, { replay, vault, until: Date.now() + MERCHANT_CHARGE_REPORT_WINDOW_MS });
+        while (this.awaiting.size > REPORTS_MAX)
+            this.awaiting.delete(this.awaiting.keys().next().value);
+        this.reporting.add(id);
+        setTimeout(() => { void this.attempt(replay, vault, 0); }, this.settleMs);
+    }
+    /** A newly read answer: each approval's confirmation that came after its last attempt is reported now, under that approval. */
+    lateConfirmation() {
+        const now = Date.now();
+        for (const [id, awaiting] of [...this.awaiting]) {
+            if (this.reported.has(id) || now > awaiting.until || !awaiting.replay.merchantTotal) {
+                this.awaiting.delete(id);
+                continue;
+            }
+            if (this.reporting.has(id))
+                continue;
+            let readable = false;
+            try {
+                readable = merchantChargeReport(this.log, awaiting.replay.profile, awaiting.replay.merchantTotal) !== null;
+            }
+            catch {
+                readable = false;
+            }
+            if (!readable)
+                continue;
+            this.reporting.add(id);
+            void this.attempt(awaiting.replay, awaiting.vault, this.retryDelaysMs.length);
+        }
+    }
+    /** One report attempt, `tries` into its retries; never rejects. */
+    async attempt(replay, vault, tries) {
+        const id = replay.authorizationId;
+        const approved = replay.merchantTotal;
+        const detail = { authorizationId: id, profile: replay.profile };
+        let retrying = false;
+        try {
+            if (!approved)
+                return;
+            // The confirmation's text is read after it finished: wait (bounded) for every answer
+            // the after-payment rules read, then report what arrived.
+            await this.log.settle(replay.profile, 'charged', approved.card, Date.now(), this.waitMs).catch(() => { });
+            const report = merchantChargeReport(this.log, replay.profile, approved);
+            let reason;
+            if (!report)
+                reason = 'no_confirmation_read';
+            else if (typeof vault?.reportMerchantCharge !== 'function')
+                reason = 'no_reporter';
+            else {
+                let result = null;
+                try {
+                    result = await vault.reportMerchantCharge(id, report);
+                }
+                catch {
+                    result = null;
+                }
+                if (result) {
+                    this.reported.add(id);
+                    while (this.reported.size > REPORTS_MAX)
+                        this.reported.delete(this.reported.values().next().value);
+                    this.awaiting.delete(id);
+                    this.onEvent?.({ type: 'merchant_charge_reported', detail: { ...detail, verdict: result.verdict, alerted: result.alerted } });
+                    return;
+                }
+                reason = 'report_failed';
+            }
+            // Only a confirmation still to come can change a missing one; a failed report or a
+            // missing reporter is not tried again by a later answer.
+            if (reason !== 'no_confirmation_read')
+                this.awaiting.delete(id);
+            // No reporter never changes, so it is not tried again at all.
+            retrying = reason !== 'no_reporter' && tries < this.retryDelaysMs.length;
+            this.onEvent?.({ type: 'merchant_charge_unreported', detail: { ...detail, reason, retrying } });
+            if (retrying)
+                later(() => { void this.attempt(replay, vault, tries + 1); }, this.retryDelaysMs[tries]);
+        }
+        catch {
+            // A report never breaks the page: an attempt that threw is the last one.
+            retrying = false;
+        }
+        finally {
+            if (!retrying)
+                this.reporting.delete(id);
+        }
+    }
+}
+/** A timer that never keeps a Node process alive on its own: a retry of the report is best effort. */
+function later(run, ms) {
+    const timer = setTimeout(run, ms);
+    timer.unref?.();
+}