@visa/cli 4.1.0-rc.229 → 4.1.0-rc.230

package/README.md

@@ -76,7 +76,7 @@ Shopify checkout skill, and both Visa and Shopify UCP MCP entries in one step:
 visa agent skill --commerce --runtime codex
 # runtimes with writable MCP config: codex, openclaw, hermes
 
-# Before the first canary, also verify the pinned local UCP profile:
+# Inspect the installed local bundle without changing skills or MCP config:
 visa agent skill --commerce --runtime codex --check
 ```
 
@@ -87,13 +87,20 @@ reports both MCP entries as mounted or already mounted; restart or reload the
 agent before using the new tools. The installer never performs discovery or a
 checkout itself. The install-only command exits successfully after writing the
 bundle, but reports `commerceReady: false` / `ucp_check_required` until the
-explicit `--check` gate passes.
-
-Checked readiness runs the pinned `ucp doctor --skip-network` diagnostic and
-reports the exact profile initialization command if local state is missing. It
-also refuses to claim natural-language shopping readiness when a top-level
-`ucp` or `shop` skill with a `SKILL.md` is present in the same runtime directory. The
-installer reports those paths but never deletes or disables user-owned skills.
+explicit `--check` gate passes. `commerceReady` is a compatibility alias for
+local bundle readiness only; it never proves that a merchant purchase can be
+completed. The JSON result keeps `purchase.ready: false` until a separate live
+checkout preflight is performed.
+
+Checked readiness is read-only: missing or modified skills and missing,
+conflicting, or malformed MCP entries are reported without installing or
+rewriting anything. It parses the active local profile and its pinned Shopify
+profile contract directly from disk, without starting `npx`, and reports the
+exact profile initialization command if local state is missing or invalid. It
+also refuses to claim local natural-language shopping readiness when a
+top-level `ucp` or `shop` skill with a `SKILL.md` is present in the same runtime
+directory. The installer reports those paths but never deletes or disables
+user-owned skills.
 
 If the selected runtime already has a non-equivalent `shopify-ucp` entry, the
 command fails without changing that entry or its environment, authentication,
@@ -234,7 +241,8 @@ is required so the CLI never guesses which agent can spend.
 | `setup_status` | Read the server's one `nextAction` for a setup operation, plus the cadence to poll it at |
 | `setup_resume` | Put the review link and compare code back in front of the human after a restart or a closed tab |
 | `setup_cancel` | Abandon a setup still waiting on the human; never undoes an approval |
-| `agent_connect` / `agent_connect_poll` | Initiate an owner-approved spending grant, then poll it to activation |
+| `agent_connect` | Initiate an owner-approved spending grant for a paired agent |
+| `agent_connect_poll` | Poll that grant ceremony to activation (returns caps, and the funding address for wallet) |
 | `wallet_status` | Delegated wallet address, network, and policy state |
 | `wallet_policy_set` | Set per-transaction / daily caps (with human approval) |
 | `wallet_discover` | Sweep x402 directories for services, with live re-probing |

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

@@ -17,9 +17,34 @@ 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<{
+export type ShopifyCheckoutSurface = {
     signal: string;
-} | null>;
+    subtype: 'recognition' | 'authentication' | 'wallet';
+};
+export type ShopifyGuestCheckoutResult = {
+    status: 'guest-ready';
+    signal: 'guest-card-form';
+} | {
+    status: 'transitioned';
+    signal: string;
+} | {
+    status: 'action-required';
+    signal: string;
+    detail: string;
+};
+export declare function detectShopifyCheckoutSurface(page: Page): Promise<ShopifyCheckoutSurface | null>;
+/**
+ * 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 declare function ensureShopifyGuestCheckout(page: Page, options?: {
+    timeoutMs?: number;
+    stableMs?: number;
+}): Promise<ShopifyGuestCheckoutResult>;
+/** Read-only assertion for the irreversible credential boundary. */
+export declare function assertShopifyGuestCheckout(page: Page): Promise<ShopifyGuestCheckoutResult>;
 /**
  * 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

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

@@ -122,41 +122,215 @@ export async function isShopifyCheckoutPage(page) {
     })
         .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 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 (!/shop\.app\/accounts\/login/i.test(src))
+        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(' ');
-        if (/verification|one[- ]?time|code/i.test(accessibleName)) {
-            return { signal: 'frame:shop-pay-code' };
-        }
+        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

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

@@ -1,5 +1,5 @@
 import { type Browser } from 'playwright-core';
-import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type CheckoutOutcome, type CheckoutFailureCode, type CheckoutResult, type PreparedCheckoutSessionStore } from './executor.js';
+import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type CheckoutMode, type CheckoutOutcome, type CheckoutFailureCode, type CheckoutResult, type PreparedCheckoutSessionStore } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
 import { serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
@@ -23,10 +23,12 @@ export declare function isTransientDrawFailure(err: unknown): boolean;
  */
 export declare function classifyCardDrawVerdictFailure(err: unknown): {
     transient: boolean;
+    grantCapacity: boolean;
     reasons: string[];
 } | null;
 export type CliReviewInput = {
     url: string;
+    checkoutRoute: 'guest-card';
     amount: string;
     currency: string;
     credentialPath: string;
@@ -42,6 +44,12 @@ export type CliReviewInput = {
     approvalBaseUrl: string;
     merchantName?: string;
     merchantCountryCode?: string;
+    trustedMerchantIdentity?: Readonly<{
+        handoffId: string;
+        checkoutId: string;
+        allowedOrigins: readonly string[];
+        expiresAt: string;
+    }>;
 };
 export type CliReviewFacts = {
     reviewId: string;
@@ -63,8 +71,9 @@ export declare class CheckoutReviewRefusedError extends Error {
     readonly failureCode?: CheckoutFailureCode;
     readonly requiresAdapter: string[];
     readonly detectedRoles: string[];
+    readonly receiptWrite: ReceiptWriteObservation;
     readonly detail?: string;
-    constructor(result: CheckoutResult);
+    constructor(result: CheckoutResult, receiptWrite: ReceiptWriteObservation);
 }
 export type CliPayInput = CliReviewInput & {
     reviewId: string;
@@ -102,6 +111,8 @@ export type CliReceiptFacts = {
     credentialIssued: boolean;
     /** True only when at least one payment field was successfully filled. */
     credentialDisclosed: boolean;
+    /** Privacy-safe local receipt persistence outcome for centralized correlation. */
+    receiptWrite?: ReceiptWriteObservation;
 };
 type PayAttempt = {
     fingerprint: string;
@@ -180,6 +191,9 @@ export type CliMandateFacts = CardMandateFacts & {
 };
 type Session = {
     browser: Browser;
+    /** Exact caller URL repeated at pay time; may contain a UCP capability. */
+    requestUrl: string;
+    checkoutRoute: 'guest-card';
     target: VgsCheckoutTarget;
     amountMinor: number;
     currency: string;
@@ -260,6 +274,14 @@ export type CliEngineDeps = {
     onApprovalUrl?: (url: string) => void;
     reportVicOutcome?: typeof realReportVicOutcome;
     writeReceipt?: typeof realWriteReceipt;
+    /**
+     * Privacy-safe receipt persistence lifecycle signal. The event deliberately
+     * excludes the receipt body, checkout URL, filesystem path, and raw error.
+     * Observer failures are swallowed so logging can never alter checkout state.
+     */
+    onReceiptWrite?: (event: ReceiptWriteObservation) => void | Promise<void>;
+    /** Injectable privacy-safe id source for terminal observations before reviewId exists. */
+    createObservationId?: () => string;
     store?: PreparedCheckoutSessionStore;
     sessions?: Map<string, Session>;
     /** Exact-review singleflight registry; tests inject a fresh map for isolation. */
@@ -295,6 +317,17 @@ export type CliEngineDeps = {
      */
     resolveEmailOtp?: OtpResolver;
 };
+export type ReceiptWriteObservation = {
+    event: 'checkout_receipt_write';
+    status: 'written' | 'failed';
+    mode: CheckoutMode;
+    checkoutOutcome: CheckoutOutcome;
+    merchantHost: string;
+    observationId: string;
+    failureCode: string | null;
+    errorCode: string | null;
+    panRedactions: number | null;
+};
 export declare function createCliCheckoutEngine(deps?: CliEngineDeps): {
     startCardMandate(input: CliStartMandateInput): Promise<CliMandateFacts>;
     claimCardMandate(input: CliClaimMandateInput): Promise<CliMandateFacts>;