@visa/cli 4.1.0-rc.24 → 4.1.0-rc.241

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' | '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,8 @@ export const ALL_ROLES = [
     'nameFirst',
     'nameLast',
     'email',
+    'phone',
+    'oneTimeCode',
     'addressLine1',
     'addressLine2',
     'city',
@@ -37,6 +39,18 @@ 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":
+// `postal_code`/`zip_code`/`country_code`/`promo_code` all contain "code" and
+// would otherwise misclassify as an OTP field and starve the address fill. A
+// bare "code" is matched LAST (bareCodeRe), after every address role.
+const oneTimeCodeRe = /(one[-_ ]?time|(^|[^a-z])otp([^a-z]|$)|passcode|(^|[^a-z])pin([^a-z]|$)|verif(y|ication)?.?code|auth.?code)/;
+// Standalone verification "code" — a last-resort OTP match tried only after the
+// specific address roles (postal/country/state/city/line) have had their say,
+// so a compound `*_code` address/product field is never stolen by the OTP role.
+const bareCodeRe = /(^|[^a-z])code([^a-z]|$)/;
 const postalRe = /(zip|postal|postcode|(^|[^a-z])plz([^a-z]|$)|(^|[^a-z])cep([^a-z]|$)|codigo.?postal)/;
 const countryRe = /(country|(^|[^a-z])land([^a-z]|$)|(^|[^a-z])pais)/;
 const stateRe = /((^|[^a-z])state([^a-z]|$)|province|region|bundesland|provincia)/;
@@ -55,6 +69,9 @@ 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',
     'address-line1': 'addressLine1',
@@ -151,6 +168,11 @@ function attrClassify(text, m) {
         return 'expCombined';
     if (emailRe.test(text))
         return 'email';
+    // 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))
@@ -163,6 +185,10 @@ function attrClassify(text, m) {
         return 'addressLine2';
     if (addr1Re.test(text))
         return 'addressLine1';
+    // Last-resort bare "code" → OTP, only once every address role has been ruled
+    // out, so `postal_code`/`country_code`/etc. keep their own role above.
+    if (bareCodeRe.test(text))
+        return 'oneTimeCode';
     if (nameFirstRe.test(text))
         return 'nameFirst';
     if (nameLastRe.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;
@@ -7,6 +7,9 @@ export type EvidenceStep = {
 export declare function maskPan(pan: string): string;
 export declare function maskCvc(_cvc: string): string;
 export declare function maskExpiry(): string;
+export declare function maskOtp(): string;
+export declare function hostOf(hostOrEmail: string): string;
+export declare function verificationLinkAllowed(link: string, messageFrom: string): boolean;
 export declare function redactContact(role: string, value: string): string;
 export declare class EvidenceLog {
     private steps;

package/dist/checkout-engine/evidence.js

@@ -3,12 +3,15 @@
 // the mandate verdict, the submit, and the final outcome, plus a compact
 // accessibility snapshot of the end state.
 //
-// Money-adjacent hygiene rule: the full PAN, the cvc, and the card expiry
-// NEVER enter the log. PANs are masked to last-4; cvc and expiry are redacted
-// entirely. maskPan/maskCvc/maskExpiry are the only sanctioned way to put a
-// card value anywhere near a log line. Contact PII (cardholder name, email,
-// address, ...) is redacted via redactContact: the log records THAT a field
-// was filled, never the personal value.
+// Money-adjacent hygiene rule: the full PAN, the cvc, the card expiry, and any
+// one-time verification code NEVER enter the log. PANs are masked to last-4;
+// cvc, expiry, and OTP codes are redacted entirely. maskPan/maskCvc/maskExpiry/
+// maskOtp are the only sanctioned way to put such a value anywhere near a log
+// line. (receipt.ts redactPanLikeDigits only catches 12-19-digit PANs, so a
+// 4-8-digit OTP would slip straight through — maskOtp at the fill site is the
+// load-bearing guarantee it never reaches the evidence log.) Contact PII
+// (cardholder name, email, address, ...) is redacted via redactContact: the
+// log records THAT a field was filled, never the personal value.
 // Mask a PAN to its last four digits. Non-digits are stripped for the count.
 export function maskPan(pan) {
     const digits = (pan || '').replace(/\D/g, '');
@@ -25,6 +28,48 @@ export function maskCvc(_cvc) {
 export function maskExpiry() {
     return 'redacted';
 }
+// A merchant one-time verification code is single-use secret material — it
+// never enters the log, in any format. Used at the oneTimeCode fill site so
+// the code is masked exactly as cvc/PAN are (see the header note above).
+export function maskOtp() {
+    return 'redacted';
+}
+// The registrable domain (approx eTLD+1) of an email address or hostname, for
+// the caller-side from-domain guard on verification links: before navigating a
+// link parsed from an untrusted OTP email, require the link host to match the
+// message sender's domain. extract.ts guarantees mechanical extraction, NOT
+// navigation safety — this guard is the anti-injection backstop.
+export function hostOf(hostOrEmail) {
+    return (hostOrEmail.split('@').pop() ?? '').trim().toLowerCase().replace(/\.$/, '');
+}
+// Strict bidirectional host-suffix match (exact / child / parent). Deliberately
+// NOT approximate eTLD+1 — that collapses shared-tenant hosts (`x.myshopify.com`,
+// `x.co.uk`) to a common suffix and lets a sibling tenant match; siblings never
+// match here. Fails SAFE: an unrelated-but-legitimate sender is skipped, not
+// trusted.
+function hostsRelated(a, b) {
+    const x = hostOf(a);
+    const y = hostOf(b);
+    if (!x || !y)
+        return false;
+    return x === y || x.endsWith('.' + y) || y.endsWith('.' + x);
+}
+// Whether a verification LINK is safe to navigate: the sender must NOT be the
+// unauthenticated inbound variant (AgentMail marks spoofable inbound with an
+// `.unauthenticated` sub-label), and the link host must belong to the sender's
+// domain. Returns false to SKIP a link that fails either check.
+export function verificationLinkAllowed(link, messageFrom) {
+    if (/\.unauthenticated\b/i.test(messageFrom))
+        return false;
+    let linkHost;
+    try {
+        linkHost = new URL(link).hostname;
+    }
+    catch {
+        return false;
+    }
+    return hostsRelated(linkHost, messageFrom);
+}
 // Contact values (cardholder name, email, address, ...) are PII and never
 // enter the log raw either. Email keeps its domain for debuggability;
 // everything else becomes a bare presence marker.

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

@@ -2,11 +2,41 @@ import type { Browser, BrowserContext, Page } from 'playwright-core';
 import { type FieldMap } from './detect.js';
 import { type Mandate } from './mandate.js';
 import type { Instrument } from './instrument.js';
-import type { Contact } from './types.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,26 +52,43 @@ 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;
     contact: Contact;
     mode: CheckoutMode;
     outcomeDeadlineMs?: number;
+    resolveEmailOtp?: OtpResolver;
 };
 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;
@@ -49,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';
@@ -66,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';
@@ -86,9 +135,19 @@ export type SubmitApprovedCheckoutOptions = {
     outcomeDeadlineMs?: number;
     challengeHoldMs?: number;
     onChallengeHold?: (signal: string | null) => void;
+    resolveEmailOtp?: OtpResolver;
+};
+export type SubmitCandidateMeta = {
+    label: string;
+    ariaHidden: boolean;
+    tabIndex: number | null;
+    visible: boolean;
+    area: number;
 };
-export declare function minorFromDecimal(text: string): number | null;
-export declare function pageCurrency(text: string): string | null;
+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;
@@ -131,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;