@visa/cli 4.1.0-rc.25 → 4.1.0-rc.250

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

@@ -1,19 +1,55 @@
 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 { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type CheckoutMode, type CheckoutOutcome, type CheckoutFailureCode, type CheckoutResult, type PreparedCheckoutSessionStore } from './executor.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;
+/**
+ * A verdict refusal may be wrapped by drawFromMandate after its local
+ * reservation is released. Walk the cause chain so the original auth status +
+ * reasons still decide whether the mandate is permanently disabled.
+ */
+export declare function classifyCardDrawVerdictFailure(err: unknown): {
+    transient: boolean;
+    grantCapacity: boolean;
+    reasons: string[];
+} | null;
 export type CliReviewInput = {
     url: string;
+    checkoutRoute: 'guest-card';
     amount: string;
     currency: string;
     credentialPath: string;
+    /** See {@link CardInstrumentSource}. */
+    cardTokenId?: string;
+    /** Exact request-key identity selected by the caller. */
+    agentJkt?: string;
+    /** Owner-facing selected-agent label for the compact local receipt. */
+    agentName?: string;
+    /** Safe display suffix derived from the selected card grant label. */
+    cardLast4?: string;
     contact: Contact;
     approvalBaseUrl: string;
     merchantName?: string;
     merchantCountryCode?: string;
+    trustedMerchantIdentity?: Readonly<{
+        handoffId: string;
+        checkoutId: string;
+        allowedOrigins: readonly string[];
+        expiresAt: string;
+    }>;
 };
 export type CliReviewFacts = {
     reviewId: string;
@@ -23,38 +59,295 @@ export type CliReviewFacts = {
     submitTargetFingerprint: string;
     detectedRoles: string[];
 };
+/**
+ * A checkout was inspected successfully but cannot be reviewed safely.
+ *
+ * The explicit fields survive the CLI's copied-engine boundary structurally,
+ * so MCP callers do not have to parse the human-readable message.
+ */
+export declare class CheckoutReviewRefusedError extends Error {
+    readonly code = "CHECKOUT_REVIEW_REFUSED";
+    readonly checkoutOutcome: CheckoutOutcome;
+    readonly failureCode?: CheckoutFailureCode;
+    readonly requiresAdapter: string[];
+    readonly detectedRoles: string[];
+    readonly receiptWrite: ReceiptWriteObservation;
+    readonly detail?: string;
+    constructor(result: CheckoutResult, receiptWrite: ReceiptWriteObservation);
+}
 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;
+    outcome: CheckoutOutcome;
     confirmationRef: string | null;
     receiptPath: string | null;
     detail: string | null;
     vicConfirmation: VicConfirmationReport | null;
+    /**
+     * Which credential path actually ran: `mandate` = tap-free draw against an
+     * existing card mandate; `null` = none ran (a pre-flight refusal, e.g. no
+     * prepared review or no covering mandate). Transparency, never magic — the
+     * caller can always see whether a passkey was skipped.
+     */
+    source: 'mandate' | 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;
+    /** True only when the checkout engine recorded a credential-minted step. */
+    credentialIssued: boolean;
+    /** True only when at least one payment field was successfully filled. */
+    credentialDisclosed: boolean;
+    /** Privacy-safe local receipt persistence outcome for centralized correlation. */
+    receiptWrite?: ReceiptWriteObservation;
+};
+type PayAttempt = {
+    fingerprint: string;
+    promise: Promise<CliReceiptFacts>;
+};
+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;
+    /**
+     * Per-call relay of the hosted-approval URL, the moment it is known and
+     * BEFORE the (up-to-timeout) wait. Takes precedence over the engine-level
+     * `deps.onApprovalUrl`.
+     *
+     * The engine seam was deps-only, and the MCP surface builds its engine once
+     * per process without it — so `start_card_mandate` produced an approval URL,
+     * printed it to stderr, and blocked the agent's turn for minutes with no way
+     * to tell the human what to open. A per-call hook lets one caller relay the
+     * URL without every caller sharing one engine-wide callback.
+     */
+    onApprovalUrl?: (url: string) => void;
+};
+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;
+    /** Exact caller URL repeated at pay time; may contain a UCP capability. */
+    requestUrl: string;
+    checkoutRoute: 'guest-card';
     target: VgsCheckoutTarget;
     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;
+    /** Root-signed delegation for a short-lived device key. */
+    runtimeCertificate?: string;
+    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;
+        runtimeCertificate?: string;
+        mandateId: string;
+        drawId: string;
+        draw: CardDrawVerdictDraw;
+    }) => Promise<{
+        verdict: string;
+        remainingCents: number;
+    }>;
+}
+export interface CardMandateRegisterSeam {
+    loadCapability: (agentRef?: string) => {
+        agentKey: unknown;
+        runtimeCertificate?: string;
+        agentJkt: string;
+        authBaseUrl: string;
+    } | null;
+    register: (input: {
+        authBaseUrl: string;
+        agentKey: unknown;
+        runtimeCertificate?: string;
+        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;
+    /**
+     * Privacy-safe receipt persistence lifecycle signal. The event deliberately
+     * excludes the receipt body, checkout URL, filesystem path, and raw error.
+     * Observer failures are swallowed so logging can never alter checkout state.
+     */
+    onReceiptWrite?: (event: ReceiptWriteObservation) => void | Promise<void>;
+    /** Injectable privacy-safe id source for terminal observations before reviewId exists. */
+    createObservationId?: () => string;
     store?: PreparedCheckoutSessionStore;
     sessions?: Map<string, Session>;
+    /** Exact-review singleflight registry; tests inject a fresh map for isolation. */
+    payAttempts?: Map<string, PayAttempt>;
     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 type ReceiptWriteObservation = {
+    event: 'checkout_receipt_write';
+    status: 'written' | 'failed';
+    mode: CheckoutMode;
+    checkoutOutcome: CheckoutOutcome;
+    merchantHost: string;
+    observationId: string;
+    failureCode: string | null;
+    errorCode: string | null;
+    panRedactions: number | null;
 };
 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 {};