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

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');
@@ -1337,19 +1372,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;