@visa/cli 4.1.0-rc.136 → 4.1.0-rc.138

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

@@ -223,18 +223,18 @@ export function createCliCheckoutEngine(deps = {}) {
         }
         // Register failed: the server `card_mandate_spend` row was never created, so
         // a delegated draw against this mandate would 404 `no_mandate`. Mark it
-        // register-failed so findCovering() SKIPS it and the owner's next checkout
-        // falls through to a fresh per-purchase tap, rather than silently selecting
-        // a mandate that can't be drawn. Marking is best-effort too — a failure here
-        // must not abort the flow.
+        // register-failed so findCovering() SKIPS it rather than silently selecting
+        // a mandate that can't be drawn. A v4 grant then refuses until a usable
+        // mandate exists; only a legacy credential-file runtime can still use the
+        // old per-purchase approval. Marking is best-effort too.
         const marked = await ledger
             .markRegisterFailed(args.mandateId, now())
             .then(() => true)
             .catch(() => false);
         process.stderr.write(marked
             ? `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) — this mandate ` +
-                `will NOT be used for tap-free draws; your next checkout will interrupt the owner ` +
-                `for a fresh per-purchase approval. Re-run 'mandate start' to try again.\n`
+                `will NOT be used for draws. A v4 card grant cannot spend until a usable mandate ` +
+                `is registered. Re-run 'mandate start' to try again.\n`
             : // Escalate: the mark write ALSO failed, so the mandate is persisted but
                 // NOT disabled — findCovering could still select an undrawable mandate.
                 // Tell the owner loudly not to rely on it and how to recover.
@@ -492,6 +492,11 @@ export function createCliCheckoutEngine(deps = {}) {
         },
         async pay(input) {
             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
+            // omit it. Keeping the classification here prevents copy and fallback
+            // behavior from drifting onto different grant detectors.
+            const isV4CardGrant = typeof input.cardTokenId === 'string' && input.cardTokenId.trim() !== '';
             if (!session) {
                 return {
                     outcome: 'failed',
@@ -740,7 +745,9 @@ export function createCliCheckoutEngine(deps = {}) {
                                     }
                                     throw new Error(verdictFailure.transient
                                         ? `the card-mandate draw could not be authorized right now (${verdictFailure.reasons.join(', ') || 'temporary error'}) — retry shortly`
-                                        : `this card mandate can no longer be drawn (${verdictFailure.reasons.join(', ') || 'refused'}); it has been disabled — retry the checkout to use a fresh per-purchase approval`, { cause: err });
+                                        : `this card mandate can no longer be drawn (${verdictFailure.reasons.join(', ') || 'refused'}); it has been disabled — ${isV4CardGrant
+                                            ? 'create and claim a new mandate before retrying this v4 checkout'
+                                            : 'retry the checkout to use a legacy fresh per-purchase approval'}`, { cause: err });
                                 }
                                 if (!isTransientDrawFailure(err.cause ?? err)) {
                                     await ledger.markUnhonored(mandateId, now());
@@ -758,9 +765,31 @@ export function createCliCheckoutEngine(deps = {}) {
                     instrument = new VgsLiveInstrument(reference, session.contact.fullName ?? '', fetchCredential);
                 }
                 else {
-                    // --- 1:1 fresh-tap flow (unchanged) ---------------------------------
+                    // A v4 card grant is aggregate authority, not a credential-only escape
+                    // hatch. Its spend must be represented by a claimed mandate so auth can
+                    // atomically reserve both the card scope and aggregate budget before a
+                    // payable cryptogram is minted. Falling through to the legacy 1:1 tap
+                    // here would create a real card credential with zero canonical draw.
+                    if (isV4CardGrant) {
+                        return {
+                            outcome: 'failed',
+                            confirmationRef: null,
+                            receiptPath: null,
+                            detail: 'this v4 card grant has no active mandate covering the purchase; run ' +
+                                '`visa mandate start --ceiling <usd> --per-transaction <usd>` for the selected ' +
+                                'agent, approve and claim the mandate, then retry this checkout. No payment ' +
+                                'credential was requested and no charge was made.',
+                            vicConfirmation: null,
+                            source: null,
+                            remainingMinor: null,
+                        };
+                    }
+                    // --- Legacy 1:1 fresh-tap flow --------------------------------------
+                    // Kept only for a pre-v4 credential-file runtime. A selected v4 grant
+                    // can never reach this parallel, non-canonical accounting path.
                     source = 'fresh-tap';
-                    // Legacy credential file OR the activated card:vic grant's token.
+                    // Legacy credential file only. A v4 grant was refused above unless a
+                    // covering mandate selected the canonical draw path.
                     const credential = await resolveCardInstrument(input);
                     const assurance = await runHostedApproval({
                         baseUrl: input.approvalBaseUrl,

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

@@ -144,7 +144,7 @@ export async function createCardMandate(input, deps) {
 const DRAW_REMEDY = 'the card-mandate draw did not complete — a ceiling-scoped assurance may not be honored ' +
     'for this sub-amount draw. The budget is untouched. If this was a transient network error ' +
     '(gateway 5xx / try again), retry — the mandate stays active; a persistent decline disables ' +
-    'the mandate and your next pay_merchant uses a fresh per-purchase tap';
+    'the mandate; a v4 card grant then requires a new mandate before another checkout';
 /**
  * Thrown ONLY for the post-reservation network/validation rejection class — the
  * cryptogram fetch failed or returned a non-payable credential (the DRAW_REMEDY