@visa/cli 4.1.0-rc.21 → 4.1.0-rc.211

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

@@ -0,0 +1,514 @@
+// Shopify checkout adapter. Shopify commonly renders shipping first and keeps
+// a distinct billing address collapsed behind a radio/checkbox. Detection runs
+// once before adapter selection, so this adapter reuses the detected candidate
+// locators, reveals the billing surface, and fills it without a second scan.
+import { minorFromDecimal, pageCurrency } from '../amount.js';
+import { detectFields, } from '../detect.js';
+import { fillContactFieldMap, fillFieldMap } from './generic.js';
+const SUMMARY_LABELS = /^(Subtotal|Shipping|Estimated taxes|Taxes|Tax|Discounts?|Total)(?:\s*:?\s+((?:[A-Z]{3}\s+)?-?[$€£]?\s*\d[\d.,]*|Free))?$/i;
+function valueAfterLabel(lines, index, inline) {
+    if (inline)
+        return inline;
+    return lines.slice(index + 1, index + 4).find((line) => /\d|free/i.test(line)) ?? '';
+}
+export function parseShopifySummary(text) {
+    const lines = text
+        .split(/\n+/)
+        .map((line) => line.replace(/\s+/g, ' ').trim())
+        .filter(Boolean);
+    const values = new Map();
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = lines[index].match(SUMMARY_LABELS);
+        if (!match)
+            continue;
+        const key = match[1].toLowerCase();
+        const value = valueAfterLabel(lines, index, match[2]);
+        values.set(key, [...(values.get(key) ?? []), value]);
+    }
+    const uniqueValue = (...keys) => {
+        const found = keys.flatMap((key) => values.get(key) ?? []).filter(Boolean);
+        const unique = [...new Set(found)];
+        return unique.length === 1 ? unique[0] : undefined;
+    };
+    const parse = (value) => {
+        if (!value)
+            return null;
+        if (/\bfree\b/i.test(value))
+            return 0;
+        return minorFromDecimal(value);
+    };
+    const subtotalMinor = parse(uniqueValue('subtotal'));
+    const shippingMinor = parse(uniqueValue('shipping'));
+    const taxMinor = parse(uniqueValue('estimated taxes', 'taxes', 'tax'));
+    const discountMinor = parse(uniqueValue('discount', 'discounts')) ?? 0;
+    const totalText = uniqueValue('total');
+    const totalMinor = parse(totalText);
+    // 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,
+        taxMinor,
+        discountMinor,
+        totalMinor,
+        currency: pageCurrency(totalText ?? ''),
+        verified,
+    };
+}
+export async function readShopifyAmount(page, requireVerified) {
+    const text = await page.evaluate(() => document.body?.innerText ?? '').catch(() => '');
+    const summary = parseShopifySummary(text);
+    if (summary.totalMinor == null) {
+        return /\btotal\b/i.test(text)
+            ? { kind: 'unreadable', reason: 'Shopify total is present but unreadable' }
+            : { kind: 'none' };
+    }
+    if (requireVerified && !summary.verified) {
+        return {
+            kind: 'unreadable',
+            reason: 'Shopify tax and total do not form a complete, reconciled summary',
+        };
+    }
+    return {
+        kind: 'ok',
+        amountMinor: summary.totalMinor,
+        currency: summary.currency,
+        source: 'shopify-summary',
+    };
+}
+export async function readStableShopifyAmount(page, timeoutMs = 6_000) {
+    const startedAt = Date.now();
+    let previous = '';
+    let stableReads = 0;
+    while (Date.now() - startedAt < timeoutMs) {
+        const latest = await readShopifyAmount(page, true);
+        const fingerprint = JSON.stringify(latest);
+        stableReads = fingerprint === previous ? stableReads + 1 : 0;
+        if (latest.kind === 'ok' && stableReads >= 1)
+            return latest;
+        previous = fingerprint;
+        await page.waitForTimeout(200);
+    }
+    return {
+        kind: 'unreadable',
+        reason: 'Shopify tax and total did not settle before the review deadline',
+    };
+}
+export async function isShopifyCheckoutPage(page) {
+    return page
+        .evaluate(() => {
+        const payButton = document.querySelector('#checkout-pay-button');
+        const shopifyAddress = document.querySelector('[name^="checkout[shipping_address]"], [name^="checkout[billing_address]"]');
+        const shippingAddress = document.querySelector('[autocomplete~="shipping"][autocomplete~="address-line1"]');
+        return (Boolean(payButton) ||
+            Boolean(shopifyAddress) ||
+            (Boolean(window.Shopify) &&
+                (/\/checkouts?\//i.test(window.location.pathname) || Boolean(shippingAddress))));
+    })
+        .catch(() => false);
+}
+export async function detectShopifyChallenge(page) {
+    const visibleDialog = await page
+        .evaluate(() => Array.from(document.querySelectorAll('dialog, [role="dialog"], [aria-modal="true"]')).some((element) => {
+        const style = getComputedStyle(element);
+        if (element.offsetParent === null ||
+            style.display === 'none' ||
+            style.visibility === 'hidden') {
+            return false;
+        }
+        const text = element.innerText ?? '';
+        return (/\bshop pay\b/i.test(text) &&
+            /enter (?:the )?(?:verification|one[- ]?time)?\s*code|code (?:was |has been )?sent/i.test(text));
+    }))
+        .catch(() => false);
+    if (visibleDialog)
+        return { signal: 'body:shop-pay-code' };
+    const frames = page.locator('iframe');
+    for (let index = 0; index < (await frames.count().catch(() => 0)); index += 1) {
+        const frame = frames.nth(index);
+        if (!(await frame.isVisible().catch(() => false)))
+            continue;
+        const src = (await frame.getAttribute('src').catch(() => '')) ?? '';
+        if (!/shop\.app\/accounts\/login/i.test(src))
+            continue;
+        const accessibleName = [
+            await frame.getAttribute('title').catch(() => ''),
+            await frame.getAttribute('aria-label').catch(() => ''),
+            await frame.getAttribute('name').catch(() => ''),
+        ].join(' ');
+        if (/verification|one[- ]?time|code/i.test(accessibleName)) {
+            return { signal: 'frame:shop-pay-code' };
+        }
+    }
+    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',
+    'nameLast',
+    'addressLine1',
+    'addressLine2',
+    'city',
+    'state',
+    'postalCode',
+    'country',
+]);
+const CONTACT_ROLES = new Set([
+    'email',
+    'phone',
+    'name',
+    'nameFirst',
+    'nameLast',
+    'addressLine1',
+    'addressLine2',
+    'city',
+    'state',
+    'postalCode',
+    'country',
+]);
+const PAYMENT_ROLES = new Set([
+    'number',
+    'cvc',
+    'name',
+    'expCombined',
+    'expMonth',
+    'expYear',
+]);
+const BILLING_ROLE_NAMES = {
+    name: 'billingName',
+    nameFirst: 'billingNameFirst',
+    nameLast: 'billingNameLast',
+    addressLine1: 'billingAddressLine1',
+    addressLine2: 'billingAddressLine2',
+    city: 'billingCity',
+    state: 'billingState',
+    postalCode: 'billingPostalCode',
+    country: 'billingCountry',
+};
+function candidateText(candidate) {
+    const meta = candidate.meta;
+    return [meta.name, meta.id, meta.autocomplete, meta.labelText, meta.placeholder, meta.ariaLabel]
+        .join(' ')
+        .toLowerCase();
+}
+function isShopifyCandidate(candidate) {
+    const text = candidateText(candidate);
+    return (/(?:^|[^a-z])shopify(?:[^a-z]|$)/i.test(text) ||
+        /checkout\[(?:shipping|billing)_address\]/i.test(text));
+}
+function isBillingCandidate(candidate) {
+    return /billing[_ -]?address|billingaddress|(?:^|[^a-z])billing(?:[^a-z]|$)/i.test(candidateText(candidate));
+}
+function isPaymentCandidate(candidate) {
+    return /cc-|cardholder|card holder|payment/i.test(candidateText(candidate));
+}
+function entryFromCandidate(candidate) {
+    if (!candidate.source)
+        return null;
+    return {
+        locator: `[data-ca-id="${candidate.meta.idx}"]`,
+        confidence: candidate.confidence,
+        source: candidate.source,
+        frame: candidate.frame,
+        tag: candidate.meta.tag,
+        inputType: candidate.meta.type,
+        // The billing control is revealed before these entries are filled.
+        visible: true,
+        options: candidate.meta.options.length ? candidate.meta.options : undefined,
+        maxlength: candidate.meta.maxlength ? Number.parseInt(candidate.meta.maxlength, 10) : undefined,
+    };
+}
+function billingFieldMap(detected) {
+    const fields = {};
+    for (const candidate of detected.candidates) {
+        const role = candidate.role;
+        if (!role || !BILLING_ROLES.has(role) || !isBillingCandidate(candidate))
+            continue;
+        const entry = entryFromCandidate(candidate);
+        if (!entry)
+            continue;
+        const existing = fields[role];
+        if (!existing || entry.confidence > existing.confidence)
+            fields[role] = entry;
+    }
+    return fields;
+}
+function shippingFieldMap(detected) {
+    const fields = {};
+    for (const candidate of detected.candidates) {
+        const role = candidate.role;
+        if (!role ||
+            !CONTACT_ROLES.has(role) ||
+            !candidate.meta.visible ||
+            isBillingCandidate(candidate) ||
+            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;
+}
+function paymentFieldMap(detected) {
+    const fields = {};
+    for (const candidate of detected.candidates) {
+        const role = candidate.role;
+        if (!role || !PAYMENT_ROLES.has(role) || isBillingCandidate(candidate))
+            continue;
+        if (role === 'name' && !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;
+}
+async function clickFirstVisible(locators) {
+    for (const locator of locators) {
+        const first = locator.first();
+        if ((await first.count().catch(() => 0)) < 1)
+            continue;
+        if (!(await first.isVisible().catch(() => false)))
+            continue;
+        await first.click();
+        return true;
+    }
+    return false;
+}
+async function hasVisibleBillingField(page) {
+    const fields = page.locator('input:not([type="radio"]):not([type="checkbox"])[name*="billing_address" i], select[name*="billing_address" i], textarea[name*="billing_address" i]');
+    for (let index = 0; index < (await fields.count()); index += 1) {
+        if (await fields
+            .nth(index)
+            .isVisible()
+            .catch(() => false))
+            return true;
+    }
+    return false;
+}
+async function waitForVisibleBillingField(page) {
+    if (await hasVisibleBillingField(page))
+        return true;
+    return page
+        .waitForFunction(() => Array.from(document.querySelectorAll('input:not([type="radio"]):not([type="checkbox"])[name*="billing_address" i], select[name*="billing_address" i], textarea[name*="billing_address" i]')).some((element) => {
+        const style = window.getComputedStyle(element);
+        return (style.display !== 'none' &&
+            style.visibility !== 'hidden' &&
+            element.getClientRects().length > 0);
+    }), undefined, { timeout: 2_000 })
+        .then(() => true)
+        .catch(() => false);
+}
+async function revealSeparateBilling(page) {
+    if (await hasVisibleBillingField(page))
+        return true;
+    const roleRadio = page
+        .getByRole('radio', { name: /different billing|use a different billing/i })
+        .first();
+    if ((await roleRadio.count().catch(() => 0)) > 0 &&
+        (await roleRadio.isVisible().catch(() => false))) {
+        await roleRadio.check();
+        return waitForVisibleBillingField(page);
+    }
+    if (await clickFirstVisible([
+        page.locator('input[name="billing_address_selector"][value="billing_address"]'),
+        page.locator('input[type="radio"][name*="billing" i][value*="different" i], input[type="radio"][name*="billing" i][value*="billing" i]'),
+    ])) {
+        return waitForVisibleBillingField(page);
+    }
+    const sameAsShipping = page
+        .getByRole('checkbox', { name: /same as shipping|use shipping address/i })
+        .first();
+    if ((await sameAsShipping.count().catch(() => 0)) > 0 &&
+        (await sameAsShipping.isVisible().catch(() => false))) {
+        if (await sameAsShipping.isChecked().catch(() => false))
+            await sameAsShipping.uncheck();
+        return waitForVisibleBillingField(page);
+    }
+    return false;
+}
+function billingContact(address) {
+    return {
+        firstName: address.firstName,
+        lastName: address.lastName,
+        fullName: address.fullName,
+        addressLine1: address.addressLine1,
+        addressLine2: address.addressLine2,
+        city: address.city,
+        state: address.state,
+        postalCode: address.postalCode,
+        country: address.country,
+    };
+}
+function labelBillingEvidence(filled) {
+    return filled.map((field) => ({
+        ...field,
+        role: BILLING_ROLE_NAMES[field.role] ?? `billing:${field.role}`,
+    }));
+}
+function requiredAddressRoles(address, prefix = '') {
+    const role = (name) => `${prefix}${prefix ? name[0].toUpperCase() + name.slice(1) : name}`;
+    const regionRequired = ['US', 'CA', 'AU'].includes(address.country?.toUpperCase() ?? '');
+    return [
+        ...(address.firstName ? [role('nameFirst')] : []),
+        ...(address.lastName ? [role('nameLast')] : []),
+        ...(!address.firstName && !address.lastName && address.fullName ? [role('name')] : []),
+        ...(address.addressLine1 ? [role('addressLine1')] : []),
+        ...(address.addressLine2 ? [role('addressLine2')] : []),
+        ...(address.city ? [role('city')] : []),
+        ...(address.state && regionRequired ? [role('state')] : []),
+        ...(address.postalCode ? [role('postalCode')] : []),
+        ...(address.country ? [role('country')] : []),
+    ];
+}
+/**
+ * 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';
+    constructor(detected) {
+        this.detected = detected;
+    }
+    matches(detected) {
+        return detected.candidates.some(isShopifyCandidate);
+    }
+    async prepareContact(page, contact) {
+        const { fields: contactFields, surface } = contactPrefillFieldMap(this.detected);
+        const shippingFilled = await fillContactFieldMap(page, contactFields, contact);
+        const shippingExpected = [...requiredAddressRoles(contact), ...(contact.phone ? ['phone'] : [])];
+        const shippingMissing = missingContactRoles(shippingFilled, shippingExpected);
+        if (surface === 'billing-only' || !contact.billingAddress) {
+            return {
+                ok: shippingMissing.length === 0,
+                filled: shippingFilled,
+                ...(shippingMissing.length
+                    ? {
+                        detail: `Shopify ${surface === 'billing-only' ? 'contact' : 'shipping'} prefill incomplete: missing ${shippingMissing.join(', ')}`,
+                    }
+                    : {}),
+            };
+        }
+        if (!(await revealSeparateBilling(page))) {
+            return {
+                ok: false,
+                filled: shippingFilled,
+                detail: 'Shopify billing address fields did not become visible during prefill',
+            };
+        }
+        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, ...missingContactRoles(billingFilled, billingExpected)];
+        return {
+            ok: missing.length === 0,
+            filled: [...shippingFilled, ...billingFilled],
+            ...(missing.length
+                ? { detail: `Shopify contact prefill incomplete: missing ${missing.join(', ')}` }
+                : {}),
+        };
+    }
+    async fill(page, _fields, credential, _contact) {
+        const filled = await fillFieldMap(page, paymentFieldMap(this.detected), credential, {});
+        const numberOk = filled.some((field) => field.role === 'number' && field.ok);
+        return { ok: numberOk, filled };
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { Page } from 'playwright-core';
+export declare function minorFromDecimal(text: string): number | null;
+export declare function pageCurrency(text: string): string | null;
+export type PageAmountRead = {
+    kind: 'none';
+} | {
+    kind: 'unreadable';
+    reason?: string;
+} | {
+    kind: 'ok';
+    amountMinor: number;
+    currency: string | null;
+    source: 'page-attr' | 'page-text' | 'shopify-summary';
+};
+export declare function readGenericPageAmount(page: Page): Promise<PageAmountRead>;

package/dist/checkout-engine/amount.js

@@ -0,0 +1,72 @@
+// Convert a human decimal like "$50.00" to integer minor units without
+// floats. Fail closed on separator ambiguity. Only 2-decimal currencies are
+// supported (matching pageCurrency's allowlist).
+export function minorFromDecimal(text) {
+    const match = text.match(/\d[\d.,]*/);
+    if (!match)
+        return null;
+    const token = match[0].replace(/[.,]+$/, '');
+    if (/^\d+$/.test(token))
+        return Number.parseInt(token, 10) * 100;
+    if (/^\d{1,3}(,\d{3})+\.\d{2}$/.test(token)) {
+        const [whole, fraction] = token.replace(/,/g, '').split('.');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(fraction, 10);
+    }
+    if (/^\d{1,3}(\.\d{3})+,\d{2}$/.test(token)) {
+        const [whole, fraction] = token.replace(/\./g, '').split(',');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(fraction, 10);
+    }
+    if (/^\d+\.\d{1,2}$/.test(token)) {
+        const [whole, fraction] = token.split('.');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(fraction.padEnd(2, '0'), 10);
+    }
+    if (/^\d+,\d{1,2}$/.test(token)) {
+        const [whole, fraction] = token.split(',');
+        return Number.parseInt(whole, 10) * 100 + Number.parseInt(fraction.padEnd(2, '0'), 10);
+    }
+    return null;
+}
+const ISO_CURRENCIES = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'CHF', 'NZD'];
+export function pageCurrency(text) {
+    const iso = text.match(/\b([A-Z]{3})\b/);
+    if (iso && ISO_CURRENCIES.includes(iso[1]))
+        return iso[1];
+    if (text.includes('€'))
+        return 'EUR';
+    if (text.includes('£'))
+        return 'GBP';
+    return null;
+}
+export async function readGenericPageAmount(page) {
+    const explicitLocator = page.locator('[data-total-minor]').first();
+    if ((await explicitLocator.count().catch(() => 0)) > 0) {
+        const explicit = await explicitLocator.getAttribute('data-total-minor').catch(() => null);
+        if (explicit && /^\d+$/.test(explicit)) {
+            const text = (await explicitLocator.textContent().catch(() => null)) ?? '';
+            return {
+                kind: 'ok',
+                amountMinor: Number.parseInt(explicit, 10),
+                currency: pageCurrency(text),
+                source: 'page-attr',
+            };
+        }
+    }
+    const totalLocator = page
+        .locator('#order-total, .order-total, [data-testid="order-total"]')
+        .first();
+    if ((await totalLocator.count().catch(() => 0)) > 0) {
+        const totalText = await totalLocator.textContent().catch(() => null);
+        if (totalText && /\d/.test(totalText)) {
+            const amountMinor = minorFromDecimal(totalText);
+            if (amountMinor == null)
+                return { kind: 'unreadable' };
+            return {
+                kind: 'ok',
+                amountMinor,
+                currency: pageCurrency(totalText),
+                source: 'page-text',
+            };
+        }
+    }
+    return { kind: 'none' };
+}