@visa/cli 4.1.0-rc.17 → 4.1.0-rc.171

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');
@@ -73,6 +74,51 @@ export function scrubFillErrorMessage(message, value) {
         scrubbed = scrubbed.split(value).join('<redacted>');
     return scrubbed;
 }
+/**
+ * A fill failure in a few words, for a message a human reads.
+ *
+ * Playwright's error is a multi-line call log — useful in the evidence file,
+ * unreadable in a refusal message and in the receipt an operator opens a week
+ * later. The refusal names WHICH fields refused; without this it never says
+ * WHY, so diagnosing a merchant we cannot drive means either reproducing it or
+ * reading someone's evidence JSON. Each cause maps to a different fix:
+ *
+ *   not editable      — the input exists but is readonly/disabled at fill time
+ *                       (a custom widget owning the value, or a not-yet-ready
+ *                       form). Typing will not help; the field needs an adapter
+ *                       or a longer wait.
+ *   not a text field  — a non-input element pretending to be one. Needs an
+ *                       adapter that drives the widget.
+ *   not visible /
+ *   detached          — a re-render race. The reveal loop is the lever.
+ *
+ * Input is already scrubbed by scrubFillErrorMessage; this only ever shortens.
+ */
+export function summarizeFillFailure(error) {
+    if (!error)
+        return 'no reason recorded';
+    if (/not an? <input>|not.*\[contenteditable\]/i.test(error))
+        return 'not a text field';
+    if (/element is not visible/i.test(error))
+        return 'not visible';
+    if (/not attached to the DOM|detached/i.test(error))
+        return 'detached from the page';
+    if (/element is not enabled/i.test(error))
+        return 'disabled';
+    if (/not editable/i.test(error)) {
+        const timeout = /Timeout (\d+)ms exceeded/i.exec(error);
+        return timeout
+            ? `not editable within ${Math.round(Number(timeout[1]) / 1000)}s`
+            : 'not editable';
+    }
+    if (/Timeout (\d+)ms exceeded/i.test(error)) {
+        const timeout = /Timeout (\d+)ms exceeded/i.exec(error);
+        return `timed out after ${Math.round(Number(timeout[1]) / 1000)}s`;
+    }
+    // Unrecognized: the first line, bounded. Better a clipped real message than a
+    // confident wrong summary.
+    return error.split('\n')[0].slice(0, 120);
+}
 const DEFAULT_FILL_TIMEOUT_MS = 5000;
 async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
     const base = {
@@ -97,13 +143,24 @@ async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
         return { ...base, ok: false, error: scrubFillErrorMessage(err.message, value) };
     }
 }
