@visa/cli 4.1.0-rc.8 → 4.1.0-rc.80

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/adapters/stripe-like.d.ts

@@ -0,0 +1,10 @@
+import type { Page } from 'playwright-core';
+import type { DetectResult, FieldMap } from '../detect.js';
+import type { CardCredential } from '../instrument.js';
+import type { Contact, FillResult } from '../types.js';
+import { type CheckoutAdapter } from './generic.js';
+export declare class StripeLikeAdapter implements CheckoutAdapter {
+    name: string;
+    matches(detected: DetectResult): boolean;
+    fill(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact): Promise<FillResult>;
+}

package/dist/checkout-engine/adapters/stripe-like.js

@@ -0,0 +1,21 @@
+// Stripe-like adapter. Matches checkouts whose card fields live inside a
+// same-origin iframe laid out like Stripe Elements (a card-number frame, an
+// expiry frame, a cvc frame, or one combined frame). It fills through
+// Playwright frameLocator. For M0 only same-origin test iframes are fillable;
+// a real cross-origin PSP iframe is detected upstream and reported as
+// requiresAdapter instead.
+import { fillFieldMap } from './generic.js';
+export class StripeLikeAdapter {
+    name = 'stripe-like';
+    matches(detected) {
+        // We take this adapter when the card number was found inside a frame.
+        return Boolean(detected.fields.number?.frame);
+    }
+    async fill(page, fields, credential, contact) {
+        const filled = await fillFieldMap(page, fields, credential, contact);
+        return {
+            ok: filled.some((f) => f.role === 'number' && f.ok),
+            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' };
+}

package/dist/checkout-engine/browser-launch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Browser provisioning for the checkout engine.
+ *
+ * @purpose The engine depends on `playwright-core` (NOT `playwright`) so that
+ * installing @visa/cli never triggers a postinstall Chromium download. A real
+ * browser is resolved lazily, on the first checkout, in this order:
+ *
+ *   1. VISA_CHECKOUT_BROWSER  — explicit executable path override (deterministic
+ *      for CI / pinned environments; wins over everything). If it is set but
+ *      FAILS to launch, we ABORT loudly rather than fall through — a pinned
+ *      money flow must not run in a browser the operator did not choose.
+ *   2. channel: 'chrome'      — a system-installed Google Chrome (no download).
+ *   3. channel: 'msedge'      — a system-installed Microsoft Edge (no download).
+ *   4. default chromium       — a playwright-managed browser, IF one was already
+ *      installed via `npx playwright-core install chromium` (still no download
+ *      here — it only USES an existing one; launch throws if absent).
+ *
+ * If none launch, we throw one actionable error listing every attempt and the
+ * three ways to fix it. We never silently download hundreds of MB mid-command;
+ * provisioning stays an explicit user choice (install Chrome, run the documented
+ * `playwright-core install`, or point VISA_CHECKOUT_BROWSER at a binary).
+ *
+ * The install command is `playwright-core`, NOT `playwright`: this package no
+ * longer depends on the full `playwright`, so `npx playwright …` would fetch an
+ * unrelated latest `playwright` and can install a browser revision that does not
+ * match the pinned `playwright-core` — the very launch this is meant to fix.
+ * `npx playwright-core install` uses the installed, version-matched package.
+ */
+import { type Browser, type LaunchOptions } from 'playwright-core';
+export type LaunchCheckoutBrowserDeps = {
+    env?: NodeJS.ProcessEnv;
+    /** Injectable launcher (default: playwright-core chromium.launch) — tests
+     *  pass a fake to assert the fallback order without a real browser. */
+    launch?: (opts: LaunchOptions) => Promise<Browser>;
+    log?: (msg: string) => void;
+};
+type Attempt = {
+    label: string;
+    opts: LaunchOptions;
+    override?: boolean;
+};
+/** Build the ordered launch attempts for the current environment. Exported for
+ *  unit testing the resolution order without launching anything. */
+export declare function buildLaunchAttempts(env: NodeJS.ProcessEnv): Attempt[];
+export declare function launchCheckoutBrowser(deps?: LaunchCheckoutBrowserDeps): Promise<Browser>;
+export {};

package/dist/checkout-engine/browser-launch.js

@@ -0,0 +1,81 @@
+/**
+ * Browser provisioning for the checkout engine.
+ *
+ * @purpose The engine depends on `playwright-core` (NOT `playwright`) so that
+ * installing @visa/cli never triggers a postinstall Chromium download. A real
+ * browser is resolved lazily, on the first checkout, in this order:
+ *
+ *   1. VISA_CHECKOUT_BROWSER  — explicit executable path override (deterministic
+ *      for CI / pinned environments; wins over everything). If it is set but
+ *      FAILS to launch, we ABORT loudly rather than fall through — a pinned
+ *      money flow must not run in a browser the operator did not choose.
+ *   2. channel: 'chrome'      — a system-installed Google Chrome (no download).
+ *   3. channel: 'msedge'      — a system-installed Microsoft Edge (no download).
+ *   4. default chromium       — a playwright-managed browser, IF one was already
+ *      installed via `npx playwright-core install chromium` (still no download
+ *      here — it only USES an existing one; launch throws if absent).
+ *
+ * If none launch, we throw one actionable error listing every attempt and the
+ * three ways to fix it. We never silently download hundreds of MB mid-command;
+ * provisioning stays an explicit user choice (install Chrome, run the documented
+ * `playwright-core install`, or point VISA_CHECKOUT_BROWSER at a binary).
+ *
+ * The install command is `playwright-core`, NOT `playwright`: this package no
+ * longer depends on the full `playwright`, so `npx playwright …` would fetch an
+ * unrelated latest `playwright` and can install a browser revision that does not
+ * match the pinned `playwright-core` — the very launch this is meant to fix.
+ * `npx playwright-core install` uses the installed, version-matched package.
+ */
+import { chromium } from 'playwright-core';
+const HEADFUL = { headless: false };
+/** Build the ordered launch attempts for the current environment. Exported for
+ *  unit testing the resolution order without launching anything. */
+export function buildLaunchAttempts(env) {
+    const attempts = [];
+    const override = env.VISA_CHECKOUT_BROWSER?.trim();
+    if (override) {
+        attempts.push({
+            label: `VISA_CHECKOUT_BROWSER (${override})`,
+            opts: { ...HEADFUL, executablePath: override },
+            override: true,
+        });
+    }
+    attempts.push({
+        label: 'system Chrome (channel=chrome)',
+        opts: { ...HEADFUL, channel: 'chrome' },
+    });
+    attempts.push({ label: 'system Edge (channel=msedge)', opts: { ...HEADFUL, channel: 'msedge' } });
+    attempts.push({ label: 'playwright-managed chromium', opts: { ...HEADFUL } });
+    return attempts;
+}
+export async function launchCheckoutBrowser(deps = {}) {
+    const env = deps.env ?? process.env;
+    const launch = deps.launch ?? ((opts) => chromium.launch(opts));
+    const log = deps.log ?? (() => { });
+    const errors = [];
+    for (const attempt of buildLaunchAttempts(env)) {
+        try {
+            const browser = await launch(attempt.opts);
+            log(`checkout browser: launched via ${attempt.label}`);
+            return browser;
+        }
+        catch (err) {
+            const first = err.message.split('\n')[0];
+            if (attempt.override) {
+                // An explicit VISA_CHECKOUT_BROWSER is a deterministic, pinned choice
+                // (CI / a locked-down operator env). If it fails to launch, ABORT loudly
+                // rather than silently substituting a system browser the operator did
+                // not pin — this is a money flow. Unsetting the var opts back into the
+                // system-browser fallback below.
+                throw new Error(`VISA_CHECKOUT_BROWSER="${env.VISA_CHECKOUT_BROWSER?.trim()}" failed to launch: ${first}. ` +
+                    'Fix the path/binary, or unset VISA_CHECKOUT_BROWSER to allow a system-browser ' +
+                    'fallback — refusing to substitute an unpinned browser for a checkout.');
+            }
+            errors.push(`${attempt.label}: ${first}`);
+        }
+    }
+    throw new Error('Could not launch a browser for checkout. Tried — ' +
+        errors.join(' | ') +
+        '. Install Google Chrome, or run `npx playwright-core install chromium` ' +
+        '(matches the pinned version), or set VISA_CHECKOUT_BROWSER to a browser executable path.');
+}