@visa/cli 4.1.0-rc.154 → 4.1.0-rc.156

package/dist/checkout-engine/adapters/generic.d.ts

@@ -10,12 +10,54 @@ export interface CheckoutAdapter {
 }
 export declare function resolveLocator(page: Page, entry: FieldEntry): Locator;
 export declare function scrubFillErrorMessage(message: string, value: string): string;
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export declare function contactNameShapes(contact: Contact, cardholderName?: string): {
+    fullName?: string;
+    first?: string;
+    last?: string;
+};
 export declare function fillContactFieldMap(page: Page, fields: FieldMap, contact: Contact, opts?: {
     fillTimeoutMs?: number;
 }): Promise<FilledField[]>;
 export declare function fillFieldMap(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact, opts?: {
     fillTimeoutMs?: number;
 }): Promise<FilledField[]>;
+/**
+ * Re-detect and adopt fresh entries for every card field after the panel is
+ * unfolded. Injected for tests; the executor's own detector is used in
+ * production.
+ */
+export declare function refreshCardGroupFromPage(page: Page, fields: FieldMap, detect?: (page: Page) => Promise<DetectResult>): Promise<string[]>;
+/**
+ * Reveal card fields that a checkout keeps collapsed until a payment method is
+ * chosen.
+ *
+ * `fillFields` skips any entry with `visible === false`, so a card-number input
+ * sitting inside a folded panel is never even attempted — the generic adapter
+ * then reports `ok: false` ("fill incomplete") without having typed anything.
+ * That is the correct default: filling an invisible input is how a credential
+ * gets typed into the wrong place. But a payment-method `<select>` guarding the
+ * card panel is common enough to be worth handling, and the recovery is a
+ * single deterministic interaction rather than a guess.
+ *
+ * We only ever SELECT a card option — never a wallet, bank transfer, or
+ * anything else — and we only act when the card field is already detected but
+ * hidden. If nothing changes, the caller proceeds exactly as before and still
+ * fails closed.
+ *
+ * Mutates `fields.number.visible` on success so the subsequent fill attempts
+ * the field it just revealed.
+ */
+export declare function revealCollapsedCardSection(page: Page, fields: FieldMap, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    revealed: boolean;
+    via: string | null;
+}>;
 export declare class GenericAdapter implements CheckoutAdapter {
     name: string;
     matches(_detected: DetectResult): boolean;

package/dist/checkout-engine/adapters/generic.js

@@ -2,6 +2,7 @@
 // <select> dropdowns, handles split vs combined expiry, two- vs four-digit
 // years, and split first/last name. It is the fallback that should beat any
 // well-behaved guest checkout on its own.
+import { detectFields } from '../detect.js';
 import { maskCvc, maskExpiry, maskPan, redactContact } from '../evidence.js';
 function pad2(n) {
     return String(n).padStart(2, '0');
@@ -97,12 +98,24 @@ async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
         return { ...base, ok: false, error: scrubFillErrorMessage(err.message, value) };
     }
 }
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export function contactNameShapes(contact, cardholderName) {
+    const fullName = contact.fullName ??
+        (contact.firstName && contact.lastName
+            ? `${contact.firstName} ${contact.lastName}`
+            : cardholderName);
+    const first = contact.firstName ?? (fullName?.split(/\s+/)[0] || undefined);
+    const last = contact.lastName ?? (fullName?.split(/\s+/).slice(1).join(' ') || undefined);
+    return { fullName, first, last };
+}
 async function fillFields(page, fields, credential, contact, opts = {}) {
     const fillTimeoutMs = opts.fillTimeoutMs ?? DEFAULT_FILL_TIMEOUT_MS;
     const filled = [];
-    const fullName = contact.fullName ?? credential?.cardholderName;
-    const first = contact.firstName ?? fullName?.split(/\s+/)[0];
-    const last = contact.lastName ?? fullName?.split(/\s+/).slice(1).join(' ');
+    const { fullName, first, last } = contactNameShapes(contact, credential?.cardholderName);
     // Order matters a little: contact/name before card is harmless, but we fill
     // card fields explicitly per role so order is not load-bearing.
     const jobs = [];
@@ -200,6 +213,145 @@ export async function fillContactFieldMap(page, fields, contact, opts = {}) {
 export async function fillFieldMap(page, fields, credential, contact, opts = {}) {
     return fillFields(page, fields, credential, contact, opts);
 }
+/** Option text that identifies a card-paying choice, most specific first. */
+const CARD_OPTION_PATTERNS = [
+    /^\s*visa\s*$/i,
+    /credit\s*card|card\s*payment/i,
+    /^\s*(mastercard|master\s*card)\s*$/i,
+    /\bcard\b/i,
+];
+/**
+ * Attribute selectors for a card-number input that survive a panel re-render,
+ * tried in order. The originally detected locator is tried first so a page that
+ * does NOT re-render keeps its higher-confidence match.
+ */
+const CARD_NUMBER_FALLBACK_SELECTORS = [
+    'input[autocomplete="cc-number"]',
+    'input[name*="creditcardnumber" i]',
+    'input[name*="cardnumber" i]',
+    'input[id*="cardnumber" i]',
+    'input[name*="cc-number" i]',
+];
+/** First selector that resolves to a visible input, or null if none do. */
+async function firstVisibleCardNumberLocator(page, detectedLocator, timeoutMs) {
+    for (const selector of [detectedLocator, ...CARD_NUMBER_FALLBACK_SELECTORS]) {
+        try {
+            await page
+                .locator(selector)
+                .first()
+                .waitFor({ state: 'visible', timeout: Math.max(500, Math.floor(timeoutMs / 3)) });
+            return selector;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/** Card-credential roles that share the panel a payment select unfolds. */
+const CARD_GROUP_ROLES = ['number', 'cvc', 'expCombined', 'expMonth', 'expYear'];
+/**
+ * Re-detect and adopt fresh entries for every card field after the panel is
+ * unfolded. Injected for tests; the executor's own detector is used in
+ * production.
+ */
+export async function refreshCardGroupFromPage(page, fields, detect = detectFields) {
+    let fresh;
+    try {
+        fresh = (await detect(page)).fields;
+    }
+    catch {
+        return [];
+    }
+    const adopted = [];
+    for (const role of CARD_GROUP_ROLES) {
+        const next = fresh[role];
+        if (!next || next.visible === false)
+            continue;
+        const current = fields[role];
+        // Only ever replace an entry we could not have filled anyway. A field that
+        // is already visible was detected against the live DOM and keeps its
+        // higher-confidence match.
+        if (current && current.visible !== false)
+            continue;
+        fields[role] = next;
+        adopted.push(role);
+    }
+    return adopted;
+}
+/**
+ * Reveal card fields that a checkout keeps collapsed until a payment method is
+ * chosen.
+ *
+ * `fillFields` skips any entry with `visible === false`, so a card-number input
+ * sitting inside a folded panel is never even attempted — the generic adapter
+ * then reports `ok: false` ("fill incomplete") without having typed anything.
+ * That is the correct default: filling an invisible input is how a credential
+ * gets typed into the wrong place. But a payment-method `<select>` guarding the
+ * card panel is common enough to be worth handling, and the recovery is a
+ * single deterministic interaction rather than a guess.
+ *
+ * We only ever SELECT a card option — never a wallet, bank transfer, or
+ * anything else — and we only act when the card field is already detected but
+ * hidden. If nothing changes, the caller proceeds exactly as before and still
+ * fails closed.
+ *
+ * Mutates `fields.number.visible` on success so the subsequent fill attempts
+ * the field it just revealed.
+ */
+export async function revealCollapsedCardSection(page, fields, opts = {}) {
+    const number = fields.number;
+    if (!number || number.visible !== false)
+        return { revealed: false, via: null };
+    const timeoutMs = opts.timeoutMs ?? 5_000;
+    const selects = page.locator('select');
+    const count = await selects.count().catch(() => 0);
+    for (let i = 0; i < Math.min(count, 12); i++) {
+        const select = selects.nth(i);
+        // Read option labels through the locator API rather than page.evaluate.
+        // A bundled build rewrites the function passed to evaluate() and the
+        // injected helper is not defined in page scope, so it throws at runtime —
+        // silently, once a catch treats it as "this select didn't match". Staying
+        // on the locator API keeps this working in source and bundled alike.
+        let labels;
+        try {
+            labels = await select.locator('option').allTextContents();
+        }
+        catch {
+            continue;
+        }
+        for (const pattern of CARD_OPTION_PATTERNS) {
+            const label = labels.map((l) => l.trim()).find((l) => l && pattern.test(l));
+            if (!label)
+                continue;
+            try {
+                await select.selectOption({ label }, { timeout: timeoutMs });
+            }
+            catch {
+                continue;
+            }
+            // Re-acquire the field instead of waiting on the detected locator.
+            // Unfolding the panel typically re-renders it, and the detector's
+            // synthetic `data-ca-id` attribute does not survive that — waiting on the
+            // old locator times out even though the field is now on screen and
+            // fillable. Stable attribute selectors survive the re-render.
+            const revealedLocator = await firstVisibleCardNumberLocator(page, number.locator, timeoutMs);
+            if (!revealedLocator)
+                continue;
+            number.locator = revealedLocator;
+            number.visible = true;
+            // The number is not alone in that panel: cvc and expiry were re-rendered
+            // with it and still carry stale, invisible entries. Filling only the
+            // number would trade "adapter fill incomplete" for "credential fill
+            // incomplete: missing cvc, expiry" — still a failed purchase, still after
+            // a credential was minted. Re-detect and adopt fresh entries for the
+            // whole card group.
+            await refreshCardGroupFromPage(page, fields);
+            return { revealed: true, via: label };
+        }
+    }
+    return { revealed: false, via: null };
+}
 export class GenericAdapter {
     name = 'generic';
     matches(_detected) {
@@ -207,10 +359,17 @@ export class GenericAdapter {
         return true;
     }
     async fill(page, fields, credential, contact) {
+        const reveal = await revealCollapsedCardSection(page, fields);
         const filled = await fillFieldMap(page, fields, credential, contact);
+        const ok = filled.some((f) => f.role === 'number' && f.ok);
         return {
-            ok: filled.some((f) => f.role === 'number' && f.ok),
+            ok,
             filled,
+            ...(ok || !reveal.revealed
+                ? {}
+                : {
+                    detail: `revealed the card section via "${reveal.via}" but the number field still did not fill`,
+                }),
         };
     }
 }

package/dist/checkout-engine/adapters/shopify.d.ts

@@ -2,7 +2,7 @@ import type { Page } from 'playwright-core';
 import { type PageAmountRead } from '../amount.js';
 import { type DetectResult, type FieldMap } from '../detect.js';
 import type { CardCredential } from '../instrument.js';
-import type { Contact, FillResult } from '../types.js';
+import type { Contact, FillResult, FilledField } from '../types.js';
 import { type CheckoutAdapter } from './generic.js';
 type ShopifySummary = {
     subtotalMinor: number | null;
@@ -20,6 +20,30 @@ export declare function isShopifyCheckoutPage(page: Page): Promise<boolean>;
 export declare function detectShopifyChallenge(page: Page): Promise<{
     signal: string;
 } | null>;
+/**
+ * The en-US variant of a localized Shopify checkout URL, or null when it is
+ * already English (or not locale-suffixed). Shopify renders the checkout in
+ * the URL's trailing locale segment, and amount reconciliation reads the
+ * order summary by its ENGLISH labels — a store whose primary market is not
+ * English serves /checkouts/cn/<token>/<locale> and the total never parses
+ * (observed live 2026-08-16: /es-us rendered "Precio total" and the review
+ * refused fail-closed on a good checkout). The locale segment is
+ * presentation-only: swapping it keeps the same checkout session and token.
+ */
+export declare function shopifyEnglishCheckoutUrl(current: string): string | null;
+export declare function missingContactRoles(filled: FilledField[], expected: string[]): string[];
+/**
+ * The contact surface to prefill. Shipping fields when the checkout has them —
+ * but a digital-goods (no-shipping) Shopify checkout renders exactly one
+ * address block and marks every field autocomplete="billing ..." (observed
+ * live 2026-08-16: all 18 candidates billing-classified, so the shipping map
+ * came back empty and the prefill reported every role missing). That billing
+ * block IS the primary contact surface, under its base roles.
+ */
+export declare function contactPrefillFieldMap(detected: DetectResult): {
+    fields: FieldMap;
+    surface: 'shipping' | 'billing-only';
+};
 export declare class ShopifyAdapter implements CheckoutAdapter {
     private readonly detected;
     name: string;

package/dist/checkout-engine/adapters/shopify.js

@@ -43,11 +43,23 @@ export function parseShopifySummary(text) {
     const discountMinor = parse(uniqueValue('discount', 'discounts')) ?? 0;
     const totalText = uniqueValue('total');
     const totalMinor = parse(totalText);
-    const verified = subtotalMinor != null &&
-        shippingMinor != null &&
-        taxMinor != null &&
-        totalMinor != null &&
-        subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor;
+    // A digital-goods checkout renders no component rows at all — just a total
+    // ("Cost summary / Total / USD $6.00", observed live 2026-08-16), so there
+    // is nothing to reconcile against and a parsed total stands on its own. The
+    // moment ANY component label parsed by SUMMARY_LABELS appears — including a
+    // pending "Calculated at next step" — the full reconciliation is required again,
+    // so a mid-render pre-tax total still refuses.
+    // The discount-code entry form puts a bare "Discount" label on every
+    // checkout, value or not, and discount already defaults to 0 — only the
+    // additive components force reconciliation.
+    const componentLabelPresent = [...values.keys()].some((key) => key !== 'total' && key !== 'discount' && key !== 'discounts');
+    const verified = componentLabelPresent
+        ? subtotalMinor != null &&
+            shippingMinor != null &&
+            taxMinor != null &&
+            totalMinor != null &&
+            subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor
+        : totalMinor != null;
     return {
         subtotalMinor,
         shippingMinor,
@@ -145,6 +157,30 @@ export async function detectShopifyChallenge(page) {
     }
     return null;
 }
+/**
+ * The en-US variant of a localized Shopify checkout URL, or null when it is
+ * already English (or not locale-suffixed). Shopify renders the checkout in
+ * the URL's trailing locale segment, and amount reconciliation reads the
+ * order summary by its ENGLISH labels — a store whose primary market is not
+ * English serves /checkouts/cn/<token>/<locale> and the total never parses
+ * (observed live 2026-08-16: /es-us rendered "Precio total" and the review
+ * refused fail-closed on a good checkout). The locale segment is
+ * presentation-only: swapping it keeps the same checkout session and token.
+ */
+export function shopifyEnglishCheckoutUrl(current) {
+    let url;
+    try {
+        url = new URL(current);
+    }
+    catch {
+        return null;
+    }
+    const match = url.pathname.match(/^(\/checkouts\/[^?#]+\/)([a-z]{2,3}(?:-[a-z0-9]+)*)(\/?)$/i);
+    if (!match || match[2].toLowerCase().startsWith('en'))
+        return null;
+    url.pathname = `${match[1]}en-us${match[3]}`;
+    return url.toString();
+}
 const BILLING_ROLES = new Set([
     'name',
     'nameFirst',
@@ -370,10 +406,62 @@ function requiredAddressRoles(address, prefix = '') {
         ...(address.country ? [role('country')] : []),
     ];
 }
-function missingRoles(filled, expected) {
-    const successful = new Set(filled.filter((field) => field.ok).map((field) => field.role));
+/**
+ * A checkout renders ONE name shape (a single full-name input, or first/last)
+ * while the contact record may carry the other, so the expected role and the
+ * filled role can disagree while the page is completely filled. Either shape
+ * satisfies the name requirement; same for the billing-prefixed variants.
+ */
+function withNameEquivalence(successful) {
+    const out = new Set(successful);
+    for (const [full, first, last] of [
+        ['name', 'nameFirst', 'nameLast'],
+        ['billingName', 'billingNameFirst', 'billingNameLast'],
+    ]) {
+        if (out.has(first) && out.has(last))
+            out.add(full);
+        if (out.has(full)) {
+            out.add(first);
+            out.add(last);
+        }
+    }
+    return out;
+}
+export function missingContactRoles(filled, expected) {
+    const successful = withNameEquivalence(new Set(filled.filter((field) => field.ok).map((field) => field.role)));
     return expected.filter((role) => !successful.has(role));
 }
+function hasAddressRole(fields) {
+    return Boolean(fields.addressLine1 ?? fields.city ?? fields.postalCode);
+}
+/**
+ * The contact surface to prefill. Shipping fields when the checkout has them —
+ * but a digital-goods (no-shipping) Shopify checkout renders exactly one
+ * address block and marks every field autocomplete="billing ..." (observed
+ * live 2026-08-16: all 18 candidates billing-classified, so the shipping map
+ * came back empty and the prefill reported every role missing). That billing
+ * block IS the primary contact surface, under its base roles.
+ */
+export function contactPrefillFieldMap(detected) {
+    const shipping = shippingFieldMap(detected);
+    if (hasAddressRole(shipping))
+        return { fields: shipping, surface: 'shipping' };
+    const fields = {};
+    for (const candidate of detected.candidates) {
+        const role = candidate.role;
+        if (!role || !CONTACT_ROLES.has(role) || !candidate.meta.visible)
+            continue;
+        if (isPaymentCandidate(candidate))
+            continue;
+        const entry = entryFromCandidate(candidate);
+        if (!entry)
+            continue;
+        const existing = fields[role];
+        if (!existing || entry.confidence > existing.confidence)
+            fields[role] = entry;
+    }
+    return { fields, surface: 'billing-only' };
+}
 export class ShopifyAdapter {
     detected;
     name = 'shopify';
@@ -384,15 +472,18 @@ export class ShopifyAdapter {
         return detected.candidates.some(isShopifyCandidate);
     }
     async prepareContact(page, contact) {
-        const shippingFilled = await fillContactFieldMap(page, shippingFieldMap(this.detected), contact);
+        const { fields: contactFields, surface } = contactPrefillFieldMap(this.detected);
+        const shippingFilled = await fillContactFieldMap(page, contactFields, contact);
         const shippingExpected = [...requiredAddressRoles(contact), ...(contact.phone ? ['phone'] : [])];
-        const shippingMissing = missingRoles(shippingFilled, shippingExpected);
-        if (!contact.billingAddress) {
+        const shippingMissing = missingContactRoles(shippingFilled, shippingExpected);
+        if (surface === 'billing-only' || !contact.billingAddress) {
             return {
                 ok: shippingMissing.length === 0,
                 filled: shippingFilled,
                 ...(shippingMissing.length
-                    ? { detail: `Shopify shipping prefill incomplete: missing ${shippingMissing.join(', ')}` }
+                    ? {
+                        detail: `Shopify ${surface === 'billing-only' ? 'contact' : 'shipping'} prefill incomplete: missing ${shippingMissing.join(', ')}`,
+                    }
                     : {}),
             };
         }
@@ -406,7 +497,7 @@ export class ShopifyAdapter {
         const billingFields = billingFieldMap(await detectFields(page));
         const billingFilled = labelBillingEvidence(await fillContactFieldMap(page, billingFields, billingContact(contact.billingAddress)));
         const billingExpected = requiredAddressRoles(contact.billingAddress, 'billing');
-        const missing = [...shippingMissing, ...missingRoles(billingFilled, billingExpected)];
+        const missing = [...shippingMissing, ...missingContactRoles(billingFilled, billingExpected)];
         return {
             ok: missing.length === 0,
             filled: [...shippingFilled, ...billingFilled],

package/dist/checkout-engine/cli-engine.d.ts

@@ -34,6 +34,10 @@ export type CliReviewInput = {
     cardTokenId?: string;
     /** Exact request-key identity selected by the caller. */
     agentJkt?: string;
+    /** Owner-facing selected-agent label for the compact local receipt. */
+    agentName?: string;
+    /** Safe display suffix derived from the selected card grant label. */
+    cardLast4?: string;
     contact: Contact;
     approvalBaseUrl: string;
     merchantName?: string;

package/dist/checkout-engine/cli-engine.js

@@ -99,6 +99,9 @@ export function classifyCardDrawVerdictFailure(err) {
  * grant on every draw. Nothing here authorizes anything.
  */
 async function resolveCardInstrument(input) {
+    if (typeof input.cardTokenId === 'string' && input.cardTokenId.trim()) {
+        return { tokenId: input.cardTokenId.trim(), source: 'card-grant' };
+    }
     let credential = null;
     let readError = null;
     try {
@@ -110,9 +113,6 @@ async function resolveCardInstrument(input) {
     if (credential && typeof credential.tokenId === 'string' && credential.tokenId.trim()) {
         return credential;
     }
-    if (typeof input.cardTokenId === 'string' && input.cardTokenId.trim()) {
-        return { tokenId: input.cardTokenId, source: 'card-grant' };
-    }
     throw new Error('no card instrument is available to this runtime: there is no usable credential at ' +
         `${input.credentialPath} and no activated card:vic grant token was supplied. Run ` +
         '`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait` to ' +
@@ -917,6 +917,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     merchant: {
                         name: session.target.merchantName,
                         host: new URL(session.target.merchantUrl).hostname,
+                        url: session.target.merchantUrl,
                     },
                     transaction: {
                         amount: session.target.transactionAmount,
@@ -925,6 +926,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     },
                     result,
                     vicConfirmation,
+                    agentName: input.agentName,
+                    cardLast4: input.cardLast4,
                 }));
                 if (report.written)
                     receiptPath = report.path;

package/dist/checkout-engine/confirmed-merchants.js

@@ -23,28 +23,36 @@ import { RECEIPT_DIR } from './receipt-dir.js';
 /**
  * The URL a receipt's charge happened at.
  *
- * The receipt's top-level merchant block records the HOST only, on purpose: a
- * full checkout URL can carry cart/session identifiers, so it stays out of the
- * shareable summary. The evidence log still holds it (the executor's first
- * 'navigation' step is the page the run opened), so recover it from there and
- * fall back to the host when the evidence is absent or shaped differently.
+ * A compact v2 receipt carries an exact checkout URL only when it is already in
+ * the curated identity map; otherwise it carries the host. Legacy v1 receipts
+ * keep the URL in the evidence log (the executor's first 'navigation' step is
+ * the page the run opened), so recover it there and fall back to the host when
+ * that evidence is absent or shaped differently.
  */
 function checkoutUrlOf(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const checkoutUrl = receipt.merchant.checkoutUrl;
+        return checkoutUrl && KNOWN_MERCHANT_IDENTITIES[checkoutUrl]
+            ? checkoutUrl
+            : `https://${receipt.merchant.host}/`;
+    }
     const navigation = receipt.evidence.steps.find((step) => step?.type === 'navigation');
     const data = navigation?.data;
     const url = typeof data === 'object' && data !== null ? data.url : undefined;
     return typeof url === 'string' && url.length > 0 ? url : `https://${receipt.merchant.host}/`;
 }
 function isConfirmedCompletion(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        return receipt.outcome === 'confirmed' && receipt.network.confirmation === 'APPROVED';
+    }
     return (receipt.outcome === 'confirmed' &&
         receipt.vicConfirmation?.posted === true &&
         receipt.vicConfirmation.transactionStatus === 'APPROVED');
 }
 /**
- * Parse one receipt file, or null when it is not a v1 receipt this module can
- * read. Deliberately permissive about everything the grouping does not touch:
- * the file was written by an older or newer engine and only has to carry the
- * fields read below.
+ * Parse one supported receipt file, or null when its fields cannot safely feed
+ * the registry. Deliberately permissive about everything the grouping does not
+ * touch: older and newer engines only have to carry the fields read below.
  */
 function parseReceipt(json) {
     let parsed;
@@ -57,19 +65,40 @@ function parseReceipt(json) {
     if (typeof parsed !== 'object' || parsed === null)
         return null;
     const receipt = parsed;
-    if (receipt.schema !== 'checkout-agent-receipt/v1')
-        return null;
-    if (typeof receipt.recordedAt !== 'string')
-        return null;
-    if (typeof receipt.merchant?.host !== 'string')
-        return null;
-    if (typeof receipt.transaction?.amount !== 'string')
-        return null;
-    if (typeof receipt.transaction?.currency !== 'string')
-        return null;
-    if (!Array.isArray(receipt.evidence?.steps))
-        return null;
-    return receipt;
+    if (receipt.schema === 'checkout-agent-receipt/v1') {
+        const v1 = receipt;
+        if (typeof v1.recordedAt !== 'string')
+            return null;
+        if (typeof v1.merchant?.host !== 'string')
+            return null;
+        if (typeof v1.transaction?.amount !== 'string')
+            return null;
+        if (typeof v1.transaction?.currency !== 'string')
+            return null;
+        if (!Array.isArray(v1.evidence?.steps))
+            return null;
+        return v1;
+    }
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const v2 = receipt;
+        if (typeof v2.recordedAt !== 'string')
+            return null;
+        if (typeof v2.merchant?.host !== 'string')
+            return null;
+        if (v2.merchant.checkoutUrl !== null && typeof v2.merchant.checkoutUrl !== 'string')
+            return null;
+        if (typeof v2.transaction?.amount !== 'string')
+            return null;
+        if (typeof v2.transaction?.currency !== 'string')
+            return null;
+        if (v2.network?.confirmation !== null &&
+            v2.network?.confirmation !== 'APPROVED' &&
+            v2.network?.confirmation !== 'DECLINED') {
+            return null;
+        }
+        return v2;
+    }
+    return null;
 }
 /**
  * Merchants this device has completed a real card checkout at, newest first.

package/dist/checkout-engine/executor.d.ts

@@ -5,6 +5,7 @@ import type { Instrument } from './instrument.js';
 import type { Contact, OtpResolver } from './types.js';
 import { EvidenceLog } from './evidence.js';
 import { type ObservedOutcome } from './outcome.js';
+import { type WebBotAuthConfig } from './web-bot-auth.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 export type CheckoutMode = 'dry-run' | 'submit';
 export type CheckoutOutcome = 'reviewed-dry-run'
@@ -35,6 +36,7 @@ export type PrepareCheckoutOptions = {
     amountMinor?: number;
     currency?: string;
     debugShotsDir?: string;
+    webBotAuth?: WebBotAuthConfig | null;
 };
 export type RunCheckoutOptions = PrepareCheckoutOptions & {
     instrument: Instrument;