-// The shared fill routine used by every adapter. Takes an already-detected
-// FieldMap so the executor controls when detection runs.
-export async function fillFieldMap(page, fields, credential, contact, opts = {}) {
+/**
+ * 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 first = contact.firstName ?? credential.cardholderName.split(/\s+/)[0] ?? credential.cardholderName;
-    const last = contact.lastName ?? credential.cardholderName.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 = [];
@@ -120,26 +177,31 @@ export async function fillFieldMap(page, fields, credential, contact, opts = {})
             run: async () => fillOne(page, role, entry, value(), display(), fillTimeoutMs),
         });
     };
-    add('number', fields.number, () => credential.pan, () => maskPan(credential.pan));
-    add('cvc', fields.cvc, () => credential.cvc, () => maskCvc(credential.cvc));
-    add('name', fields.name, () => credential.cardholderName, () => redactContact('name', credential.cardholderName));
-    add('nameFirst', fields.nameFirst, () => first, () => redactContact('nameFirst', first));
-    add('nameLast', fields.nameLast, () => last, () => redactContact('nameLast', last));
+    if (credential) {
+        add('number', fields.number, () => credential.pan, () => maskPan(credential.pan));
+        add('cvc', fields.cvc, () => credential.cvc, () => maskCvc(credential.cvc));
+    }
+    if (fullName)
+        add('name', fields.name, () => fullName, () => redactContact('name', fullName));
+    if (first)
+        add('nameFirst', fields.nameFirst, () => first, () => redactContact('nameFirst', first));
+    if (last)
+        add('nameLast', fields.nameLast, () => last, () => redactContact('nameLast', last));
     // Expiry display values are always redacted: the expiry is part of the
     // keyable credential (DPAN + expiry + DAVV) and never enters the log.
-    if (fields.expCombined) {
+    if (credential && fields.expCombined) {
         const e = fields.expCombined;
         const v = expCombinedValue(e, credential.expMonth, credential.expYear);
         add('expCombined', e, () => v, () => maskExpiry());
     }
-    if (fields.expMonth) {
+    if (credential && fields.expMonth) {
         const e = fields.expMonth;
         const value = e.tag === 'select'
             ? (monthOptionValue(e.options ?? [], credential.expMonth) ?? pad2(credential.expMonth))
             : pad2(credential.expMonth);
         add('expMonth', e, () => value, () => maskExpiry());
     }
-    if (fields.expYear) {
+    if (credential && fields.expYear) {
         const e = fields.expYear;
         let value;
         if (e.tag === 'select') {
@@ -157,6 +219,8 @@ export async function fillFieldMap(page, fields, credential, contact, opts = {})
     // the evidence log is built to be persistable.
     if (contact.email)
         add('email', fields.email, () => contact.email, () => redactContact('email', contact.email));
+    if (contact.phone)
+        add('phone', fields.phone, () => contact.phone, () => redactContact('phone', contact.phone));
     if (contact.addressLine1)
         add('addressLine1', fields.addressLine1, () => contact.addressLine1, () => redactContact('addressLine1', contact.addressLine1));
     if (contact.addressLine2)
@@ -185,6 +249,154 @@ export async function fillFieldMap(page, fields, credential, contact, opts = {})
     }
     return filled;
 }
+// Credential-free contact prefill for merchants that must calculate shipping,
+// tax, and the final total before a human reviews the payment.
+export async function fillContactFieldMap(page, fields, contact, opts = {}) {
+    return fillFields(page, fields, null, contact, opts);
+}
+// The shared post-approval fill routine used by every adapter.
+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) {
@@ -192,10 +404,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/index.d.ts

@@ -2,6 +2,9 @@ import type { DetectResult } from '../detect.js';
 import type { CheckoutAdapter } from './generic.js';
 export type { CheckoutAdapter } from './generic.js';
 export { GenericAdapter } from './generic.js';
+export { ShopifyAdapter } from './shopify.js';
 export { StripeLikeAdapter } from './stripe-like.js';
 export { fillFieldMap, resolveLocator } from './generic.js';
-export declare function selectAdapter(detected: DetectResult): CheckoutAdapter;
+export declare function selectAdapter(detected: DetectResult, pageKind?: {
+    shopify?: boolean;
+}): CheckoutAdapter;

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

@@ -2,14 +2,21 @@
 // the universal fallback and always matches last. Selection is a pure
 // function of an already-run detection — adapters never re-detect.
 import { GenericAdapter } from './generic.js';
+import { ShopifyAdapter } from './shopify.js';
 import { StripeLikeAdapter } from './stripe-like.js';
 export { GenericAdapter } from './generic.js';
+export { ShopifyAdapter } from './shopify.js';
 export { StripeLikeAdapter } from './stripe-like.js';
 export { fillFieldMap, resolveLocator } from './generic.js';
-const SPECIFIC = [new StripeLikeAdapter()];
 const FALLBACK = new GenericAdapter();
-export function selectAdapter(detected) {
-    for (const a of SPECIFIC) {
+export function selectAdapter(detected, pageKind = {}) {
+    // Shopify owns the outer checkout form and can still delegate card fields to
+    // an iframe, so it gets first crack and reuses fillFieldMap for both.
+    const shopify = new ShopifyAdapter(detected);
+    if (pageKind.shopify === true)
+        return shopify;
+    const specific = [shopify, new StripeLikeAdapter()];
+    for (const a of specific) {
         if (a.matches(detected))
             return a;
     }

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

@@ -0,0 +1,55 @@
+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, FilledField } from '../types.js';
+import { type CheckoutAdapter } from './generic.js';
+type ShopifySummary = {
+    subtotalMinor: number | null;
+    shippingMinor: number | null;
+    taxMinor: number | null;
+    discountMinor: number;
+    totalMinor: number | null;
+    currency: string | null;
+    verified: boolean;
+};
+export declare function parseShopifySummary(text: string): ShopifySummary;
+export declare function readShopifyAmount(page: Page, requireVerified: boolean): Promise<PageAmountRead>;
+export declare function readStableShopifyAmount(page: Page, timeoutMs?: number): Promise<PageAmountRead>;
+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;
+    constructor(detected: DetectResult);
+    matches(detected: DetectResult): boolean;
+    prepareContact(page: Page, contact: Contact): Promise<FillResult>;
+    fill(page: Page, _fields: FieldMap, credential: CardCredential, _contact: Contact): Promise<FillResult>;
+}
+export {};