@visa/cli 4.1.0-rc.108 → 4.1.0-rc.109

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

@@ -177,6 +177,12 @@ export interface CardMandateRegisterSeam {
     }) => Promise<{
         ok: boolean;
         reason?: string;
+        /**
+         * The ceiling the server committed — `min(requested, the owner's live card
+         * grant cap)`. Omitted by an older auth that does not report it, in which
+         * case the requested ceiling stands.
+         */
+        approvedCeilingMinor?: number;
     }>;
 }
 export type CliEngineDeps = {

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

@@ -16,7 +16,7 @@ import { readFile } from 'node:fs/promises';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
-import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, } from './vgs-live-instrument.js';
+import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
 import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
 import { createCardMandate, DEFAULT_MANDATE_MAX_DRAWS, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.js';
 import { MandateLedger } from './mandate/mandate-ledger.js';
@@ -140,6 +140,21 @@ export function createCliCheckoutEngine(deps = {}) {
             transactionCurrencyCode: input.currency,
         };
     }
+    /**
+     * Restate the facts at the ceiling the SERVER approved, when it lowered the
+     * one that was requested. Nothing has been spent or reserved on a mandate this
+     * new, so its remaining headroom IS its ceiling — see `createCardMandate`,
+     * which records `spentMinor: 0` with no reservations.
+     *
+     * Only ever lowers, mirroring `applyApprovedCeiling`: the server clamps
+     * downward, so a higher number means an unexpected response and is ignored
+     * rather than reported as headroom no human approved.
+     */
+    function approvedCeilingFacts(facts, approvedCeilingMinor) {
+        if (approvedCeilingMinor === undefined || approvedCeilingMinor >= facts.ceilingMinor)
+            return {};
+        return { ceilingMinor: approvedCeilingMinor, remainingMinor: approvedCeilingMinor };
+    }
     // Seed the one server-authoritative cumulative store keyed by the VGS intent
     // ID (#5942). On failure the local record is marked register-failed so
     // findCovering() SKIPS it — the mandate exists but is never drawn tap-free —
@@ -162,8 +177,50 @@ export function createCliCheckoutEngine(deps = {}) {
             ok: false,
             reason: err instanceof Error ? err.message : String(err),
         }));
-        if (reg.ok)
-            return { registerFailed: false };
+        if (reg.ok) {
+            // ONE SPENDING LIMIT: auth just clamped the requested ceiling to the
+            // owner's live grant cap and told us what it committed. Adopt it, so the
+            // local record — which findCovering() selects on and `mandate list`
+            // prints — states the budget the owner actually approved. Best-effort:
+            // the mandate is registered and drawable either way, and auth's verdict
+            // remains the enforcing cap, so a failed local write must not abort the
+            // ceremony. It leaves the record overstating headroom, which is exactly
+            // the pre-existing behaviour.
+            //
+            // If that write fails the returned facts still carry the approved figure —
+            // telling the human the truth beats echoing a ceiling their grant refused,
+            // and the ledger is left exactly as overstated as it was before this
+            // existed. But the two then disagree, so say so out loud rather than let
+            // `mandate list` quietly contradict what `mandate start` just printed.
+            // Same posture as the mark-failed escalation below.
+            if (reg.approvedCeilingMinor !== undefined) {
+                const applied = await ledger
+                    .applyApprovedCeiling(args.mandateId, reg.approvedCeilingMinor)
+                    .then(() => true)
+                    .catch(() => false);
+                if (!applied) {
+                    // Rendered through minorToDecimal, never raw /100 — and only when the
+                    // value is a sane integer, because THIS branch is also where an
+                    // unusable value lands (applyApprovedCeiling rejects it). A warning
+                    // must not throw on its way out. The currency is omitted deliberately:
+                    // both mandate paths refuse anything but USD long before register, so
+                    // it is known, and passing it would let a non-2-decimal code throw here.
+                    const approved = Number.isSafeInteger(reg.approvedCeilingMinor) && reg.approvedCeilingMinor > 0
+                        ? ` (${args.currency} ${minorToDecimal(reg.approvedCeilingMinor)})`
+                        : '';
+                    process.stderr.write(`warning: your owner's approved limit for this budget${approved} could NOT be saved ` +
+                        `locally — 'mandate list' will overstate the remaining balance until you re-run ` +
+                        `'mandate start'. Spending is still capped at the approved limit; a draw over it ` +
+                        `is refused. mandateId=${args.mandateId}\n`);
+                }
+            }
+            return {
+                registerFailed: false,
+                ...(reg.approvedCeilingMinor !== undefined
+                    ? { approvedCeilingMinor: reg.approvedCeilingMinor }
+                    : {}),
+            };
+        }
         // 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
