@agent-cards/checkout 0.1.0 → 0.2.0

package/dist/client.js

@@ -1,4 +1,11 @@
-import { BUILTIN_REGISTRY, findRecognizer } from './registry.js';
+import { BUILTIN_REGISTRY, cardUrlPatterns as deriveCardUrlPatterns, findRecognizer, } from './registry.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'];
+const AMOUNT_AUTHORITIES = ['stripe_payment_intent', 'hosted_form_sum', 'display_only'];
 export class CardEncryptedError extends Error {
     psp;
     constructor(psp) {
@@ -8,17 +15,200 @@ export class CardEncryptedError extends Error {
         this.name = 'CardEncryptedError';
     }
 }
+/**
+ * The API approved an authorization in a mode this SDK build cannot finish.
+ * Unreachable by construction (syncRegistry asks only for SUPPORTED_MODES and
+ * every create names its mode), so it is treated as terminal: retrying the
+ * same page could only raise more prompts for the same dead end.
+ */
+export class UnsupportedModeError extends Error {
+    mode;
+    constructor(mode) {
+        super(`the authorization was approved in 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 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.';
+    }
+}
+/**
+ * The cardholder's device sent the card and the processor refused it
+ * outright (a card decline, a bad CVC, an invalid request). Nothing was
+ * charged; the authorization is `declined` with reason `processor_refused`
+ * and the processor's own code in `pspErrorCode` (Stripe's `card_declined`,
+ * `incorrect_cvc`, …). A decline like any other for the adapters: the paused
+ * request is aborted and the page's retry gets a fresh approval, where the
+ * person can pick another card.
+ */
+export class ProcessorRefusedError extends ApprovalDeclinedError {
+    authorizationId;
+    pspErrorCode;
+    code = 'processor_refused';
+    constructor(authorizationId, pspErrorCode) {
+        super('processor_refused');
+        this.authorizationId = authorizationId;
+        this.pspErrorCode = pspErrorCode;
+        this.name = 'ProcessorRefusedError';
+        this.message = `the processor refused the card on ${authorizationId}${pspErrorCode ? ` (${pspErrorCode})` : ''}. Nothing was charged.`;
+    }
+}
+/**
+ * A non-2xx from the Agentcard API, carrying the status so callers can tell a
+ * misconfiguration from a blip. The adapters use this to decide whether
+ * retrying is worth anything: a 404 `connection_not_found` will answer the same
+ * way forever, while a 429 or a 502 will not.
+ */
+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;
+        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];
 export class VaultClient {
     opts;
     baseUrl;
     fetch;
     pollIntervalMs;
+    unverifiableRetryDelaysMs;
     registry;
     constructor(opts) {
         this.opts = opts;
@@ -26,14 +216,21 @@ export class VaultClient {
         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');
+            raw = await this.get(`/v2/checkout/recognizers?modes=${SUPPORTED_MODES.join(',')}`);
         }
         catch {
             return;
@@ -50,6 +247,20 @@ export class VaultClient {
     isCardRequest(url, method = 'POST') {
         return method.toUpperCase() === 'POST' && findRecognizer(url, this.registry) !== 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);
+    }
     /**
      * 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
@@ -58,34 +269,171 @@ export class VaultClient {
     async authorize(input) {
         const rec = findRecognizer(input.request.url, this.registry);
         if (!rec)
-            throw new Error(`not a known tokenization endpoint: ${input.request.url}`);
-        if (rec.clientSideEncrypted)
+            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 (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 travels as a display string, a number with its currency, or
+        // both. Refuse half a pair here, before a network call: the API would too,
+        // and a retry loop cannot fix a missing field.
+        const hasCents = input.amountCents != null;
+        const hasCurrency = typeof input.currency === 'string' && input.currency.length > 0;
+        if (hasCents !== hasCurrency) {
+            throw new Error('amountCents and currency go together: pass both or neither.');
+        }
+        if (!input.amount && !hasCents) {
+            throw new Error('authorize needs amount (a display string), or amountCents with currency.');
+        }
         const timeoutMs = input.timeoutMs ?? 15 * 60_000;
-        const created = await this.post('/v2/checkout/authorizations', {
+        const created = await this.createAuthorization({
             user: input.user,
             merchant: input.merchant,
-            amount: input.amount,
+            ...(input.amount ? { amount: input.amount } : {}),
+            // snake_case on the wire; camelCase is this SDK's convention.
+            ...(hasCents ? { amount_cents: input.amountCents, currency: input.currency } : {}),
             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 } : {}),
             request: {
                 url: input.request.url,
                 method: input.request.method,
                 headers: pickHeaders(input.request.headers, rec.passthroughHeaders),
                 body: input.request.body,
             },
-        });
+        }, input.currency);
         input.onApprovalUrl?.(created.approvalUrl);
+        const authorizationId = String(created.id);
         const deadline = Date.now() + timeoutMs;
         while (Date.now() < deadline) {
             await sleep(this.pollIntervalMs);
-            const s = await this.get(`/v2/checkout/authorizations/${created.id}`);
-            if (s.status === 'approved')
-                return s.response;
-            if (s.status === 'declined')
+            const s = await this.get(`/v2/checkout/authorizations/${authorizationId}`);
+            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 (not permanent: the next poll,
+                // or request, may carry it).
+                const mode = typeof s.mode === 'string' ? s.mode : 'token';
+                if (mode !== 'hosted_form')
+                    throw new Error(`malformed authorization ${authorizationId}: submitted_on_device on mode ${mode}`);
+                if (typeof s.submitted_at !== 'string' || !s.submitted_at) {
+                    throw new Error(`malformed hosted_form submission on authorization ${authorizationId}: no submitted_at`);
+                }
+                return { mode: 'hosted_form', kind: 'submitted_on_device', outcome: 'unverified', authorizationId, submittedAt: s.submitted_at, ...amountAuthority };
+            }
+            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 Error(`malformed authorization ${authorizationId}: a hosted_form authorization finishes as submitted_on_device, never approved`);
+                }
+                if (approvedMode === 'cse') {
+                    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 Error(`malformed substitutions on approved authorization ${authorizationId}`);
+                    // `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 Error(`malformed substitutions.remove on approved authorization ${authorizationId}`);
+                    }
+                    return {
+                        mode: 'cse',
+                        authorizationId,
+                        substitutions: {
+                            encoding: 'json',
+                            at: sub.at,
+                            fields: { ...sub.fields },
+                            ...(removeRaw ? { remove: [...removeRaw] } : {}),
+                        },
+                        ...amountAuthority,
+                    };
+                }
+                if (approvedMode !== 'token')
+                    throw new UnsupportedModeError(approvedMode);
+                const response = s.response;
+                return {
+                    mode: 'token',
+                    authorizationId,
+                    ...response,
+                    amountVerified: typeof s.amount_verified === 'boolean' ? s.amount_verified : null,
+                    chargedAmountCents: typeof s.charged_amount_cents === 'number' ? s.charged_amount_cents : 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,
+                };
+            }
+            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 (s.reason === 'processor_refused') {
+                    throw new ProcessorRefusedError(String(created.id), typeof s.psp_error_code === 'string' ? s.psp_error_code : null);
+                }
                 throw new ApprovalDeclinedError(s.reason ?? 'no reason given');
+            }
         }
         throw new ApprovalTimeoutError(timeoutMs);
     }
