@visa/cli 4.1.0-rc.262 → 4.1.0-rc.263

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

@@ -2,7 +2,7 @@ import type { Page } from 'playwright-core';
 import { type PageAmountRead } from '../amount.js';
 import { type DetectResult, type FieldMap } from '../detect.js';
 import type { CardCredential } from '../instrument.js';
-import type { Contact, FillResult, FilledField } from '../types.js';
+import type { Contact, FillResult, FilledField, PostalAddress } from '../types.js';
 import { type CheckoutAdapter } from './generic.js';
 type ShopifySummary = {
     subtotalMinor: number | null;
@@ -12,10 +12,27 @@ type ShopifySummary = {
     totalMinor: number | null;
     currency: string | null;
     verified: boolean;
+    /**
+     * Component rows that never rendered and were counted as zero to reconcile
+     * the total (#8669). A summary that leans on an implied row is weaker than a
+     * fully rendered one: the row may simply not have been painted yet.
+     */
+    impliedZeroRows: Array<'tax' | 'shipping'>;
 };
 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>;
+/** Consecutive identical reads (200 ms apart) an implied-zero summary must hold. */
+export declare const IMPLIED_ZERO_STABLE_READS = 8;
+export type StableShopifyAmountOptions = {
+    /**
+     * A merchant-authoritative total (minor units) the page must equal before an
+     * implied-zero summary is trusted: for a trusted UCP handoff this is the
+     * server-settled checkout total. Without it, the page must hold the same
+     * implied-zero summary for {@link IMPLIED_ZERO_STABLE_READS} reads.
+     */
+    expectedMinor?: number | null;
+};
+export declare function readStableShopifyAmount(page: Page, timeoutMs?: number, options?: StableShopifyAmountOptions): Promise<PageAmountRead>;
 export declare function isShopifyCheckoutPage(page: Page): Promise<boolean>;
 export type ShopifyCheckoutSurface = {
     signal: string;
@@ -56,6 +73,7 @@ export declare function assertShopifyGuestCheckout(page: Page): Promise<ShopifyG
  * presentation-only: swapping it keeps the same checkout session and token.
  */
 export declare function shopifyEnglishCheckoutUrl(current: string): string | null;
+export declare function requiredAddressRoles(address: PostalAddress, prefix?: string): string[];
 export declare function missingContactRoles(filled: FilledField[], expected: string[]): string[];
 /**
  * The contact surface to prefill. Shipping fields when the checkout has them —

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

@@ -6,10 +6,22 @@ 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;
+// A row whose value has not been computed yet. Shopify phrases it several
+// ways; every one of them means "not a number", never "zero".
+const PENDING_VALUE = /calculated at (?:the )?next step|enter (?:a |your )?shipping address|calculating|getting rates|pending/i;
 function valueAfterLabel(lines, index, inline) {
     if (inline)
         return inline;
-    return lines.slice(index + 1, index + 4).find((line) => /\d|free/i.test(line)) ?? '';
+    for (const line of lines.slice(index + 1, index + 4)) {
+        // Never borrow a later row's number: the scan stops at the next label and
+        // a pending phrase ends it with no value (#8669: "Shipping / Calculated at
+        // next step / Total / $1.50" used to read shipping as $1.50).
+        if (SUMMARY_LABELS.test(line) || PENDING_VALUE.test(line))
+            return '';
+        if (/\d|free/i.test(line))
+            return line;
+    }
+    return '';
 }
 export function parseShopifySummary(text) {
     const lines = text
@@ -53,12 +65,33 @@ export function parseShopifySummary(text) {
     // 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');
+    // Shopify omits a component row entirely when its value is zero: a tax-free
+    // destination renders no "Taxes" line and a free-shipping order can render no
+    // "Shipping" line (observed live 2026-09-02, #8669: a settled Colorado
+    // checkout showed Subtotal + Shipping = Total with no tax row and refused as
+    // unreadable). A row that is absent may only ever count as zero when the
+    // rows that ARE present reconcile exactly to the total; a pending
+    // "Calculated at next step" still parses as null and still refuses.
+    const rowAbsent = (...keys) => keys.every((key) => !values.has(key));
+    const taxAbsent = rowAbsent('estimated taxes', 'taxes', 'tax');
+    const shippingAbsent = rowAbsent('shipping');
+    const reconciles = (shipping, tax) => subtotalMinor != null &&
+        shipping != null &&
+        tax != null &&
+        totalMinor != null &&
+        subtotalMinor + shipping + tax - discountMinor === totalMinor;
+    // A row that rendered with a pending or unreadable value is present-and-null
+    // and always refuses; only a row that never rendered at all may imply zero.
+    const fullyReconciled = reconciles(shippingMinor, taxMinor);
+    const impliedZeroRows = [];
+    if (componentLabelPresent && !fullyReconciled) {
+        if (taxAbsent && reconciles(shippingMinor, 0))
+            impliedZeroRows.push('tax');
+        else if (shippingAbsent && reconciles(0, taxMinor))
+            impliedZeroRows.push('shipping');
+    }
     const verified = componentLabelPresent
-        ? subtotalMinor != null &&
-            shippingMinor != null &&
-            taxMinor != null &&
-            totalMinor != null &&
-            subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor
+        ? fullyReconciled || impliedZeroRows.length > 0
         : totalMinor != null;
     return {
         subtotalMinor,
@@ -68,6 +101,7 @@ export function parseShopifySummary(text) {
         totalMinor,
         currency: pageCurrency(totalText ?? ''),
         verified,
+        impliedZeroRows,
     };
 }
 export async function readShopifyAmount(page, requireVerified) {
@@ -89,24 +123,46 @@ export async function readShopifyAmount(page, requireVerified) {
         amountMinor: summary.totalMinor,
         currency: summary.currency,
         source: 'shopify-summary',
+        ...(summary.impliedZeroRows.length > 0 ? { impliedZeroRows: summary.impliedZeroRows } : {}),
     };
 }
-export async function readStableShopifyAmount(page, timeoutMs = 6_000) {
+/** Consecutive identical reads (200 ms apart) an implied-zero summary must hold. */
+export const IMPLIED_ZERO_STABLE_READS = 8;
+export async function readStableShopifyAmount(page, timeoutMs = 6_000, options = {}) {
     const startedAt = Date.now();
     let previous = '';
     let stableReads = 0;
+    let sawImpliedZeroMismatch = false;
     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;
+        if (latest.kind === 'ok') {
+            const implied = (latest.impliedZeroRows?.length ?? 0) > 0;
+            if (!implied) {
+                if (stableReads >= 1)
+                    return latest;
+            }
+            else if (options.expectedMinor != null) {
+                // A missing tax or shipping row may be a pre-tax render (#8669). The
+                // merchant-authoritative total is the settle signal: accept the implied
+                // summary only once the page total equals it.
+                if (latest.amountMinor === options.expectedMinor && stableReads >= 1)
+                    return latest;
+                sawImpliedZeroMismatch = true;
+            }
+            else if (stableReads >= IMPLIED_ZERO_STABLE_READS) {
+                return latest;
+            }
+        }
         previous = fingerprint;
         await page.waitForTimeout(200);
     }
     return {
         kind: 'unreadable',
-        reason: 'Shopify tax and total did not settle before the review deadline',
+        reason: sawImpliedZeroMismatch
+            ? 'Shopify summary omitted a tax or shipping row and its total never matched the merchant-settled total'
+            : 'Shopify tax and total did not settle before the review deadline',
     };
 }
 export async function isShopifyCheckoutPage(page) {
@@ -565,7 +621,7 @@ function labelBillingEvidence(filled) {
         role: BILLING_ROLE_NAMES[field.role] ?? `billing:${field.role}`,
     }));
 }
