@visa/cli 4.1.0-rc.42 → 4.1.0-rc.44

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

@@ -5,10 +5,14 @@ import type { Contact, FillResult, FilledField } from '../types.js';
 export interface CheckoutAdapter {
     name: string;
     matches(detected: DetectResult): boolean;
+    prepareContact?: (page: Page, contact: Contact) => Promise<FillResult>;
     fill(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact): Promise<FillResult>;
 }
 export declare function resolveLocator(page: Page, entry: FieldEntry): Locator;
 export declare function scrubFillErrorMessage(message: string, value: string): 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[]>;

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

@@ -97,13 +97,12 @@ 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 = {}) {
+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 = contact.fullName ?? credential?.cardholderName;
+    const first = contact.firstName ?? fullName?.split(/\s+/)[0];
+    const last = contact.lastName ?? fullName?.split(/\s+/).slice(1).join(' ');
     // 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 +119,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 +161,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 +191,15 @@ 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);
+}
 export class GenericAdapter {
     name = 'generic';
     matches(_detected) {

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

@@ -2,6 +2,7 @@ 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;

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

@@ -2,14 +2,18 @@
 // 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) {
+    // 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 specific = [new ShopifyAdapter(detected), new StripeLikeAdapter()];
+    for (const a of specific) {
         if (a.matches(detected))
             return a;
     }

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

@@ -0,0 +1,31 @@
+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 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>;
+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 {};

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

@@ -0,0 +1,423 @@
+// 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);
+    const verified = subtotalMinor != null &&
+        shippingMinor != null &&
+        taxMinor != null &&
+        totalMinor != null &&
+        subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor;
+    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;
+}
+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')] : []),
+    ];
+}
+function missingRoles(filled, expected) {
+    const successful = new Set(filled.filter((field) => field.ok).map((field) => field.role));
+    return expected.filter((role) => !successful.has(role));
+}
+export class ShopifyAdapter {
+    detected;
+    name = 'shopify';
+    constructor(detected) {
+        this.detected = detected;
+    }
+    matches(detected) {
+        return detected.candidates.some(isShopifyCandidate);
+    }
+    async prepareContact(page, contact) {
+        const shippingFilled = await fillContactFieldMap(page, shippingFieldMap(this.detected), contact);
+        const shippingExpected = [...requiredAddressRoles(contact), ...(contact.phone ? ['phone'] : [])];
+        const shippingMissing = missingRoles(shippingFilled, shippingExpected);
+        if (!contact.billingAddress) {
+            return {
+                ok: shippingMissing.length === 0,
+                filled: shippingFilled,
+                ...(shippingMissing.length
+                    ? { detail: `Shopify 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, ...missingRoles(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' };
+}