@@ -293,6 +350,7 @@ export function createCliCheckoutEngine(deps = {}) {
             });
             return {
                 ...facts,
+                ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
                 merchantHost: new URL(merchant.url).hostname,
                 registerFailed: registered.registerFailed,
                 ...(registered.registerFailureReason !== undefined
@@ -353,6 +411,7 @@ export function createCliCheckoutEngine(deps = {}) {
             });
             return {
                 ...facts,
+                ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
                 merchantHost: new URL(claim.merchant.url).hostname,
                 registerFailed: registered.registerFailed,
                 ...(registered.registerFailureReason !== undefined

package/dist/checkout-engine/mandate/mandate-ledger.d.ts

@@ -127,6 +127,27 @@ export declare class MandateLedger {
      * Throws only if the mandate is unknown.
      */
     markRegisterFailed(mandateId: string, now?: Date): Promise<CardMandateRecord>;
+    /**
+     * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
+     *
+     * The requested ceiling is only a request. At register, auth clamps it to the
+     * owner's live card-grant cap (`min(requested, grant daily limit)`) and writes
+     * that. The local record used to keep the requested figure, so a runtime whose
+     * request exceeded the grant reported — and selected against — a budget the
+     * owner never approved. The draw still failed closed at auth's verdict, so it
+     * was never over-spend; it was the runtime lying about its own headroom and
+     * then hitting a decline it could not explain.
+     *
+     * LOWERS ONLY. A value at or above the current ceiling is ignored, not
+     * written: the server clamps downward, so a higher number means an unexpected
+     * response, and honouring it would let a client-observed value hand a runtime
+     * headroom no human approved. Cap authority stays server-side either way —
+     * this only stops the local copy from overstating it.
+     *
+     * Atomic and idempotent on the same serialized chain as every other mutation.
+     * Throws only if the mandate is unknown.
+     */
+    applyApprovedCeiling(mandateId: string, approvedCeilingMinor: number): Promise<CardMandateRecord>;
     /**
      * Atomically reserve headroom for a draw. Fail-closed: refuses when the
      * mandate is unknown, expired, or the amount exceeds remaining headroom. The

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

@@ -252,6 +252,40 @@ export class MandateLedger {
             return record;
         });
     }
+    /**
+     * ONE SPENDING LIMIT: adopt the ceiling the SERVER actually approved.
+     *
+     * The requested ceiling is only a request. At register, auth clamps it to the
+     * owner's live card-grant cap (`min(requested, grant daily limit)`) and writes
+     * that. The local record used to keep the requested figure, so a runtime whose
+     * request exceeded the grant reported — and selected against — a budget the
+     * owner never approved. The draw still failed closed at auth's verdict, so it
+     * was never over-spend; it was the runtime lying about its own headroom and
+     * then hitting a decline it could not explain.
+     *
+     * LOWERS ONLY. A value at or above the current ceiling is ignored, not
+     * written: the server clamps downward, so a higher number means an unexpected
+     * response, and honouring it would let a client-observed value hand a runtime
+     * headroom no human approved. Cap authority stays server-side either way —
+     * this only stops the local copy from overstating it.
+     *
+     * Atomic and idempotent on the same serialized chain as every other mutation.
+     * Throws only if the mandate is unknown.
+     */
+    applyApprovedCeiling(mandateId, approvedCeilingMinor) {
+        return this.run(async () => {
+            assertPositiveInteger(approvedCeilingMinor, 'approved mandate ceiling');
+            const file = await this.load();
+            const record = file.mandates.find((m) => m.mandateId === mandateId);
+            if (!record)
+                throw new Error(`no such mandate ${mandateId}`);
+            if (approvedCeilingMinor >= record.ceilingMinor)
+                return record;
+            record.ceilingMinor = approvedCeilingMinor;
+            await this.save(file);
+            return record;
+        });
+    }
     /**
      * Atomically reserve headroom for a draw. Fail-closed: refuses when the
      * mandate is unknown, expired, or the amount exceeds remaining headroom. The