-function requiredAddressRoles(address, prefix = '') {
+export 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 [

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

@@ -11,5 +11,7 @@ export type PageAmountRead = {
     amountMinor: number;
     currency: string | null;
     source: 'page-attr' | 'page-text' | 'shopify-summary';
+    /** Shopify rows counted as zero because they never rendered (#8669). */
+    impliedZeroRows?: Array<'tax' | 'shipping'>;
 };
 export declare function readGenericPageAmount(page: Page): Promise<PageAmountRead>;

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

@@ -1,5 +1,6 @@
 import { type Browser } from 'playwright-core';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type CheckoutMode, type CheckoutOutcome, type CheckoutFailureCode, type CheckoutResult, type PreparedCheckoutSessionStore } from './executor.js';
+import type { MandateRefusalCode } from './mandate.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
 import { ServerIntentError, serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
@@ -74,6 +75,8 @@ export declare class CheckoutReviewRefusedError extends Error {
     readonly code = "CHECKOUT_REVIEW_REFUSED";
     readonly checkoutOutcome: CheckoutOutcome;
     readonly failureCode?: CheckoutFailureCode;
+    /** Bounded mandate/trusted-identity reason (#8669); absent for other outcomes. */
+    readonly refusalCode?: MandateRefusalCode;
     readonly requiresAdapter: string[];
     readonly detectedRoles: string[];
     readonly receiptWrite: ReceiptWriteObservation;

package/dist/checkout-engine/cli-engine.js

@@ -161,6 +161,8 @@ export class CheckoutReviewRefusedError extends Error {
     code = 'CHECKOUT_REVIEW_REFUSED';
     checkoutOutcome;
     failureCode;
+    /** Bounded mandate/trusted-identity reason (#8669); absent for other outcomes. */
+    refusalCode;
     requiresAdapter;
     detectedRoles;
     receiptWrite;
@@ -172,6 +174,7 @@ export class CheckoutReviewRefusedError extends Error {
         this.name = 'CheckoutReviewRefusedError';
         this.checkoutOutcome = result.outcome;
         this.failureCode = result.failureCode;
+        this.refusalCode = result.refusalCode;
         this.requiresAdapter = [...result.requiresAdapter];
         this.detectedRoles = Object.keys(result.fields);
         this.receiptWrite = receiptWrite;

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

@@ -1,11 +1,12 @@
 import type { Browser, BrowserContext, Page } from 'playwright-core';
 import { type FieldMap } from './detect.js';
-import { type Mandate } from './mandate.js';
+import { type Mandate, type MandateRefusalCode } from './mandate.js';
 import type { Instrument } from './instrument.js';
 import type { Contact, OtpResolver } from './types.js';
 import { EvidenceLog } from './evidence.js';
 import { type ObservedOutcome } from './outcome.js';
 import { type WebBotAuthConfig } from './web-bot-auth.js';
+import { type NavigationRedirectEvidence } from './shopify-primary-domain.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 export type CheckoutMode = 'dry-run' | 'submit';
 export type CheckoutRoute = 'guest-card';
@@ -53,6 +54,8 @@ export type CheckoutResult = {
     credentialLifecycle: CredentialLifecycle;
     credentialTiming: CredentialTiming;
     failureCode?: CheckoutFailureCode;
+    /** Bounded reason behind a `blocked-by-mandate` outcome; absent otherwise. */
+    refusalCode?: MandateRefusalCode;
     detail?: string;
 };
 export type PrepareCheckoutOptions = {
@@ -190,7 +193,34 @@ export declare class InMemoryPreparedCheckoutStore implements PreparedCheckoutSe
     private scheduleReaper;
     private closeState;
 }
+export type TrustedOriginVerdict = Readonly<{
+    code: MandateRefusalCode;
+    reason: string;
+}>;
+export declare function trustedMerchantOriginVerdict(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): TrustedOriginVerdict | null;
 export declare function trustedMerchantOriginRefusal(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): string | null;
+/**
+ * Bind the storefront a trusted UCP continuation actually lands on (#8669).
+ *
+ * The merchant published its UCP business profile at its own business origin
+ * and declared the permanent `*.myshopify.com` service that issued the
+ * continuation; the CLI verified both before minting the handoff. That is
+ * independently verified merchant provenance, so the review may bind the final
+ * page origin when, and only when: the navigation started on that declared
+ * myshopify origin, the final origin is plain HTTPS, and its host is the
+ * declared business host modulo a leading `www.` label. The redirect chain in
+ * between (Shopify's primary-domain hop, its shop.app bounce, #8496) carries no
+ * authority either way: a redirect cannot land on the merchant's own business
+ * domain unless the merchant controls it, and any other final host stays an
+ * undeclared origin. Shopify's `primary_domain_redirection` proof is recorded
+ * as evidence when present but is not required.
+ */
+export declare function trustedShopifyAliasOrigin(args: {
+    allowedOrigins: readonly string[];
+    initialUrl: string;
+    finalUrl: string;
+    redirects: readonly NavigationRedirectEvidence[];
+}): string | null;
 export declare function reconcileHeldOutcome(original: ObservedOutcome, held: ObservedOutcome): ObservedOutcome;
 export declare function debugShotMaskPlan(fields: FieldMap): {
     skipReason: string | null;