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

package/dist/checkout-engine/confirmed-merchants.d.ts

@@ -0,0 +1,31 @@
+/** One confirmed charge, in the receipt's own terms. */
+export type ConfirmedCharge = {
+    recordedAt: string;
+    amount: string;
+    currency: string;
+    /** Receipt file basename, so an operator can open the evidence log. */
+    receiptFile: string;
+};
+export type ConfirmedMerchant = {
+    /** The checkout page the card went through. */
+    url: string;
+    host: string;
+    /**
+     * Curated human identity (known-merchants.ts), present only when someone has
+     * identified who is behind this checkout URL. Hosted payment links carry an
+     * opaque path on the PSP's host, so without this a row names nobody.
+     */
+    name?: string;
+    category?: string;
+    website?: string;
+    confirmedCount: number;
+    lastConfirmedAt: string;
+    charges: ConfirmedCharge[];
+};
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export declare function readConfirmedMerchants(receiptDir?: string): Promise<ConfirmedMerchant[]>;

package/dist/checkout-engine/confirmed-merchants.js

@@ -0,0 +1,165 @@
+// "Where can I use my card?", the merchant registry derived from this
+// device's checkout receipts.
+//
+// Receipts (receipt.ts) are the only local record that a real merchant
+// checkout completed on this box. This module reads them back and answers one
+// question: which checkout pages has this card actually gone through?
+//
+// A merchant only counts when BOTH halves agree. The engine's own outcome must
+// be 'confirmed' (the merchant showed a definitive success) AND the VIC
+// confirmation must have posted APPROVED (the network side of the same
+// purchase). Either half alone is a claim, not a completion: a 'confirmed' with
+// no posted confirmation is exactly the reconciliation case receipt.ts flags,
+// and a posted DECLINED is a completed report of a failure.
+//
+// Reading is best-effort by construction. The receipts directory is an operator
+// artifact that anything on the box can touch, so an unreadable or malformed
+// file is skipped rather than failing the whole read. One bad file must not
+// hide every merchant behind it.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+import { RECEIPT_DIR } from './receipt-dir.js';
+/**
+ * The URL a receipt's charge happened at.
+ *
+ * A compact v2 receipt carries an exact checkout URL only when it is already in
+ * the curated identity map; otherwise it carries the host. Legacy v1 receipts
+ * keep the URL in the evidence log (the executor's first 'navigation' step is
+ * the page the run opened), so recover it there and fall back to the host when
+ * that evidence is absent or shaped differently.
+ */
+function checkoutUrlOf(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const checkoutUrl = receipt.merchant.checkoutUrl;
+        return checkoutUrl && KNOWN_MERCHANT_IDENTITIES[checkoutUrl]
+            ? checkoutUrl
+            : `https://${receipt.merchant.host}/`;
+    }
+    const navigation = receipt.evidence.steps.find((step) => step?.type === 'navigation');
+    const data = navigation?.data;
+    const url = typeof data === 'object' && data !== null ? data.url : undefined;
+    return typeof url === 'string' && url.length > 0 ? url : `https://${receipt.merchant.host}/`;
+}
+function isConfirmedCompletion(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        return receipt.outcome === 'confirmed' && receipt.network.confirmation === 'APPROVED';
+    }
+    return (receipt.outcome === 'confirmed' &&
+        receipt.vicConfirmation?.posted === true &&
+        receipt.vicConfirmation.transactionStatus === 'APPROVED');
+}
+/**
+ * Parse one supported receipt file, or null when its fields cannot safely feed
+ * the registry. Deliberately permissive about everything the grouping does not
+ * touch: older and newer engines only have to carry the fields read below.
+ */
+function parseReceipt(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const receipt = parsed;
+    if (receipt.schema === 'checkout-agent-receipt/v1') {
+        const v1 = receipt;
+        if (typeof v1.recordedAt !== 'string')
+            return null;
+        if (typeof v1.merchant?.host !== 'string')
+            return null;
+        if (typeof v1.transaction?.amount !== 'string')
+            return null;
+        if (typeof v1.transaction?.currency !== 'string')
+            return null;
+        if (!Array.isArray(v1.evidence?.steps))
+            return null;
+        return v1;
+    }
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const v2 = receipt;
+        if (typeof v2.recordedAt !== 'string')
+            return null;
+        if (typeof v2.merchant?.host !== 'string')
+            return null;
+        if (v2.merchant.checkoutUrl !== null && typeof v2.merchant.checkoutUrl !== 'string')
+            return null;
+        if (typeof v2.transaction?.amount !== 'string')
+            return null;
+        if (typeof v2.transaction?.currency !== 'string')
+            return null;
+        if (v2.network?.confirmation !== null &&
+            v2.network?.confirmation !== 'APPROVED' &&
+            v2.network?.confirmation !== 'DECLINED') {
+            return null;
+        }
+        return v2;
+    }
+    return null;
+}
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export async function readConfirmedMerchants(receiptDir = RECEIPT_DIR) {
+    let names;
+    try {
+        names = await readdir(receiptDir);
+    }
+    catch {
+        return [];
+    }
+    const byUrl = new Map();
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(receiptDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const receipt = parseReceipt(raw);
+        if (!receipt || !isConfirmedCompletion(receipt))
+            continue;
+        const url = checkoutUrlOf(receipt);
+        const charge = {
+            recordedAt: receipt.recordedAt,
+            amount: receipt.transaction.amount,
+            currency: receipt.transaction.currency,
+            receiptFile: name,
+        };
+        const existing = byUrl.get(url);
+        if (existing) {
+            existing.confirmedCount += 1;
+            existing.charges.push(charge);
+            if (charge.recordedAt > existing.lastConfirmedAt) {
+                existing.lastConfirmedAt = charge.recordedAt;
+            }
+            continue;
+        }
+        const identity = KNOWN_MERCHANT_IDENTITIES[url];
+        byUrl.set(url, {
+            url,
+            host: receipt.merchant.host,
+            // Conditional spread on purpose: an unidentified merchant carries no
+            // identity keys at all, rather than keys holding undefined.
+            ...(identity ?? {}),
+            confirmedCount: 1,
+            lastConfirmedAt: charge.recordedAt,
+            charges: [charge],
+        });
+    }
+    const merchants = [...byUrl.values()];
+    for (const merchant of merchants) {
+        merchant.charges.sort((left, right) => (left.recordedAt < right.recordedAt ? 1 : -1));
+    }
+    merchants.sort((left, right) => (left.lastConfirmedAt < right.lastConfirmedAt ? 1 : -1));
+    return merchants;
+}

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

