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

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

@@ -0,0 +1,688 @@
+// 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);
+}
+const SHOP_SURFACE_SELECTOR = [
+    'dialog',
+    '[role="dialog"]',
+    '[aria-modal="true"]',
+    '[data-shop-pay-modal]',
+    '[data-shopify-pay-modal]',
+].join(', ');
+const SHOP_CODE_TEXT = /enter (?:the )?(?:verification|one[- ]?time)?\s*code|code (?:was |has been )?sent|verification code/i;
+const SHOP_AUTH_TEXT = /sign in|log in|confirm (?:it(?:'|’)s )?you|continue with shop|shop account/i;
+const SHOP_RECOGNITION_TEXT = /recognized|faster checkout|remembered|saved (?:payment|details)/i;
+async function classifyBodyShopSurface(page) {
+    const roots = page.locator(SHOP_SURFACE_SELECTOR);
+    for (let index = 0; index < (await roots.count().catch(() => 0)); index += 1) {
+        const root = roots.nth(index);
+        if (!(await root.isVisible().catch(() => false)))
+            continue;
+        const [text, attrs, shopMark] = await Promise.all([
+            root.innerText().catch(() => ''),
+            Promise.all(['id', 'class', 'aria-label', 'data-testid'].map((name) => root.getAttribute(name).catch(() => ''))).then((values) => values.join(' ')),
+            root
+                .locator('img[alt="Shop" i], img[alt="Shop Pay" i], [aria-label="Shop" i]')
+                .count()
+                .then((count) => count > 0)
+                .catch(() => false),
+        ]);
+        // A generic dialog, generic Close button, or marketing use of "shop" is
+        // not enough. Positive identification requires Shop Pay copy/attributes,
+        // or a Shop mark paired with authentication/guest-checkout language.
+        const positiveShopSignal = /\bshop\s*pay\b/i.test(`${text} ${attrs}`) ||
+            /shop[-_ ]?(?:pay|ify-pay)/i.test(attrs) ||
+            (shopMark && (SHOP_AUTH_TEXT.test(text) || /checkout as guest/i.test(text)));
+        if (!positiveShopSignal)
+            continue;
+        const subtype = SHOP_CODE_TEXT.test(text)
+            ? 'authentication'
+            : /checkout as guest/i.test(text)
+                ? 'wallet'
+                : SHOP_AUTH_TEXT.test(text)
+                    ? 'authentication'
+                    : SHOP_RECOGNITION_TEXT.test(text)
+                        ? 'recognition'
+                        : 'wallet';
+        return {
+            root,
+            subtype,
+            signal: `body:shop-${subtype}`,
+        };
+    }
+    return null;
+}
+async function classifyFrameShopSurface(page) {
+    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 (!/^https:\/\/(?:[^/]+\.)?shop\.app\/(?:accounts\/login|pay|checkout)\b/i.test(src))
+            continue;
+        const accessibleName = [
+            await frame.getAttribute('title').catch(() => ''),
+            await frame.getAttribute('aria-label').catch(() => ''),
+            await frame.getAttribute('name').catch(() => ''),
+        ].join(' ');
+        const subtype = SHOP_CODE_TEXT.test(accessibleName) ? 'authentication' : 'wallet';
+        return { frame, subtype, signal: `frame:shop-${subtype}` };
+    }
+    return null;
+}
+export async function detectShopifyCheckoutSurface(page) {
+    const located = (await classifyBodyShopSurface(page)) ?? (await classifyFrameShopSurface(page));
+    return located ? { signal: located.signal, subtype: located.subtype } : null;
+}
+async function locateShopifyCheckoutSurface(page) {
+    return (await classifyBodyShopSurface(page)) ?? (await classifyFrameShopSurface(page));
+}
+async function visibleGuestCardForm(page) {
+    const detected = await detectFields(page).catch(() => null);
+    return Boolean(detected?.fields.number?.visible);
+}
+/**
+ * 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 async function ensureShopifyGuestCheckout(page, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 1_800;
+    const stableMs = options.stableMs ?? 650;
+    const startedAt = Date.now();
+    let guestStableSince = null;
+    let located = null;
+    while (Date.now() - startedAt < timeoutMs) {
+        located = await locateShopifyCheckoutSurface(page);
+        if (located)
+            break;
+        if (await visibleGuestCardForm(page)) {
+            guestStableSince ??= Date.now();
+            if (Date.now() - guestStableSince >= stableMs) {
+                return { status: 'guest-ready', signal: 'guest-card-form' };
+            }
+        }
+        else {
+            guestStableSince = null;
+        }
+        await page.waitForTimeout(75);
+    }
+    if (!located) {
+        return (await visibleGuestCardForm(page))
+            ? { status: 'guest-ready', signal: 'guest-card-form' }
+            : {
+                status: 'action-required',
+                signal: 'shopify:guest-card-form-unavailable',
+                detail: 'Shopify guest card form did not become stable before review; no payment credential was requested',
+            };
+    }
+    const originBefore = new URL(page.url()).origin;
+    let action = null;
+    let actionSignal = '';
+    if (located.root) {
+        const exactGuest = located.root
+            .getByRole('button', { name: /^checkout as guest$/i })
+            .or(located.root.getByRole('link', { name: /^checkout as guest$/i }))
+            .first();
+        if ((await exactGuest.count().catch(() => 0)) > 0 &&
+            (await exactGuest.isVisible().catch(() => false))) {
+            action = exactGuest;
+            actionSignal = `${located.signal}:checkout-as-guest`;
+        }
+        else if (located.subtype !== 'authentication' ||
+            !(await located.root.innerText()).match(SHOP_CODE_TEXT)) {
+            const scopedClose = located.root
+                .getByRole('button', { name: /^close(?: shop(?: pay)?)?$/i })
+                .first();
+            if ((await scopedClose.count().catch(() => 0)) > 0 &&
+                (await scopedClose.isVisible().catch(() => false))) {
+                action = scopedClose;
+                actionSignal = `${located.signal}:scoped-close`;
+            }
+        }
+    }
+    else if (located.frame) {
+        const frame = located.frame.contentFrame();
+        const exactGuest = frame.getByRole('button', { name: /^checkout as guest$/i }).first();
+        if ((await exactGuest.count().catch(() => 0)) > 0 &&
+            (await exactGuest.isVisible().catch(() => false))) {
+            action = exactGuest;
+            actionSignal = `${located.signal}:checkout-as-guest`;
+        }
+    }
+    if (!action) {
+        return {
+            status: 'action-required',
+            signal: located.signal,
+            detail: `Shopify Shop surface could not be safely exited (${located.signal}); no payment credential was requested`,
+        };
+    }
+    await action.click();
+    const surfaceGone = await page
+        .waitForFunction((selector) => !Array.from(document.querySelectorAll(selector)).some((element) => {
+        const style = getComputedStyle(element);
+        const text = element.innerText ?? '';
+        const attrs = [
+            element.id,
+            element.className,
+            element.getAttribute('aria-label'),
+            element.getAttribute('data-testid'),
+        ].join(' ');
+        const visible = element.offsetParent !== null &&
+            style.display !== 'none' &&
+            style.visibility !== 'hidden';
+        return visible && /\bshop\s*pay\b|shop[-_ ]?(?:pay|ify-pay)/i.test(`${text} ${attrs}`);
+    }), SHOP_SURFACE_SELECTOR, { timeout: 2_000 })
+        .then(() => true)
+        .catch(() => false);
+    const sameOrigin = new URL(page.url()).origin === originBefore;
+    const surfaceRemains = Boolean(await locateShopifyCheckoutSurface(page));
+    if (!surfaceGone || surfaceRemains || !sameOrigin || !(await visibleGuestCardForm(page))) {
+        const signal = !sameOrigin
+            ? 'shopify:guest-transition-origin-changed'
+            : !surfaceGone || surfaceRemains
+                ? 'shopify:shop-surface-remained'
+                : 'shopify:guest-card-form-unavailable';
+        return {
+            status: 'action-required',
+            signal,
+            detail: `Shopify guest transition could not be verified (${signal}); no payment credential was requested`,
+        };
+    }
+    return { status: 'transitioned', signal: actionSignal };
+}
+/** Read-only assertion for the irreversible credential boundary. */
+export async function assertShopifyGuestCheckout(page) {
+    const surface = await locateShopifyCheckoutSurface(page);
+    if (surface) {
+        return {
+            status: 'action-required',
+            signal: surface.signal,
+            detail: `Shopify Shop surface reappeared after review (${surface.signal}); no payment credential was requested`,
+        };
+    }
+    return (await visibleGuestCardForm(page))
+        ? { status: 'guest-ready', signal: 'guest-card-form' }
+        : {
+            status: 'action-required',
+            signal: 'shopify:guest-card-form-unavailable',
+            detail: 'Shopify guest card form is no longer available after review; no payment credential was requested',
+        };
+}
+/**
+ * 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 };
+    }
+}