@visa/cli 4.1.0-rc.13 → 4.1.0-rc.131

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

@@ -1,15 +1,30 @@
 import { type Browser } from 'playwright-core';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type PreparedCheckoutSessionStore } from './executor.js';
-import { runHostedApproval as realRunHostedApproval } from './hosted-approval.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';
+import { type CardMandateFacts } from './mandate/card-mandate.js';
+import { MandateLedger } from './mandate/mandate-ledger.js';
 import { writeReceipt as realWriteReceipt } from './receipt.js';
 import { reportVicOutcome as realReportVicOutcome, type VicConfirmationReport } from './vic-confirmation.js';
-import type { Contact } from './types.js';
+import type { Contact, OtpResolver } from './types.js';
+/**
+ * A card-mandate draw failed transiently (retryable) rather than definitively.
+ * Gateway 5xx, "server cryptogram not completed / try again", and network
+ * reset/timeout errors are transient: the mandate stays healthy and must NOT be
+ * disabled. Walks the error's cause chain so a wrapped MandateDrawDeclinedError
+ * is classified by its underlying gateway error. Exported for tests.
+ */
+export declare function isTransientDrawFailure(err: unknown): boolean;
 export type CliReviewInput = {
     url: string;
     amount: string;
     currency: string;
     credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
+    /** Exact request-key identity selected by the caller. */
+    agentJkt?: string;
     contact: Contact;
     approvalBaseUrl: string;
     merchantName?: string;
@@ -26,6 +41,12 @@ export type CliReviewFacts = {
 export type CliPayInput = CliReviewInput & {
     reviewId: string;
     submit: boolean;
+    /**
+     * Headless handoff for this payment attempt. The MCP layer uses it to return
+     * the hosted passkey URL to a messaging surface while the engine continues
+     * waiting in-process.
+     */
+    onApprovalUrl?: (url: string) => void;
 };
 export type CliReceiptFacts = {
     outcome: string;
@@ -33,6 +54,81 @@ export type CliReceiptFacts = {
     receiptPath: string | null;
     detail: string | null;
     vicConfirmation: VicConfirmationReport | null;
+    /**
+     * Which credential path actually ran: `mandate` = tap-free draw against an
+     * existing card mandate; `fresh-tap` = today's 1:1 hosted-passkey mint; `null`
+     * = neither ran (a pre-flight refusal, e.g. no prepared review). Transparency,
+     * never magic — the caller can always see whether a passkey was skipped.
+     */
+    source: 'mandate' | 'fresh-tap' | null;
+    /** Remaining mandate budget (minor units) after a mandate draw; else null. */
+    remainingMinor: number | null;
+    /**
+     * Immutable VIC/VGS intent used for server-side receipt correlation. This is
+     * an opaque non-credential identifier; it never carries the mint/verdict
+     * bearer that authorizes a cryptogram or confirmation. Present only after a
+     * card confirmation target exists.
+     */
+    processorIntentId?: string | null;
+};
+export type CliStartMandateInput = {
+    /** Optional local card-capability selector (legacy name or exact request-key JKT). */
+    agentRef?: string;
+    ceiling: string;
+    currency: string;
+    credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
+    contact: Contact;
+    approvalBaseUrl: string;
+    /**
+     * Per-purchase cap (decimal string, > 0 and <= ceiling). Registered with the
+     * approval context so the operator reads it as a worst-case term, and carried
+     * onto the budget mint token so it is enforced at draw time.
+     */
+    perTransaction?: string;
+    /**
+     * Agent-supplied one-liner shown on the approval page in a labeled
+     * "written by the agent" block — provenance for the human, never trusted.
+     */
+    intent?: string;
+};
+export type CliClaimMandateInput = {
+    /** Optional local card-capability selector (legacy name or exact request-key JKT). */
+    agentRef?: string;
+    /** Single-use pickup code the owner handed over from the panel. */
+    pickupCode: string;
+    /**
+     * The agent handoff this runtime just redeemed, when the pickup code rode
+     * inside its claim code. A dialog-minted budget pins that handoff instead of
+     * a key — there was no key yet — so this is what the pin is checked against.
+     */
+    expectedHandoffId?: string;
+    credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
+    approvalBaseUrl: string;
+};
+export type CliMandateFacts = CardMandateFacts & {
+    merchantHost: string;
+    /**
+     * True when the mandate minted its ceiling intent but the #5942 register
+     * handshake failed, so `findCovering` will SKIP it and no tap-free draw is
+     * possible. The mandate exists but is not usable — the caller must surface
+     * this (not report a plain success). Absent/false means registration succeeded;
+     * mandate-start now refuses before approval when no capability can register.
+     */
+    registerFailed?: boolean;
+    /**
+     * The server's refusal reason when {@link registerFailed} is true, verbatim.
+     * Carried out so the CLI can distinguish causes that need DIFFERENT operator
+     * actions — notably `token_mismatch`, which means the on-device grant record's
+     * cached token no longer matches the owner's live agentic token (they
+     * re-enrolled a card after the grant) and is fixed by re-running `grant-card`,
+     * not by retrying `mandate start`. Without the reason every failure reads as
+     * "the auth server was unreachable", which sends the operator in a loop.
+     */
+    registerFailureReason?: string;
 };
 type Session = {
     browser: Browser;
@@ -40,21 +136,130 @@ type Session = {
     amountMinor: number;
     currency: string;
     contact: Contact;
+    agentJkt?: string;
     cleanupTimer: ReturnType<typeof setTimeout>;
 };
+export interface CardDrawVerdictDraw {
+    tokenId: string;
+    amount: string;
+    currency: string;
+    merchantName: string;
+    merchantUrl: string;
+    merchantCountryCode: string;
+}
+export interface CardDrawVerdictCapability {
+    /** Opaque to the engine — passed straight back to {@link CardDrawVerdictSeam.fetchVerdict}. */
+    agentKey: unknown;
+    agentJkt: string;
+    /** Auth origin that minted the binding and hosts the /v4/card/draw* routes. */
+    authBaseUrl: string;
+}
+export interface CardDrawVerdictSeam {
+    loadCapability: (agentRef?: string) => CardDrawVerdictCapability | null;
+    fetchVerdict: (input: {
+        authBaseUrl: string;
+        agentKey: unknown;
+        mandateId: string;
+        drawId: string;
+        draw: CardDrawVerdictDraw;
+    }) => Promise<{
+        verdict: string;
+        remainingCents: number;
+    }>;
+}
+export interface CardMandateRegisterSeam {
+    loadCapability: (agentRef?: string) => {
+        agentKey: unknown;
+        agentJkt: string;
+        authBaseUrl: string;
+    } | null;
+    register: (input: {
+        authBaseUrl: string;
+        agentKey: unknown;
+        mandateId: string;
+        mintToken: string;
+        ceiling: string;
+        currency: string;
+    }) => 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 = {
     launchBrowser?: () => Promise<Browser>;
     prepareCheckout?: typeof realPrepareCheckout;
     submitApprovedCheckout?: typeof realSubmitApprovedCheckout;
     runHostedApproval?: typeof realRunHostedApproval;
+    /** Injectable pickup-code redeem for claimCardMandate — tests pass a fake. */
+    claimMandatePickup?: typeof realClaimMandatePickup;
+    /**
+     * Relay the hosted-approval URL to the caller as DATA the moment it is known,
+     * before the (up-to-timeout) poll wait. A headless agent surface wires this to
+     * hand the URL to its operator; the raw CLI leaves it unset (the URL prints to
+     * stderr and best-effort opens a browser).
+     */
+    onApprovalUrl?: (url: string) => void;
     reportVicOutcome?: typeof realReportVicOutcome;
     writeReceipt?: typeof realWriteReceipt;
     store?: PreparedCheckoutSessionStore;
     sessions?: Map<string, Session>;
     ttlMs?: number;
+    /** Owner-only card-mandate ledger — defaults to the ~/.visa-mcp singleton. */
+    ledger?: MandateLedger;
+    /** Injectable clock for mandate expiry decisions (tests pin it). */
+    now?: () => Date;
+    /**
+     * Cryptogram transport for the TAP-FREE mandate draw — defaults to the real
+     * server-side mint route. Injectable so a test can drive the draw-reject ->
+     * markUnhonored path with no network.
+     */
+    serverFetchCryptogram?: typeof serverFetchCryptogram;
+    /** Injectable confirmation transport; defaults to verify-web. */
+    serverPostConfirmation?: typeof serverPostConfirmation;
+    /**
+     * #5923 delegated card-draw verdict seam (see {@link CardDrawVerdictSeam}).
+     * Injected by the CLI when the runtime holds separately provisioned card
+     * authority. When absent, a covering-mandate draw fails before cryptogram mint.
+     */
+    cardDrawVerdict?: CardDrawVerdictSeam;
+    /**
+     * #5942 delegated card-mandate register seam (see {@link CardMandateRegisterSeam}).
+     * Required by mandate-start. When absent, the ceremony is refused before
+     * passkey approval because a budget token cannot act as draw authority.
+     */
+    cardMandateRegister?: CardMandateRegisterSeam;
+    /**
+     * Canonical mailbox OTP reader supplied by the runtime. The checkout engine
+     * owns no mailbox credential and never imports an email provider package.
+     */
+    resolveEmailOtp?: OtpResolver;
 };
 export declare function createCliCheckoutEngine(deps?: CliEngineDeps): {
+    startCardMandate(input: CliStartMandateInput): Promise<CliMandateFacts>;
+    claimCardMandate(input: CliClaimMandateInput): Promise<CliMandateFacts>;
     review(input: CliReviewInput): Promise<CliReviewFacts>;
+    /**
+     * Give up a prepared review without paying it (#7100).
+     *
+     * The retained browser is what lets a same-process MCP `review` → `pay`
+     * draw against the checkout it already inspected. A TERMINAL review-only
+     * run has no such second call — that process tells the operator to re-RUN
+     * with `--submit`, and the new process cannot reach this one's in-memory
+     * session. So the browser sat open for the full TTL, and because a live
+     * browser connection keeps the event loop alive, a command that had already
+     * succeeded looked hung until Ctrl-C.
+     *
+     * Idempotent and non-throwing: an unknown or already-released id is a
+     * no-op, so it is safe on an error path that may not have prepared anything
+     * and safe to call twice.
+     */
+    releaseReview(reviewId: string): Promise<void>;
     pay(input: CliPayInput): Promise<CliReceiptFacts>;
 };
 export {};