+    /**
+     * 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) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.post('/v2/checkout/authorizations', payload);
+            }
+            catch (err) {
+                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 = err instanceof CheckoutApiError && err.status === 502
+                    && (err.code === 'amount_unverifiable' || err.code === 'cse_key_unavailable');
+                if (!retryable || attempt >= this.unverifiableRetryDelaysMs.length)
+                    throw err;
+                await sleep(this.unverifiableRetryDelaysMs[attempt]);
+            }
+        }
+    }
     // --- auth: client_credentials, cached until just before it expires --------
     token = null;
     inflight = null;
@@ -136,7 +484,7 @@ export class VaultClient {
             return this.call(path, init, true);
         }
         if (!r.ok)
-            throw new Error(`agentcard ${path} -> ${r.status} ${await r.text()}`);
+            throw new CheckoutApiError(r.status, path, await r.text());
         return r.json();
     }
     post(path, body) {

package/dist/hosted-form.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The hosted_form half of a replay: what the paused navigation is resolved
+ * with once the cardholder's device has submitted the processor's own form.
+ *
+ * On a hosted-form processor (Tranzila) the paused request is a top-level
+ * form navigation inside the processor's iframe, not an XHR. The cardholder's
+ * device rebuilds that form with the real card and submits it itself, so the
+ * processor's answer (approved, declined) is shown on the device and reaches
+ * the merchant from the processor. The agent's browser never gets it.
+ *
+ * The paused navigation still has to resolve to SOMETHING. Aborting it is the
+ * wrong something: an aborted navigation renders no error page, the iframe
+ * silently stays on the dummy-card form, and the agent's natural next move is
+ * to click Pay again. A fake copy of the processor's result page is wrong too:
+ * this SDK does not know the outcome or the merchant's contract, so it must
+ * not claim one. What it CAN say is exactly what happened: the cardholder
+ * completed this payment on their own device, do not resubmit, confirm the
+ * order with the merchant. This page says that, for a person and for an
+ * agent, and nothing else.
+ */
+export interface HostedFormSubmittedPageInput {
+    /** The approved authorization (`cauth_…`). */
+    authorizationId: string;
+    /** The merchant name the authorization was created with. */
+    merchant: string;
+    /** When the device reported the form left it (ISO 8601). */
+    submittedAt: string;
+}
+export interface SyntheticPage {
+    status: 200;
+    headers: Record<string, string>;
+    body: string;
+}
+/** The outcome word on the page, the header and the JSON: one spelling everywhere. */
+export declare const HOSTED_FORM_SUBMITTED_OUTCOME = "submitted_on_device";
+/**
+ * A self-contained HTML document: no external resources, no script that runs
+ * (the one `<script>` is `application/json`, inert by type), machine-readable
+ * through the meta tag, the header and the JSON block, and human-readable in
+ * one paragraph. `merchant` is integrator text and lands escaped; inside the
+ * JSON every `<`, `>` and `&` is a \u escape (still valid JSON), so a merchant
+ * name can never close the script block early or open a comment inside it.
+ */
+export declare function hostedFormSubmittedPage(input: HostedFormSubmittedPageInput): SyntheticPage;

