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

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));
@@ -1251,6 +1268,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);

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;

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;
+}