@visa/cli 4.1.0-rc.27 → 4.1.0-rc.270

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

@@ -1,13 +1,14 @@
 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 type { MandateRefusalCode } from './mandate.js';
+import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
 import { type VgsCheckoutTarget } from './vgs-live-instrument.js';
-import { serverFetchCryptogram } from './vgs-gateway/server-mint-client.js';
+import { ServerIntentError, 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
@@ -16,15 +17,45 @@ import type { Contact } from './types.js';
  * 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;
+    /**
+     * #8047: agent-authored purchase narrative captured at review time and
+     * replayed into the card draw's Transaction Intent Journal at pay time.
+     */
+    intentNarrative?: CardIntentNarrative;
     merchantName?: string;
     merchantCountryCode?: string;
+    trustedMerchantIdentity?: Readonly<{
+        handoffId: string;
+        checkoutId: string;
+        allowedOrigins: readonly string[];
+        expiresAt: string;
+    }>;
 };
 export type CliReviewFacts = {
     reviewId: string;
@@ -34,41 +65,77 @@ 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;
+    /** Bounded mandate/trusted-identity reason (#8669); absent for other outcomes. */
+    readonly refusalCode?: MandateRefusalCode;
+    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; `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.
+     * 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' | 'fresh-tap' | null;
+    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 = {
-    /** The merchant URL for a merchant-scoped mandate. Optional (and ignored) when
-     * `anyMerchant` is set — a budget mandate is not tied to a merchant. */
-    url?: string;
+    /** 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;
-    merchantName?: string;
-    merchantCountryCode?: string;
-    /** ISO 8601 mandate expiry; defaults to now + 24h. */
-    expiresAt?: string;
-    /** Max draws the ceiling intent may fulfil. */
-    maxDraws?: number;
     /**
      * 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
@@ -81,11 +148,33 @@ export type CliStartMandateInput = {
      */
     intent?: string;
     /**
-     * BUDGET mode: create a mandate spendable at ANY merchant (no merchant lock),
-     * bounded by the ceiling + per-transaction limit. The passkey approval shows
-     * "spend budget mandate" so the owner consents to the broader scope.
+     * 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.
      */
-    anyMerchant?: boolean;
+    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;
@@ -93,19 +182,86 @@ export type CliMandateFacts = CardMandateFacts & {
      * 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 → registered (or no
-     * delegated binding was present, so register was intentionally not attempted).
+     * 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;
+};
+/**
+ * The owner approved a budget but the intent bootstrap did not complete
+ * (#8470). `resumable` means the same approval can be resumed without a second
+ * passkey ceremony: the server's bootstrap state is at-most-once per signed
+ * token, so a resume can only recover an intent that already exists or
+ * dispatch once when nothing was ever dispatched — never create a sibling.
+ */
+export type CardMandateActivationFacts = {
+    phase: 'intent';
+    /** `uncertain`: the provider may have created the intent. `not_created`: proven not. */
+    outcome: 'uncertain' | 'not_created';
+    resumable: boolean;
+    status: number | null;
+    errorCode: string | null;
+    requestId: string | null;
+    bootstrapState: string;
+    /** Opaque, process-bound handle for {@link CliCheckoutEngine.resumeCardMandate}. */
+    resumeToken?: string;
+    /** When the approval's bootstrap credential stops being usable. */
+    resumeExpiresAt?: string;
+};
+export declare class CardMandateActivationError extends Error {
+    readonly facts: CardMandateActivationFacts;
+    readonly code = "CARD_MANDATE_ACTIVATION_INCOMPLETE";
+    constructor(message: string, facts: CardMandateActivationFacts);
+}
+export type CliResumeMandateInput = {
+    resumeToken: string;
+};
+/**
+ * Sort a budget-intent route failure into resume semantics. Exported for the
+ * regression net; the truth table is the product contract of #8470.
+ */
+export declare function classifyServerIntentFailure(err: ServerIntentError): {
+    outcome: 'uncertain' | 'not_created';
+    resumable: boolean;
 };
 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;
+    /** #8047: narrative for this review's journal, carried review -> pay. */
+    intentNarrative?: CardIntentNarrative;
     cleanupTimer: ReturnType<typeof setTimeout>;
 };
+/**
+ * #8047 Transaction Intent Journal narrative — the agent-authored half of the
+ * journal. Structural mirror of the CLI card client's `CardIntentNarrative`;
+ * the engine only threads it through and never interprets it.
+ */
+export interface CardIntentNarrative {
+    userRequest: string;
+    product: string;
+    purpose?: string;
+    quantity?: number;
+    expectedResult?: string;
+    recurring?: boolean;
+    userIntentSalt?: string;
+}
 export interface CardDrawVerdictDraw {
     tokenId: string;
     amount: string;
@@ -117,32 +273,39 @@ export interface CardDrawVerdictDraw {
 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: () => CardDrawVerdictCapability | null;
+    loadCapability: (agentRef?: string) => CardDrawVerdictCapability | null;
     fetchVerdict: (input: {
         authBaseUrl: string;
         agentKey: unknown;
+        runtimeCertificate?: string;
         mandateId: string;
         drawId: string;
         draw: CardDrawVerdictDraw;
+        /** #8047: narrative the client turns into the draw's journal sidecar. */
+        intentNarrative?: CardIntentNarrative;
     }) => Promise<{
         verdict: string;
         remainingCents: number;
     }>;
 }
 export interface CardMandateRegisterSeam {
-    loadCapability: () => {
+    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;
@@ -150,6 +313,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 = {
@@ -157,6 +326,8 @@ export type CliEngineDeps = {
     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
@@ -166,8 +337,18 @@ export type CliEngineDeps = {
     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;
@@ -179,24 +360,58 @@ export type CliEngineDeps = {
      * 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 agent holds a mode='card' delegated binding;
-     * when absent the covering-mandate draw keeps using the bearer mint token (the
-     * shipped #5917 flow, unchanged).
+     * 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}).
-     * Injected by the CLI when the agent holds a mode='card' delegated binding;
-     * when absent mandate-start skips the register (best-effort — the bearer path
-     * still works, only the delegated draw needs the register row).
+     * 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>;
+    resumeCardMandate(input: CliResumeMandateInput): 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 {};