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

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

@@ -10,6 +10,27 @@ export interface CheckoutAdapter {
 }
 export declare function resolveLocator(page: Page, entry: FieldEntry): Locator;
 export declare function scrubFillErrorMessage(message: string, value: string): string;
+/**
+ * A fill failure in a few words, for a message a human reads.
+ *
+ * Playwright's error is a multi-line call log — useful in the evidence file,
+ * unreadable in a refusal message and in the receipt an operator opens a week
+ * later. The refusal names WHICH fields refused; without this it never says
+ * WHY, so diagnosing a merchant we cannot drive means either reproducing it or
+ * reading someone's evidence JSON. Each cause maps to a different fix:
+ *
+ *   not editable      — the input exists but is readonly/disabled at fill time
+ *                       (a custom widget owning the value, or a not-yet-ready
+ *                       form). Typing will not help; the field needs an adapter
+ *                       or a longer wait.
+ *   not a text field  — a non-input element pretending to be one. Needs an
+ *                       adapter that drives the widget.
+ *   not visible /
+ *   detached          — a re-render race. The reveal loop is the lever.
+ *
+ * Input is already scrubbed by scrubFillErrorMessage; this only ever shortens.
+ */
+export declare function summarizeFillFailure(error: string | undefined): string;
 /**
  * The contact record and the page rarely agree on name shape: the record may
  * carry fullName while the page wants first/last inputs, or vice versa. Derive

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

@@ -74,6 +74,51 @@ export function scrubFillErrorMessage(message, value) {
         scrubbed = scrubbed.split(value).join('<redacted>');
     return scrubbed;
 }
+/**
+ * A fill failure in a few words, for a message a human reads.
+ *
+ * Playwright's error is a multi-line call log — useful in the evidence file,
+ * unreadable in a refusal message and in the receipt an operator opens a week
+ * later. The refusal names WHICH fields refused; without this it never says
+ * WHY, so diagnosing a merchant we cannot drive means either reproducing it or
+ * reading someone's evidence JSON. Each cause maps to a different fix:
+ *
+ *   not editable      — the input exists but is readonly/disabled at fill time
+ *                       (a custom widget owning the value, or a not-yet-ready
+ *                       form). Typing will not help; the field needs an adapter
+ *                       or a longer wait.
+ *   not a text field  — a non-input element pretending to be one. Needs an
+ *                       adapter that drives the widget.
+ *   not visible /
+ *   detached          — a re-render race. The reveal loop is the lever.
+ *
+ * Input is already scrubbed by scrubFillErrorMessage; this only ever shortens.
+ */
+export function summarizeFillFailure(error) {
+    if (!error)
+        return 'no reason recorded';
+    if (/not an? <input>|not.*\[contenteditable\]/i.test(error))
+        return 'not a text field';
+    if (/element is not visible/i.test(error))
+        return 'not visible';
+    if (/not attached to the DOM|detached/i.test(error))
+        return 'detached from the page';
+    if (/element is not enabled/i.test(error))
+        return 'disabled';
+    if (/not editable/i.test(error)) {
+        const timeout = /Timeout (\d+)ms exceeded/i.exec(error);
+        return timeout
+            ? `not editable within ${Math.round(Number(timeout[1]) / 1000)}s`
+            : 'not editable';
+    }
+    if (/Timeout (\d+)ms exceeded/i.test(error)) {
+        const timeout = /Timeout (\d+)ms exceeded/i.exec(error);
+        return `timed out after ${Math.round(Number(timeout[1]) / 1000)}s`;
+    }
+    // Unrecognized: the first line, bounded. Better a clipped real message than a
+    // confident wrong summary.
+    return error.split('\n')[0].slice(0, 120);
+}
 const DEFAULT_FILL_TIMEOUT_MS = 5000;
 async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
     const base = {

package/dist/checkout-engine/executor.js

@@ -22,6 +22,7 @@ import { checkMandate, checkMandatePreFill } from './mandate.js';
 import { EvidenceLog, maskOtp } from './evidence.js';
 import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
+import { summarizeFillFailure } from './adapters/generic.js';
 import { traceHandleFields } from './trace-handles.js';
 import { readGenericPageAmount } from './amount.js';
 import { webBotAuthHeadersOrNone } from './web-bot-auth.js';
@@ -1210,7 +1211,23 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         // 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');
+            // Name the CAUSE per field, not just the field. The refusal is the only
+            // artifact that survives to the operator (a v2 receipt carries no evidence
+            // log), and "city, postalCode refused" without a reason means the next
+            // person has to reproduce a live merchant to learn anything. Each cause
+            // points at a different fix — see summarizeFillFailure.
+            //
+            // Last attempt wins: a role that failed differently across reveal passes
+            // is best described by how it failed when we finally gave up on it.
+            const lastFillError = (role) => {
+                const errors = evidence
+                    .getSteps()
+                    .filter((step) => step.type === 'field-fill' && step.data.ok === false && step.data.role === role)
+                    .map((step) => (typeof step.data.error === 'string' ? step.data.error : undefined));
+                return errors[errors.length - 1];
+            };
+            const reasons = failedFillRoles.map((role) => `${role} (${summarizeFillFailure(lastFillError(role))})`);
+            return makeResult('partial-fill', state.fields, evidence, requiresAdapter, `required field fill failed: ${reasons.join(', ')} — not submitting an incomplete form. Nothing was charged.`, undefined, 'required-field-unfillable');
         }
         if (!submit) {
             evidence.setSnapshotSummary(await snapshotSummary(page));

package/dist/checkout-engine/hosted-approval.js

@@ -58,9 +58,11 @@ const defaultSleep = (ms) => new Promise((r) => {
 function defaultOpenUrl(url) {
     // Best-effort convenience only — the URL is always surfaced via `log`/
     // `onApprovalUrl`, so this must never throw or hang if there is no browser.
-    // `CHECKOUT_SKIP_BROWSER_OPEN=1` disables it (headless/agent hosts where
-    // launching a browser on the WRONG machine is pointless or noisy).
-    if (process.env.CHECKOUT_SKIP_BROWSER_OPEN === '1')
+    // `CHECKOUT_SKIP_BROWSER_OPEN=1` or `VISA_SUPPRESS_BROWSER=true|1` disables it
+    // (headless/agent hosts where launching a browser on the WRONG machine is pointless or noisy).
+    if (process.env.CHECKOUT_SKIP_BROWSER_OPEN === '1' ||
+        process.env.VISA_SUPPRESS_BROWSER === '1' ||
+        process.env.VISA_SUPPRESS_BROWSER === 'true')
         return;
     // Platform-appropriate opener; unknown platforms just skip (the URL is logged).
     const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start ""' : 'xdg-open';

package/dist/checkout-engine/receipt.js

@@ -44,7 +44,12 @@ export function buildReceipt(input) {
                         // 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.'
+                        ? // A v2 receipt carries no evidence log, so this line is the only
+                            // place the CAUSE survives — which field refused and why. An
+                            // operator opening this a week later can act on it; "could not
+                            // be filled" alone means reproducing a live merchant to learn
+                            // anything.
+                            `${result.detail ?? '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;