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

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

@@ -5,13 +5,16 @@
  * 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
+ *   1. VISA_CHECKOUT_BROWSERBASE_ENABLED=1 — explicit remote Browserbase
+ *      session for a headless runtime. It is mutually exclusive with a local
+ *      executable override and never falls back after provider failure.
+ *   2. 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
+ *   3. channel: 'chrome'      — a system-installed Google Chrome (no download).
+ *   4. channel: 'msedge'      — a system-installed Microsoft Edge (no download).
+ *   5. 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).
  *
@@ -27,11 +30,13 @@
  * `npx playwright-core install` uses the installed, version-matched package.
  */
 import { type Browser, type LaunchOptions } from 'playwright-core';
+import { launchBrowserbaseCheckoutBrowser } from './browserbase-browser.js';
 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>;
+    launchBrowserbase?: typeof launchBrowserbaseCheckoutBrowser;
     log?: (msg: string) => void;
 };
 type Attempt = {

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

@@ -5,13 +5,16 @@
  * 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
+ *   1. VISA_CHECKOUT_BROWSERBASE_ENABLED=1 — explicit remote Browserbase
+ *      session for a headless runtime. It is mutually exclusive with a local
+ *      executable override and never falls back after provider failure.
+ *   2. 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
+ *   3. channel: 'chrome'      — a system-installed Google Chrome (no download).
+ *   4. channel: 'msedge'      — a system-installed Microsoft Edge (no download).
+ *   5. 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).
  *
@@ -27,6 +30,7 @@
  * `npx playwright-core install` uses the installed, version-matched package.
  */
 import { chromium } from 'playwright-core';
+import { launchBrowserbaseCheckoutBrowser } from './browserbase-browser.js';
 const HEADFUL = { headless: false };
 /** Build the ordered launch attempts for the current environment. Exported for
  *  unit testing the resolution order without launching anything. */
