@visa/cli 4.1.0-rc.26 → 4.1.0-rc.260

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,7 +74,136 @@ 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;
+/**
+ * How many times one fill pass may re-detect after a locator goes stale.
+ *
+ * One re-mount usually invalidates a whole block of fields at once, so a single
+ * pass normally recovers all of them. The cap is here so a page that re-mounts
+ * on EVERY keystroke degrades to the old timeout behaviour instead of looping.
+ */
+const MAX_FILL_REDETECTS = 3;
+/**
+ * True when a detected field's locator no longer resolves to anything.
+ *
+ * `data-ca-id` is stamped onto the live nodes during detection, so it is an
+ * identity that dies with the node. A merchant that re-mounts part of its form
+ * mid-fill (address autocomplete is the common one) replaces those nodes with
+ * fresh, unstamped ones — the old locator then matches NOTHING and the fill
+ * waits out its entire timeout on an element that can never appear.
+ */
+async function locatorIsMissing(page, entry) {
+    try {
+        return (await resolveLocator(page, entry).count()) === 0;
+    }
+    catch {
+        // A frame that went away, a detached context: let the fill run and report
+        // the real error rather than inventing a diagnosis here.
+        return false;
+    }
+}
+/**
+ * Contact and address roles — plain inputs whose value can be read straight
+ * back. The credential roles are deliberately absent: they sit in PSP iframes
+ * that tokenize and reformat what they are given, so a readback there compares
+ * against a value the merchant never promised to keep, and they are not what an
+ * address re-mount disturbs anyway.
+ */
+const READBACK_ROLES = [
+    'name',
+    'nameFirst',
+    'nameLast',
+    'email',
+    'phone',
+    'addressLine1',
+    'addressLine2',
+    'city',
+    'state',
+    'postalCode',
+    'country',
+];
+/**
+ * Downgrade any field whose value did not survive to the end of the pass.
+ *
+ * Only runs when a re-mount was actually observed, and only for the roles
+ * above. A page that rebuilds its address block on EVERY edit erases the field
+ * we just filled when we fill the NEXT one, so a fill can report success over a
+ * box that is empty by the time anyone submits it. Recovering from a re-mount
+ * must not buy that recovery with a false claim: without this, the engine would
+ * hand the pre-submit gate a clean bill of health for an empty form — and the
+ * gate would let it through. Before the recovery existed these fields failed
+ * loudly instead, and a wrong "filled" is worse than an honest refusal.
+ */
+async function downgradeFieldsThatDidNotHold(page, fields, filled) {
+    for (const record of filled) {
+        if (!record.ok)
+            continue;
+        if (!READBACK_ROLES.includes(record.role))
+            continue;
+        const entry = fields[record.role];
+        if (!entry)
+            continue;
+        let held;
+        try {
+            const loc = resolveLocator(page, entry);
+            held = (await loc.count()) > 0 && (await loc.inputValue()).trim() !== '';
+        }
+        catch {
+            // Unreadable is not evidence of empty. Leave the record alone rather than
+            // failing a field that is probably fine.
+            continue;
+        }
+        if (held)
+            continue;
+        record.ok = false;
+        record.error = 'value did not survive a re-render of the form';
+    }
+}
 async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
     const base = {
         role,
@@ -97,66 +227,77 @@ 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 detect = opts.detect ?? detectFields;
     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.
+    //
+    // A job records the ROLE it fills, never a captured entry: the entry is
+    // resolved from the live map at the moment the job runs, because a re-mount
+    // part-way through this pass can replace the element a role points at.
+    // `value` is derived from that same entry, since whether a role is a <select>
+    // (and which options it offers) is a property of the element we end up with.
     const jobs = [];
-    const add = (role, entry, value, display) => {
-        if (!entry)
-            return;
-        // Skip fields that are not currently visible (e.g. a collapsed accordion
-        // panel or a not-yet-reached step). The executor reveals them and re-fills.
-        if (entry.visible === false)
+    const add = (role, detected, value, display) => {
+        // Gate on the role having been detected at all. Roles absent from the
+        // original map stay out of scope even if a later pass would find them.
+        if (!detected)
             return;
-        jobs.push({
-            role,
-            entry,
-            run: async () => fillOne(page, role, entry, value(), display(), fillTimeoutMs),
-        });
+        jobs.push({ role, value, display });
     };
-    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) {
-        const e = fields.expCombined;
-        const v = expCombinedValue(e, credential.expMonth, credential.expYear);
-        add('expCombined', e, () => v, () => maskExpiry());
-    }
-    if (fields.expMonth) {
-        const e = fields.expMonth;
-        const value = e.tag === 'select'
+    if (credential && fields.expCombined) {
+        add('expCombined', fields.expCombined, (e) => expCombinedValue(e, credential.expMonth, credential.expYear), () => maskExpiry());
+    }
+    if (credential && fields.expMonth) {
+        add('expMonth', fields.expMonth, (e) => e.tag === 'select'
             ? (monthOptionValue(e.options ?? [], credential.expMonth) ?? pad2(credential.expMonth))
-            : pad2(credential.expMonth);
-        add('expMonth', e, () => value, () => maskExpiry());
-    }
-    if (fields.expYear) {
-        const e = fields.expYear;
-        let value;
-        if (e.tag === 'select') {
-            value = yearOptionValue(e.options ?? [], credential.expYear) ?? String(credential.expYear);
-        }
-        else if ((e.maxlength ?? 0) === 2) {
-            value = pad2(credential.expYear % 100);
-        }
-        else {
-            value = String(credential.expYear);
-        }
-        add('expYear', e, () => value, () => maskExpiry());
+            : pad2(credential.expMonth), () => maskExpiry());
+    }
+    if (credential && fields.expYear) {
+        add('expYear', fields.expYear, (e) => {
+            if (e.tag === 'select') {
+                return yearOptionValue(e.options ?? [], credential.expYear) ?? String(credential.expYear);
+            }
+            if ((e.maxlength ?? 0) === 2)
+                return pad2(credential.expYear % 100);
+            return String(credential.expYear);
+        }, () => maskExpiry());
     }
     // Contact / shipping. Display values are always redacted: these are PII and
     // 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)
@@ -166,25 +307,202 @@ export async function fillFieldMap(page, fields, credential, contact, opts = {})
     if (contact.postalCode)
         add('postalCode', fields.postalCode, () => contact.postalCode, () => redactContact('postalCode', contact.postalCode));
     if (fields.state && contact.state) {
-        const e = fields.state;
         const wanted = contact.state;
-        const value = e.tag === 'select' ? (matchOption(e.options ?? [], [wanted]) ?? wanted) : wanted;
-        add('state', e, () => value, () => redactContact('state', value));
+        add('state', fields.state, (e) => (e.tag === 'select' ? (matchOption(e.options ?? [], [wanted]) ?? wanted) : wanted), (value) => redactContact('state', value));
     }
     if (fields.country && contact.country) {
-        const e = fields.country;
-        const value = e.tag === 'select'
-            ? (matchOption(e.options ?? [], [contact.country]) ?? contact.country)
-            : contact.country;
-        add('country', e, () => value, () => redactContact('country', value));
+        const wanted = contact.country;
+        add('country', fields.country, (e) => (e.tag === 'select' ? (matchOption(e.options ?? [], [wanted]) ?? wanted) : wanted), (value) => redactContact('country', value));
     }
-    for (const j of jobs) {
-        const r = await j.run();
-        if (r)
-            filled.push(r);
+    // The map is re-read per job, and a re-detect REPLACES it wholesale rather
+    // than patching the one entry that went stale: a detection pass re-stamps
+    // every element from scratch, so an id handed out by the previous pass can
+    // afterwards name a different element. Adopting the fresh map for every
+    // remaining job is what keeps a recovery from filling the wrong box.
+    let current = fields;
+    let redetects = 0;
+    for (const job of jobs) {
+        let entry = current[job.role];
+        // Skip fields that are not currently visible (e.g. a collapsed accordion
+        // panel or a not-yet-reached step). The executor reveals them and re-fills.
+        if (!entry || entry.visible === false)
+            continue;
+        let relocated = false;
+        if (redetects < MAX_FILL_REDETECTS && (await locatorIsMissing(page, entry))) {
+            redetects++;
+            const fresh = await detect(page).then((r) => r.fields, () => null);
+            if (fresh) {
+                current = fresh;
+                const next = current[job.role];
+                if (next && next.visible !== false) {
+                    entry = next;
+                    relocated = true;
+                }
+                // If the role is gone from the fresh map, deliberately keep the stale
+                // entry and let the fill fail on it. Skipping would leave NO record of
+                // the field, and the pre-submit gate reads "never attempted" as
+                // "nothing to worry about" — which is how an incomplete form gets
+                // submitted. A recorded failure refuses; a silent skip does not.
+            }
+        }
+        const value = job.value(entry);
+        const result = await fillOne(page, job.role, entry, value, job.display(value), fillTimeoutMs);
+        filled.push(relocated ? { ...result, relocated: true } : result);
     }
+    // Only when a re-mount was actually seen: everywhere else the page never
+    // moved under us and the readback would be pure cost.
+    if (redetects > 0)
+        await downgradeFieldsThatDidNotHold(page, current, filled);
     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 +510,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,80 @@
+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 type ShopifyCheckoutSurface = {
+    signal: string;
+    subtype: 'recognition' | 'authentication' | 'wallet';
+};
+export type ShopifyGuestCheckoutResult = {
+    status: 'guest-ready';
+    signal: 'guest-card-form';
+} | {
+    status: 'transitioned';
+    signal: string;
+} | {
+    status: 'action-required';
+    signal: string;
+    detail: string;
+};
+export declare function detectShopifyCheckoutSurface(page: Page): Promise<ShopifyCheckoutSurface | null>;
+/**
+ * Resolve Shopify's reversible Shop-wallet takeover before review. The helper
+ * only clicks an exact guest action or a scoped accessible close control inside
+ * a positively identified Shop surface. It never solves authentication, uses a
+ * Shop-saved payment method, force-clicks, or mutates the DOM.
+ */
+export declare function ensureShopifyGuestCheckout(page: Page, options?: {
+    timeoutMs?: number;
+    stableMs?: number;
+}): Promise<ShopifyGuestCheckoutResult>;
+/** Read-only assertion for the irreversible credential boundary. */
+export declare function assertShopifyGuestCheckout(page: Page): Promise<ShopifyGuestCheckoutResult>;
+/**
+ * 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 {};