@visa/cli 4.1.0-rc.9 → 4.1.0-rc.91

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

@@ -0,0 +1,6 @@
+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 { 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

@@ -0,0 +1,8 @@
+// Public API of @visa/checkout-engine. The pay_merchant tool in @visa/cli
+// consumes createCliCheckoutEngine() through a structural seam; the core engine
+// primitives are re-exported for direct/embedded use.
+export { createCliCheckoutEngine, } from './cli-engine.js';
+export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.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/inline-target.d.ts

@@ -0,0 +1,13 @@
+import type { VgsCheckoutTarget } from './vgs-live-instrument.js';
+/**
+ * Build a checkout target from inline CLI flags (`--merchant-url` +
+ * `--amount`, with optional `--merchant-name` / `--country` / `--currency`)
+ * so any merchant can be paid without authoring a checkout JSON file first.
+ *
+ * Returns null when neither driving flag is present (file mode). Shape-only:
+ * the returned target flows through run-live-fill's existing validation block
+ * (positive-decimal amount, ISO codes, HTTPS), which stays the single source
+ * of truth — nothing is double-validated here except the URL parse, which
+ * must happen early because the merchant-name default derives from it.
+ */
+export declare function inlineTargetFromFlags(input: Map<string, string>): VgsCheckoutTarget | null;

package/dist/checkout-engine/inline-target.js

@@ -0,0 +1,37 @@
+/**
+ * Build a checkout target from inline CLI flags (`--merchant-url` +
+ * `--amount`, with optional `--merchant-name` / `--country` / `--currency`)
+ * so any merchant can be paid without authoring a checkout JSON file first.
+ *
+ * Returns null when neither driving flag is present (file mode). Shape-only:
+ * the returned target flows through run-live-fill's existing validation block
+ * (positive-decimal amount, ISO codes, HTTPS), which stays the single source
+ * of truth — nothing is double-validated here except the URL parse, which
+ * must happen early because the merchant-name default derives from it.
+ */
+export function inlineTargetFromFlags(input) {
+    const merchantUrl = input.get('--merchant-url');
+    const amount = input.get('--amount');
+    if (merchantUrl === undefined && amount === undefined)
+        return null;
+    if (!merchantUrl || !amount) {
+        throw new Error('inline checkout needs both --merchant-url and --amount');
+    }
+    let host;
+    try {
+        host = new URL(merchantUrl).hostname;
+    }
+    catch {
+        throw new Error('--merchant-url must be a valid URL');
+    }
+    if (!host) {
+        throw new Error('--merchant-url must have a hostname');
+    }
+    return {
+        merchantName: input.get('--merchant-name') ?? host,
+        merchantUrl,
+        merchantCountryCode: input.get('--country') ?? 'US',
+        transactionAmount: amount,
+        transactionCurrencyCode: input.get('--currency') ?? 'USD',
+    };
+}

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

@@ -0,0 +1,61 @@
+export type CardCredential = {
+    pan: string;
+    expMonth: number;
+    expYear: number;
+    cvc: string;
+    cardholderName: string;
+    /** Dynamic payment credential expiry, distinct from the card expiration. */
+    credentialExpiresAt?: string;
+    /**
+     * Non-sensitive, bounded request-correlation handles returned by the mint
+     * route. These are evidence pointers, not card credential material.
+     */
+    vgsTraceId?: string;
+    networkCorrelationId?: string;
+};
+export type InstrumentContext = {
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+};
+export type InstrumentKind = 'test-card' | 'vgs-alias' | 'agentic-token';
+export interface Instrument {
+    kind: InstrumentKind;
+    getCredential(ctx: InstrumentContext): Promise<CardCredential>;
+}
+export declare const OFFICIAL_TEST_PANS: {
+    readonly visa: "4242424242424242";
+    readonly visaAlt: "4111111111111111";
+    readonly visaDecline: "4000000000000002";
+    readonly visaSlowConfirm: "4000000000000069";
+    readonly visaUnknownOutcome: "4000000000000044";
+    readonly visaChallenge: "4000000000000010";
+    readonly visaEmailOtp: "4000000000000077";
+};
+export type TestCardOptions = {
+    pan?: string;
+    cardholderName?: string;
+    cvc?: string;
+    expMonth?: number;
+    expYear?: number;
+};
+export declare class TestCardInstrument implements Instrument {
+    readonly kind: "test-card";
+    private readonly credential;
+    constructor(opts?: TestCardOptions);
+    getCredential(_ctx: InstrumentContext): Promise<CardCredential>;
+}
+export declare class VgsAliasInstrument implements Instrument {
+    private readonly _alias;
+    readonly kind: "vgs-alias";
+    constructor(_alias: string);
+    getCredential(_ctx: InstrumentContext): Promise<CardCredential>;
+}
+export declare class AgenticTokenInstrument implements Instrument {
+    private readonly tokenRef;
+    private readonly mintCredential?;
+    readonly kind: "agentic-token";
+    private used;
+    constructor(tokenRef: string, mintCredential?: ((ctx: InstrumentContext) => Promise<CardCredential>) | undefined);
+    getCredential(ctx: InstrumentContext): Promise<CardCredential>;
+}

package/dist/checkout-engine/instrument.js

@@ -0,0 +1,87 @@
+// Instrument abstraction: the checkout engine is deliberately blind to WHERE
+// card credentials come from. Official test PANs, callback-backed agentic
+// credentials, and owner-only VIC harness files are enabled; VGS aliases stay
+// stubbed until a reveal seam exists. The executor remains unchanged across
+// every instrument.
+// Official public test PANs only. These are the sanctioned Visa/network test
+// numbers used against local fixtures; they carry no funds and pass Luhn.
+export const OFFICIAL_TEST_PANS = {
+    visa: '4242424242424242',
+    visaAlt: '4111111111111111',
+    // PAN whose last four are 0002 is treated as a forced decline by the
+    // fixture acquirer, for exercising the declined outcome path.
+    visaDecline: '4000000000000002',
+    // Ending 0069: the fixture acquirer shows a processing interstitial, then
+    // JS-redirects to a Shopify-style thank-you URL with no confirmation text —
+    // exercises the outcome observer's late, URL-signal confirmation path.
+    visaSlowConfirm: '4000000000000069',
+    // Ending 0044: the fixture acquirer returns a neutral page with neither a
+    // confirmation nor a decline signal — exercises the unknown-outcome deadline.
+    visaUnknownOutcome: '4000000000000044',
+    // Ending 0010: the fixture acquirer answers with a 3DS-style verification
+    // page embedding an ACS challenge iframe that never completes — exercises
+    // the observer's action-required (issuer challenge) path.
+    visaChallenge: '4000000000000010',
+    // Ending 0077: the fixture acquirer emails a one-time code to the agent
+    // inbox and shows a 'check your email for a code' page with a one-time-code
+    // field — exercises the executor's agent-resolvable email-OTP subroutine.
+    visaEmailOtp: '4000000000000077',
+};
+function futureExpiry() {
+    const now = new Date();
+    return { expMonth: 12, expYear: now.getFullYear() + 3 };
+}
+export class TestCardInstrument {
+    kind = 'test-card';
+    credential;
+    constructor(opts = {}) {
+        const exp = futureExpiry();
+        this.credential = {
+            pan: opts.pan ?? OFFICIAL_TEST_PANS.visa,
+            expMonth: opts.expMonth ?? exp.expMonth,
+            expYear: opts.expYear ?? exp.expYear,
+            cvc: opts.cvc ?? '123',
+            cardholderName: opts.cardholderName ?? 'Test Agent',
+        };
+    }
+    async getCredential(_ctx) {
+        return this.credential;
+    }
+}
+const NOT_ENABLED = 'not enabled: pending VGS alias reveal support';
+// Stub. Once VGS enablement lands, this resolves a network token / alias into a
+// fillable credential (a virtual PAN plus its verification value).
+export class VgsAliasInstrument {
+    _alias;
+    kind = 'vgs-alias';
+    constructor(_alias) {
+        this._alias = _alias;
+    }
+    async getCredential(_ctx) {
+        throw new Error(`${NOT_ENABLED}. VgsAliasInstrument cannot resolve alias "${this._alias}" ` +
+            'to a fillable PAN until VGS exposes the reveal seam for this spike.');
+    }
+}
+// A server-side provider mints the transaction-bound credential whose pan
+// carries the DPAN and whose cvc carries the short DAVV. Omitting the provider
+// preserves a clear fail-closed result for callers that have only a token ref.
+export class AgenticTokenInstrument {
+    tokenRef;
+    mintCredential;
+    kind = 'agentic-token';
+    used = false;
+    constructor(tokenRef, mintCredential) {
+        this.tokenRef = tokenRef;
+        this.mintCredential = mintCredential;
+    }
+    async getCredential(ctx) {
+        if (!this.mintCredential) {
+            throw new Error('not enabled: no agentic credential provider configured. ' +
+                `Token ${this.tokenRef} needs a server-side VGS credential provider.`);
+        }
+        if (this.used)
+            throw new Error('agentic credential instrument is single-use');
+        this.used = true;
+        return this.mintCredential(ctx);
+    }
+}

package/dist/checkout-engine/live-fill-approval.d.ts

@@ -0,0 +1,43 @@
+import type { CheckoutMode, CheckoutOutcome, CheckoutResult } from './executor.js';
+export declare const SUBMIT_ENV_FLAG = "CHECKOUT_AGENT_ALLOW_SUBMIT";
+export declare const MODE_ENV_FLAG = "CHECKOUT_AGENT_MODE";
+/**
+ * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
+ * CHECKOUT_AGENT_MODE environment default, then to the safe dry-run default.
+ */
+export declare function parseCheckoutMode(value: string | undefined, env?: Record<string, string | undefined>): CheckoutMode;
+/**
+ * Fail fast (before any file read or browser launch) when submit lacks an
+ * enablement. The env arm exists to stop AUTOMATION from reaching a live
+ * charge by accident — so it is required only when stdin is not a real TTY
+ * (scripts, agents, pipes). An interactive human needs no standing config:
+ * their per-run consent is the typed PAY phrase plus the passkey tap, both of
+ * which a non-interactive caller cannot fake (the phrase names the exact
+ * review id; the passkey is a FIDO ceremony on the verify site).
+ */
+export declare function assertSubmitAllowed(mode: CheckoutMode, env?: Record<string, string | undefined>, isInteractive?: boolean): void;
+/** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
+export declare function approvalPhrase(mode: CheckoutMode, reviewId: string): string;
+/** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
+export declare function formatAmountMinor(amountMinor: number, currency: string): string;
+/** The operator question. In submit mode it names the exact charge — amount and merchant. */
+export declare function approvalQuestion(mode: CheckoutMode, review: {
+    merchantHost: string;
+    amountMinor: number;
+    currency: string;
+}, phrase: string): string;
+/** The one outcome each mode may exit 0 with. */
+export declare function isRunSuccess(mode: CheckoutMode, outcome: CheckoutOutcome): boolean;
+/**
+ * True when the pay control was actually clicked but the run ended with an
+ * UNKNOWN outcome — neither 'confirmed' nor 'declined' (e.g. a slow redirect
+ * or confirmation copy the heuristics don't recognize). The charge may still
+ * have gone through; the operator must verify with the merchant before any
+ * retry, because a blind rerun risks a double charge. A 'declined' outcome is
+ * a definitive negative from the merchant, so it does not warn. Neither does
+ * 'action-required': a 3-D Secure challenge intercepts BEFORE authorization,
+ * so no charge can exist until it is completed — the double-charge warning
+ * would misdirect the operator, and the runner prints the challenge-specific
+ * notice instead.
+ */
+export declare function submitClickedWithoutConfirmation(result: CheckoutResult): boolean;

package/dist/checkout-engine/live-fill-approval.js

@@ -0,0 +1,90 @@
+// Deliberate-enablement seam for run-live-fill's submit mode. A real submit
+// moves real money, so it requires:
+//   1. an interactive human at a real TTY — or, for scripted/agent runs,
+//      the explicit CHECKOUT_AGENT_ALLOW_SUBMIT=1 environment arm,
+//   2. the invocation opts in (--mode submit, or the CHECKOUT_AGENT_MODE
+//      environment default for operators who always run one mode),
+//   3. the operator types the PAY phrase against the exact review id (and a
+//      hosted run additionally requires the passkey tap on the verify site).
+// The env arm is an anti-automation gate, not a human ritual: a TTY human's
+// consent is act 3 — the PAY phrase differs from dry-run's FILL phrase, so a
+// muscle-memory rerun of the dry-run procedure still cannot drift into
+// charging a card — while a non-interactive caller (script, agent, pipe) can
+// fake neither the phrase's review id nor the FIDO ceremony and must also be
+// explicitly armed. Fresh checkouts therefore need ZERO persisted config.
+export const SUBMIT_ENV_FLAG = 'CHECKOUT_AGENT_ALLOW_SUBMIT';
+export const MODE_ENV_FLAG = 'CHECKOUT_AGENT_MODE';
+/**
+ * `--mode` values map 1:1 onto CheckoutMode; an absent flag falls back to the
+ * CHECKOUT_AGENT_MODE environment default, then to the safe dry-run default.
+ */
+export function parseCheckoutMode(value, env = process.env) {
+    const effective = value ?? env[MODE_ENV_FLAG];
+    if (effective === undefined || effective === 'dry-run')
+        return 'dry-run';
+    if (effective === 'submit')
+        return 'submit';
+    throw new Error(`--mode (or ${MODE_ENV_FLAG}) must be dry-run or submit (got ${JSON.stringify(effective)})`);
+}
+/**
+ * Fail fast (before any file read or browser launch) when submit lacks an
+ * enablement. The env arm exists to stop AUTOMATION from reaching a live
+ * charge by accident — so it is required only when stdin is not a real TTY
+ * (scripts, agents, pipes). An interactive human needs no standing config:
+ * their per-run consent is the typed PAY phrase plus the passkey tap, both of
+ * which a non-interactive caller cannot fake (the phrase names the exact
+ * review id; the passkey is a FIDO ceremony on the verify site).
+ */
+export function assertSubmitAllowed(mode, env = process.env, isInteractive = process.stdin.isTTY === true) {
+    if (mode !== 'submit')
+        return;
+    if (env[SUBMIT_ENV_FLAG] === '1')
+        return;
+    if (isInteractive)
+        return;
+    throw new Error(`--mode submit refused: this is not an interactive terminal, and scripted submits ` +
+        `require ${SUBMIT_ENV_FLAG}=1. The gate is default-off so automation cannot ` +
+        'reach a live charge by accident.');
+}
+/** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
+export function approvalPhrase(mode, reviewId) {
+    return `${mode === 'submit' ? 'PAY' : 'CHECK'} ${reviewId}`;
+}
+/** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */
+export function formatAmountMinor(amountMinor, currency) {
+    return `${Math.floor(amountMinor / 100)}.${String(amountMinor % 100).padStart(2, '0')} ${currency}`;
+}
+/** The operator question. In submit mode it names the exact charge — amount and merchant. */
+export function approvalQuestion(mode, review, phrase) {
+    if (mode === 'submit') {
+        return (`Inspect the visible checkout. This WILL charge ` +
+            `${formatAmountMinor(review.amountMinor, review.currency)} at ${review.merchantHost}. ` +
+            `Type ${JSON.stringify(phrase)} to disclose the credential AND submit the order: `);
+    }
+    return (`Inspect the visible checkout. Type ${JSON.stringify(phrase)} ` +
+        `to validate the reviewed page without minting, filling, or submitting a credential: `);
+}
+/** The one outcome each mode may exit 0 with. */
+export function isRunSuccess(mode, outcome) {
+    return outcome === (mode === 'submit' ? 'confirmed' : 'reviewed-dry-run');
+}
+/**
+ * True when the pay control was actually clicked but the run ended with an
+ * UNKNOWN outcome — neither 'confirmed' nor 'declined' (e.g. a slow redirect
+ * or confirmation copy the heuristics don't recognize). The charge may still
+ * have gone through; the operator must verify with the merchant before any
+ * retry, because a blind rerun risks a double charge. A 'declined' outcome is
+ * a definitive negative from the merchant, so it does not warn. Neither does
+ * 'action-required': a 3-D Secure challenge intercepts BEFORE authorization,
+ * so no charge can exist until it is completed — the double-charge warning
+ * would misdirect the operator, and the runner prints the challenge-specific
+ * notice instead.
+ */
+export function submitClickedWithoutConfirmation(result) {
+    if (result.outcome === 'confirmed' ||
+        result.outcome === 'declined' ||
+        result.outcome === 'action-required') {
+        return false;
+    }
+    return result.evidence.getSteps().some((s) => s.type === 'submit' && s.data.clicked === true);
+}

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

@@ -0,0 +1,121 @@
+import { type VgsCheckoutTarget, type VgsPaymentCredential } from '../vgs-live-instrument.js';
+import { MandateLedger } from './mandate-ledger.js';
+/**
+ * Default number of draws a ceiling intent may fulfil (VGS mandate quantity).
+ * This is a purchase-COUNT cap, NOT the exposure bound: VGS enforces the
+ * declineThreshold as a CUMULATIVE cap across draws (live-verified 2026-07-23),
+ * so the total the network will authorize is the ceiling REGARDLESS of how many
+ * draws it is spread across — maxDraws only limits the number of separate
+ * purchases, it does not multiply the exposure. Kept SMALL as a sensible default
+ * purchase count (the owner-side client ledger also caps cumulative spend at ONE
+ * ceiling). This is the single default; callers that don't set maxDraws inherit
+ * it (do not re-duplicate it upstream).
+ */
+export declare const DEFAULT_MANDATE_MAX_DRAWS = 3;
+export type CardMandateMerchant = {
+    name: string;
+    url: string;
+    countryCode: string;
+};
+export type CreateCardMandateInput = {
+    /** Exact current runtime request key selected before human approval. */
+    agentJkt: string;
+    tokenId: string;
+    assuranceData: unknown;
+    ceilingMinor: number;
+    merchant: CardMandateMerchant;
+    currencyCode: string;
+    expiresAt: string;
+    /** Max draws the ceiling intent may fulfil; defaults to DEFAULT_MANDATE_MAX_DRAWS. */
+    maxDraws?: number;
+    /** Cross-host retail budget; network category eligibility still applies. */
+    crossMerchant?: boolean;
+};
+export type CreateIntentFn = (input: {
+    tokenId: string;
+    assuranceData: unknown;
+    transaction: VgsCheckoutTarget;
+    mandate: {
+        declineThresholdAmount: string;
+        quantity: number;
+        effectiveUntil: string;
+        consumerPrompt: string;
+    };
+}) => Promise<{
+    intentId: string;
+    status: string | null;
+}>;
+export type CreateCardMandateDeps = {
+    /** Mint the ceiling intent — wire serverCreateIntent(base, mintToken, …). */
+    createIntent: CreateIntentFn;
+    ledger: MandateLedger;
+    /** verify-web origin the intent is minted against (persisted for later draws). */
+    approvalBaseUrl: string;
+    /** Scoped mint token to persist for tap-free draws. */
+    mintToken?: string;
+    now?: () => Date;
+};
+export type CardMandateFacts = {
+    mandateId: string;
+    ceilingMinor: number;
+    remainingMinor: number;
+    currencyCode: string;
+    merchant: CardMandateMerchant;
+    expiresAt: string;
+    /** Network-enforced maximum purchase count disclosed at approval. */
+    maxDraws: number;
+};
+/**
+ * Create a card mandate: approve a spend CEILING once (the passkey assurance
+ * passed here was scoped to the ceiling + merchant), mint one VGS intent with
+ * that ceiling as its decline threshold, and record the cumulative-budget
+ * ledger entry. Integer minor units only.
+ */
+export declare function createCardMandate(input: CreateCardMandateInput, deps: CreateCardMandateDeps): Promise<CardMandateFacts>;
+export type FetchCryptogramFn = (input: {
+    tokenId: string;
+    intentId: string;
+    transaction: VgsCheckoutTarget;
+}) => Promise<VgsPaymentCredential>;
+export type DrawFromMandateInput = {
+    mandateId: string;
+    amountMinor: number;
+    /** The exact per-draw checkout target (merchant + amount + currency). */
+    transaction: VgsCheckoutTarget;
+};
+export type DrawFromMandateDeps = {
+    /** Draw a cryptogram against the mandate intent — wire serverFetchCryptogram. */
+    fetchCryptogram: FetchCryptogramFn;
+    ledger: MandateLedger;
+    /** Override the payable-credential gate (default validateCredential). */
+    validate?: (credential: VgsPaymentCredential) => void;
+    now?: () => Date;
+};
+export type DrawResult = {
+    payment: VgsPaymentCredential;
+    intentId: string;
+    remainingMinor: number;
+};
+/**
+ * Thrown ONLY for the post-reservation network/validation rejection class — the
+ * cryptogram fetch failed or returned a non-payable credential (the DRAW_REMEDY
+ * path). This is the sole draw failure that should DISABLE the mandate: it means
+ * the acquirer would not honor a ceiling-scoped assurance for a sub-amount draw.
+ *
+ * Pre-network failures — a fail-closed `reserve()` (concurrent over-budget race
+ * or expiry) or a `commit()` file-I/O error — throw a plain Error instead, so
+ * the caller (cli-engine) can rethrow them WITHOUT marking a HEALTHY mandate
+ * unhonored. Discriminating on this type is what keeps a transient race from
+ * permanently disabling a good mandate (michaelyang1 M1).
+ */
+export declare class MandateDrawDeclinedError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Draw a cryptogram against an existing card mandate with NO fresh tap. The
+ * reservation is atomic and the budget is decremented ONLY after a payable
+ * cryptogram returns; any rejection releases the reservation so remaining is
+ * unchanged. Validates merchant + currency + amount against the mandate first.
+ */
+export declare function drawFromMandate(input: DrawFromMandateInput, deps: DrawFromMandateDeps): Promise<DrawResult>;