@@ -52,6 +56,17 @@ export async function launchCheckoutBrowser(deps = {}) {
     const env = deps.env ?? process.env;
     const launch = deps.launch ?? ((opts) => chromium.launch(opts));
     const log = deps.log ?? (() => { });
+    const browserbaseFlag = env.VISA_CHECKOUT_BROWSERBASE_ENABLED?.trim();
+    if (browserbaseFlag && browserbaseFlag !== '0' && browserbaseFlag !== '1') {
+        throw new Error('VISA_CHECKOUT_BROWSERBASE_ENABLED must be 1 or 0 when set');
+    }
+    if (browserbaseFlag === '1') {
+        if (env.VISA_CHECKOUT_BROWSER?.trim()) {
+            throw new Error('VISA_CHECKOUT_BROWSERBASE_ENABLED and VISA_CHECKOUT_BROWSER cannot both be set');
+        }
+        const launchBrowserbase = deps.launchBrowserbase ?? launchBrowserbaseCheckoutBrowser;
+        return launchBrowserbase({ env, log });
+    }
     const errors = [];
     for (const attempt of buildLaunchAttempts(env)) {
         try {

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

@@ -0,0 +1,24 @@
+/**
+ * Browserbase provisioning for the checkout engine.
+ *
+ * Browserbase exposes one pre-created Chromium context over CDP. The checkout
+ * engine normally asks a locally launched Browser for a fresh context, so this
+ * module adapts that one remote context to the narrow Browser surface the
+ * engine uses. It deliberately refuses unsupported context options instead of
+ * silently weakening a future checkout isolation setting.
+ */
+import { type Browser, type BrowserContext } from 'playwright-core';
+type FetchLike = typeof fetch;
+export type LaunchBrowserbaseCheckoutBrowserDeps = {
+    env?: NodeJS.ProcessEnv;
+    fetch?: FetchLike;
+    connectOverCDP?: (connectUrl: string) => Promise<Browser>;
+    log?: (message: string) => void;
+};
+/**
+ * Adapt Browserbase's one recorded default context to Browser.newContext().
+ * One launch serves one checkout review, so the context is leased exactly once.
+ */
+export declare function adaptBrowserbaseBrowser(browser: Browser, context: BrowserContext): Browser;
+export declare function launchBrowserbaseCheckoutBrowser(deps?: LaunchBrowserbaseCheckoutBrowserDeps): Promise<Browser>;
+export {};

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

@@ -0,0 +1,186 @@
+/**
+ * Browserbase provisioning for the checkout engine.
+ *
+ * Browserbase exposes one pre-created Chromium context over CDP. The checkout
+ * engine normally asks a locally launched Browser for a fresh context, so this
+ * module adapts that one remote context to the narrow Browser surface the
+ * engine uses. It deliberately refuses unsupported context options instead of
+ * silently weakening a future checkout isolation setting.
+ */
+import { chromium, } from 'playwright-core';
+const BROWSERBASE_SESSIONS_URL = 'https://api.browserbase.com/v1/sessions';
+const BROWSERBASE_SESSION_TIMEOUT_SECONDS = 600;
+const BROWSERBASE_API_TIMEOUT_MS = 15_000;
+function requiredSecret(env, name) {
+    const value = env[name]?.trim();
+    if (!value) {
+        throw new Error(`${name} is required when VISA_CHECKOUT_BROWSERBASE_ENABLED=1. ` +
+            'Set it in the runtime environment; never pass it through an agent prompt.');
+    }
+    return value;
+}
+function parseSession(value) {
+    if (!value || typeof value !== 'object') {
+        throw new Error('Browserbase session response was not an object');
+    }
+    const record = value;
+    if (typeof record.id !== 'string' || record.id.length === 0) {
+        throw new Error('Browserbase session response did not include an id');
+    }
+    if (typeof record.connectUrl !== 'string') {
+        throw new Error('Browserbase session response did not include a connect URL');
+    }
+    let connectUrl;
+    try {
+        connectUrl = new URL(record.connectUrl);
+    }
+    catch {
+        throw new Error('Browserbase session response included an invalid connect URL');
+    }
+    if (connectUrl.protocol !== 'wss:') {
+        throw new Error('Browserbase session response included a non-WSS connect URL');
+    }
+    return { id: record.id, connectUrl: connectUrl.toString() };
+}
+async function releaseBrowserbaseSession(fetchImpl, apiKey, sessionId, projectId, log) {
+    const requestStartedAt = Date.now();
+    try {
+        const response = await fetchImpl(`${BROWSERBASE_SESSIONS_URL}/${encodeURIComponent(sessionId)}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-BB-API-Key': apiKey,
+            },
+            body: JSON.stringify({
+                status: 'REQUEST_RELEASE',
+                ...(projectId ? { projectId } : {}),
+            }),
+            signal: AbortSignal.timeout(BROWSERBASE_API_TIMEOUT_MS),
+        });
+        logBoundary(log, `checkout browser boundary: provider=browserbase operation=release_session status=${response.status} duration_ms=${Date.now() - requestStartedAt}`);
+    }
+    catch (error) {
+        const outcome = error instanceof Error && error.name === 'TimeoutError' ? 'timed_out' : 'failed';
+        logBoundary(log, `checkout browser boundary: provider=browserbase operation=release_session outcome=${outcome} duration_ms=${Date.now() - requestStartedAt}`);
+    }
+}
+function unsupportedContextOptions(options) {
+    return Object.keys(options).filter((key) => key !== 'locale' &&
+        key !== 'extraHTTPHeaders' &&
+        options[key] !== undefined);
+}
+function checkoutHeaders(headers = {}) {
+    const withoutAcceptLanguage = Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== 'accept-language'));
+    return { ...withoutAcceptLanguage, 'Accept-Language': 'en-US' };
+}
+function logBoundary(log, message) {
+    try {
+        log(message);
+    }
+    catch {
+        // Observability must never break checkout or expose the provider payload.
+    }
+}
+/**
+ * Adapt Browserbase's one recorded default context to Browser.newContext().
+ * One launch serves one checkout review, so the context is leased exactly once.
+ */
+export function adaptBrowserbaseBrowser(browser, context) {
+    let leased = false;
+    return new Proxy(browser, {
+        get(target, property, receiver) {
+            if (property === 'newContext') {
+                return async (options = {}) => {
+                    if (leased)
+                        throw new Error('Browserbase checkout context has already been leased');
+                    const unsupported = unsupportedContextOptions(options);
+                    if (unsupported.length > 0) {
+                        throw new Error(`Browserbase checkout does not support context options: ${unsupported.join(', ')}`);
+                    }
+                    if (options.locale !== undefined && options.locale !== 'en-US') {
+                        throw new Error('Browserbase checkout requires the en-US locale');
+                    }
+                    leased = true;
+                    try {
+                        await context.setExtraHTTPHeaders(checkoutHeaders(options.extraHTTPHeaders));
+                    }
+                    catch {
+                        throw new Error('Browserbase checkout context headers could not be configured');
+                    }
+                    return context;
+                };
+            }
+            const value = Reflect.get(target, property, target);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+}
+export async function launchBrowserbaseCheckoutBrowser(deps = {}) {
+    const env = deps.env ?? process.env;
+    const fetchImpl = deps.fetch ?? fetch;
+    const connectOverCDP = deps.connectOverCDP ?? ((url) => chromium.connectOverCDP(url));
+    const log = deps.log ?? (() => { });
+    const apiKey = requiredSecret(env, 'BROWSERBASE_API_KEY');
+    const projectId = env.BROWSERBASE_PROJECT_ID?.trim() || undefined;
+    const requestStartedAt = Date.now();
+    let response;
+    try {
+        response = await fetchImpl(BROWSERBASE_SESSIONS_URL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-BB-API-Key': apiKey,
+            },
+            body: JSON.stringify({
+                ...(projectId ? { projectId } : {}),
+                timeout: BROWSERBASE_SESSION_TIMEOUT_SECONDS,
+                keepAlive: false,
+                browserSettings: { viewport: { width: 1280, height: 900 } },
+                userMetadata: { surface: 'visa-checkout-engine' },
+            }),
+            signal: AbortSignal.timeout(BROWSERBASE_API_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error && error.name === 'TimeoutError' ? 'timed out' : 'failed';
+        logBoundary(log, `checkout browser boundary: provider=browserbase operation=create_session outcome=${reason.replace(' ', '_')} duration_ms=${Date.now() - requestStartedAt}`);
+        throw new Error(`Browserbase session creation ${reason}`);
+    }
+    logBoundary(log, `checkout browser boundary: provider=browserbase operation=create_session status=${response.status} duration_ms=${Date.now() - requestStartedAt}`);
+    if (!response.ok) {
+        throw new Error(`Browserbase session creation failed with HTTP ${response.status}`);
+    }
+    const sessionPayload = await response.json().catch(() => null);
+    let session;
+    try {
+        session = parseSession(sessionPayload);
+    }
+    catch (error) {
+        const sessionId = sessionPayload &&
+            typeof sessionPayload === 'object' &&
+            typeof sessionPayload.id === 'string'
+            ? String(sessionPayload.id)
+            : null;
+        if (sessionId) {
+            await releaseBrowserbaseSession(fetchImpl, apiKey, sessionId, projectId, log);
+        }
+        throw error;
+    }
+    let browser;
+    try {
+        browser = await connectOverCDP(session.connectUrl);
+    }
+    catch {
+        await releaseBrowserbaseSession(fetchImpl, apiKey, session.id, projectId, log);
+        throw new Error('Browserbase session was created but the secure CDP connection failed');
+    }
+    const context = browser.contexts()[0];
+    if (!context) {
+        await browser.close().catch(() => undefined);
+        await releaseBrowserbaseSession(fetchImpl, apiKey, session.id, projectId, log);
+        throw new Error('Browserbase CDP connection did not expose its default browser context');
+    }
+    await Promise.all(context.pages().map((page) => page.close().catch(() => undefined)));
+    logBoundary(log, 'checkout browser: connected to Browserbase');
+    return adaptBrowserbaseBrowser(browser, context);
+}