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

package/dist/checkout-engine/executor.js

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

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