@@ -1,6 +1,6 @@
 import type { Page } from 'playwright-core';
 export type FieldSource = 'autocomplete' | 'attr-heuristic' | 'label-text' | 'iframe-psp' | 'type-inference';
-export type FieldRole = 'number' | 'expMonth' | 'expYear' | 'expCombined' | 'cvc' | 'name' | 'nameFirst' | 'nameLast' | 'email' | 'oneTimeCode' | 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'postalCode' | 'country';
+export type FieldRole = 'number' | 'expMonth' | 'expYear' | 'expCombined' | 'cvc' | 'name' | 'nameFirst' | 'nameLast' | 'email' | 'phone' | 'oneTimeCode' | 'addressLine1' | 'addressLine2' | 'city' | 'state' | 'postalCode' | 'country';
 export declare const ALL_ROLES: FieldRole[];
 export type SelectOption = {
     value: string;

package/dist/checkout-engine/detect.js

@@ -21,6 +21,7 @@ export const ALL_ROLES = [
     'nameFirst',
     'nameLast',
     'email',
+    'phone',
     'oneTimeCode',
     'addressLine1',
     'addressLine2',
@@ -38,6 +39,7 @@ const expMonthRe = /(exp.?month|expmonth|exp_mm|(^|[^a-z])mm([^a-z]|$)|(^|[^a-z]
 const expYearRe = /(exp.?year|expyear|exp_yy|(^|[^a-z])yy(yy)?([^a-z]|$)|(^|[^a-z])year([^a-z]|$)|jahr|annee|(^|[^a-z])ano([^a-z]|$))/;
 const expCombinedRe = /(exp(iry|iration)?(.?date)?|mm.?\/.?yy|mm.?jj|valid.?thru|ablauf|caducidad)/;
 const emailRe = /(e-?mail|correo|courriel)/;
+const phoneRe = /(phone|telephone|mobile|(^|[^a-z])tel([^a-z]|$)|telefono|téléphone)/;
 // One-time verification code (merchant email/SMS OTP). Ordered AFTER cvcRe in
 // attrClassify so a card CVC ("security code"/"card code") still wins — this
 // regex deliberately omits those card phrasings. It also OMITS a bare "code":
@@ -67,6 +69,8 @@ const AUTOCOMPLETE_MAP = {
     'cc-name': 'name',
     name: 'name',
     email: 'email',
+    tel: 'phone',
+    'tel-national': 'phone',
     'one-time-code': 'oneTimeCode',
     'given-name': 'nameFirst',
     'family-name': 'nameLast',
@@ -167,6 +171,8 @@ function attrClassify(text, m) {
     // OTP comes after cvc (checked above) so card CVC still classifies as 'cvc'.
     if (oneTimeCodeRe.test(text))
         return 'oneTimeCode';
+    if (phoneRe.test(text))
+        return 'phone';
     if (postalRe.test(text))
         return 'postalCode';
     if (countryRe.test(text))

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

@@ -1,4 +1,4 @@
-export type EvidenceStepType = 'navigation' | 'dom-stable' | 'review' | 'approval' | 'adapter-selected' | 'reveal' | 'detect' | 'field-fill' | 'amount-fill' | 'credential-minted' | 'fill-complete' | 'psp-detected' | 'mandate-verdict' | 'submit' | 'challenge-hold' | 'outcome' | 'note';
+export type EvidenceStepType = 'navigation' | 'dom-stable' | 'review' | 'approval' | 'adapter-selected' | 'reveal' | 'detect' | 'field-fill' | 'amount-fill' | 'contact-prefill' | 'credential-minted' | 'credential-skipped' | 'credential-expiry-check' | 'fill-complete' | 'psp-detected' | 'mandate-verdict' | 'submit' | 'challenge-hold' | 'outcome' | 'note';
 export type EvidenceStep = {
     ts: string;
     type: EvidenceStepType;

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

@@ -5,8 +5,38 @@ 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';
+export { minorFromDecimal, pageCurrency } from './amount.js';
 export type CheckoutMode = 'dry-run' | 'submit';
-export type CheckoutOutcome = 'filled-dry-run' | 'partial-fill' | 'adapter-required' | 'confirmed' | 'declined' | 'action-required' | 'cancelled' | 'blocked-by-mandate' | 'failed';
+export type CheckoutRoute = 'guest-card';
+export type CheckoutOutcome = 'reviewed-dry-run'
+/** Historical receipt value from the credential-disclosing dry-run. */
+ | 'filled-dry-run' | 'partial-fill' | 'adapter-required' | 'confirmed' | 'declined' | 'action-required' | 'cancelled' | 'blocked-by-mandate'
+/**
+ * KNOWN-NOT-CHARGED. Every `failed` path ends before the pay control was
+ * clicked (or before a credential existed at all), so a caller may retry it
+ * without risking a second charge.
+ */
+ | 'failed'
+/**
+ * SUBMITTED, OUTCOME UNKNOWN — the pay control WAS clicked and neither a
+ * confirmation nor a decline was observed before the deadline. The charge may
+ * have captured. NEVER retry this automatically.
+ *
+ * This case used to be reported as `failed`, and the difference is not
+ * academic: on 2026-08-17 a whop.com checkout returned `failed` here, the
+ * caller read that as "nothing happened" and re-ran the purchase, and the
+ * second run drew a second $5 against the owner's mandate. `outcome.ts`
+ * already treats an unrecognized post-submit page as the SAFE direction
+ * ('unknown' → operator verification); collapsing it into `failed` at the
+ * boundary is what threw that safety away. The distinction has to survive all
+ * the way to the value consumers branch on.
+ */
+ | 'unverified';
+/** Stable machine-readable cause for an expected terminal checkout result. */
+export type CheckoutFailureCode = 'card-number-field-unavailable' | 'human-action-required' | 'mandate-blocked'
+/** A detected, visible field we held a value for refused every fill attempt. */
+ | 'required-field-unfillable';
 export type CredentialLifecycle = 'not-requested' | 'minted-not-exposed' | 'partially-exposed' | 'fully-filled';
 export type CredentialTiming = {
     approvedAt?: string;
@@ -22,15 +52,29 @@ export type CheckoutResult = {
     requiresAdapter: string[];
     credentialLifecycle: CredentialLifecycle;
     credentialTiming: CredentialTiming;
+    failureCode?: CheckoutFailureCode;
     detail?: string;
 };
 export type PrepareCheckoutOptions = {
     url: string;
+    checkoutRoute: CheckoutRoute;
     mandate: Mandate;
     browser: Browser;
+    contact?: Contact;
     amountMinor?: number;
     currency?: string;
     debugShotsDir?: string;
+    webBotAuth?: WebBotAuthConfig | null;
+    /**
+     * Process-internal UCP provenance. Public callers may relay only handoffId;
+     * this origin set is recovered by the CLI from its single-use registry.
+     */
+    trustedMerchantIdentity?: Readonly<{
+        handoffId: string;
+        checkoutId: string;
+        allowedOrigins: readonly string[];
+        expiresAt: string;
+    }>;
 };
 export type RunCheckoutOptions = PrepareCheckoutOptions & {
     instrument: Instrument;
@@ -43,6 +87,8 @@ export type CheckoutReview = {
     id: string;
     url: string;
     merchantHost: string;
+    /** Exact origin frozen for a trusted UCP checkout; omitted for generic flows. */
+    merchantOrigin?: string;
     amountMinor: number;
     currency: string;
     mandateMaxAmountMinor: number;
@@ -50,6 +96,7 @@ export type CheckoutReview = {
     submitTarget: string | null;
     submitTargetFingerprint: Readonly<CheckoutSubmitTargetFingerprint> | null;
     detectedRoles: readonly string[];
+    checkoutRoute: CheckoutRoute;
 };
 export type CheckoutSubmitTargetFingerprint = {
     kind: 'submit-control' | 'text-button';
@@ -67,6 +114,7 @@ export type PreparedCheckout = {
     readonly fields: Readonly<FieldMap>;
     readonly evidence: EvidenceLog;
     readonly requiresAdapter: readonly string[];
+    readonly checkoutRoute: CheckoutRoute;
 };
 export type PrepareCheckoutResult = {
     status: 'ready';
@@ -89,8 +137,17 @@ export type SubmitApprovedCheckoutOptions = {
     onChallengeHold?: (signal: string | null) => void;
     resolveEmailOtp?: OtpResolver;
 };
-export declare function minorFromDecimal(text: string): number | null;
-export declare function pageCurrency(text: string): string | null;
+export type SubmitCandidateMeta = {
+    label: string;
+    ariaHidden: boolean;
+    tabIndex: number | null;
+    visible: boolean;
+    area: number;
+};
+export declare function preferredSubmitIndex(cands: readonly SubmitCandidateMeta[], opts?: {
+    allowDeferred?: boolean;
+}): number;
+export declare function snapshotOrigin(rawUrl: string): string;
 export type PreparedCheckoutSession = {
     checkout: PreparedCheckout;
     context: BrowserContext;
@@ -133,6 +190,7 @@ export declare class InMemoryPreparedCheckoutStore implements PreparedCheckoutSe
     private scheduleReaper;
     private closeState;
 }
+export declare function trustedMerchantOriginRefusal(options: PrepareCheckoutOptions, pageUrl: string, expectedOrigin?: string): string | null;
 export declare function reconcileHeldOutcome(original: ObservedOutcome, held: ObservedOutcome): ObservedOutcome;
 export declare function debugShotMaskPlan(fields: FieldMap): {
     skipReason: string | null;