@vonpay/checkout-cli 0.15.1 → 0.16.0

package/dist/index.js

@@ -36,6 +36,12 @@ function emitCliError(json, text) {
 // src/utils/key-mode.ts
 import { isLiveKey } from "@vonpay/checkout-node";
 var TEST_SECRET_KEY_PREFIX = "vp_sk_test_";
+function requiresLiveConfirmation(key) {
+  if (typeof key !== "string") return true;
+  if (key.startsWith(TEST_SECRET_KEY_PREFIX)) return false;
+  if (key.startsWith("vp_pk_")) return false;
+  return true;
+}
 function secretKeyMode(key) {
   if (typeof key !== "string") return null;
   if (isLiveKey(key)) return "live";
@@ -373,8 +379,19 @@ import {
   RETRY_WITHHELD_HELP,
   VonPayError
 } from "@vonpay/checkout-node";
+
+// src/utils/secret-patterns.ts
 var SECRET_PATTERNS = [
+  // Checkout-session client secret (2026-10-21): keep the session id, which is
+  // useful in a support thread, and drop the secret after `_secret_`.
+  [/(vp_cs_(?:test|live)_[A-Za-z0-9_-]{1,64}?)_secret_[A-Za-z0-9]+/g, "$1_secret_***"],
   [/vp_sk_(?:test|live)_[A-Za-z0-9_-]+/g, "vp_sk_***"],
+  // A legacy API key (`vp_key_*`), which checkout still accepts and treats as
+  // secret, and a single-use subscription portal code (`vsc_` + 43 base64url
+  // characters; a longer run is taken whole). Both case-sensitive, as
+  // checkout's own rules (src/lib/scrub.ts). Added 2026-10-22.
+  [/vp_key_(?:test|live)_[A-Za-z0-9_-]+/g, "vp_key_***"],
+  [/vsc_[A-Za-z0-9_-]{43,}/g, "vsc_***"],
   [/ss_(?:test|live)_[A-Za-z0-9_-]+/g, "ss_***"],
   [/whsec_[A-Za-z0-9_-]+/g, "whsec_***"],
   [/sk_(?:test|live)_[A-Za-z0-9_-]+/g, "sk_***"],
@@ -385,6 +402,25 @@ function scrubSecrets(s) {
   for (const [re, replacement] of SECRET_PATTERNS) out = out.replace(re, replacement);
   return out;
 }
+
+// src/utils/sanitize.ts
+var ANSI_PATTERN = /\x1B\[[0-9;?]*[A-Za-z]/g;
+var C0_CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+function stripAnsi(s) {
+  return s.replace(ANSI_PATTERN, "").replace(C0_CONTROL_PATTERN, "");
+}
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + "\u2026";
+}
+function safeDisplay(s, max = 200) {
+  return truncate(stripAnsi(s), max);
+}
+function safeInline(s, max = 200) {
+  return safeDisplay(s.replace(/[\r\n]+/g, " "), max);
+}
+
+// src/utils/errors.ts
 var CLI_READ_BACK = "From this CLI: `vonpay checkout payment-intents get <id>` (charge, capture, void), `vonpay checkout refunds list --payment-intent <id>` or `--transaction <id>` (refund), `sessions get <id>` (checkout session).";
 var READ_BACK_FIRST = "Check the payment first: read it back (`vonpay checkout payment-intents get <id>` for a charge, capture or void; `vonpay checkout refunds list --payment-intent <id>` (or `--transaction <id>`) for a refund; `sessions get <id>` for a checkout session) and act only on what it shows.";
 var UNKNOWN_OUTCOME_GUIDANCE = `${READ_BACK_FIRST} If you then retry, reuse the SAME --idempotency-key as the first attempt, never a new one: a new key is a new action and can move money twice.`;
@@ -401,7 +437,10 @@ var FIELD_PRINTERS = {
     // What to do is the SDK's RETRY_WITHHELD_HELP, printed on the Hint line
     // (the SDK puts it in llmHint; quoted here only when the error carries
     // something else). This line adds the CLI commands for the read-back.
-    "Retry withheld: the outcome is unknown and the CLI did not retry it. " + (e.llmHint === RETRY_WITHHELD_HELP.llmHint ? "" : `${RETRY_WITHHELD_HELP.llmHint} `) + CLI_READ_BACK
+    "Retry withheld: the outcome is unknown and the CLI did not retry it. " + // startsWith, not equality: the SDK extends the base hint for one code
+    // (SETTLE_ONLY_UNVERIFIABLE_WITHHELD_HELP), and the Hint line already
+    // carries it then, so it must not be printed twice.
+    (typeof e.llmHint === "string" && e.llmHint.startsWith(RETRY_WITHHELD_HELP.llmHint) ? "" : `${RETRY_WITHHELD_HELP.llmHint} `) + CLI_READ_BACK
   ) : null,
   captureOutcome: (e) => e.captureOutcome ? `Capture outcome: ${str(e.captureOutcome)} \u2014 the provider accepted the capture but it could not be recorded, so money may have moved. Do NOT capture again; read the payment intent back first.` : null,
   voidOutcome: (e) => e.voidOutcome ? `Void outcome: ${str(e.voidOutcome)} \u2014 the provider accepted the void but it could not be recorded. Do NOT void again or tell the buyer the hold was released until a read-back confirms it.` : null,
@@ -416,6 +455,25 @@ var FIELD_PRINTERS = {
   rawReason: (e) => e.rawReason && e.rawReason !== e.reason ? `Reason as sent: ${str(e.rawReason)}` : null,
   retryAfterSeconds: (e) => typeof e.retryAfterSeconds === "number" ? `Retry after: ${e.retryAfterSeconds} seconds \u2014 then ask again` : null,
   session: (e) => e.session ? `Session: ${JSON.stringify(e.session)}` : null,
+  // Restricted API keys (built ahead of the API; served in production since 2026-10-27).
+  // The SDK validates these; they are server-supplied all the same, so every
+  // value goes through safeInline (no escape sequence, control character or
+  // line break reaches the terminal) before it is printed.
+  limit: (e) => e.limit ? `Key limit: ${safeInline(String(e.limit))}` : null,
+  limitMinor: (e) => typeof e.limitMinor === "number" ? `Key limit amount: ${safeInline(String(e.limitMinor))} (minor units)` : null,
+  usedMinor: (e) => typeof e.usedMinor === "number" ? `Used in the last 24 hours: ${safeInline(String(e.usedMinor))} (minor units)` : null,
+  limitCurrency: (e) => e.limitCurrency ? `Key limit currency: ${safeInline(String(e.limitCurrency))}` : null,
+  refusedFields: (e) => Array.isArray(e.refusedFields) && e.refusedFields.length > 0 ? `Fields this key may not send: ${e.refusedFields.map((f) => safeInline(String(f), 128)).join(", ")}` : null,
+  // A refused payment-only settle (mirror_settle_only_*; built ahead of the
+  // API's production release): the charge asked for and the store order's
+  // facts. Validated by the SDK, printed through safeInline all the same.
+  chargeAmount: (e) => typeof e.chargeAmount === "number" ? `Charge asked for: ${safeInline(String(e.chargeAmount))} (minor units)` : null,
+  chargeCurrency: (e) => e.chargeCurrency ? `Charge currency: ${safeInline(String(e.chargeCurrency))}` : null,
+  orderBalance: (e) => typeof e.orderBalance === "number" ? `Store order balance: ${safeInline(String(e.orderBalance))} (minor units) \u2014 on an amount mismatch, charge this instead` : e.orderBalance === null ? "Store order balance: unknown \u2014 the store could not be read" : null,
+  orderBalanceRaw: (e) => e.orderBalanceRaw ? `Store's own balance figure: ${safeInline(String(e.orderBalanceRaw))}` : null,
+  orderCurrency: (e) => e.orderCurrency ? `Store order currency: ${safeInline(String(e.orderCurrency))}` : null,
+  orderStatus: (e) => e.orderStatus ? `Store order status: ${safeInline(String(e.orderStatus))}` : null,
+  orderPaymentStatus: (e) => e.orderPaymentStatus ? `Store order payment status: ${safeInline(String(e.orderPaymentStatus))}` : null,
   // On a withheld retry the SDK sets this to RETRY_WITHHELD_HELP.llmHint — the
   // one wording for every surface — so it is printed as is.
   llmHint: (e) => e.llmHint ? `Hint: ${str(e.llmHint)}` : null,
@@ -535,6 +593,22 @@ function optionalMinorUnitsOrExit(raw, flag) {
   return raw === void 0 ? void 0 : minorUnitsOrExit(raw, flag);
 }
 
+// src/utils/mask-secrets.ts
+function maskSecretsInJson(json) {
+  return scrubSecrets(json);
+}
+var SHOW_SECRETS_HELP = "With --json, print the session's client secret in full. \u26A0 The output then contains a secret: do not paste it or let it reach a log";
+function withClientSecret(session) {
+  if (session === null || typeof session !== "object" || Array.isArray(session)) return session;
+  if (!("clientSecret" in session)) return session;
+  return { ...session, clientSecret: session.clientSecret };
+}
+function sessionJson(session, showSecrets) {
+  const json = JSON.stringify(withClientSecret(session), null, 2);
+  if (json === void 0) return String(json);
+  return showSecrets === true ? json : maskSecretsInJson(json);
+}
+
 // src/commands/sessions.ts
 var makeClient = makeCheckoutClient;
 function sessionLines(session) {
@@ -582,7 +656,7 @@ function sessionsCommand() {
   const sessions = new Command4("sessions").description(
     "Create and manage checkout sessions"
   );
-  sessions.command("create").description("Create a new checkout session").requiredOption("--amount <cents>", "Amount in minor units, a whole number (e.g. 1499 = $14.99)").requiredOption("--currency <code>", "Currency code (e.g. USD)").option("--country <code>", "Country code (e.g. US)").option("--description <text>", "Session description").option("--success-url <url>", "Redirect URL on success").option("--cancel-url <url>", "Redirect URL on cancel").option("--idempotency-key <key>", "Idempotency key for safe retries").option("--dry-run", "Validate without creating a session").option("--json", "Output raw JSON").action(async (opts) => {
+  sessions.command("create").description("Create a new checkout session").requiredOption("--amount <cents>", "Amount in minor units, a whole number (e.g. 1499 = $14.99)").requiredOption("--currency <code>", "Currency code (e.g. USD)").option("--country <code>", "Country code (e.g. US)").option("--description <text>", "Session description").option("--success-url <url>", "Redirect URL on success").option("--cancel-url <url>", "Redirect URL on cancel").option("--idempotency-key <key>", "Idempotency key for safe retries").option("--dry-run", "Validate without creating a session").option("--json", "Output raw JSON (the session's client secret masked, see --show-secrets)").option("--show-secrets", SHOW_SECRETS_HELP).action(async (opts) => {
     const amount = minorUnitsOrExit(String(opts.amount), "--amount");
     const client = makeClient();
     const spinner = startSpinner("Creating session...");
@@ -619,7 +693,7 @@ function sessionsCommand() {
       );
       spinner.stop();
       if (opts.json) {
-        console.log(JSON.stringify(session, null, 2));
+        console.log(sessionJson(session, opts.showSecrets));
       } else {
         console.log(chalk5.green("\u2713 Session created"));
         console.log(`  ID:       ${session.id}`);
@@ -631,14 +705,14 @@ function sessionsCommand() {
       handleError(err);
     }
   });
-  sessions.command("get").description("Get session status").argument("<id>", "Session ID").option("--json", "Output raw JSON").action(async (id, opts) => {
+  sessions.command("get").description("Get session status").argument("<id>", "Session ID").option("--json", "Output raw JSON (the session's client secret masked, see --show-secrets)").option("--show-secrets", SHOW_SECRETS_HELP).action(async (id, opts) => {
     const client = makeClient();
     const spinner = startSpinner("Fetching session...");
     try {
       const session = await client.sessions.get(id);
       spinner.stop();
       if (opts.json) {
-        console.log(JSON.stringify(session, null, 2));
+        console.log(sessionJson(session, opts.showSecrets));
       } else {
         for (const line of sessionLines(session)) console.log(line);
       }
@@ -715,20 +789,6 @@ function parseMetadata(pairs) {
   return out;
 }
 
-// src/utils/sanitize.ts
-var ANSI_PATTERN = /\x1B\[[0-9;?]*[A-Za-z]/g;
-var C0_CONTROL_PATTERN = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
-function stripAnsi(s) {
-  return s.replace(ANSI_PATTERN, "").replace(C0_CONTROL_PATTERN, "");
-}
-function truncate(s, max) {
-  if (s.length <= max) return s;
-  return s.slice(0, max - 1) + "\u2026";
-}
-function safeDisplay(s, max = 200) {
-  return truncate(stripAnsi(s), max);
-}
-
 // src/utils/live-key.ts
 import { createInterface as createInterface2 } from "readline";
 import chalk7 from "chalk";
@@ -762,10 +822,10 @@ var terminal = {
 };
 function keyFingerprint(key) {
   const m = key.match(/^(vp_sk_live_)([A-Za-z0-9_-]{0,4})/);
-  return m ? `${m[1]}${m[2]}\u2026` : "vp_sk_live_\u2026";
+  return m ? `${m[1]}${m[2]}\u2026` : "a key that is not a sandbox key";
 }
 async function confirmLiveAction(key, summary, opts = {}) {
-  if (!isLiveKey2(key)) return;
+  if (!requiresLiveConfirmation(key)) return;
   if (!terminal.isInteractive()) {
     const message = `Refusing to ${summary.action} with a live key: no person is at an interactive terminal to confirm it. A live-key action must be confirmed by a person typing at a terminal (stdin and stdout both a terminal); scripts, CI jobs and AI agents cannot confirm it, and --confirm-live is no longer enough. Use a sandbox key (vp_sk_test_\u2026) for automation, or run the command yourself in a terminal. Nothing was sent.`;
     exitWithCliError(message, chalk7.red(message));
@@ -796,7 +856,7 @@ function retiredConfirmLiveOption() {
   ).hideHelp();
 }
 function warnLiveSecretFlag(key, flag) {
-  if (!isLiveKey2(key)) return;
+  if (!requiresLiveConfirmation(key)) return;
   console.warn(
     chalk7.yellow(
       `Warning: passing ${flag} as a command argument with a live key exposes it to shell history and process-list (\`ps\`). Consider piping or env-injecting the value instead.`
@@ -872,8 +932,15 @@ function buildMITBlock(opts) {
     originalTransactionId
   };
 }
+function statusTone(status) {
+  if (status === "succeeded") return "green";
+  if (status === "authorized") return "cyan";
+  if (status === "requires_action") return "yellow";
+  if (status === "failed" || status === "cancelled") return "red";
+  return "gray";
+}
 function printPaymentIntent(intent) {
-  const statusColor = intent.status === "succeeded" ? chalk8.green : intent.status === "authorized" ? chalk8.cyan : intent.status === "requires_action" ? chalk8.yellow : intent.status === "failed" || intent.status === "canceled" ? chalk8.red : chalk8.gray;
+  const statusColor = chalk8[statusTone(intent.status)];
   console.log(`  ID:           ${intent.id}`);
   console.log(`  Status:       ${statusColor(intent.status)}`);
   console.log(
@@ -893,6 +960,12 @@ function printPaymentIntent(intent) {
   if (intent.declineCode) {
     console.log(`  Decline code: ${chalk8.red(safeDisplay(intent.declineCode))}`);
   }
+  if (intent.networkAdvice) {
+    console.log(`  Network advice: ${chalk8.red(safeInline(intent.networkAdvice))}`);
+    if (typeof intent.networkAdviceRetryAfterMs === "number") {
+      console.log(`  Retry after:  ${intent.networkAdviceRetryAfterMs} ms (earliest)`);
+    }
+  }
   console.log(`  Created:      ${intent.createdAt}`);
 }
 var AMOUNT_HELP = "Amount in minor units, a whole number (e.g. 1499 = $14.99)";
@@ -1627,6 +1700,7 @@ function warnIfUnsubscribable(event, write = (m) => console.warn(m)) {
   );
   return true;
 }
+var PROCESSOR_CONNECTION = null;
 function buildEventData(event, ids, amount, currency) {
   const base = {
     session_id: ids.sessionId,
@@ -1637,17 +1711,24 @@ function buildEventData(event, ids, amount, currency) {
   };
   switch (event) {
     case "session.succeeded":
-    case "payment_intent.succeeded":
       return base;
+    case "payment_intent.succeeded":
+      return { ...base, processor_connection: PROCESSOR_CONNECTION };
     case "charge.succeeded":
-      return { ...base, vp_tx_id: ids.transactionId, card: null };
+      return { ...base, vp_tx_id: ids.transactionId, card: null, processor_connection: PROCESSOR_CONNECTION };
     case "session.failed":
     case "payment_intent.failed":
       return {
         ...base,
         failure_reason: "Card declined",
         failure_code: "card_declined",
-        network_decline_code: "05"
+        network_decline_code: "05",
+        // The card network's advice: null when the network gave none that
+        // could be read (as on this ordinary decline) — never permission to retry.
+        network_advice: null,
+        network_advice_retry_after_ms: null,
+        // payment_intent.failed only: session.failed does not send it.
+        ...event === "payment_intent.failed" ? { processor_connection: PROCESSOR_CONNECTION } : {}
       };
     case "charge.failed":
       return {
@@ -1659,7 +1740,11 @@ function buildEventData(event, ids, amount, currency) {
         rule_code: null,
         // Always null on a decline: no money moved, no settlement row.
         vp_tx_id: null,
-        network_decline_code: "05"
+        network_decline_code: "05",
+        // Same two fields and values as payment_intent.failed / session.failed.
+        network_advice: null,
+        network_advice_retry_after_ms: null,
+        processor_connection: PROCESSOR_CONNECTION
       };
     case "mirror.order.created":
       return {
@@ -1668,7 +1753,7 @@ function buildEventData(event, ids, amount, currency) {
         order_status_url: null
       };
     case "payment_intent.cancelled":
-      return { ...base, cancellation_reason: "buyer_abandoned" };
+      return { ...base, cancellation_reason: "buyer_abandoned", processor_connection: PROCESSOR_CONNECTION };
     case "charge.refunded":
       return {
         ...base,
@@ -1682,7 +1767,8 @@ function buildEventData(event, ids, amount, currency) {
         reason: "customer_request",
         is_partial: false,
         original_charge_amount: amount,
-        card: null
+        card: null,
+        processor_connection: PROCESSOR_CONNECTION
       };
     case "refund.failed":
       return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vonpay/checkout-cli",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Von Payments CLI — developer tools for checkout integration",
   "repository": {
     "type": "git",
@@ -20,7 +20,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@vonpay/checkout-node": "^4.0.0",
+    "@vonpay/checkout-node": "^4.3.0",
     "commander": "^13.0.0",
     "chalk": "^5.4.0",
     "ora": "^8.2.0"