package/dist/hosted-form.js

@@ -0,0 +1,78 @@
+/**
+ * The hosted_form half of a replay: what the paused navigation is resolved
+ * with once the cardholder's device has submitted the processor's own form.
+ *
+ * On a hosted-form processor (Tranzila) the paused request is a top-level
+ * form navigation inside the processor's iframe, not an XHR. The cardholder's
+ * device rebuilds that form with the real card and submits it itself, so the
+ * processor's answer (approved, declined) is shown on the device and reaches
+ * the merchant from the processor. The agent's browser never gets it.
+ *
+ * The paused navigation still has to resolve to SOMETHING. Aborting it is the
+ * wrong something: an aborted navigation renders no error page, the iframe
+ * silently stays on the dummy-card form, and the agent's natural next move is
+ * to click Pay again. A fake copy of the processor's result page is wrong too:
+ * this SDK does not know the outcome or the merchant's contract, so it must
+ * not claim one. What it CAN say is exactly what happened: the cardholder
+ * completed this payment on their own device, do not resubmit, confirm the
+ * order with the merchant. This page says that, for a person and for an
+ * agent, and nothing else.
+ */
+/** The outcome word on the page, the header and the JSON: one spelling everywhere. */
+export const HOSTED_FORM_SUBMITTED_OUTCOME = 'submitted_on_device';
+function escapeHtml(s) {
+    return String(s)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+/**
+ * A self-contained HTML document: no external resources, no script that runs
+ * (the one `<script>` is `application/json`, inert by type), machine-readable
+ * through the meta tag, the header and the JSON block, and human-readable in
+ * one paragraph. `merchant` is integrator text and lands escaped; inside the
+ * JSON every `<`, `>` and `&` is a \u escape (still valid JSON), so a merchant
+ * name can never close the script block early or open a comment inside it.
+ */
+export function hostedFormSubmittedPage(input) {
+    const merchant = String(input.merchant ?? '');
+    const record = {
+        outcome: HOSTED_FORM_SUBMITTED_OUTCOME,
+        // In words, so an agent reading this block cannot take it for a receipt:
+        // the cardholder's device attested the form left it, nothing more.
+        payment: 'unverified',
+        attested_by: 'cardholder_device',
+        authorization_id: String(input.authorizationId),
+        merchant,
+        submitted_at: String(input.submittedAt),
+        next: "poll the merchant's order state; never resubmit",
+    };
+    const json = JSON.stringify(record).replace(/</g, '\\u003c').replace(/>/g, '\\u003e').replace(/&/g, '\\u0026');
+    const body = [
+        '<!doctype html>',
+        '<html lang="en">',
+        '<head>',
+        '<meta charset="utf-8">',
+        `<meta name="agentcard-checkout" content="${HOSTED_FORM_SUBMITTED_OUTCOME}">`,
+        '<meta name="robots" content="noindex">',
+        '<title>Submitted on the cardholder\'s device</title>',
+        '</head>',
+        '<body>',
+        `<p>The cardholder submitted this payment from their own device. Agentcard holds no evidence of the processor's answer: this is not a receipt. Do not resubmit this form. Confirm the order with the merchant${merchant ? ` (${escapeHtml(merchant)})` : ''}.</p>`,
+        `<script type="application/json" id="agentcard-checkout">${json}</script>`,
+        '</body>',
+        '</html>',
+        '',
+    ].join('\n');
+    return {
+        status: 200,
+        headers: {
+            'content-type': 'text/html; charset=utf-8',
+            'cache-control': 'no-store',
+            'x-agentcard-checkout': HOSTED_FORM_SUBMITTED_OUTCOME,
+        },
+        body,
+    };
+}

package/dist/index.d.ts

@@ -1,6 +1,10 @@
-export { VaultClient, CardEncryptedError, ApprovalTimeoutError, ApprovalDeclinedError } from './client.js';
-export type { PausedRequest, ReplayResponse, AuthorizeInput, VaultClientOptions } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, } from './client.js';
+export type { PausedRequest, ReplayResponse, TokenReplay, CseReplay, HostedFormReplay, AmountAuthority, AuthorizeInput, VaultClientOptions, } from './client.js';
 export { attachToCdp, attachToPlaywright } from './cdp.js';
 export type { CdpLike, AttachOptions } from './cdp.js';
