@visa/cli 4.1.0-rc.153 → 4.1.0-rc.155

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/mandate/mandate-ledger.d.ts

@@ -61,6 +61,13 @@ export type CardMandateRecord = {
      * created record attempted registration. ISO 8601.
      */
     registerFailedAt?: string;
+    /**
+     * Set after an authenticated owner-scoped server read proves this mandate was
+     * revoked. The local file is only an execution cache; server revocation is
+     * canonical and permanently retires the cached mandate from selection while
+     * retaining its receipt history for the owner.
+     */
+    serverRevokedAt?: string;
     /**
      * A cross-host retail budget, not scoped to one `merchantHost`. The local
      * selector may attempt it at any host, while the provider/network still
@@ -127,6 +134,12 @@ export declare class MandateLedger {
      * Throws only if the mandate is unknown.
      */
     markRegisterFailed(mandateId: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * Retire a locally cached mandate after the authenticated account API proves
+     * it was revoked. This is idempotent and monotonic: an owner revocation can
+     * never be undone by a later stale/local read.
+     */
+    markServerRevoked(mandateId: string, revokedAt: string): Promise<CardMandateRecord>;
     /**
      * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
      *

package/dist/checkout-engine/mandate/mandate-ledger.js

@@ -203,6 +203,7 @@ export class MandateLedger {
             m.currencyCode.toUpperCase() === query.currencyCode.toUpperCase() &&
             !m.unhonoredAt &&
             !m.registerFailedAt &&
+            !m.serverRevokedAt &&
             !isExpired(m, now) &&
             hasDrawCountHeadroom(m) &&
             remainingMinor(m) >= query.amountMinor);
@@ -252,6 +253,27 @@ export class MandateLedger {
             return record;
         });
     }
+    /**
+     * Retire a locally cached mandate after the authenticated account API proves
+     * it was revoked. This is idempotent and monotonic: an owner revocation can
+     * never be undone by a later stale/local read.
+     */
+    markServerRevoked(mandateId, revokedAt) {
+        return this.run(async () => {
+            const parsed = new Date(revokedAt);
+            if (Number.isNaN(parsed.getTime()))
+                throw new Error('server revocation timestamp is invalid');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (!record.serverRevokedAt) {
+                record.serverRevokedAt = parsed.toISOString();
+                await this.save(file);
+            }
+            return record;
+        });
+    }
     /**
      * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
      *

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');

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

@@ -1,7 +1,8 @@
 import type { EvidenceStep } from './evidence.js';
 import type { CheckoutMode, CheckoutOutcome, CheckoutResult, CredentialLifecycle, CredentialTiming } from './executor.js';
 import type { VicConfirmationReport } from './vic-confirmation.js';
-export type CheckoutReceipt = {
+/** Published v1 artifact shape. Retained so patch releases remain readable/typable. */
+export type CheckoutReceiptV1 = {
     schema: 'checkout-agent-receipt/v1';
     recordedAt: string;
     mode: CheckoutMode;
@@ -32,6 +33,42 @@ export type CheckoutReceipt = {
         snapshotSummary: string | null;
     };
 };
+export type CheckoutReceiptV2 = {
+    schema: 'checkout-agent-receipt/v2';
+    recordedAt: string;
+    merchant: {
+        name: string;
+        host: string;
+        checkoutUrl: string | null;
+    };
+    transaction: {
+        amount: string;
+        amountMinor: number;
+        currency: string;
+    };
+    outcome: CheckoutOutcome;
+    agent: {
+        name: string;
+    } | null;
+    rail: {
+        type: 'card';
+        cardLast4: string | null;
+    };
+    network: {
+        confirmation: 'APPROVED' | 'DECLINED' | null;
+    };
+    /** Local reviewed-attempt identifier. Keeps filenames stable across schema versions. */
+    receiptId: string | null;
+    /** Merchant confirmation reference only; never substituted with an internal review id. */
+    reference: string | null;
+    recovery: {
+        required: boolean;
+        retrySafe: boolean;
+        action: string;
+        actions: string[];
+    };
+};
+export type CheckoutReceipt = CheckoutReceiptV1 | CheckoutReceiptV2;
 export type ReceiptWriteReport = {
     written: true;
     path: string;
@@ -46,6 +83,7 @@ export declare function buildReceipt(input: {
     merchant: {
         name: string;
         host: string;
+        url?: string;
     };
     transaction: {
         amount: string;
@@ -54,9 +92,11 @@ export declare function buildReceipt(input: {
     };
     result: CheckoutResult;
     vicConfirmation: VicConfirmationReport | null;
+    agentName?: string;
+    cardLast4?: string;
     /** Injectable for tests; defaults to now. */
     recordedAt?: Date;
-}): CheckoutReceipt;
+}): CheckoutReceiptV2;
 /**
  * Defense-in-depth scrub before anything touches disk: any standalone
  * 12–19-digit run that passes Luhn is replaced — contiguous OR separated by

package/dist/checkout-engine/receipt.js

@@ -1,5 +1,6 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
 import { submitClickedWithoutConfirmation } from './live-fill-approval.js';
 /**
  * What the operator still owes after this run. Empty for a clean dry-run fill
@@ -29,23 +30,37 @@ function reconciliationFor(result, vicConfirmation) {
 }
 export function buildReceipt(input) {
     const { result } = input;
+    const reconciliation = reconciliationFor(result, input.vicConfirmation);
+    const fallbackAction = input.mode === 'dry-run'
+        ? 'Dry run only — nothing was submitted; safe to run again.'
+        : result.outcome === 'confirmed'
+            ? 'No action needed.'
+            : result.outcome === 'declined'
+                ? 'Review the decline before trying again.'
+                : '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;
+    const networkConfirmation = input.vicConfirmation?.posted === true ? input.vicConfirmation.transactionStatus : null;
     return {
-        schema: 'checkout-agent-receipt/v1',
+        schema: 'checkout-agent-receipt/v2',
         recordedAt: (input.recordedAt ?? new Date()).toISOString(),
-        mode: input.mode,
-        reviewId: input.reviewId,
-        merchant: { name: input.merchant.name, host: input.merchant.host },
+        merchant: { name: input.merchant.name, host: input.merchant.host, checkoutUrl },
         transaction: input.transaction,
         outcome: result.outcome,
-        detail: result.detail ?? null,
-        confirmationRef: result.confirmationRef ?? null,
-        vicConfirmation: input.vicConfirmation,
-        credentialLifecycle: result.credentialLifecycle,
-        credentialTiming: result.credentialTiming,
-        detectedRoles: Object.keys(result.fields),
-        requiresAdapter: [...result.requiresAdapter],
-        reconciliation: reconciliationFor(result, input.vicConfirmation),
-        evidence: result.evidence.toObject(),
+        agent: input.agentName ? { name: input.agentName } : null,
+        rail: { type: 'card', cardLast4 },
+        network: { confirmation: networkConfirmation },
+        receiptId: input.reviewId,
+        reference: result.confirmationRef ?? null,
+        recovery: {
+            required: reconciliation.required,
+            // A clean dry-run did not submit anything, so repeating inspection is
+            // safe. Every submit outcome requires either no retry or owner review.
+            retrySafe: input.mode === 'dry-run' && !reconciliation.required,
+            action: recoveryActions[0],
+            actions: recoveryActions,
+        },
     };
 }
 function luhnValid(digits) {
@@ -88,7 +103,8 @@ export function serializeReceipt(receipt) {
 }
 export function receiptFileName(receipt) {
     const ts = receipt.recordedAt.replace(/[:.]/g, '-');
-    const review = (receipt.reviewId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
+    const receiptId = receipt.schema === 'checkout-agent-receipt/v1' ? receipt.reviewId : receipt.receiptId;
+    const review = (receiptId ?? 'no-review').replace(/[^A-Za-z0-9-]/g, '');
     return `receipt-${ts}-${review || 'no-review'}.json`;
 }
 /**