@visa/cli 4.1.0-rc.157 → 4.1.0-rc.158

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

@@ -1,5 +1,5 @@
 import { type Browser } from 'playwright-core';
-import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, type CheckoutOutcome, type PreparedCheckoutSessionStore } from './executor.js';
+import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, 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';
@@ -51,6 +51,21 @@ 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 detail?: string;
+    constructor(result: CheckoutResult);
+}
 export type CliPayInput = CliReviewInput & {
     reviewId: string;
     submit: boolean;

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

@@ -118,6 +118,31 @@ async function resolveCardInstrument(input) {
         '`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait` to ' +
         'attach one, or use a pre-provisioned VIC runtime.', readError instanceof Error ? { cause: readError } : undefined);
 }
+/**
+ * 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 class CheckoutReviewRefusedError extends Error {
+    code = 'CHECKOUT_REVIEW_REFUSED';
+    checkoutOutcome;
+    failureCode;
+    requiresAdapter;
+    detectedRoles;
+    detail;
+    constructor(result) {
+        super(result.detail
+            ? `review refused: ${result.outcome} — ${result.detail}`
+            : `review refused: ${result.outcome}`);
+        this.name = 'CheckoutReviewRefusedError';
+        this.checkoutOutcome = result.outcome;
+        this.failureCode = result.failureCode;
+        this.requiresAdapter = [...result.requiresAdapter];
+        this.detectedRoles = Object.keys(result.fields);
+        this.detail = result.detail;
+    }
+}
 function payAttemptFingerprint(input) {
     return JSON.stringify([
         input.url,
@@ -488,8 +513,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     contact: input.contact,
                 }, store);
                 if (prep.status !== 'ready') {
-                    await browser.close();
-                    throw new Error(`review refused: ${prep.result.outcome} — ${prep.result.detail ?? ''}`);
+                    throw new CheckoutReviewRefusedError(prep.result);
                 }
                 const r = prep.checkout.review;
                 // Expire the companion session on the SAME schedule as the store entry

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

@@ -11,6 +11,8 @@ export type CheckoutMode = 'dry-run' | 'submit';
 export type CheckoutOutcome = 'reviewed-dry-run'
 /** Historical receipt value from the credential-disclosing dry-run. */
  | 'filled-dry-run' | 'partial-fill' | 'adapter-required' | 'confirmed' | 'declined' | 'action-required' | 'cancelled' | 'blocked-by-mandate' | 'failed';
+/** Stable machine-readable cause for an expected terminal checkout result. */
+export type CheckoutFailureCode = 'card-number-field-unavailable' | 'human-action-required' | 'mandate-blocked';
 export type CredentialLifecycle = 'not-requested' | 'minted-not-exposed' | 'partially-exposed' | 'fully-filled';
 export type CredentialTiming = {
     approvedAt?: string;
@@ -26,6 +28,7 @@ export type CheckoutResult = {
     requiresAdapter: string[];
     credentialLifecycle: CredentialLifecycle;
     credentialTiming: CredentialTiming;
+    failureCode?: CheckoutFailureCode;
     detail?: string;
 };
 export type PrepareCheckoutOptions = {

package/dist/checkout-engine/executor.js

@@ -341,7 +341,7 @@ function unknownPreparedCheckoutResult(reviewId) {
     evidence.step('approval', { approved: false, reviewId, reason: detail });
     return makeResult('failed', {}, evidence, [], detail);
 }
-function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirmationRef) {
+function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirmationRef, failureCode) {
     const steps = evidence.getSteps();
     const approved = steps.find((step) => step.type === 'approval' && step.data.approved === true);
     const minted = steps.find((step) => step.type === 'credential-minted');
@@ -359,6 +359,12 @@ function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirma
             : filledRoles.has('number') || filledRoles.has('cvc')
                 ? 'partially-exposed'
                 : 'minted-not-exposed';
+    const terminalFailureCode = failureCode ??
+        (outcome === 'action-required'
+            ? 'human-action-required'
+            : outcome === 'blocked-by-mandate'
+                ? 'mandate-blocked'
+                : undefined);
     return {
         outcome,
         fields,
@@ -373,6 +379,7 @@ function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirma
                 : {}),
             ...(completed ? { fillCompletedAt: completed.ts } : {}),
         },
+        ...(terminalFailureCode ? { failureCode: terminalFailureCode } : {}),
         ...(detail ? { detail } : {}),
         ...(confirmationRef ? { confirmationRef } : {}),
     };
@@ -844,7 +851,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return {
                 status: 'finished',
-                result: makeResult('failed', fields, evidence, requiresAdapter, reason),
+                result: makeResult('failed', fields, evidence, requiresAdapter, reason, undefined, 'card-number-field-unavailable'),
             };
         }
         const facts = await readTransactionFacts(page, options, 'review');

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

@@ -1,6 +1,6 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, } from './cli-engine.js';
+export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, CheckoutReviewRefusedError, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-export type { CheckoutResult, CheckoutReview, CheckoutOutcome } from './executor.js';
+export type { CheckoutResult, CheckoutReview, CheckoutOutcome, CheckoutFailureCode, } from './executor.js';
 export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';
 export { KNOWN_MERCHANT_IDENTITIES, type MerchantIdentity } from './known-merchants.js';
 export { RECEIPT_DIR } from './receipt-dir.js';

package/dist/checkout-engine/index.js

@@ -1,7 +1,7 @@
 // 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 { createCliCheckoutEngine, CheckoutReviewRefusedError, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 export { readConfirmedMerchants, } from './confirmed-merchants.js';
 export { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';