-export { BUILTIN_REGISTRY, findRecognizer } from './registry.js';
-export type { Recognizer } from './registry.js';
+export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
+export type { Substitutions } from './substitute.js';
+export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
+export type { HostedFormSubmittedPageInput, SyntheticPage } from './hosted-form.js';
+export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';
+export type { Recognizer, CheckoutMode } from './registry.js';

package/dist/index.js

@@ -1,3 +1,5 @@
-export { VaultClient, CardEncryptedError, ApprovalTimeoutError, ApprovalDeclinedError } from './client.js';
+export { VaultClient, CardEncryptedError, UnsupportedModeError, ApprovalTimeoutError, ApprovalDeclinedError, AmountMismatchError, IntentNotConfirmableError, ProcessorRefusedError, CheckoutApiError, redactUrl, SUPPORTED_MODES, } from './client.js';
 export { attachToCdp, attachToPlaywright } from './cdp.js';
-export { BUILTIN_REGISTRY, findRecognizer } from './registry.js';
+export { substituteEncryptedFields, SubstitutionError } from './substitute.js';
+export { hostedFormSubmittedPage, HOSTED_FORM_SUBMITTED_OUTCOME } from './hosted-form.js';
+export { BUILTIN_REGISTRY, cardUrlPatterns, findRecognizer } from './registry.js';