@visa/cli 4.1.0-rc.152 → 4.1.0-rc.154

package/README.md

@@ -180,6 +180,7 @@ is required so the CLI never guesses which agent can spend.
 | `wallet_directory_pay` | Directory find + pay in one call, same policy path |
 | `wallet_history` | Journaled payment receipts |
 | `wallet_fund` | Funding instructions for the wallet address |
+| `checkout_merchants` | Read-only: merchants where your card has completed real checkouts, from this device's receipts |
 | `get_status` | Account and wallet state summary |
 | `feedback` | Submit feedback on a tool result |
 | `reset` | Clear local auth state and credentials |

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

@@ -1,5 +1,5 @@
 import { type Browser } from 'playwright-core';
-import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type PreparedCheckoutSessionStore } from './executor.js';
+import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type CheckoutOutcome, type PreparedCheckoutSessionStore } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
 import { serverFetchCryptogram, serverPostConfirmation } from './vgs-gateway/server-mint-client.js';
@@ -58,7 +58,7 @@ export type CliPayInput = CliReviewInput & {
     onApprovalUrl?: (url: string) => void;
 };
 export type CliReceiptFacts = {
-    outcome: string;
+    outcome: CheckoutOutcome;
     confirmationRef: string | null;
     receiptPath: string | null;
     detail: string | null;
@@ -84,6 +84,10 @@ export type CliReceiptFacts = {
     /** True only when at least one payment field was successfully filled. */
     credentialDisclosed: boolean;
 };
+type PayAttempt = {
+    fingerprint: string;
+    promise: Promise<CliReceiptFacts>;
+};
 export type CliStartMandateInput = {
     /** Optional local card-capability selector (legacy name or exact request-key JKT). */
     agentRef?: string;
@@ -222,6 +226,8 @@ export type CliEngineDeps = {
     writeReceipt?: typeof realWriteReceipt;
     store?: PreparedCheckoutSessionStore;
     sessions?: Map<string, Session>;
+    /** Exact-review singleflight registry; tests inject a fresh map for isolation. */
+    payAttempts?: Map<string, PayAttempt>;
     ttlMs?: number;
     /** Owner-only card-mandate ledger — defaults to the ~/.visa-mcp singleton. */
     ledger?: MandateLedger;

package/dist/checkout-engine/cli-engine.js

@@ -10,10 +10,9 @@
 //
 // Every browser/network primitive is injectable (CliEngineDeps) so the session/
 // timer/store lifecycle is unit-testable without launching Chromium.
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { launchCheckoutBrowser } from './browser-launch.js';
+import { RECEIPT_DIR } from './receipt-dir.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
 import { VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
@@ -119,16 +118,45 @@ async function resolveCardInstrument(input) {
         '`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait` to ' +
         'attach one, or use a pre-provisioned VIC runtime.', readError instanceof Error ? { cause: readError } : undefined);
 }
-const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');
+function payAttemptFingerprint(input) {
+    return JSON.stringify([
+        input.url,
+        input.amount,
+        input.currency,
+        input.credentialPath,
+        input.cardTokenId ?? null,
+        input.agentJkt ?? null,
+        input.contact,
+        input.approvalBaseUrl,
+        input.merchantName ?? null,
+        input.merchantCountryCode ?? null,
+        input.submit,
+    ]);
+}
+function failedPay(detail) {
+    return {
+        outcome: 'failed',
+        confirmationRef: null,
+        receiptPath: null,
+        detail,
+        vicConfirmation: null,
+        source: null,
+        remainingMinor: null,
+        credentialIssued: false,
+        credentialDisclosed: false,
+    };
+}
 // Must match the prepared-checkout store TTL so a session and its store entry
 // expire together — an abandoned review can't leak the browser + state.
 const PREPARED_TTL_MS = 5 * 60 * 1000;
 const defaultStore = new InMemoryPreparedCheckoutStore({ ttlMs: PREPARED_TTL_MS });
 const defaultSessions = new Map();
+const defaultPayAttempts = new Map();
 const defaultLedger = new MandateLedger();
 export function createCliCheckoutEngine(deps = {}) {
     const store = deps.store ?? defaultStore;
     const sessions = deps.sessions ?? defaultSessions;
+    const payAttempts = deps.payAttempts ?? defaultPayAttempts;
     const ttlMs = deps.ttlMs ?? PREPARED_TTL_MS;
     const launchBrowser = deps.launchBrowser ?? (() => launchCheckoutBrowser());
     const prepareCheckout = deps.prepareCheckout ?? realPrepareCheckout;
@@ -508,12 +536,20 @@ export function createCliCheckoutEngine(deps = {}) {
          */
         async releaseReview(reviewId) {
             await closeSession(reviewId);
+            payAttempts.delete(reviewId);
         },
         async pay(input) {
             const noCredentialFacts = {
                 credentialIssued: false,
                 credentialDisclosed: false,
             };
+            const fingerprint = payAttemptFingerprint(input);
+            const priorAttempt = payAttempts.get(input.reviewId);
+            if (priorAttempt) {
+                return priorAttempt.fingerprint === fingerprint
+                    ? priorAttempt.promise
+                    : failedPay(`review ${input.reviewId} is already executing with different payment facts — wait for that exact attempt and inspect its receipt`);
+            }
             const session = sessions.get(input.reviewId);
             // One signal for the whole pay lifecycle. `cardTokenId` is populated only
             // by the resolved v4 card-grant authority; legacy credential-file calls
@@ -629,6 +665,23 @@ export function createCliCheckoutEngine(deps = {}) {
                     ...noCredentialFacts,
                 };
             }
+            let resolveAttempt;
+            let rejectAttempt;
+            const sharedResult = new Promise((resolve, reject) => {
+                resolveAttempt = resolve;
+                rejectAttempt = reject;
+            });
+            // The first caller still receives the direct execution result below; this
+            // retained promise exists for overlapping and bounded late duplicates.
+            // Mark its rejection handled even when there is no duplicate consumer.
+            void sharedResult.catch(() => undefined);
+            payAttempts.set(input.reviewId, { fingerprint, promise: sharedResult });
+            let completedAttempt;
+            const finishAttempt = (result) => {
+                completedAttempt = result;
+                resolveAttempt(result);
+                return result;
+            };
             clearTimeout(session.cleanupTimer);
             try {
                 // NO instrument read here. A tap-free mandate draw spends `covering
@@ -672,7 +725,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     const verdictSeam = cardDrawVerdict;
                     const capability = verdictSeam?.loadCapability(covering.agentJkt) ?? null;
                     if (!capability || !verdictSeam) {
-                        return {
+                        return finishAttempt({
                             outcome: 'failed',
                             confirmationRef: null,
                             receiptPath: null,
@@ -682,10 +735,10 @@ export function createCliCheckoutEngine(deps = {}) {
                             source,
                             remainingMinor: null,
                             ...noCredentialFacts,
-                        };
+                        });
                     }
                     if (covering.agentJkt && capability.agentJkt !== covering.agentJkt) {
-                        return {
+                        return finishAttempt({
                             outcome: 'failed',
                             confirmationRef: null,
                             receiptPath: null,
@@ -695,7 +748,7 @@ export function createCliCheckoutEngine(deps = {}) {
                             source,
                             remainingMinor: null,
                             ...noCredentialFacts,
-                        };
+                        });
                     }
                     // VgsLiveInstrument mints against an EXISTING intent (the mandate) with
                     // no fresh assurance — exactly the draw semantics. The fetchCredential
@@ -803,7 +856,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     // registration and non-budget mint tokens at verification; this
                     // client refusal exists to give the honest remedy up front instead
                     // of a mid-flow server error.
-                    return {
+                    return finishAttempt({
                         outcome: 'failed',
                         confirmationRef: null,
                         receiptPath: null,
@@ -821,7 +874,7 @@ export function createCliCheckoutEngine(deps = {}) {
                         source: null,
                         remainingMinor: null,
                         ...noCredentialFacts,
-                    };
+                    });
                 }
                 const mode = input.submit ? 'submit' : 'dry-run';
                 const result = await submitApprovedCheckout(input.reviewId, {
@@ -875,7 +928,7 @@ export function createCliCheckoutEngine(deps = {}) {
                 }));
                 if (report.written)
                     receiptPath = report.path;
-                return {
+                return finishAttempt({
                     outcome: result.outcome,
                     confirmationRef: result.confirmationRef ?? null,
                     receiptPath,
@@ -887,10 +940,29 @@ export function createCliCheckoutEngine(deps = {}) {
                     credentialIssued: result.credentialLifecycle !== 'not-requested',
                     credentialDisclosed: result.credentialLifecycle === 'partially-exposed' ||
                         result.credentialLifecycle === 'fully-filled',
-                };
+                });
+            }
+            catch (error) {
+                rejectAttempt(error);
+                throw error;
             }
             finally {
                 await closeSession(input.reviewId);
+                if (!completedAttempt ||
+                    completedAttempt.outcome === 'failed' ||
+                    completedAttempt.outcome === 'declined') {
+                    if (payAttempts.get(input.reviewId)?.promise === sharedResult) {
+                        payAttempts.delete(input.reviewId);
+                    }
+                }
+                else {
+                    const expiry = setTimeout(() => {
+                        if (payAttempts.get(input.reviewId)?.promise === sharedResult) {
+                            payAttempts.delete(input.reviewId);
+                        }
+                    }, ttlMs);
+                    expiry.unref?.();
+                }
             }
         },
     };

package/dist/checkout-engine/confirmed-merchants.d.ts

@@ -0,0 +1,31 @@
+/** One confirmed charge, in the receipt's own terms. */
+export type ConfirmedCharge = {
+    recordedAt: string;
+    amount: string;
+    currency: string;
+    /** Receipt file basename, so an operator can open the evidence log. */
+    receiptFile: string;
+};
+export type ConfirmedMerchant = {
+    /** The checkout page the card went through. */
+    url: string;
+    host: string;
+    /**
+     * Curated human identity (known-merchants.ts), present only when someone has
+     * identified who is behind this checkout URL. Hosted payment links carry an
+     * opaque path on the PSP's host, so without this a row names nobody.
+     */
+    name?: string;
+    category?: string;
+    website?: string;
+    confirmedCount: number;
+    lastConfirmedAt: string;
+    charges: ConfirmedCharge[];
+};
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export declare function readConfirmedMerchants(receiptDir?: string): Promise<ConfirmedMerchant[]>;

package/dist/checkout-engine/confirmed-merchants.js

@@ -0,0 +1,136 @@
+// "Where can I use my card?", the merchant registry derived from this
+// device's checkout receipts.
+//
+// Receipts (receipt.ts) are the only local record that a real merchant
+// checkout completed on this box. This module reads them back and answers one
+// question: which checkout pages has this card actually gone through?
+//
+// A merchant only counts when BOTH halves agree. The engine's own outcome must
+// be 'confirmed' (the merchant showed a definitive success) AND the VIC
+// confirmation must have posted APPROVED (the network side of the same
+// purchase). Either half alone is a claim, not a completion: a 'confirmed' with
+// no posted confirmation is exactly the reconciliation case receipt.ts flags,
+// and a posted DECLINED is a completed report of a failure.
+//
+// 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. One bad file must not
+// hide every merchant behind it.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+import { RECEIPT_DIR } from './receipt-dir.js';
+/**
+ * The URL a receipt's charge happened at.
+ *
+ * The receipt's top-level merchant block records the HOST only, on purpose: a
+ * full checkout URL can carry cart/session identifiers, so it stays out of the
+ * shareable summary. The evidence log still holds it (the executor's first
+ * 'navigation' step is the page the run opened), so recover it from there and
+ * fall back to the host when the evidence is absent or shaped differently.
+ */
+function checkoutUrlOf(receipt) {
+    const navigation = receipt.evidence.steps.find((step) => step?.type === 'navigation');
+    const data = navigation?.data;
+    const url = typeof data === 'object' && data !== null ? data.url : undefined;
+    return typeof url === 'string' && url.length > 0 ? url : `https://${receipt.merchant.host}/`;
+}
+function isConfirmedCompletion(receipt) {
+    return (receipt.outcome === 'confirmed' &&
+        receipt.vicConfirmation?.posted === true &&
+        receipt.vicConfirmation.transactionStatus === 'APPROVED');
+}
+/**
+ * Parse one receipt file, or null when it is not a v1 receipt this module can
+ * read. Deliberately permissive about everything the grouping does not touch:
+ * the file was written by an older or newer engine and only has to carry the
+ * fields read below.
+ */
+function parseReceipt(json) {
+    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')
+        return null;
+    if (typeof receipt.recordedAt !== 'string')
+        return null;
+    if (typeof receipt.merchant?.host !== 'string')
+        return null;
+    if (typeof receipt.transaction?.amount !== 'string')
+        return null;
+    if (typeof receipt.transaction?.currency !== 'string')
+        return null;
+    if (!Array.isArray(receipt.evidence?.steps))
+        return null;
+    return receipt;
+}
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export async function readConfirmedMerchants(receiptDir = RECEIPT_DIR) {
+    let names;
+    try {
+        names = await readdir(receiptDir);
+    }
+    catch {
+        return [];
+    }
+    const byUrl = new Map();
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(receiptDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const receipt = parseReceipt(raw);
+        if (!receipt || !isConfirmedCompletion(receipt))
+            continue;
+        const url = checkoutUrlOf(receipt);
+        const charge = {
+            recordedAt: receipt.recordedAt,
+            amount: receipt.transaction.amount,
+            currency: receipt.transaction.currency,
+            receiptFile: name,
+        };
+        const existing = byUrl.get(url);
+        if (existing) {
+            existing.confirmedCount += 1;
+            existing.charges.push(charge);
+            if (charge.recordedAt > existing.lastConfirmedAt) {
+                existing.lastConfirmedAt = charge.recordedAt;
+            }
+            continue;
+        }
+        const identity = KNOWN_MERCHANT_IDENTITIES[url];
+        byUrl.set(url, {
+            url,
+            host: receipt.merchant.host,
+            // Conditional spread on purpose: an unidentified merchant carries no
+            // identity keys at all, rather than keys holding undefined.
+            ...(identity ?? {}),
+            confirmedCount: 1,
+            lastConfirmedAt: charge.recordedAt,
+            charges: [charge],
+        });
+    }
+    const merchants = [...byUrl.values()];
+    for (const merchant of merchants) {
+        merchant.charges.sort((left, right) => (left.recordedAt < right.recordedAt ? 1 : -1));
+    }
+    merchants.sort((left, right) => (left.lastConfirmedAt < right.lastConfirmedAt ? 1 : -1));
+    return merchants;
+}

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

@@ -1,6 +1,9 @@
 export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 export type { CheckoutResult, CheckoutReview, CheckoutOutcome } from './executor.js';
+export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES, type MerchantIdentity } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
 export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
 export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, type CreateCardMandateInput, type CreateCardMandateDeps, type CardMandateFacts, type DrawFromMandateInput, type DrawFromMandateDeps, type DrawResult, type CardMandateMerchant, } from './mandate/card-mandate.js';
 export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, type CardMandateRecord, type CardMandateLedgerFile, type CardMandateDraw, type CardMandateReservation, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/index.js

@@ -3,6 +3,9 @@
 // primitives are re-exported for direct/embedded use.
 export { createCliCheckoutEngine, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export { readConfirmedMerchants, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
 export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
 export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, } from './mandate/card-mandate.js';
 export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/known-merchants.d.ts

@@ -0,0 +1,10 @@
+export type MerchantIdentity = {
+    /** Human-recognizable merchant name. */
+    name: string;
+    /** What the merchant is, e.g. "charity (animal rescue)". */
+    category: string;
+    /** The merchant's own site, when known — not the checkout URL. */
+    website?: string;
+};
+/** Checkout URL → who is actually behind it. Confirmed live 2026-07/2026-08. */
+export declare const KNOWN_MERCHANT_IDENTITIES: Readonly<Record<string, MerchantIdentity>>;

package/dist/checkout-engine/known-merchants.js

@@ -0,0 +1,38 @@
+// Curated identities for checkout URLs the registry cannot name on its own.
+//
+// Hosted payment links are anonymous by construction: the page host is the
+// PSP's (donate.stripe.com, buy.stripe.com), the path is an opaque token, and
+// the receipt records nothing else. So a registry row for a completed payment
+// link answers "where can I use my card?" with a string no human recognizes.
+// This map carries the once-per-link human identification, keyed by the exact
+// checkout URL the receipts group on.
+//
+// Curation rule: an entry is added only after a checkout at that URL completed
+// for real (engine outcome 'confirmed' + VIC APPROVED — the same admission rule
+// confirmed-merchants.ts enforces) and the merchant behind the link was
+// identified by a person. The map never creates registry rows; it only names
+// rows the device's own receipts already earned. A URL missing here still
+// lists — it just shows as its host.
+/** Checkout URL → who is actually behind it. Confirmed live 2026-07/2026-08. */
+export const KNOWN_MERCHANT_IDENTITIES = {
+    'https://donate.stripe.com/3cscPcaqY20H8ta4gh': {
+        name: 'NC Seaside Animal Rescue',
+        category: 'charity (animal rescue, NC nonprofit)',
+        website: 'https://www.ncseasideanimalrescue.org/make-a-donation',
+    },
+    'https://donate.stripe.com/14k3ei9TYgwFclq145': {
+        name: 'FreeCAD',
+        category: 'open-source project donation (CAD software)',
+        website: 'https://www.freecad.org',
+    },
+    'https://buy.stripe.com/dR6eWGaK41MX2YgaEF': {
+        name: 'scribepod',
+        category: 'indie creator tip jar (AI podcast project)',
+        website: 'https://github.com/yacineMTB/scribepod',
+    },
+    'https://donate.stripe.com/7sIcNj9Gs4WO6d29AA': {
+        name: 'n0bleKing GRAFFITI',
+        category: 'indie creator tip jar (pixel art and fonts)',
+        website: 'https://nobleking-graffiti.itch.io',
+    },
+};

package/dist/checkout-engine/receipt-dir.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Where this device's checkout receipts live. Owned by its own module so the
+ * writer (cli-engine.ts) and the reader (confirmed-merchants.ts) can never
+ * drift onto two paths.
+ */
+export declare const RECEIPT_DIR: string;

package/dist/checkout-engine/receipt-dir.js

@@ -0,0 +1,8 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Where this device's checkout receipts live. Owned by its own module so the
+ * writer (cli-engine.ts) and the reader (confirmed-merchants.ts) can never
+ * drift onto two paths.
+ */
+export const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');