@visa/cli 4.1.0-rc.165 → 4.1.0-rc.167

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

@@ -10,9 +10,32 @@ export { minorFromDecimal, pageCurrency } from './amount.js';
 export type CheckoutMode = 'dry-run' | 'submit';
 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' | 'failed';
+ | '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';
+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;

package/dist/checkout-engine/executor.js

@@ -1116,9 +1116,30 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 ? []
                 : ['expiry']),
         ];
+        // Roles the adapter TRIED to fill and never landed, across every reveal
+        // attempt. A job only exists when the field was detected, was visible, and
+        // we held a value for it (see `add()` in adapters/generic.ts) — so a failure
+        // here is never "the page didn't ask for it". It means the page asked, we
+        // answered, and the element refused.
+        //
+        // Roles that failed on an early attempt and succeeded after a reveal are
+        // excluded: `successfulRoles` spans all four attempts, same as above.
+        const failedFillRoles = [
+            ...new Set(evidence
+                .getSteps()
+                .filter((step) => step.type === 'field-fill' && step.data.ok === false)
+                .map((step) => String(step.data.role))),
+        ]
+            .filter((role) => !successfulRoles.has(role))
+            .sort();
         evidence.step('fill-complete', {
-            ok: missingCredentialRoles.length === 0,
+            // "Ready to submit", not "the card fields landed". Before 2026-08-17 this
+            // read only the credential roles, so a whop.com run whose city/state/
+            // postalCode all timed out recorded `ok: true` and clicked Get access on
+            // a form it knew was incomplete.
+            ok: missingCredentialRoles.length === 0 && failedFillRoles.length === 0,
             missingCredentialRoles,
+            failedFillRoles,
         });
         if (options.debugShotsDir) {
             await captureDebugShot(page, options.debugShotsDir, checkout.review.id, '2-filled', evidence, state.fields);
@@ -1177,6 +1198,20 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('failed', state.fields, evidence, requiresAdapter, `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
         }
+        // STOP BEFORE THE CLICK when any field we tried to fill refused. Submitting
+        // a form we know is incomplete is how a PSP ends up holding a charge we
+        // cannot then confirm or account for: the 2026-08-17 whop.com run filled the
+        // card into Basis Theory iframes, watched city/state/postalCode time out at
+        // 5s each, clicked Get access anyway, and could never observe an outcome.
+        //
+        // This refusal happens BEFORE the submit click, so nothing can be charged by
+        // it — the safe direction, and the reason it is allowed to be strict. A
+        // merchant whose address widget we cannot drive now fails cleanly and
+        // retryably instead of dangerously.
+        if (failedFillRoles.length > 0) {
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('partial-fill', state.fields, evidence, requiresAdapter, `required field fill failed: ${failedFillRoles.join(', ')} — not submitting an incomplete form. Nothing was charged.`, undefined, 'required-field-unfillable');
+        }
         if (!submit) {
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('failed', state.fields, evidence, requiresAdapter, 'no submit control detected');
@@ -1216,6 +1251,12 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 credentialExpiresAt,
             });
         }
+        // ORDER IS LOAD-BEARING: record the click BEFORE performing it. The catch
+        // block classifies a throw by whether this step exists — recorded means
+        // "we may have charged" (`unverified`), absent means "retry is safe"
+        // (`failed`). Recording after `submit.click()` would let a throw raised by
+        // the click itself look retry-safe, which is the double-charge direction.
+        // Pinned by "a throw AFTER the pay control was clicked reports unverified".
         evidence.step('submit', { clicked: true, target: submit.desc });
         await submit.click();
         await settle(page);
@@ -1337,19 +1378,35 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             });
             return makeResult('confirmed', state.fields, evidence, requiresAdapter, undefined, confirmationRef);
         }
+        // The pay control was clicked and the observer reached its deadline with no
+        // definitive answer. This is NOT a failure — it is the absence of an answer,
+        // and the charge may well have captured. Reporting it as `failed` is what
+        // let a caller re-run the 2026-08-17 whop.com purchase and draw a second $5.
         evidence.step('outcome', {
-            outcome: 'failed',
+            outcome: 'unverified',
             reason: 'no confirmation or decline signal',
             lastSeen: observed.lastSeen,
             attempts: observed.attempts,
             elapsedMs: observed.elapsedMs,
         });
-        return makeResult('failed', state.fields, evidence, requiresAdapter, observed.lastSeen === 'processing'
-            ? 'submitted but outcome unknown (page still processing at deadline)'
-            : 'submitted but outcome unknown');
+        return makeResult('unverified', state.fields, evidence, requiresAdapter, observed.lastSeen === 'processing'
+            ? 'submitted but outcome unknown (page still processing at deadline) — the charge may have gone through; verify with the merchant before any retry'
+            : 'submitted but outcome unknown — the charge may have gone through; verify with the merchant before any retry');
     }
     catch (err) {
         const detail = err.message;
+        // A throw AFTER the pay control was clicked (browser teardown, navigation
+        // race, evidence I/O) leaves the same open question as the deadline path: we
+        // clicked, and we do not know what happened. It must not report `failed`
+        // either. A throw before the click never disclosed a payable form, so it
+        // stays a clean, retry-safe failure.
+        const submitted = evidence
+            .getSteps()
+            .some((step) => step.type === 'submit' && step.data.clicked === true);
+        if (submitted) {
+            evidence.step('outcome', { outcome: 'unverified', error: detail });
+            return makeResult('unverified', state.fields, evidence, requiresAdapter, `${detail} — the pay control was already clicked; the charge may have gone through, so verify with the merchant before any retry`);
+        }
         evidence.step('outcome', { outcome: 'failed', error: detail });
         return makeResult('failed', state.fields, evidence, requiresAdapter, detail);
     }

package/dist/checkout-engine/live-fill-approval.d.ts

@@ -28,5 +28,10 @@ export declare function isRunSuccess(mode: CheckoutMode, outcome: CheckoutOutcom
  * so no charge can exist until it is completed — the double-charge warning
  * would misdirect the operator, and the runner prints the challenge-specific
  * notice instead.
+ *
+ * The executor now NAMES this state in the outcome itself ('unverified'), so
+ * the two agree by construction. This predicate stays the broader guard: it
+ * also catches a post-click throw or any future outcome that leaves the same
+ * question open, and it is what the receipt's reconciliation list reads.
  */
 export declare function submitClickedWithoutConfirmation(result: CheckoutResult): boolean;

package/dist/checkout-engine/live-fill-approval.js

@@ -60,6 +60,11 @@ export function isRunSuccess(mode, outcome) {
  * so no charge can exist until it is completed — the double-charge warning
  * would misdirect the operator, and the runner prints the challenge-specific
  * notice instead.
+ *
+ * The executor now NAMES this state in the outcome itself ('unverified'), so
+ * the two agree by construction. This predicate stays the broader guard: it
+ * also catches a post-click throw or any future outcome that leaves the same
+ * question open, and it is what the receipt's reconciliation list reads.
  */
 export function submitClickedWithoutConfirmation(result) {
     if (result.outcome === 'confirmed' ||

package/dist/checkout-engine/receipt.js

@@ -37,7 +37,15 @@ export function buildReceipt(input) {
             ? 'No action needed.'
             : result.outcome === 'declined'
                 ? 'Review the decline before trying again.'
-                : 'Review this outcome before retrying.';
+                : result.outcome === 'unverified'
+                    ? // Defensive: reconciliationFor() already pushes the richer
+                        // submit-clicked reason for this outcome, so this line is only
+                        // reached if that ever stops firing. It must still not invite a
+                        // retry.
+                        'The charge may have gone through. Confirm with the merchant before retrying.'
+                    : result.outcome === 'partial-fill'
+                        ? 'Nothing was submitted and nothing was charged. Safe to try again once the checkout can be filled.'
+                        : 'Review this outcome before retrying.';
     const recoveryActions = reconciliation.reasons.length > 0 ? reconciliation.reasons : [fallbackAction];
     const cardLast4 = input.cardLast4 && /^\d{4}$/.test(input.cardLast4) ? input.cardLast4 : null;
     const checkoutUrl = input.merchant.url && KNOWN_MERCHANT_IDENTITIES[input.merchant.url] ? input.merchant.url : null;

package/dist/checkout-engine/unresolved-charges.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Outcomes whose receipt cannot rule out a charge.
+ *
+ * Both of these record a run where the pay control was clicked and no
+ * definitive answer came back:
+ *   - `unverified`      — no confirmation or decline observed before the deadline
+ *   - `action-required` — an issuer challenge appeared, which happens AFTER the
+ *                         click, so the authorization may already exist
+ *
+ * Everything else is either definitive (`confirmed`, `declined`) or provably
+ * pre-click (`reviewed-dry-run`, `partial-fill`, `failed`, ...). Widening this
+ * set blocks legitimate retries; narrowing it lets a double charge through, so
+ * an outcome earns a place here only by being genuinely post-click.
+ */
+export declare const MAY_HAVE_CHARGED_OUTCOMES: ReadonlySet<string>;
+/** One local attempt that may have taken money and was never resolved. */
+export type UnresolvedCharge = {
+    recordedAt: string;
+    host: string;
+    amount: string;
+    amountMinor: number;
+    currency: string;
+    outcome: string;
+    /** Receipt file basename, so a caller can name the evidence a human must check. */
+    receiptFile: string;
+};
+/**
+ * Local attempts that may have charged, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as "no unresolved charges". The caller
+ * decides what an empty answer means — see the fail-open note at its call site.
+ */
+export declare function readUnresolvedCharges(receiptDir?: string): Promise<UnresolvedCharge[]>;

package/dist/checkout-engine/unresolved-charges.js

@@ -0,0 +1,125 @@
+// "Did this device already submit this exact purchase?", read back from the
+// checkout receipts on disk.
+//
+// The engine now reports a submitted-but-unobserved checkout as `unverified`
+// instead of `failed`, and pay_merchant tells the caller not to retry it. This
+// module is the belt to that suspenders: even a caller that ignores the words
+// can be stopped, because the previous attempt left a receipt.
+//
+// It answers one question — which local receipts record an attempt that MAY
+// HAVE CHARGED and was never resolved — and deliberately answers nothing else.
+// The matching (same merchant, same amount, recent enough) lives in the caller,
+// which owns the policy; this side owns only the read.
+//
+// Sibling of confirmed-merchants.ts and loaded through the same seam: it
+// imports node built-ins and types only, so reading receipts never pulls
+// playwright into the CLI process.
+//
+// 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.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { RECEIPT_DIR } from './receipt-dir.js';
+/**
+ * Outcomes whose receipt cannot rule out a charge.
+ *
+ * Both of these record a run where the pay control was clicked and no
+ * definitive answer came back:
+ *   - `unverified`      — no confirmation or decline observed before the deadline
+ *   - `action-required` — an issuer challenge appeared, which happens AFTER the
+ *                         click, so the authorization may already exist
+ *
+ * Everything else is either definitive (`confirmed`, `declined`) or provably
+ * pre-click (`reviewed-dry-run`, `partial-fill`, `failed`, ...). Widening this
+ * set blocks legitimate retries; narrowing it lets a double charge through, so
+ * an outcome earns a place here only by being genuinely post-click.
+ */
+export const MAY_HAVE_CHARGED_OUTCOMES = new Set([
+    'unverified',
+    'action-required',
+]);
+/**
+ * Every field this module reads, validated. Deliberately permissive about
+ * everything else: older and newer engines only have to carry these.
+ *
+ * Both receipt schemas expose all of them at the same paths, so unlike
+ * confirmed-merchants.ts there is nothing here that needs a per-schema branch.
+ */
+function parseUnresolved(json, receiptFile) {
+    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' &&
+        receipt.schema !== 'checkout-agent-receipt/v2') {
+        return null;
+    }
+    if (typeof receipt.outcome !== 'string' || !MAY_HAVE_CHARGED_OUTCOMES.has(receipt.outcome)) {
+        return null;
+    }
+    if (typeof receipt.recordedAt !== 'string' || Number.isNaN(Date.parse(receipt.recordedAt))) {
+        return null;
+    }
+    const host = receipt.merchant?.host;
+    if (typeof host !== 'string' || host.length === 0)
+        return null;
+    const transaction = receipt.transaction;
+    if (typeof transaction?.amount !== 'string')
+        return null;
+    if (typeof transaction.currency !== 'string')
+        return null;
+    // A receipt whose amount cannot be compared cannot gate a retry on amount, and
+    // a guard that silently matched every amount would be worse than none.
+    if (typeof transaction.amountMinor !== 'number' || !Number.isFinite(transaction.amountMinor)) {
+        return null;
+    }
+    return {
+        recordedAt: receipt.recordedAt,
+        host,
+        amount: transaction.amount,
+        amountMinor: transaction.amountMinor,
+        currency: transaction.currency,
+        outcome: receipt.outcome,
+        receiptFile,
+    };
+}
+/**
+ * Local attempts that may have charged, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as "no unresolved charges". The caller
+ * decides what an empty answer means — see the fail-open note at its call site.
+ */
+export async function readUnresolvedCharges(receiptDir = RECEIPT_DIR) {
+    let names;
+    try {
+        names = await readdir(receiptDir);
+    }
+    catch {
+        return [];
+    }
+    const charges = [];
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(receiptDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const charge = parseUnresolved(raw, name);
+        if (charge)
+            charges.push(charge);
+    }
+    charges.sort((left, right) => (left.recordedAt < right.recordedAt ? 1 : -1));
+    return charges;
+}