@vonpay/checkout-cli 0.13.0 → 0.15.0

package/dist/index.js

@@ -1,16 +1,2798 @@
 #!/usr/bin/env node
-import { Command } from "commander";
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { registerCheckout } from "./commands/checkout.js";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
-const program = new Command();
-program
-    .name("vonpay")
-    .description("Von Payments developer tools")
-    .version(pkg.version);
+
+// src/index.ts
+import { Command as Command13 } from "commander";
+import { readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+
+// src/commands/login.ts
+import { Command, Option } from "commander";
+import { createInterface } from "readline";
+import chalk from "chalk";
+
+// src/config.ts
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+// src/utils/json-errors.ts
+var jsonErrors = false;
+function setJsonErrors(enabled) {
+  jsonErrors = enabled;
+}
+function jsonErrorsEnabled() {
+  return jsonErrors;
+}
+function printJsonError(obj) {
+  console.error(JSON.stringify(obj));
+}
+function emitCliError(json, text) {
+  if (jsonErrors) printJsonError(json);
+  else console.error(text);
+  return process.exit(1);
+}
+
+// src/utils/key-mode.ts
+import { isLiveKey } from "@vonpay/checkout-node";
+var TEST_SECRET_KEY_PREFIX = "vp_sk_test_";
+function secretKeyMode(key) {
+  if (typeof key !== "string") return null;
+  if (isLiveKey(key)) return "live";
+  if (key.startsWith(TEST_SECRET_KEY_PREFIX)) return "test";
+  return null;
+}
+var NOT_A_SECRET_KEY_MESSAGE = "This is not a Von Payments secret key: it must start with vp_sk_test_ (sandbox) or vp_sk_live_ (live). Publishable keys (vp_pk_\u2026) and keys from other services cannot be used with this CLI.";
+
+// src/config.ts
+var CONFIG_DIR = join(homedir(), ".vonpay");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+function loadConfig() {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    console.error(
+      "Warning: ~/.vonpay/config.json is malformed. Run `vonpay checkout login` to reset it."
+    );
+    return {};
+  }
+}
+var LiveKeyNotStoredError = class extends Error {
+  constructor() {
+    super(
+      "Refusing to save a live key (vp_sk_live_\u2026) to ~/.vonpay/config.json: live keys are never stored on disk. Supply it for this terminal session only, through the VON_PAY_SECRET_KEY environment variable."
+    );
+    this.name = "LiveKeyNotStoredError";
+  }
+};
+function saveConfig(config) {
+  const key = config.checkout?.apiKey;
+  if (secretKeyMode(key) === "live") {
+    if (key !== loadConfig().checkout?.apiKey) throw new LiveKeyNotStoredError();
+    warnStoredLiveKey();
+  }
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  }
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", {
+    encoding: "utf-8",
+    mode: 384
+  });
+  chmodSync(CONFIG_FILE, 384);
+}
+function clearStoredApiKey() {
+  const config = loadConfig();
+  if (!config.checkout?.apiKey) return { removed: false };
+  delete config.checkout.apiKey;
+  if (Object.keys(config.checkout).length === 0) delete config.checkout;
+  if (Object.keys(config).length === 0) {
+    rmSync(CONFIG_FILE, { force: true });
+  } else {
+    saveConfig(config);
+  }
+  return { removed: true };
+}
+function getApiKey() {
+  const envKey = process.env.VON_PAY_SECRET_KEY;
+  if (envKey) return envKey;
+  const config = loadConfig();
+  const stored = config.checkout?.apiKey;
+  if (secretKeyMode(stored) === "live") warnStoredLiveKey();
+  return stored;
+}
+var warnedStoredLiveKey = false;
+function warnStoredLiveKey() {
+  if (warnedStoredLiveKey) return;
+  warnedStoredLiveKey = true;
+  console.warn(
+    "Warning: a LIVE key is saved in plaintext in ~/.vonpay/config.json (stored by an older version of this CLI). Live keys are no longer stored. Run `vonpay checkout logout` to delete it, and supply the key through the VON_PAY_SECRET_KEY environment variable for the session instead."
+  );
+}
+function requireApiKey() {
+  const key = getApiKey();
+  if (!key) {
+    const message = "No API key found. Run `vonpay checkout login` or set VON_PAY_SECRET_KEY.";
+    emitCliError({ error: message, code: null }, message);
+  }
+  if (secretKeyMode(key) === null) {
+    emitCliError({ error: NOT_A_SECRET_KEY_MESSAGE, code: null }, NOT_A_SECRET_KEY_MESSAGE);
+  }
+  return key;
+}
+
+// src/commands/login.ts
+var LIVE_KEY_NOT_SAVED_MESSAGE = "Live keys (vp_sk_live_\u2026) are never saved to ~/.vonpay/config.json: the file is plaintext, and a live key moves real money. Supply it for this terminal session only, through the environment, for example:\n  read -rs VON_PAY_SECRET_KEY && export VON_PAY_SECRET_KEY\n(paste the key at the silent prompt; it ends with the session). Use `login` for sandbox keys (vp_sk_test_\u2026).";
+function evaluateCliKeyGate(key, _opts = {}) {
+  if (!key) return { action: "prompt" };
+  const refusal = evaluateKeyToSave(key);
+  if (refusal) return refusal;
+  return {
+    action: "save",
+    warning: "Warning: passing keys as a command argument exposes them in shell history and process-list (`ps`). Use interactive mode (`vonpay checkout login`) instead."
+  };
+}
+function evaluateKeyToSave(key) {
+  const mode = secretKeyMode(key);
+  if (mode === null) return { action: "refuse", reason: NOT_A_SECRET_KEY_MESSAGE };
+  if (mode === "live") return { action: "refuse", reason: LIVE_KEY_NOT_SAVED_MESSAGE };
+  return null;
+}
+function readLine(prompt) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  return new Promise((resolve2) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve2(answer.trim());
+    });
+  });
+}
+function loginCommand() {
+  return new Command("login").description("Store a sandbox API key (vp_sk_test_\u2026) for CLI access. Live keys are never stored").argument("[key]", "Sandbox API secret key (vp_sk_test_*)").addOption(
+    new Option(
+      "--confirm-cli-exposure",
+      "No longer has any effect: live keys are never saved"
+    ).hideHelp()
+  ).action(async (key, opts) => {
+    let apiKey = key;
+    const verdict = evaluateCliKeyGate(key, opts);
+    if (verdict.action === "refuse") {
+      console.error(chalk.red(verdict.reason));
+      process.exit(1);
+    }
+    if (verdict.action === "save" && verdict.warning) {
+      console.warn(chalk.yellow(verdict.warning));
+    }
+    if (!apiKey) {
+      console.log(
+        chalk.dim(
+          "Get your API key from the Von Payments dashboard \u2192 Developers"
+        )
+      );
+      apiKey = await readLine("Sandbox API key (vp_sk_test_*): ");
+    }
+    if (!apiKey) {
+      console.error(chalk.red("No key provided."));
+      process.exit(1);
+    }
+    const refusal = evaluateKeyToSave(apiKey);
+    if (refusal) {
+      console.error(chalk.red(refusal.reason));
+      process.exit(1);
+    }
+    const config = loadConfig();
+    config.checkout = { ...config.checkout, apiKey };
+    saveConfig(config);
+    console.log(
+      chalk.green(`\u2713 API key saved (test mode) \u2192 ~/.vonpay/config.json`)
+    );
+  });
+}
+
+// src/commands/logout.ts
+import { Command as Command2 } from "commander";
+import chalk2 from "chalk";
+function logoutCommand() {
+  return new Command2("logout").description("Remove the stored API key from ~/.vonpay/config.json").action(() => {
+    const { removed } = clearStoredApiKey();
+    if (removed) {
+      console.log(
+        chalk2.green("\u2713 Stored API key removed from ~/.vonpay/config.json")
+      );
+    } else {
+      console.log(
+        chalk2.dim("No stored API key found in ~/.vonpay/config.json")
+      );
+    }
+    if (process.env.VON_PAY_SECRET_KEY) {
+      console.warn(
+        chalk2.yellow(
+          "Note: VON_PAY_SECRET_KEY is still set in your environment and takes precedence over the stored config. Run `unset VON_PAY_SECRET_KEY` to fully log out of this shell."
+        )
+      );
+    }
+  });
+}
+
+// src/commands/init.ts
+import { Command as Command3 } from "commander";
+import { appendFileSync, chmodSync as chmodSync2, existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { resolve } from "path";
+import chalk3 from "chalk";
+var LIVE_KEY_NOT_WRITTEN_MESSAGE = "Refusing to write a live key (vp_sk_live_\u2026) to .env: live keys are never written to disk. Run `init` with a sandbox key (vp_sk_test_\u2026), and give your app its live key through your deployment's secret store or the environment when you go live.";
+function ensureGitignoreBlocksEnv() {
+  if (!existsSync2(".gitignore")) return "no-repo";
+  if (envAlreadyIgnored(".gitignore")) {
+    return "already";
+  }
+  appendFileSync(".gitignore", "\n# Added by vonpay checkout init\n.env\n");
+  return "added";
+}
+var POSITIVE_ENV_PATTERNS = /* @__PURE__ */ new Set([
+  ".env",
+  "/.env",
+  "**/.env",
+  "*.env",
+  "**/.env*",
+  ".env*"
+]);
+var NEGATION_ENV_PATTERNS = /* @__PURE__ */ new Set([
+  "!.env",
+  "!/.env",
+  "!**/.env",
+  "!*.env",
+  "!**/.env*",
+  "!.env*"
+]);
+function envAlreadyIgnoredFromText(gitignoreText) {
+  const lines = gitignoreText.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith("#"));
+  let ignored = false;
+  for (const p of lines) {
+    if (POSITIVE_ENV_PATTERNS.has(p)) ignored = true;
+    else if (NEGATION_ENV_PATTERNS.has(p)) ignored = false;
+  }
+  return ignored;
+}
+function envAlreadyIgnored(rootIgnorePath) {
+  return envAlreadyIgnoredFromText(readFileSync2(rootIgnorePath, "utf-8"));
+}
+function initCommand() {
+  return new Command3("init").description("Initialize a project with Von Payments checkout").option("-f, --force", "Overwrite existing .env file").action(async (opts) => {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+      console.error(
+        chalk3.red(
+          "No API key found. Run `vonpay checkout login` first or set VON_PAY_SECRET_KEY."
+        )
+      );
+      process.exit(1);
+    }
+    const envFile = ".env";
+    const absPath = resolve(envFile);
+    if (existsSync2(envFile) && !opts.force) {
+      console.error(
+        chalk3.yellow(
+          `.env already exists at ${absPath}. Use --force to overwrite.`
+        )
+      );
+      process.exit(1);
+    }
+    const mode = secretKeyMode(apiKey);
+    if (mode === null) {
+      console.error(chalk3.red(NOT_A_SECRET_KEY_MESSAGE));
+      process.exit(1);
+    }
+    if (mode === "live") {
+      console.error(chalk3.red(LIVE_KEY_NOT_WRITTEN_MESSAGE));
+      process.exit(1);
+    }
+    const content = [
+      "# Von Payments Checkout",
+      `# Mode: ${mode}`,
+      `VON_PAY_SECRET_KEY=${apiKey}`,
+      ""
+    ].join("\n");
+    writeFileSync2(envFile, content, { encoding: "utf-8", mode: 384 });
+    chmodSync2(envFile, 384);
+    console.log(chalk3.green(`\u2713 .env created (${mode} mode) \u2192 ${absPath}`));
+    const gitignoreState = ensureGitignoreBlocksEnv();
+    if (gitignoreState === "added") {
+      console.log(chalk3.dim("  Added .env to .gitignore"));
+    } else if (gitignoreState === "already") {
+      console.log(chalk3.dim("  .env already listed in .gitignore \u2713"));
+    } else {
+      console.log(
+        chalk3.yellow(
+          "  No .gitignore found. If this is a git repo, add .env to your .gitignore before committing."
+        )
+      );
+    }
+  });
+}
+
+// src/commands/sessions.ts
+import { Command as Command4 } from "commander";
+import chalk5 from "chalk";
+
+// src/utils/spinner.ts
+import ora from "ora";
+function startSpinner(text) {
+  return ora({ text, isSilent: jsonErrorsEnabled() }).start();
+}
+
+// src/commands/sessions.ts
+import { formatMinorUnits } from "@vonpay/checkout-node";
+
+// src/client-factory.ts
+import { VonPayCheckout } from "@vonpay/checkout-node";
+
+// src/app-info.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+var pkg = JSON.parse(
+  readFileSync3(join2(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")
+);
+var CLI_VERSION = pkg.version;
+var CLI_APP_INFO = { name: "vonpay-cli", version: CLI_VERSION };
+var SILENT_ERROR_REPORTER = () => {
+};
+
+// src/utils/base-url.ts
+import { keyDestinationProblem as sdkKeyDestinationProblem } from "@vonpay/checkout-node";
+var ALLOW_CUSTOM_BASE_URL_ENV = "VONPAY_ALLOW_CUSTOM_BASE_URL";
+function customBaseUrlAllowed(env = process.env) {
+  return env[ALLOW_CUSTOM_BASE_URL_ENV] === "1";
+}
+var UNSAFE_URL_CHARS = /[\s\x00-\x1f\x7f\\]/;
+var WHERE = "It comes from VONPAY_BASE_URL or baseUrl in ~/.vonpay/config.json; fix it, or unset it to use https://checkout.vonpay.com.";
+function keyDestinationProblem(apiKey, baseUrl, env = process.env) {
+  if (baseUrl === void 0) return null;
+  if (UNSAFE_URL_CHARS.test(baseUrl)) {
+    return `Refusing to use the base URL: it contains spaces, control characters or backslashes. ${WHERE}`;
+  }
+  let url;
+  try {
+    url = new URL(baseUrl);
+  } catch {
+    return `Refusing to use the base URL: it is not a valid absolute URL (for example https://checkout.vonpay.com). ${WHERE}`;
+  }
+  if (url.username !== "" || url.password !== "") {
+    return `Refusing to use the base URL: it contains a user name or password, which would be sent with every request. ${WHERE}`;
+  }
+  const problem = sdkKeyDestinationProblem(apiKey, baseUrl, { allowCustom: customBaseUrlAllowed(env) });
+  return problem === null ? null : `${problem} ${WHERE}`;
+}
+function allowCustomBaseUrl(env = process.env) {
+  return customBaseUrlAllowed(env);
+}
+
+// src/utils/errors.ts
+import chalk4 from "chalk";
+import {
+  RETRY_WITHHELD_HELP,
+  VonPayError
+} from "@vonpay/checkout-node";
+var SECRET_PATTERNS = [
+  [/vp_sk_(?:test|live)_[A-Za-z0-9_-]+/g, "vp_sk_***"],
+  [/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_***"],
+  [/rk_(?:test|live)_[A-Za-z0-9_-]+/g, "rk_***"]
+];
+function scrubSecrets(s) {
+  let out = s;
+  for (const [re, replacement] of SECRET_PATTERNS) out = out.replace(re, replacement);
+  return out;
+}
+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.`;
+var str = (v) => v === void 0 || v === null ? null : String(v);
+var FIELD_PRINTERS = {
+  code: (e) => `Code: ${str(e.code)}`,
+  fix: (e) => `Fix:  ${str(e.fix)}`,
+  nextAction: (e) => (
+    // A withheld retry carries its own (SDK) guidance on the line below.
+    e.nextAction === "reconcile" && e.retryWithheld !== true ? `Next action: reconcile \u2014 ${UNKNOWN_OUTCOME_GUIDANCE}` : e.nextAction ? `Next action: ${str(e.nextAction)}` : null
+  ),
+  retryable: (e) => typeof e.retryable === "boolean" ? `Retryable: ${e.retryable ? "yes" : "no \u2014 do not re-run this command as-is"}` : null,
+  retryWithheld: (e) => e.retryWithheld === true ? (
+    // 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
+  ) : 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,
+  currentStatus: (e) => e.currentStatus ? `Current status: ${str(e.currentStatus)}` : null,
+  rejectReason: (e) => e.rejectReason ? `Reject reason: ${str(e.rejectReason)}` : null,
+  paymentIntent: (e) => e.paymentIntent ? `Payment intent: ${str(e.paymentIntent)}` : null,
+  // refund_target_is_duplicate: the SDK has already checked this is a
+  // transaction id (vp_tx_*), so it is safe to echo as a command.
+  refundInstead: (e) => e.refundInstead ? `Refund instead: vonpay checkout refunds create --transaction ${str(e.refundInstead)}` : null,
+  reason: (e) => e.reason ? `Reason: ${str(e.reason)}` : null,
+  // An unrecognised expire reason reads "unknown"; show what the API sent.
+  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,
+  // 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,
+  docs: (e) => e.docs ? `Docs: ${str(e.docs)}` : null,
+  status: (e) => typeof e.status === "number" ? `HTTP status: ${e.status}` : null,
+  rateLimit: (e) => e.rateLimit ? `Rate limit: ${JSON.stringify(e.rateLimit)}` : null,
+  requestId: (e) => e.requestId ? `Request ID: ${str(e.requestId)}` : null
+};
+var ERROR_FIELDS = Object.keys(FIELD_PRINTERS);
+function errorDetailLines(err) {
+  const source = err;
+  const lines = [];
+  for (const print of Object.values(FIELD_PRINTERS)) {
+    const line = print(source);
+    if (line !== null) lines.push(`  ${scrubSecrets(line)}`);
+  }
+  return lines;
+}
+function scrubDeep(value) {
+  if (typeof value === "string") return scrubSecrets(value);
+  if (Array.isArray(value)) return value.map(scrubDeep);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = scrubDeep(v);
+    return out;
+  }
+  return value;
+}
+function errorJson(err) {
+  if (err instanceof VonPayError) {
+    const out = { error: err.message };
+    const source = err;
+    for (const field of ERROR_FIELDS) {
+      const value = source[field];
+      if (value !== void 0) out[field] = value;
+    }
+    return scrubDeep(out);
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return { error: scrubSecrets(message), code: null };
+}
+function exitWithCliError(message, text) {
+  return emitCliError({ error: scrubSecrets(message), code: null }, text);
+}
+function handleError(err) {
+  if (jsonErrorsEnabled()) {
+    printJsonError(errorJson(err));
+    process.exit(1);
+  }
+  if (err instanceof VonPayError) {
+    console.error(chalk4.red(`Error: ${scrubSecrets(err.message)}`));
+    for (const line of errorDetailLines(err)) console.error(chalk4.dim(line));
+    process.exit(1);
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(chalk4.red(`Error: ${scrubSecrets(message)}`));
+  process.exit(1);
+}
+
+// src/client-factory.ts
+function getBaseUrl() {
+  const envBase = process.env.VONPAY_BASE_URL;
+  if (envBase) return envBase;
+  const config = loadConfig();
+  return config.checkout?.baseUrl;
+}
+function refuseUnsafeLiveDestination(apiKey) {
+  const problem = keyDestinationProblem(apiKey, getBaseUrl());
+  if (problem) exitWithCliError(problem, problem);
+}
+function apiHostDetail() {
+  const baseUrl = getBaseUrl();
+  if (!baseUrl) return [];
+  let origin = baseUrl;
+  try {
+    origin = new URL(baseUrl).origin;
+  } catch {
+  }
+  return origin === "https://checkout.vonpay.com" ? [] : [["API host", origin]];
+}
+function makeCheckoutClient() {
+  const apiKey = requireApiKey();
+  const baseUrl = getBaseUrl();
+  refuseUnsafeLiveDestination(apiKey);
+  return new VonPayCheckout({
+    apiKey,
+    ...baseUrl ? { baseUrl } : {},
+    // The SDK applies the same host rule at construction; the opt-in is the
+    // same environment variable (real process environment only).
+    allowCustomBaseUrl: allowCustomBaseUrl(),
+    appInfo: CLI_APP_INFO,
+    // The CLI prints every error itself (handleError / --json). Without this the SDK's fallback
+    // reporter adds its own `[vonpay] …` line to stderr on EVERY API error, live key included.
+    errorReporter: SILENT_ERROR_REPORTER
+  });
+}
+
+// src/utils/amount.ts
+var WHOLE_NUMBER = /^\d+$/;
+function parseMinorUnits(raw, flag) {
+  const text = raw.trim();
+  const value = Number(text);
+  if (!WHOLE_NUMBER.test(text) || !Number.isSafeInteger(value)) {
+    return {
+      ok: false,
+      message: `${flag} must be a whole number in minor units (the currency's smallest unit): for example 1499 = 14.99 USD. Got ${JSON.stringify(raw)}.`
+    };
+  }
+  return { ok: true, value };
+}
+function minorUnitsOrExit(raw, flag) {
+  const parsed = parseMinorUnits(raw, flag);
+  if (!parsed.ok) exitWithCliError(parsed.message, `Error: ${parsed.message}`);
+  return parsed.value;
+}
+function optionalMinorUnitsOrExit(raw, flag) {
+  return raw === void 0 ? void 0 : minorUnitsOrExit(raw, flag);
+}
+
+// src/commands/sessions.ts
+var makeClient = makeCheckoutClient;
+function sessionLines(session) {
+  const statusColor = session.status === "succeeded" ? chalk5.green : session.status === "failed" ? chalk5.red : session.status === "expired" ? chalk5.gray : chalk5.yellow;
+  const lines = [
+    `  ID:          ${session.id}`,
+    `  Status:      ${statusColor(session.status)}`,
+    `  Amount:      ${formatMinorUnits(session.amount, session.currency)}`
+  ];
+  if (session.paymentStatus) {
+    const paymentColor = session.paymentStatus === "paid" ? chalk5.green : session.paymentStatus === "held" ? chalk5.yellow : chalk5.gray;
+    lines.push(`  Payment:     ${paymentColor(session.paymentStatus)}`);
+    if (session.paymentStatus === "held") {
+      lines.push(
+        chalk5.yellow(
+          "               Held, not taken: capture it to take the money, or void it. Do not ship on a hold alone."
+        )
+      );
+    }
+  }
+  if (session.paymentIntentId) {
+    lines.push(`  Intent:      ${session.paymentIntentId}`);
+  }
+  if (session.transactionId) {
+    lines.push(`  Transaction: ${session.transactionId}`);
+  }
+  if (typeof session.vp_tx_id === "string") {
+    lines.push(`  Refund id:   ${session.vp_tx_id}`);
+  }
+  if (typeof session.vp_tx_count === "number") {
+    lines.push(`  Payments:    ${session.vp_tx_count}`);
+    if (session.vp_tx_count >= 2) {
+      lines.push(
+        chalk5.red(
+          `  \u26A0 Charged ${session.vp_tx_count} times: there is no single refund id. Have a person check the payments before refunding or fulfilling.`
+        )
+      );
+    }
+  }
+  lines.push(`  Created:     ${session.createdAt}`);
+  lines.push(`  Expires:     ${session.expiresAt}`);
+  return lines;
+}
+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) => {
+    const amount = minorUnitsOrExit(String(opts.amount), "--amount");
+    const client = makeClient();
+    const spinner = startSpinner("Creating session...");
+    try {
+      const params = {
+        amount,
+        currency: opts.currency.toUpperCase(),
+        country: opts.country?.toUpperCase(),
+        description: opts.description,
+        successUrl: opts.successUrl,
+        cancelUrl: opts.cancelUrl
+      };
+      if (opts.dryRun) {
+        spinner.text = "Validating...";
+        const result = await client.sessions.validate(params);
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else if (result.valid) {
+          console.log(chalk5.green("\u2713 Valid request"));
+          if (result.warnings.length > 0) {
+            for (const w of result.warnings) {
+              console.log(chalk5.yellow(`  \u26A0 ${w}`));
+            }
+          }
+        } else {
+          console.log(chalk5.red("\u2717 Invalid request"));
+        }
+        return;
+      }
+      const session = await client.sessions.create(
+        params,
+        opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : void 0
+      );
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(session, null, 2));
+      } else {
+        console.log(chalk5.green("\u2713 Session created"));
+        console.log(`  ID:       ${session.id}`);
+        console.log(`  URL:      ${chalk5.cyan(session.checkoutUrl)}`);
+        console.log(`  Expires:  ${session.expiresAt}`);
+      }
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+  sessions.command("get").description("Get session status").argument("<id>", "Session ID").option("--json", "Output raw JSON").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));
+      } else {
+        for (const line of sessionLines(session)) console.log(line);
+      }
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+  return sessions;
+}
+
+// src/commands/payment-intents.ts
+import { Command as Command5 } from "commander";
+import chalk8 from "chalk";
+import { formatMinorUnits as formatMinorUnits2 } from "@vonpay/checkout-node";
+
+// src/utils/idempotency.ts
+import { randomUUID } from "crypto";
+import chalk6 from "chalk";
+function resolveIdempotencyKey(flag) {
+  const given = flag?.trim();
+  if (given) return { key: given, generated: false };
+  return { key: `cli-${randomUUID()}`, generated: true };
+}
+function idempotencyKeyFor(flag, what) {
+  const { key, generated } = resolveIdempotencyKey(flag);
+  if (generated) {
+    console.error(
+      chalk6.dim(
+        `Idempotency key: ${key} (to retry this same ${what}, re-run with --idempotency-key ${key})`
+      )
+    );
+  }
+  return key;
+}
+
+// src/utils/metadata.ts
+var MAX_LEN = 256;
+var CONTROL_CHARS = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/;
+function parseMetadata(pairs) {
+  if (!pairs || pairs.length === 0) return void 0;
+  const out = {};
+  for (const pair of pairs) {
+    const idx = pair.indexOf("=");
+    if (idx === -1) {
+      throw new Error(
+        `Invalid --metadata value "${pair}". Expected key=value (use multiple --metadata flags for multiple pairs).`
+      );
+    }
+    const key = pair.slice(0, idx);
+    const value = pair.slice(idx + 1);
+    if (key.length === 0) {
+      throw new Error(
+        `Invalid --metadata value "${pair}": key is empty. Expected key=value with a non-empty key.`
+      );
+    }
+    if (key.length > MAX_LEN) {
+      throw new Error(
+        `--metadata key too long (${key.length} > ${MAX_LEN}).`
+      );
+    }
+    if (value.length > MAX_LEN) {
+      throw new Error(
+        `--metadata value too long (${value.length} > ${MAX_LEN}).`
+      );
+    }
+    if (CONTROL_CHARS.test(key) || CONTROL_CHARS.test(value)) {
+      throw new Error(
+        `--metadata "${key}" contains control characters; metadata must be printable text.`
+      );
+    }
+    out[key] = value;
+  }
+  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";
+import { Option as Option2 } from "commander";
+import { isLiveKey as isLiveKey2 } from "@vonpay/checkout-node";
+var CONFIRM_WORD = "confirm";
+var terminal = {
+  /**
+   * Both stdin and stdout are a terminal. A command run by a script, a CI job or
+   * an AI agent's shell tool has at least one of them piped.
+   */
+  isInteractive() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+  },
+  /** Ask one line on the terminal. End of input or Ctrl-C answers "" (cancel). */
+  ask(prompt) {
+    return new Promise((resolve2) => {
+      const rl = createInterface2({ input: process.stdin, output: process.stdout });
+      let answered = false;
+      rl.on("SIGINT", () => rl.close());
+      rl.on("close", () => {
+        if (!answered) resolve2("");
+      });
+      rl.question(prompt, (answer) => {
+        answered = true;
+        rl.close();
+        resolve2(answer);
+      });
+    });
+  }
+};
+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";
+}
+async function confirmLiveAction(key, summary, opts = {}) {
+  if (!isLiveKey2(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));
+  }
+  if (opts.confirmLive) {
+    console.warn(
+      chalk7.yellow(
+        "Note: --confirm-live no longer confirms a live action by itself. A person confirms it at the terminal."
+      )
+    );
+  }
+  const lines = [
+    chalk7.bold.red(`You are about to ${summary.action} with a LIVE key (${keyFingerprint(key)}).`),
+    ...(summary.details ?? []).map(([label, value]) => `  ${`${label}:`.padEnd(17)}${safeDisplay(value)}`),
+    chalk7.yellow(summary.consequence ?? "This moves real money and cannot be undone from here.")
+  ];
+  for (const line of lines) console.log(line);
+  const answer = await terminal.ask(`Type "${CONFIRM_WORD}" to proceed, anything else to cancel: `);
+  if (answer.trim() !== CONFIRM_WORD) {
+    const message = `Cancelled: you did not type "${CONFIRM_WORD}". Nothing was sent.`;
+    exitWithCliError(message, chalk7.red(message));
+  }
+}
+function retiredConfirmLiveOption() {
+  return new Option2(
+    "--confirm-live",
+    "No longer confirms anything: a live-key action is confirmed by a person at the terminal"
+  ).hideHelp();
+}
+function warnLiveSecretFlag(key, flag) {
+  if (!isLiveKey2(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.`
+    )
+  );
+}
+
+// src/commands/payment-intents.ts
+var MIT_INITIATORS = ["merchant", "customer"];
+var MIT_REASONS = [
+  "recurring",
+  "unscheduled",
+  "installment"
+];
+function buildCreateParams(opts, resolved) {
+  const params = {
+    amount: opts.amount,
+    currency: opts.currency.toUpperCase()
+  };
+  if (resolved.captureMethod !== void 0) {
+    params.captureMethod = resolved.captureMethod;
+  }
+  if (resolved.metadata !== void 0) {
+    params.metadata = resolved.metadata;
+  }
+  if (resolved.mit !== void 0) {
+    params.mit = resolved.mit;
+  }
+  const paymentMethodId = opts.paymentMethod?.trim();
+  if (paymentMethodId) {
+    params.paymentMethod = { id: paymentMethodId };
+  }
+  const sessionId = opts.sessionId?.trim();
+  if (sessionId) {
+    params.sessionId = sessionId;
+  }
+  const buyerId = opts.buyerId?.trim();
+  if (buyerId) {
+    params.buyerId = buyerId;
+  }
+  const buyerEmail = opts.buyerEmail?.trim();
+  if (buyerEmail) {
+    params.buyerEmail = buyerEmail;
+  }
+  return params;
+}
+function buildMITBlock(opts) {
+  const initiator = opts.mitInitiator?.trim().toLowerCase();
+  const reason = opts.mitReason?.trim().toLowerCase();
+  const originalTransactionId = opts.mitOriginalTransactionId?.trim();
+  const provided = [initiator, reason, originalTransactionId].filter(
+    (v) => v !== void 0 && v !== ""
+  ).length;
+  if (provided === 0) return void 0;
+  if (provided !== 3) {
+    throw new Error(
+      "MIT requires all three of --mit-initiator, --mit-reason, --mit-original-transaction-id (non-empty)."
+    );
+  }
+  if (!MIT_INITIATORS.includes(initiator)) {
+    throw new Error(
+      `Invalid --mit-initiator "${opts.mitInitiator}". Expected: ${MIT_INITIATORS.join(", ")}`
+    );
+  }
+  if (!MIT_REASONS.includes(reason)) {
+    throw new Error(
+      `Invalid --mit-reason "${opts.mitReason}". Expected: ${MIT_REASONS.join(", ")}`
+    );
+  }
+  return {
+    initiator,
+    reason,
+    originalTransactionId
+  };
+}
+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;
+  console.log(`  ID:           ${intent.id}`);
+  console.log(`  Status:       ${statusColor(intent.status)}`);
+  console.log(
+    `  Amount:       ${formatMinorUnits2(intent.amount, intent.currency)}`
+  );
+  console.log(`  Capture:      ${intent.captureMethod}`);
+  if (intent.nextAction) {
+    console.log(
+      `  Next action:  ${chalk8.yellow(safeDisplay(intent.nextAction.type))}`
+    );
+    if (intent.nextAction.type === "redirect_to_url") {
+      console.log(
+        `  Redirect:     ${chalk8.yellow(safeDisplay(intent.nextAction.redirectToUrl.url))}`
+      );
+    }
+  }
+  if (intent.declineCode) {
+    console.log(`  Decline code: ${chalk8.red(safeDisplay(intent.declineCode))}`);
+  }
+  console.log(`  Created:      ${intent.createdAt}`);
+}
+var AMOUNT_HELP = "Amount in minor units, a whole number (e.g. 1499 = $14.99)";
+function paymentIntentsCommand() {
+  const intents = new Command5("payment-intents").description(
+    "Create, read, capture, and void payment intents (discrete lifecycle)"
+  );
+  intents.command("create").description("Create a new payment intent").requiredOption("--amount <cents>", AMOUNT_HELP).requiredOption("--currency <code>", "ISO 4217 currency (e.g. USD)").option(
+    "--capture-method <mode>",
+    "automatic (default) or manual (parks at authorized)"
+  ).option(
+    "--metadata <pair...>",
+    "Metadata key=value (repeat flag for multiple pairs)"
+  ).option(
+    "--mit-initiator <initiator>",
+    `MIT initiator (${MIT_INITIATORS.join(" | ")})`
+  ).option(
+    "--mit-reason <reason>",
+    `MIT reason (${MIT_REASONS.join(" | ")})`
+  ).option(
+    "--mit-original-transaction-id <id>",
+    "Cardholder-initiated anchor payment intent ID (vpi_*)"
+  ).option(
+    "--payment-method <id>",
+    "Stored card to charge (vp_pmt_*). Required for saved-card / recurring charges \u2014 --mit alone declares the charge merchant-initiated but does not say which card to bill"
+  ).option(
+    "--session-id <id>",
+    "Checkout session this charge belongs to (vp_cs_*). Arms the double-charge guard: refused if that session already charged at submit. Safe to always send"
+  ).option(
+    "--buyer-id <id>",
+    "Your customer reference. Send on EVERY saved-card charge \u2014 it is what makes the server reject a charge against the wrong customer's stored card"
+  ).option("--buyer-email <email>", "Buyer email for this charge").option(
+    "--idempotency-key <key>",
+    "Idempotency key for this charge. Reuse the SAME key to retry the same charge safely. Generated (and printed) when omitted"
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(async (raw) => {
+    const apiKey = requireApiKey();
+    const opts = { ...raw, amount: minorUnitsOrExit(raw.amount, "--amount") };
+    const captureMethod = opts.captureMethod?.toLowerCase();
+    if (captureMethod !== void 0 && captureMethod !== "automatic" && captureMethod !== "manual") {
+      const message = `Invalid --capture-method "${opts.captureMethod}". Expected automatic or manual.`;
+      exitWithCliError(message, chalk8.red(message));
+    }
+    let params;
+    try {
+      const metadata = parseMetadata(opts.metadata);
+      const mit = buildMITBlock(opts);
+      params = buildCreateParams(opts, { captureMethod, metadata, mit });
+    } catch (err) {
+      handleError(err);
+    }
+    refuseUnsafeLiveDestination(apiKey);
+    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "charge");
+    await confirmLiveAction(
+      apiKey,
+      {
+        action: "create a payment intent (charge a payment)",
+        details: [
+          ...apiHostDetail(),
+          ["Amount", formatMinorUnits2(params.amount, params.currency)],
+          ["Capture", params.captureMethod ?? "automatic"],
+          ...params.paymentMethod ? [["Saved card", params.paymentMethod.id]] : [],
+          ...params.buyerId ? [["Buyer", params.buyerId]] : [],
+          ...params.sessionId ? [["Session", params.sessionId]] : [],
+          ["Idempotency key", idempotencyKey]
+        ]
+      },
+      opts
+    );
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Creating payment intent...");
+    try {
+      const intent = await client.paymentIntents.create(params, {
+        idempotencyKey
+      });
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(intent, null, 2));
+      } else {
+        console.log(chalk8.green("\u2713 Payment intent created"));
+        printPaymentIntent(intent);
+      }
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+  intents.command("get").description(
+    "Read a payment intent back \u2014 the way to check a payment whose outcome was unclear before doing anything else"
+  ).argument("<id>", "Payment intent ID (vpi_*)").option("--json", "Output raw JSON").action(async (id, opts) => {
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Fetching payment intent...");
+    try {
+      const intent = await client.paymentIntents.retrieve(id);
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(intent, null, 2));
+      } else {
+        printPaymentIntent(intent);
+      }
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+  intents.command("capture").description("Capture an authorized payment intent").argument("<id>", "Payment intent ID (vpi_*)").option(
+    "--amount-to-capture <cents>",
+    "Partial capture amount in minor units, a whole number (omit for full)"
+  ).option(
+    "--idempotency-key <key>",
+    "Idempotency key. Reuse the SAME key to retry safely. Generated (and printed) when omitted"
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(
+    async (id, opts) => {
+      const apiKey = requireApiKey();
+      const amountToCapture = optionalMinorUnitsOrExit(
+        opts.amountToCapture,
+        "--amount-to-capture"
+      );
+      refuseUnsafeLiveDestination(apiKey);
+      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "capture");
+      await confirmLiveAction(
+        apiKey,
+        {
+          action: "capture a payment intent (take the held money)",
+          details: [
+            ...apiHostDetail(),
+            ["Payment intent", id],
+            [
+              "Amount",
+              amountToCapture !== void 0 ? `${amountToCapture} in minor units (partial capture)` : "the full authorized amount"
+            ],
+            ["Idempotency key", idempotencyKey]
+          ]
+        },
+        opts
+      );
+      const client = makeCheckoutClient();
+      const spinner = startSpinner("Capturing payment intent...");
+      try {
+        const intent = await client.paymentIntents.capture(
+          id,
+          amountToCapture !== void 0 ? { amountToCapture } : void 0,
+          { idempotencyKey }
+        );
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(intent, null, 2));
+        } else {
+          const captureLabel = amountToCapture !== void 0 ? ` (partial: ${formatMinorUnits2(amountToCapture, intent.currency)})` : "";
+          console.log(chalk8.green(`\u2713 Payment intent captured${captureLabel}`));
+          printPaymentIntent(intent);
+        }
+      } catch (err) {
+        spinner.stop();
+        handleError(err);
+      }
+    }
+  );
+  intents.command("void").description("Void an authorized (uncaptured) payment intent").argument("<id>", "Payment intent ID (vpi_*)").option(
+    "--idempotency-key <key>",
+    "Idempotency key. Reuse the SAME key to retry safely. Generated (and printed) when omitted"
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(
+    async (id, opts) => {
+      const apiKey = requireApiKey();
+      refuseUnsafeLiveDestination(apiKey);
+      const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "void");
+      await confirmLiveAction(
+        apiKey,
+        {
+          action: "void a payment intent (release the hold)",
+          details: [
+            ...apiHostDetail(),
+            ["Payment intent", id],
+            ["Idempotency key", idempotencyKey]
+          ],
+          consequence: "A voided payment cannot be captured afterwards; this cannot be undone from here."
+        },
+        opts
+      );
+      const client = makeCheckoutClient();
+      const spinner = startSpinner("Voiding payment intent...");
+      try {
+        const intent = await client.paymentIntents.void(id, { idempotencyKey });
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(intent, null, 2));
+        } else {
+          console.log(chalk8.green("\u2713 Payment intent voided"));
+          printPaymentIntent(intent);
+        }
+      } catch (err) {
+        spinner.stop();
+        handleError(err);
+      }
+    }
+  );
+  return intents;
+}
+
+// src/commands/refunds.ts
+import { Command as Command6 } from "commander";
+import chalk9 from "chalk";
+import { formatMinorUnits as formatMinorUnits3 } from "@vonpay/checkout-node";
+function present(v) {
+  return v !== void 0 && v.trim() !== "";
+}
+function resolveRefundTarget(opts) {
+  const hasPi = present(opts.paymentIntent);
+  const hasTx = present(opts.transaction);
+  if (hasPi && hasTx) {
+    throw new Error(
+      "Pass exactly one of --payment-intent or --transaction, not both. A refund is issued against one target."
+    );
+  }
+  if (hasPi) return { paymentIntent: opts.paymentIntent.trim() };
+  if (hasTx) return { transaction: opts.transaction.trim() };
+  throw new Error(
+    "A refund target is required: pass --payment-intent <vpi_*> or --transaction <vp_tx_*>."
+  );
+}
+function buildRefundParams(opts, metadata) {
+  const params = { ...resolveRefundTarget(opts) };
+  if (opts.amount !== void 0) params.amount = opts.amount;
+  if (opts.currency !== void 0) {
+    params.currency = opts.currency.toUpperCase();
+  }
+  if (opts.reason !== void 0) params.reason = opts.reason;
+  if (metadata !== void 0) params.metadata = metadata;
+  return params;
+}
+function printRefund(refund) {
+  const statusColor = refund.status === "succeeded" ? chalk9.green : refund.status === "failed" ? chalk9.red : chalk9.yellow;
+  console.log(`  ID:             ${refund.id}`);
+  if (refund.transaction !== null) {
+    console.log(`  Transaction:    ${refund.transaction}`);
+  } else {
+    console.log(`  Payment intent: ${refund.paymentIntent}`);
+  }
+  console.log(`  Status:         ${statusColor(refund.status)}`);
+  console.log(
+    `  Amount:         ${formatMinorUnits3(refund.amount, refund.currency)}`
+  );
+  if (refund.reason) {
+    console.log(`  Reason:         ${safeDisplay(refund.reason)}`);
+  }
+}
+function refundsCommand() {
+  const refunds = new Command6("refunds").description(
+    "Refund a captured payment intent or a settled transaction"
+  );
+  refunds.command("create").description(
+    "Create a refund against a payment intent (--payment-intent) or a transaction (--transaction) \u2014 exactly one"
+  ).option(
+    "--payment-intent <id>",
+    "Payment intent ID to refund (vpi_*). Use this OR --transaction. A payment intent id is also visible to the shopper's browser \u2014 it is not proof a refund is wanted; only refund one you looked up from your own order records"
+  ).option(
+    "--transaction <id>",
+    "Transaction ID to refund (vp_tx_*), instead of --payment-intent (prefer --payment-intent whenever the payment has one). Use it for a payment that has no payment intent, to follow the transaction a refund_target_is_duplicate error names, or as the vp_tx_id read from the session when its payment has no payment intent \u2014 only when vp_tx_count is exactly 1, and only after matching it to the order in your own records. A transaction id is also visible to the shopper's browser \u2014 only refund one you looked up from your own order records"
+  ).option(
+    "--amount <cents>",
+    "Refund amount in minor units, a whole number (omit for full remaining balance)"
+  ).option("--currency <code>", "ISO 4217 currency code").option("--reason <text>", "Free-form reason (mirrored back on the record)").option(
+    "--metadata <pair...>",
+    "Metadata key=value (repeat flag for multiple pairs)"
+  ).option(
+    "--idempotency-key <key>",
+    "Idempotency key. Reuse the SAME key to retry safely. Generated (and printed) when omitted"
+  ).addOption(retiredConfirmLiveOption()).option("--json", "Output raw JSON").action(async (raw) => {
+    try {
+      resolveRefundTarget(raw);
+    } catch (err) {
+      const message = err.message;
+      exitWithCliError(message, chalk9.red(`Error: ${message}`));
+    }
+    const apiKey = requireApiKey();
+    const opts = {
+      ...raw,
+      amount: optionalMinorUnitsOrExit(raw.amount, "--amount")
+    };
+    let params;
+    try {
+      params = buildRefundParams(opts, parseMetadata(opts.metadata));
+    } catch (err) {
+      handleError(err);
+    }
+    const target = resolveRefundTarget(opts);
+    refuseUnsafeLiveDestination(apiKey);
+    const idempotencyKey = idempotencyKeyFor(opts.idempotencyKey, "refund");
+    await confirmLiveAction(
+      apiKey,
+      {
+        action: "create a refund (send money back to the buyer)",
+        details: [
+          ...apiHostDetail(),
+          "transaction" in target ? ["Transaction", target.transaction] : ["Payment intent", target.paymentIntent],
+          [
+            "Amount",
+            params.amount === void 0 ? "the full remaining balance" : params.currency ? formatMinorUnits3(params.amount, params.currency) : `${params.amount} in minor units`
+          ],
+          ["Idempotency key", idempotencyKey]
+        ],
+        consequence: "This pays money back out of the merchant's balance and cannot be reversed once settled."
+      },
+      opts
+    );
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Creating refund...");
+    try {
+      const refund = await client.refunds.create(params, { idempotencyKey });
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(refund, null, 2));
+      } else {
+        console.log(chalk9.green("\u2713 Refund created"));
+        printRefund(refund);
+      }
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+  refunds.command("list").description(
+    "List the refunds of ONE payment and its refund totals \u2014 the way to check a refund whose outcome was unclear"
+  ).option("--payment-intent <id>", "The payment's payment intent ID (vpi_*). Use this OR --transaction").option("--transaction <id>", "The payment's transaction ID (vp_tx_*), instead of --payment-intent").option("--limit <n>", "How many refunds to show (default 25, at most 100)").option("--starting-after <cursor>", "The next-page cursor printed by a previous run").option("--json", "Output raw JSON").action(
+    async (opts) => {
+      let target;
+      try {
+        target = resolveRefundTarget(opts);
+      } catch (err) {
+        const message = err.message.replace("A refund target is required", "A payment is required");
+        exitWithCliError(message, chalk9.red(`Error: ${message}`));
+      }
+      let limit;
+      if (opts.limit !== void 0) {
+        const parsed = parseMinorUnits(opts.limit, "--limit");
+        if (!parsed.ok || parsed.value < 1) {
+          const message = `--limit must be a whole number from 1 to 100; got ${JSON.stringify(opts.limit)}.`;
+          exitWithCliError(message, chalk9.red(`Error: ${message}`));
+        }
+        limit = parsed.value;
+      }
+      const client = makeCheckoutClient();
+      const spinner = startSpinner("Listing refunds...");
+      try {
+        const list = await client.refunds.list(target, {
+          ...limit !== void 0 ? { limit } : {},
+          ...opts.startingAfter ? { startingAfter: opts.startingAfter } : {}
+        });
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(list, null, 2));
+          return;
+        }
+        for (const line of refundListLines(list)) console.log(line);
+      } catch (err) {
+        spinner.stop();
+        handleError(err);
+      }
+    }
+  );
+  return refunds;
+}
+function refundListLines(list) {
+  const currency = list.data[0]?.currency;
+  const money = (n) => currency ? formatMinorUnits3(n, currency) : `${n} in minor units`;
+  const lines = [
+    `  Refunded so far:  ${money(list.amountRefunded)} (succeeded + still in progress)`,
+    `  Still refundable: ${money(list.remainingRefundable)}${list.refundable ? "" : " \u2014 this payment cannot be refunded now"}`
+  ];
+  if (list.data.length === 0) {
+    lines.push("  No refunds on this payment.");
+  }
+  for (const r of list.data) {
+    const status = r.status === "succeeded" ? chalk9.green(r.status) : r.status === "failed" ? chalk9.red(r.status) : chalk9.yellow(r.status);
+    lines.push(
+      `  ${r.id}  ${status}  ${formatMinorUnits3(r.amount, r.currency)}` + (r.createdAt ? `  ${r.createdAt}` : "") + (r.idempotencyKey ? `  key ${safeDisplay(r.idempotencyKey)}` : "")
+    );
+  }
+  if (list.data.some((r) => r.status === "requested")) {
+    lines.push(chalk9.yellow("  A refund marked requested is still in progress and can still fail: do not refund again."));
+  }
+  if (list.hasMore && list.nextCursor) {
+    lines.push(`  More: re-run with --starting-after ${safeDisplay(list.nextCursor)}`);
+  }
+  return lines;
+}
+
+// src/commands/tokens.ts
+import { Command as Command7 } from "commander";
+import chalk10 from "chalk";
+function printToken(token) {
+  const statusColor = token.status === "active" ? chalk10.green : token.status === "expired" ? chalk10.yellow : chalk10.red;
+  console.log(`  ID:        ${token.id}`);
+  console.log(`  Status:    ${statusColor(token.status)}`);
+  const card = formatTokenCard(token.card);
+  console.log(`  Card:      ${card.card}`);
+  console.log(`  Expires:   ${card.expires}`);
+}
+function tokensCommand() {
+  const tokens = new Command7("tokens").description(
+    "Create payment-method tokens for saved-card / MIT flows"
+  );
+  tokens.command("create").description("Create a payment-method token").option("--buyer-id <id>", "Buyer ID to attach the token to").option(
+    "--provider-reference <ref>",
+    "Provider tokenization handle (required for live keys with iframe-vault providers)"
+  ).option(
+    "--metadata <pair...>",
+    "Metadata key=value (repeat flag for multiple pairs)"
+  ).option("--idempotency-key <key>", "Idempotency key for safe retries").option("--json", "Output raw JSON").action(
+    async (opts) => {
+      const apiKey = requireApiKey();
+      if (!opts.buyerId && !opts.providerReference) {
+        console.warn(
+          chalk10.yellow(
+            "Warning: no --buyer-id or --provider-reference supplied. Providers with an iframe vault (sandbox and live alike) will fail with a 422 validation_error."
+          )
+        );
+      }
+      if (opts.providerReference !== void 0) {
+        warnLiveSecretFlag(apiKey, "--provider-reference");
+      }
+      const client = makeCheckoutClient();
+      const spinner = startSpinner("Creating token...");
+      try {
+        const metadata = parseMetadata(opts.metadata);
+        const params = {};
+        if (opts.buyerId !== void 0) params.buyerId = opts.buyerId;
+        if (opts.providerReference !== void 0) {
+          params.providerReference = opts.providerReference;
+        }
+        if (metadata !== void 0) params.metadata = metadata;
+        const token = await client.tokens.create(
+          params,
+          opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : void 0
+        );
+        spinner.stop();
+        if (opts.json) {
+          console.log(JSON.stringify(token, null, 2));
+        } else {
+          console.log(chalk10.green("\u2713 Token created"));
+          printToken(token);
+        }
+      } catch (err) {
+        spinner.stop();
+        handleError(err);
+      }
+    }
+  );
+  return tokens;
+}
+function formatTokenCard(card) {
+  const cardLine = card.brand === null && card.last4 === null ? "unknown" : `${card.brand ?? "unknown brand"} \u2022\u2022\u2022\u2022 ${card.last4 ?? "unknown"}`;
+  const expires = card.expMonth === null && card.expYear === null ? "unknown" : `${card.expMonth === null ? "??" : String(card.expMonth).padStart(2, "0")}/${card.expYear ?? "????"}`;
+  return { card: cardLine, expires };
+}
+
+// src/commands/capabilities.ts
+import { Command as Command8 } from "commander";
+import chalk11 from "chalk";
+function fmtBool(v) {
+  return v ? chalk11.green("yes") : chalk11.dim("no");
+}
+function fmtVoidPolicy(v) {
+  switch (v) {
+    case "supported":
+      return chalk11.green(v);
+    case "rerouted_to_refund":
+      return chalk11.yellow(v);
+    case "not_supported":
+      return chalk11.dim(v);
+    default:
+      return chalk11.dim(String(v));
+  }
+}
+function fmtDisputeReporting(v) {
+  return v === "tracked" ? chalk11.green(v) : chalk11.yellow(v);
+}
+function fmtSubscriptionBilling(v) {
+  if (v === true) return chalk11.yellow("yes");
+  if (v === false) return chalk11.green("no");
+  return chalk11.yellow("unknown");
+}
+function printCapabilities(caps) {
+  const ops = caps.supportedOperations;
+  console.log(chalk11.bold("Supported operations"));
+  console.log(`  auth/capture separation:  ${fmtBool(ops.authCaptureSeparation)}`);
+  console.log(`  partial capture:          ${fmtBool(ops.partialCapture)}`);
+  console.log(`  partial refund:           ${fmtBool(ops.partialRefund)}`);
+  console.log(`  unreferenced refund:      ${fmtBool(ops.unreferencedRefund)}`);
+  console.log(`  void after capture:       ${fmtVoidPolicy(ops.voidAfterCapture)}`);
+  console.log(`  MIT:                      ${fmtBool(ops.mit)}`);
+  console.log(`  network tokens:           ${fmtBool(ops.networkTokens)}`);
+  console.log(`  3D Secure 2:              ${fmtBool(ops.threeDSecure2)}`);
+  console.log(`  ACH:                      ${fmtBool(ops.ach)}`);
+  console.log(`  payouts API:              ${fmtBool(ops.payoutsApi)}`);
+  console.log(`  dispute reporting:        ${fmtDisputeReporting(ops.disputeReporting)}`);
+  console.log();
+  if (ops.disputeReporting !== "tracked") {
+    console.log(
+      chalk11.yellow(
+        "  \u26A0 Chargebacks on this connection do NOT reach Von Payments.\n    A `succeeded` payment is not evidence it was never disputed.\n    Monitor and answer disputes in your processor's own dashboard \u2014\n    they carry a deadline we cannot see or report."
+      )
+    );
+    console.log();
+  }
+  console.log(chalk11.bold("Subscription billing"));
+  console.log(`  Von Pay renews for you:   ${fmtSubscriptionBilling(caps.subscriptionBilling?.enabled)}`);
+  if (caps.subscriptionBilling?.enabled !== false) {
+    console.log(
+      chalk11.yellow(
+        `  \u26A0 Do not run renewals from your own system while this is not "no":
+    Von Pay may be charging these customers' renewals itself, and both
+    would charge them. Check again at the moment you renew.`
+      )
+    );
+  }
+  console.log();
+  console.log(chalk11.bold("Settlement currencies"));
+  console.log(
+    `  ${caps.settlementCurrencies.length ? caps.settlementCurrencies.join(", ") : chalk11.dim("(none reported)")}`
+  );
+  console.log();
+  console.log(chalk11.bold("Rate limits"));
+  console.log(
+    `  payment intents / minute: ${caps.rateLimits.paymentIntentsPerMinute}`
+  );
+}
+function capabilitiesCommand() {
+  return new Command8("capabilities").description("Show what this merchant's binder supports").option("--json", "Output raw JSON").action(async (opts) => {
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Fetching capabilities...");
+    try {
+      const caps = await client.capabilities.get();
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(caps, null, 2));
+      } else {
+        printCapabilities(caps);
+      }
+    } catch (err) {
+      spinner.stop();
+      handleError(err);
+    }
+  });
+}
+
+// src/commands/trigger.ts
+import { Command as Command9 } from "commander";
+import { createHmac as createHmac2, randomUUID as randomUUID2 } from "crypto";
+import chalk12 from "chalk";
+import ora2 from "ora";
+
+// src/utils/forward-to.ts
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "0.0.0.0",
+  // kernel-wildcard often routes to loopback on Linux / macOS dev hosts
+  "::1",
+  // URL.hostname surrounds IPv6 with brackets, but the bracket-stripping
+  // happens before this set is consulted (see normalizeHost). Both forms
+  // listed for defensiveness.
+  "[::1]",
+  // IPv6-mapped IPv4 loopback. Node's URL parser normalizes
+  // `[::ffff:127.0.0.1]` to either form depending on version — both
+  // are functionally loopback so we list every variant we have
+  // observed in the wild.
+  "::ffff:127.0.0.1",
+  "::ffff:7f00:1"
+]);
+function validateForwardTo(raw, opts) {
+  const flag = opts.flag ?? "--forward-to";
+  const tunnelFlag = opts.tunnelFlag ?? "--forward-to-tunnel";
+  if (typeof raw !== "string" || raw.length === 0) {
+    return { ok: false, reason: `${flag} URL is required` };
+  }
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return {
+      ok: false,
+      reason: `${flag} is not a parseable URL: ${truncate2(raw)}`
+    };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    return {
+      ok: false,
+      reason: `${flag} scheme must be http or https; got ${url.protocol}`
+    };
+  }
+  if (url.username !== "" || url.password !== "") {
+    return {
+      ok: false,
+      reason: `${flag} must not contain a user name or password.`
+    };
+  }
+  const host = normalizeHost(url.hostname);
+  const isLoopback = LOOPBACK_HOSTS.has(host);
+  if (!isLoopback && !opts.allowTunnel) {
+    return {
+      ok: false,
+      reason: `${flag} refuses non-loopback hosts by default (got ${url.hostname}). Re-run with ${tunnelFlag} if forwarding through ngrok / Cloudflare Tunnel / etc.`
+    };
+  }
+  const warning = host === "0.0.0.0" ? "forwarding to 0.0.0.0 \u2014 that's a bind-wildcard, not a guaranteed loopback destination (it can route off-host in some container/network setups). Prefer 127.0.0.1 or localhost if you meant your local machine." : void 0;
+  return { ok: true, url, isLoopback, warning };
+}
+function normalizeHost(hostname) {
+  if (hostname.startsWith("[") && hostname.endsWith("]")) {
+    return hostname.slice(1, -1);
+  }
+  return hostname.toLowerCase();
+}
+function truncate2(s) {
+  return s.length <= 120 ? s : `${s.slice(0, 117)}...`;
+}
+
+// src/utils/listen-forward.ts
+import { createHmac } from "crypto";
+async function forwardPayload(payload, opts) {
+  const body = JSON.stringify(payload);
+  const t = Math.floor(Date.now() / 1e3);
+  const v1 = createHmac("sha256", opts.signingSecret).update(`${t}.${body}`).digest("hex");
+  const signatureHeader = `t=${t},v1=${v1}`;
+  const timeoutMs = opts.timeoutMs ?? 5e3;
+  const localController = new AbortController();
+  const timeoutId = setTimeout(() => localController.abort(), timeoutMs);
+  const combinedSignal = anySignal([opts.signal, localController.signal]);
+  const start = Date.now();
+  try {
+    const res = await fetch(opts.url.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-vonpay-signature": signatureHeader,
+        "User-Agent": "vonpay-cli-listen"
+      },
+      body,
+      signal: combinedSignal,
+      // Never follow a redirect: a 307/308 from the local endpoint would make
+      // fetch re-send this body AND the signature header to wherever it points,
+      // including a non-loopback host --forward-to never allowed.
+      redirect: "manual"
+    });
+    try {
+      await res.arrayBuffer();
+    } catch {
+    }
+    if (isRedirect(res)) {
+      return {
+        attempted: true,
+        status: res.status,
+        latencyMs: Date.now() - start,
+        error: `the endpoint answered with a redirect (HTTP ${res.status}); it was not followed and the event was not sent anywhere else`
+      };
+    }
+    return {
+      attempted: true,
+      status: res.status,
+      latencyMs: Date.now() - start,
+      error: null
+    };
+  } catch (err) {
+    if (opts.signal.aborted) {
+      return { attempted: true, status: null, latencyMs: null, error: "aborted" };
+    }
+    if (localController.signal.aborted) {
+      return { attempted: true, status: null, latencyMs: null, error: `timeout after ${timeoutMs}ms` };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { attempted: true, status: null, latencyMs: null, error: message };
+  } finally {
+    clearTimeout(timeoutId);
+  }
+}
+function isRedirect(res) {
+  return res.status >= 300 && res.status < 400 || res.type === "opaqueredirect";
+}
+function anySignal(signals) {
+  if (typeof AbortSignal.any === "function") {
+    return AbortSignal.any(signals);
+  }
+  const controller = new AbortController();
+  const tracked = [];
+  const onAbort = () => {
+    for (const sig of tracked) {
+      sig.removeEventListener("abort", onAbort);
+    }
+    controller.abort();
+  };
+  for (const signal of signals) {
+    if (signal.aborted) {
+      controller.abort();
+      for (const sig of tracked) {
+        sig.removeEventListener("abort", onAbort);
+      }
+      return controller.signal;
+    }
+    signal.addEventListener("abort", onAbort);
+    tracked.push(signal);
+  }
+  return controller.signal;
+}
+
+// src/commands/trigger.ts
+var SUPPORTED_EVENTS = [
+  "charge.succeeded",
+  "charge.failed",
+  "charge.refunded",
+  "refund.failed",
+  "payment_intent.succeeded",
+  "payment_intent.failed",
+  "payment_intent.cancelled",
+  "mirror.order.created",
+  "session.succeeded",
+  "session.failed"
+];
+var UNSUBSCRIBABLE_EVENTS = [
+  "session.succeeded",
+  "session.failed"
+];
+function warnIfUnsubscribable(event, write = (m) => console.warn(m)) {
+  if (!UNSUBSCRIBABLE_EVENTS.includes(event)) return false;
+  const suggestion = event === "session.succeeded" ? "charge.succeeded" : "charge.failed";
+  write(
+    chalk12.yellow(
+      `\u26A0  ${event} is emitted internally but is NOT subscribable.
+   The subscription API accepts the key, stores nothing and returns success, so a
+   real endpoint receives this event NEVER \u2014 a handler tested only against it is
+   untested. Use ${suggestion} instead.`
+    )
+  );
+  return true;
+}
+function buildEventData(event, ids, amount, currency) {
+  const base = {
+    session_id: ids.sessionId,
+    payment_intent_id: ids.paymentIntentId,
+    transaction_id: ids.transactionId,
+    amount,
+    currency
+  };
+  switch (event) {
+    case "session.succeeded":
+    case "payment_intent.succeeded":
+      return base;
+    case "charge.succeeded":
+      return { ...base, vp_tx_id: ids.transactionId, card: null };
+    case "session.failed":
+    case "payment_intent.failed":
+      return {
+        ...base,
+        failure_reason: "Card declined",
+        failure_code: "card_declined",
+        network_decline_code: "05"
+      };
+    case "charge.failed":
+      return {
+        ...base,
+        failure_reason: "Card declined",
+        failure_code: "card_declined",
+        // Non-null ONLY when failure_code is `blocked_by_rule`; this fixture is
+        // an ordinary decline, so a consumer must see the null.
+        rule_code: null,
+        // Always null on a decline: no money moved, no settlement row.
+        vp_tx_id: null,
+        network_decline_code: "05"
+      };
+    case "mirror.order.created":
+      return {
+        payment_intent_id: ids.paymentIntentId,
+        order_number: `TEST-${randomUUID2().slice(0, 6).toUpperCase()}`,
+        order_status_url: null
+      };
+    case "payment_intent.cancelled":
+      return { ...base, cancellation_reason: "buyer_abandoned" };
+    case "charge.refunded":
+      return {
+        ...base,
+        refund_id: `vpr_test_${randomUUID2().slice(0, 8)}`,
+        vp_tx_id: ids.transactionId,
+        // The two unambiguous companions to `amount`. The server has emitted
+        // both for some time; omitting them here made a handler that reads them
+        // look broken against a synthetic event.
+        refund_amount: amount,
+        amount_refunded_total: amount,
+        reason: "customer_request",
+        is_partial: false,
+        original_charge_amount: amount,
+        card: null
+      };
+    case "refund.failed":
+      return {
+        ...base,
+        refund_id: `vpr_test_${randomUUID2().slice(0, 8)}`,
+        // Mirrors charge.refunded: the Von transaction id of the refunded charge.
+        vp_tx_id: ids.transactionId,
+        // No money moved: this is the reversal amount that FAILED to move.
+        refund_amount: amount,
+        amount_refunded_total: 0,
+        reason: "customer_request",
+        // LOCKED two-value refund vocabulary — `refund_declined` (terminal) or
+        // `refund_unresolved` (no provider response, true state unknown).
+        reason_code: "refund_declined",
+        is_partial: false,
+        original_charge_amount: amount,
+        retry_available: true,
+        card: null
+      };
+  }
+}
+function buildPayload(event, opts) {
+  const amount = opts.amount ?? 1499;
+  const currency = opts.currency ?? "USD";
+  const ids = {
+    sessionId: opts.sessionId ?? `vp_cs_test_${randomUUID2().slice(0, 8)}`,
+    transactionId: `vp_tx_test_${randomUUID2().slice(0, 8)}`,
+    paymentIntentId: `vpi_test_${randomUUID2().slice(0, 8)}`
+  };
+  return {
+    id: `vp_evt_test_${randomUUID2().slice(0, 8)}`,
+    type: event,
+    created: Math.floor(Date.now() / 1e3),
+    livemode: false,
+    merchant_id: `vp_mer_test_${randomUUID2().slice(0, 8)}`,
+    test_event: true,
+    data: buildEventData(event, ids, amount, currency)
+  };
+}
+function triggerCommand() {
+  return new Command9("trigger").description("Send a test webhook event to a local URL").argument("<event>", `Event type (${SUPPORTED_EVENTS.join(", ")})`).requiredOption("--url <url>", "Local webhook URL (e.g. http://localhost:3000/webhooks)").option("--session-id <id>", "Custom session ID").option("--amount <cents>", "Amount in minor units, a whole number").option("--currency <code>", "Currency code").option(
+    "--url-tunnel",
+    "Allow a non-loopback --url (ngrok / Cloudflare Tunnel). Without it, --url must be this machine"
+  ).addOption(retiredConfirmLiveOption()).action(async (event, opts) => {
+    if (!SUPPORTED_EVENTS.includes(event)) {
+      console.error(
+        chalk12.red(
+          `Unknown event: ${event}
+Supported: ${SUPPORTED_EVENTS.join(", ")}`
+        )
+      );
+      process.exit(1);
+    }
+    warnIfUnsubscribable(event);
+    const destination = validateForwardTo(String(opts.url ?? ""), {
+      allowTunnel: opts.urlTunnel === true,
+      flag: "--url",
+      tunnelFlag: "--url-tunnel"
+    });
+    if (!destination.ok) {
+      console.error(chalk12.red(destination.reason));
+      process.exit(1);
+    }
+    if (destination.warning) console.warn(chalk12.yellow(destination.warning));
+    const amount = optionalMinorUnitsOrExit(
+      opts.amount === void 0 ? void 0 : String(opts.amount),
+      "--amount"
+    );
+    const apiKey = requireApiKey();
+    await confirmLiveAction(
+      apiKey,
+      {
+        action: "trigger a test webhook event",
+        details: [
+          ["Event", event],
+          ["Sent to", String(opts.url)]
+        ],
+        consequence: "The event is signed with your LIVE key: a receiver that verifies with that key will accept it as a genuine event."
+      },
+      opts
+    );
+    const payload = buildPayload(event, { ...opts, amount });
+    const body = JSON.stringify(payload);
+    const t = Math.floor(Date.now() / 1e3);
+    const v1 = createHmac2("sha256", apiKey).update(`${t}.${body}`).digest("hex");
+    const signatureHeader = `t=${t},v1=${v1}`;
+    const spinner = ora2(`Sending ${event} to ${opts.url}...`).start();
+    try {
+      const response = await fetch(opts.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-vonpay-signature": signatureHeader,
+          "User-Agent": "VonPay-Webhook/1.0 (CLI trigger)"
+        },
+        body,
+        signal: AbortSignal.timeout(1e4),
+        // Never follow a redirect: a 307/308 would re-send this signed body
+        // to wherever it points, including a host --url never allowed.
+        redirect: "manual"
+      });
+      spinner.stop();
+      if (isRedirect(response)) {
+        console.error(
+          chalk12.red(
+            `\u2717 ${event} not delivered: ${safeDisplay(String(opts.url))} answered with a redirect (HTTP ${response.status}). It was not followed, and the signed event was not sent anywhere else. Point --url at the endpoint itself.`
+          )
+        );
+        process.exit(1);
+      }
+      if (response.ok) {
+        console.log(chalk12.green(`\u2713 ${event} delivered \u2192 ${response.status}`));
+      } else {
+        console.log(
+          chalk12.yellow(
+            `\u26A0 ${event} delivered but got ${response.status} response`
+          )
+        );
+      }
+      console.log(chalk12.dim(`  Event:   ${payload.id} (${payload.type})`));
+      console.log(
+        chalk12.dim(
+          `  Amount:  ${payload.data.amount} ${payload.data.currency}`
+        )
+      );
+      console.log(
+        chalk12.dim(
+          `
+  Verify with: vonpay.webhooks.constructEvent(rawBody, signatureHeader, secret)`
+        )
+      );
+      console.log(
+        chalk12.dim(
+          `  (local dev: 'secret' is your API key here \u2014 production webhooks are signed with your endpoint's whsec_\u2026 secret, NOT your API key)`
+        )
+      );
+    } catch (err) {
+      spinner.stop();
+      if (err instanceof Error && err.name === "TimeoutError") {
+        console.error(chalk12.red(`Timeout: ${opts.url} did not respond within 10s`));
+      } else {
+        console.error(
+          chalk12.red(
+            `Failed to deliver: ${err instanceof Error ? err.message : err}`
+          )
+        );
+      }
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/listen.ts
+import { Command as Command10 } from "commander";
+import { VonPayCheckout as VonPayCheckout2 } from "@vonpay/checkout-node";
+
+// ../sse-parser/dist/index.js
+var SseParser = class {
+  on;
+  /** The stream's last event id (send as `Last-Event-ID` on a reconnect when not empty). */
+  lastId = "";
+  /** Reconnection time in ms from a `retry:` field, or -1 if none was sent. */
+  retry = -1;
+  rest = "";
+  skipLF = false;
+  data = "";
+  type = "";
+  idBuf = "";
+  max;
+  maxId;
+  constructor(on, options = {}) {
+    this.on = on;
+    this.max = options.maxPending ?? 65536;
+    this.maxId = options.maxIdLength ?? Infinity;
+  }
+  /**
+   * Start a new stream (a reconnect): pending line, data and type buffers
+   * cleared; the source's last event id and reconnection time survive.
+   *
+   * ⚠️ One deliberate departure from the letter of § 9.2.6: the spec
+   * initialises a new stream's last-event-id buffer to "", so an id-less
+   * event dispatched first on a reconnect (a server's ceiling frame has no
+   * `id:`) would clear the source's last id and the NEXT reconnect would lose
+   * its `Last-Event-ID`. We seed the buffer with the last id instead; an
+   * explicit empty `id:` still clears it.
+   */
+  reset() {
+    this.rest = this.data = this.type = "";
+    this.idBuf = this.lastId;
+    this.skipLF = false;
+  }
+  feed(chunk) {
+    if (this.skipLF && chunk) {
+      if (chunk[0] === "\n")
+        chunk = chunk.slice(1);
+      this.skipLF = false;
+    }
+    const s = this.rest + chunk;
+    const re = /\r\n|\r|\n/g;
+    re.lastIndex = this.rest.length;
+    let start = 0;
+    let m;
+    while (m = re.exec(s)) {
+      if (re.lastIndex === s.length && m[0] === "\r")
+        this.skipLF = true;
+      this.line(s.slice(start, m.index));
+      start = re.lastIndex;
+    }
+    this.rest = s.slice(start);
+    if (this.rest.length + this.data.length > this.max) {
+      throw new Error("event stream frame too large");
+    }
+  }
+  line(l) {
+    if (!l) {
+      this.lastId = this.idBuf;
+      const d = this.data;
+      const t = this.type;
+      this.data = this.type = "";
+      if (d)
+        this.on(t || "message", d.slice(0, -1));
+      return;
+    }
+    if (l[0] === ":")
+      return;
+    const c = l.indexOf(":");
+    const f = c < 0 ? l : l.slice(0, c);
+    let v = c < 0 ? "" : l.slice(c + 1);
+    if (v[0] === " ")
+      v = v.slice(1);
+    if (f === "data")
+      this.data += v + "\n";
+    else if (f === "event")
+      this.type = v;
+    else if (f === "id") {
+      if (!v.includes("\0") && v.length <= this.maxId)
+        this.idBuf = v;
+    } else if (f === "retry" && /^\d+$/.test(v))
+      this.retry = +v;
+  }
+};
+
+// src/utils/sse-consumer.ts
+var MAX_PENDING_CHARS = 1048576;
+var MAX_EVENT_ID_LENGTH = 256;
+function resumeId(lastId) {
+  return /^[\x20-\x7e]+$/.test(lastId) ? lastId : void 0;
+}
+async function* consumeSse(opts) {
+  const initialBackoffMs = opts.initialBackoffMs ?? 1e3;
+  const maxBackoffMs = opts.maxBackoffMs ?? 3e4;
+  const pending = [];
+  const parser = new SseParser(
+    (type, data) => pending.push({ type, data, lastEventId: parser.lastId || void 0 }),
+    { maxPending: MAX_PENDING_CHARS, maxIdLength: MAX_EVENT_ID_LENGTH }
+  );
+  let backoffMs = initialBackoffMs;
+  const onLifecycle = opts.onLifecycle ?? noop;
+  while (!opts.signal.aborted) {
+    const headers = {
+      Accept: "text/event-stream",
+      "Cache-Control": "no-cache",
+      ...opts.headers
+    };
+    const lastEventId = resumeId(parser.lastId);
+    if (lastEventId !== void 0) {
+      headers["Last-Event-ID"] = lastEventId;
+    }
+    onLifecycle({ kind: "connecting", lastEventId });
+    let response;
+    try {
+      response = await fetch(opts.url, {
+        method: "GET",
+        headers,
+        signal: opts.signal
+      });
+    } catch (err) {
+      if (opts.signal.aborted) return;
+      const reason = err instanceof Error ? err.message : String(err);
+      onLifecycle({ kind: "disconnected", reason, willRetryInMs: backoffMs });
+      await sleep(backoffMs, opts.signal);
+      backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+      continue;
+    }
+    if (response.status === 401 || response.status === 403) {
+      const body = await safeReadText(response);
+      onLifecycle({ kind: "auth_failed", status: response.status, body });
+      throw new SseAuthError(response.status, body);
+    }
+    if (!response.ok) {
+      const body = await safeReadText(response);
+      onLifecycle({
+        kind: "disconnected",
+        reason: `HTTP ${response.status}: ${truncate3(body, 200)}`,
+        willRetryInMs: backoffMs
+      });
+      await sleep(backoffMs, opts.signal);
+      backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+      continue;
+    }
+    if (!response.body) {
+      onLifecycle({
+        kind: "disconnected",
+        reason: "response has no body",
+        willRetryInMs: backoffMs
+      });
+      await sleep(backoffMs, opts.signal);
+      backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+      continue;
+    }
+    onLifecycle({ kind: "connected" });
+    backoffMs = initialBackoffMs;
+    parser.reset();
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let serverInitiatedReconnect = false;
+    try {
+      while (!opts.signal.aborted) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        let feedError;
+        try {
+          parser.feed(decoder.decode(value, { stream: true }));
+        } catch (err) {
+          feedError = err;
+        }
+        for (const ev of pending.splice(0)) {
+          if (ev.type === "timeout") {
+            yield ev;
+            serverInitiatedReconnect = true;
+          } else {
+            yield ev;
+          }
+        }
+        if (feedError !== void 0) throw feedError;
+      }
+    } catch (err) {
+      if (opts.signal.aborted) return;
+      const reason = err instanceof Error ? err.message : String(err);
+      onLifecycle({ kind: "disconnected", reason, willRetryInMs: backoffMs });
+    } finally {
+      try {
+        await reader.cancel();
+      } catch {
+      }
+    }
+    if (opts.signal.aborted) return;
+    if (serverInitiatedReconnect) {
+      continue;
+    }
+    onLifecycle({
+      kind: "disconnected",
+      reason: "stream ended",
+      willRetryInMs: backoffMs
+    });
+    await sleep(backoffMs, opts.signal);
+    backoffMs = Math.min(backoffMs * 2, maxBackoffMs);
+  }
+}
+var SseAuthError = class extends Error {
+  constructor(status, body) {
+    super(
+      `SSE auth failed: HTTP ${status}${body ? ` \u2014 ${truncate3(body, 200)}` : ""}`
+    );
+    this.status = status;
+    this.body = body;
+    this.name = "SseAuthError";
+  }
+  status;
+  body;
+};
+function sleep(ms, signal) {
+  return new Promise((resolve2) => {
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve2();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve2();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function safeReadText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+}
+function truncate3(s, n) {
+  return s.length <= n ? s : `${s.slice(0, n - 3)}...`;
+}
+function noop() {
+}
+
+// src/utils/listen-output.ts
+import chalk13 from "chalk";
+function formatAttemptHuman(payload, forward) {
+  const ts = formatTimestamp(payload.timestamp);
+  const eventType = chalk13.cyan(payload.event_type.padEnd(24));
+  const eventId = chalk13.gray(payload.event_id.padEnd(28));
+  const attempt = chalk13.gray(`attempt ${payload.attempt}`);
+  const arrow = chalk13.gray("\u2192");
+  const upstream = formatUpstream(payload);
+  const latency = chalk13.gray(`${payload.latency_ms}ms`);
+  const liveBadge = payload.livemode ? chalk13.red(" [LIVE]") : "";
+  let line = `[${ts}] ${eventType} ${eventId} ${attempt}  ${arrow} ${upstream}  ${latency}${liveBadge}`;
+  if (forward && forward.attempted) {
+    const fwdArrow = chalk13.gray("\u2192 local");
+    if (forward.error) {
+      line += `  ${fwdArrow} ${chalk13.red(forward.error)}`;
+    } else if (forward.status !== null) {
+      const fwdStatus = formatStatus(forward.status);
+      const fwdLatency = chalk13.gray(`${forward.latencyMs}ms`);
+      line += `  ${fwdArrow} ${fwdStatus} ${fwdLatency}`;
+    }
+  }
+  return line;
+}
+function formatAttemptJson(payload, forward) {
+  const body = {
+    type: "webhook.attempt",
+    event_id: payload.event_id,
+    event_type: payload.event_type,
+    subscription_id: payload.subscription_id,
+    attempt: payload.attempt,
+    succeeded: payload.succeeded,
+    response_status: payload.response_status,
+    latency_ms: payload.latency_ms,
+    timestamp: payload.timestamp,
+    livemode: payload.livemode
+  };
+  if (forward && forward.attempted) {
+    body.forward = {
+      status: forward.status,
+      latency_ms: forward.latencyMs,
+      error: forward.error
+    };
+  }
+  return JSON.stringify(body);
+}
+function formatLifecycleHuman(message, kind) {
+  const tag = kind === "info" ? chalk13.cyan("[vonpay]") : kind === "warn" ? chalk13.yellow("[vonpay]") : chalk13.red("[vonpay]");
+  return `${tag} ${message}`;
+}
+function formatLifecycleJson(kind, extra = {}) {
+  return JSON.stringify({ type: `cli.${kind}`, ...extra, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+}
+function formatStatus(status) {
+  if (status >= 200 && status < 300) return chalk13.green(String(status));
+  if (status >= 400 && status < 500) return chalk13.yellow(String(status));
+  if (status >= 500) return chalk13.red(String(status));
+  return chalk13.gray(String(status));
+}
+function formatUpstream(payload) {
+  if (payload.response_status === null) {
+    return chalk13.red("timeout");
+  }
+  return formatStatus(payload.response_status);
+}
+function formatTimestamp(iso) {
+  const date = new Date(iso);
+  if (isNaN(date.getTime())) return iso.slice(0, 19);
+  const h = String(date.getHours()).padStart(2, "0");
+  const m = String(date.getMinutes()).padStart(2, "0");
+  const s = String(date.getSeconds()).padStart(2, "0");
+  return `${h}:${m}:${s}`;
+}
+
+// src/commands/listen.ts
+function listenCommand() {
+  return new Command10("listen").description(
+    "Watch webhook delivery attempts in real time. Optionally re-forward each event to a local URL for development."
+  ).option(
+    "--forward-to <url>",
+    "Local URL to receive a shadow copy of each delivered event (loopback only by default)"
+  ).option(
+    "--forward-to-tunnel",
+    "Allow non-loopback --forward-to URLs (for ngrok / Cloudflare Tunnel workflows)"
+  ).option(
+    "--events <type>",
+    "Only stream attempts for the given event type. Repeat the flag for multiple types.",
+    (value, prev) => prev ? [...prev, value] : [value]
+  ).option("--json", "Emit one JSON object per line on stdout instead of the colored transcript").option("--api-key <key>", "Override the API key from env / config").addOption(retiredConfirmLiveOption()).action(async (opts) => {
+    const apiKey = opts.apiKey ?? requireApiKey();
+    if (opts.apiKey !== void 0) warnLiveSecretFlag(opts.apiKey, "--api-key");
+    const refuse = (message) => {
+      if (jsonErrorsEnabled()) exitWithCliError(message, message);
+      process.stderr.write(formatLifecycleHuman(message, "error") + "\n");
+      return process.exit(1);
+    };
+    if (secretKeyMode(apiKey) === null) {
+      refuse(
+        "Listen requires a secret key (vp_sk_*). Publishable keys are rejected by the server."
+      );
+    }
+    let forwardUrl;
+    let forwardWarning;
+    if (opts.forwardTo) {
+      const verdict = validateForwardTo(opts.forwardTo, {
+        allowTunnel: opts.forwardToTunnel === true
+      });
+      if (!verdict.ok) refuse(verdict.reason);
+      forwardUrl = verdict.url;
+      forwardWarning = verdict.warning;
+    }
+    const configuredBaseUrl = getBaseUrl();
+    const destinationProblem = keyDestinationProblem(apiKey, configuredBaseUrl);
+    if (destinationProblem) refuse(destinationProblem);
+    const baseUrl = (configuredBaseUrl ?? "https://checkout.vonpay.com").replace(
+      /\/+$/,
+      ""
+    );
+    await confirmLiveAction(
+      apiKey,
+      {
+        action: "stream live webhook delivery attempts",
+        details: [
+          ["Stream from", baseUrl],
+          ...forwardUrl ? [["Forward to", forwardUrl.toString()]] : []
+        ],
+        consequence: forwardUrl ? "Live payment events, with buyer and order details, will be shown here, and each one is signed with your LIVE key and sent to the forward URL." : "Live payment events, with buyer and order details, will be shown here."
+      },
+      opts
+    );
+    const sseUrl = new URL(`${baseUrl}/v1/webhook_listen`);
+    if (opts.events && opts.events.length > 0) {
+      sseUrl.searchParams.set("event_types", opts.events.join(","));
+    }
+    const sdk = forwardUrl ? new VonPayCheckout2({
+      apiKey,
+      baseUrl,
+      allowCustomBaseUrl: allowCustomBaseUrl(),
+      appInfo: CLI_APP_INFO,
+      errorReporter: SILENT_ERROR_REPORTER
+    }) : null;
+    const controller = new AbortController();
+    let eventCount = 0;
+    const startedAt = Date.now();
+    const mode = opts.json === true ? "json" : "human";
+    const onSignal = (sig) => {
+      const elapsedSec = Math.round((Date.now() - startedAt) / 1e3);
+      if (mode === "human") {
+        process.stderr.write(
+          "\n" + formatLifecycleHuman(
+            `Shutting down (${sig}). Received ${eventCount} event${eventCount === 1 ? "" : "s"} in ${elapsedSec}s.`,
+            "info"
+          ) + "\n"
+        );
+      } else {
+        process.stderr.write(
+          formatLifecycleJson("shutdown", {
+            signal: sig,
+            event_count: eventCount,
+            elapsed_seconds: elapsedSec
+          }) + "\n"
+        );
+      }
+      controller.abort();
+    };
+    process.once("SIGINT", () => onSignal("SIGINT"));
+    process.once("SIGTERM", () => onSignal("SIGTERM"));
+    const onLifecycle = (event) => {
+      if (mode === "json") {
+        process.stderr.write(
+          formatLifecycleJson(event.kind, lifecyclePayload(event)) + "\n"
+        );
+        return;
+      }
+      process.stderr.write(formatLifecycleHuman(lifecycleHumanMessage(event), lifecycleSeverity(event.kind)) + "\n");
+    };
+    if (forwardWarning) {
+      process.stderr.write(
+        mode === "human" ? formatLifecycleHuman(forwardWarning, "warn") + "\n" : formatLifecycleJson("warning", { message: forwardWarning }) + "\n"
+      );
+    }
+    if (mode === "human") {
+      const filterNote = opts.events?.length ? ` (filtered to ${opts.events.join(", ")})` : "";
+      const fwdNote = forwardUrl ? ` \u2192 forwarding to ${forwardUrl.toString()}` : "";
+      process.stderr.write(
+        formatLifecycleHuman(`Ready! Listening for webhook delivery attempts${filterNote}${fwdNote}.`, "info") + "\n"
+      );
+    } else {
+      process.stderr.write(
+        formatLifecycleJson("ready", {
+          base_url: baseUrl,
+          filter: opts.events ?? null,
+          forward_to: forwardUrl?.toString() ?? null
+        }) + "\n"
+      );
+    }
+    try {
+      for await (const sseEvent of consumeSse({
+        url: sseUrl.toString(),
+        headers: { Authorization: `Bearer ${apiKey}` },
+        signal: controller.signal,
+        onLifecycle
+      })) {
+        if (sseEvent.type === "timeout") {
+          onLifecycle({
+            kind: "disconnected",
+            reason: "server-ceiling (1h cap; auto-reconnecting)",
+            willRetryInMs: 0
+          });
+          continue;
+        }
+        if (sseEvent.type !== "webhook.attempt") {
+          continue;
+        }
+        let payload;
+        try {
+          payload = JSON.parse(sseEvent.data);
+        } catch {
+          continue;
+        }
+        eventCount += 1;
+        let forwardOutcome = null;
+        if (forwardUrl && sdk) {
+          try {
+            const eventRecord = await sdk.webhookEvents.retrieve(payload.event_id);
+            forwardOutcome = await forwardPayload(eventRecord.payload, {
+              url: forwardUrl,
+              signingSecret: apiKey,
+              signal: controller.signal
+            });
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            forwardOutcome = {
+              attempted: true,
+              status: null,
+              latencyMs: null,
+              error: `fetch-event failed: ${message.slice(0, 200)}`
+            };
+          }
+        }
+        if (mode === "human") {
+          process.stdout.write(formatAttemptHuman(payload, forwardOutcome) + "\n");
+        } else {
+          process.stdout.write(formatAttemptJson(payload, forwardOutcome) + "\n");
+        }
+      }
+    } catch (err) {
+      if (err instanceof SseAuthError) {
+        if (mode === "human") {
+          process.stderr.write(
+            formatLifecycleHuman(
+              `Authentication failed (HTTP ${err.status}). Run \`vonpay checkout login\` with a valid secret key.`,
+              "error"
+            ) + "\n"
+          );
+        } else {
+          process.stderr.write(
+            formatLifecycleJson("auth_failed", { status: err.status }) + "\n"
+          );
+        }
+        process.exit(1);
+      }
+      if (jsonErrorsEnabled()) handleError(err);
+      throw err;
+    }
+  });
+}
+function lifecyclePayload(event) {
+  switch (event.kind) {
+    case "connecting":
+      return { last_event_id: event.lastEventId ?? null };
+    case "connected":
+      return {};
+    case "disconnected":
+      return { reason: event.reason, will_retry_in_ms: event.willRetryInMs };
+    case "auth_failed":
+      return { status: event.status };
+    case "fatal":
+      return { error: event.error.message };
+  }
+}
+function lifecycleHumanMessage(event) {
+  switch (event.kind) {
+    case "connecting":
+      return event.lastEventId ? `Reconnecting (resume from ${event.lastEventId})` : "Connecting...";
+    case "connected":
+      return "Connected.";
+    case "disconnected":
+      return `Disconnected: ${event.reason}. Retrying in ${event.willRetryInMs}ms.`;
+    case "auth_failed":
+      return `Authentication failed (HTTP ${event.status}).`;
+    case "fatal":
+      return `Fatal: ${event.error.message}`;
+  }
+}
+function lifecycleSeverity(kind) {
+  switch (kind) {
+    case "connecting":
+    case "connected":
+      return "info";
+    case "disconnected":
+      return "warn";
+    case "auth_failed":
+    case "fatal":
+      return "error";
+  }
+}
+
+// src/commands/health.ts
+import { Command as Command11 } from "commander";
+import chalk14 from "chalk";
+import { VonPayError as VonPayError2 } from "@vonpay/checkout-node";
+function healthCommand() {
+  return new Command11("health").description("Check checkout API health").option("--json", "Output raw JSON").action(async (opts) => {
+    const client = makeCheckoutClient();
+    const spinner = startSpinner("Checking API health...");
+    try {
+      const health = await client.health();
+      spinner.stop();
+      if (opts.json) {
+        console.log(JSON.stringify(health, null, 2));
+      } else {
+        const statusColor = health.status === "ok" ? chalk14.green : health.status === "degraded" ? chalk14.yellow : chalk14.red;
+        console.log(`  Status:   ${statusColor(health.status)}`);
+        console.log(`  Latency:  ${health.latencyMs}ms`);
+        if (health.version) {
+          console.log(`  Version:  ${health.version}`);
+        }
+      }
+    } catch (err) {
+      spinner.stop();
+      if (jsonErrorsEnabled()) handleError(err);
+      if (err instanceof VonPayError2) {
+        console.error(chalk14.red(`API error: ${scrubSecrets(err.message)}`));
+        console.error(chalk14.dim(`  Code: ${err.code}`));
+      } else {
+        console.error(
+          chalk14.red(
+            `Cannot reach API: ${scrubSecrets(err instanceof Error ? err.message : String(err))}`
+          )
+        );
+      }
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/doctor.ts
+import { Command as Command12 } from "commander";
+import chalk15 from "chalk";
+import ora3 from "ora";
+import { homedir as homedir2 } from "os";
+import { existsSync as existsSync3 } from "fs";
+import {
+  VonPayCheckout as VonPayCheckout3,
+  VonPayError as VonPayError3,
+  helpFor
+} from "@vonpay/checkout-node";
+var RELEVANT_ENV_VARS = [
+  "VON_PAY_SECRET_KEY",
+  "VON_PAY_PUBLISHABLE_KEY",
+  "VON_PAY_SESSION_SECRET",
+  "VONPAY_BASE_URL",
+  "VONPAY_QUIET",
+  "NEXT_PUBLIC_BASE_URL"
+];
+function redactHome(p) {
+  const home = homedir2();
+  if (home && p.startsWith(home)) {
+    return "~" + p.slice(home.length);
+  }
+  return p;
+}
+function maskPrefix(key) {
+  if (!key) return void 0;
+  const m = key.match(/^(vp_[ps]k_(test|live)_)([A-Za-z0-9_-]{0,4})/);
+  if (!m) return void 0;
+  return `${m[1]}${m[3]}\u2026`;
+}
+function keyMode(key) {
+  if (!key) return void 0;
+  return secretKeyMode(key) ?? "not_a_secret_key";
+}
+async function gather() {
+  const config = loadConfig();
+  const apiKey = process.env.VON_PAY_SECRET_KEY || config.checkout?.apiKey;
+  const baseUrl = process.env.VONPAY_BASE_URL ?? "https://checkout.vonpay.com";
+  const envVarsPresent = RELEVANT_ENV_VARS.filter(
+    (n) => process.env[n] && process.env[n] !== ""
+  );
+  const report = {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    cli: { version: CLI_VERSION },
+    runtime: {
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      cwd: redactHome(process.cwd())
+    },
+    envVarsPresent,
+    configFile: {
+      path: `${process.env.HOME ?? process.env.USERPROFILE ?? "~"}/.vonpay/config.json`,
+      present: existsSync3(
+        `${process.env.HOME ?? process.env.USERPROFILE ?? ""}/.vonpay/config.json`
+      ),
+      keyType: config.checkout?.apiKey ? keyMode(config.checkout?.apiKey) : void 0
+    },
+    apiKeyPrefix: maskPrefix(apiKey),
+    apiKeyMode: keyMode(apiKey),
+    health: { baseUrl, reachable: false },
+    hints: []
+  };
+  if (!apiKey) {
+    report.hints.push(
+      "No API key found. Set VON_PAY_SECRET_KEY in env, or run `vonpay checkout login` to save one. Without a key the health probe still runs but sessions.validate is skipped."
+    );
+  }
+  const shapeProblem = keyDestinationProblem("", process.env.VONPAY_BASE_URL);
+  if (shapeProblem) {
+    report.health.baseUrl = "(not shown: the base URL was refused)";
+    report.health.error = shapeProblem;
+    report.hints.push(`${shapeProblem} No probe was run.`);
+  }
+  const start = Date.now();
+  if (!shapeProblem) try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 1e4);
+    const res = await fetch(`${baseUrl}/api/health`, {
+      method: "GET",
+      headers: {
+        Accept: "application/json",
+        "User-Agent": `vonpay-cli/${CLI_VERSION} (doctor)`
+      },
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    report.health.latencyMs = Date.now() - start;
+    if (res.ok) {
+      const body = await res.json().catch(() => ({}));
+      report.health.reachable = true;
+      report.health.status = body.status ?? "ok";
+    } else {
+      report.health.reachable = false;
+      report.health.status = `http_${res.status}`;
+      report.health.error = `HTTP ${res.status}`;
+      report.hints.push(
+        `Health endpoint returned HTTP ${res.status}. Either the API is having an incident or your baseUrl override is wrong.`
+      );
+    }
+  } catch (err) {
+    report.health.error = err instanceof Error ? err.message : String(err);
+    report.health.latencyMs = Date.now() - start;
+    report.hints.push(
+      "Health probe could not reach the API. Check network / DNS / firewall \u2014 vonpay-checkout requires outbound HTTPS to checkout.vonpay.com."
+    );
+  }
+  let mayProbe = Boolean(apiKey) && !shapeProblem;
+  if (apiKey && report.apiKeyMode === "not_a_secret_key") {
+    mayProbe = false;
+    report.hints.push(`${NOT_A_SECRET_KEY_MESSAGE} The sessions.validate probe was not run.`);
+  }
+  const destinationProblem = apiKey && mayProbe ? keyDestinationProblem(apiKey, process.env.VONPAY_BASE_URL) : null;
+  if (destinationProblem) {
+    mayProbe = false;
+    report.hints.push(`${destinationProblem} The sessions.validate probe was not run.`);
+  }
+  if (config.checkout?.apiKey && report.configFile.keyType === "live") {
+    report.hints.push(
+      "A LIVE key is saved in plaintext in ~/.vonpay/config.json. Live keys are no longer stored: run `vonpay checkout logout` to delete it, and supply it through VON_PAY_SECRET_KEY for the session instead."
+    );
+  }
+  if (apiKey && mayProbe && report.health.reachable) {
+    try {
+      const probeClient = new VonPayCheckout3({
+        apiKey,
+        baseUrl,
+        allowCustomBaseUrl: allowCustomBaseUrl(),
+        timeout: 1e4,
+        maxRetries: 0,
+        errorReporter: () => {
+        },
+        // suppress default warn during the probe
+        appInfo: CLI_APP_INFO
+      });
+      const result = await probeClient.sessions.validate({
+        amount: 1499,
+        currency: "USD"
+      });
+      report.validateProbe = {
+        ok: result.valid,
+        warnings: result.warnings
+      };
+      if (!result.valid) {
+        report.hints.push(
+          `sessions.validate returned valid=false with warnings: ${(result.warnings ?? []).join("; ")}.`
+        );
+      } else if (result.warnings && result.warnings.length > 0) {
+        report.hints.push(
+          `sessions.validate succeeded but with warnings: ${result.warnings.join("; ")}.`
+        );
+      }
+    } catch (err) {
+      if (err instanceof VonPayError3) {
+        const help = helpFor(err.code);
+        report.validateProbe = {
+          ok: false,
+          error: {
+            code: err.code,
+            status: err.status,
+            nextAction: help.nextAction,
+            llmHint: help.llmHint
+          }
+        };
+        report.hints.push(
+          `sessions.validate failed: ${err.code}. ${help.llmHint}`
+        );
+      } else {
+        report.validateProbe = {
+          ok: false,
+          error: {
+            code: "internal_error",
+            status: 0,
+            nextAction: "contact_support",
+            llmHint: err instanceof Error ? err.message : String(err)
+          }
+        };
+      }
+    }
+  }
+  return report;
+}
+function renderHuman(r) {
+  const lines = [];
+  lines.push(chalk15.bold.blue("vonpay doctor \u2014 diagnostic report"));
+  lines.push(chalk15.dim(`generated ${r.generatedAt}`));
+  lines.push("");
+  lines.push(chalk15.bold("Runtime"));
+  lines.push(`  CLI:       ${r.cli.version}`);
+  lines.push(`  Node:      ${r.runtime.node}`);
+  lines.push(`  Platform:  ${r.runtime.platform} (${r.runtime.arch})`);
+  lines.push(`  CWD:       ${r.runtime.cwd}`);
+  lines.push("");
+  lines.push(chalk15.bold("API key"));
+  if (r.apiKeyPrefix) {
+    lines.push(`  Prefix:    ${r.apiKeyPrefix}`);
+    lines.push(`  Mode:      ${r.apiKeyMode}`);
+  } else {
+    lines.push(chalk15.dim("  (no key found in env or ~/.vonpay/config.json)"));
+  }
+  lines.push("");
+  lines.push(chalk15.bold("Env vars present (names only)"));
+  if (r.envVarsPresent.length === 0) {
+    lines.push(chalk15.dim("  (none of the expected vonpay env vars are set)"));
+  } else {
+    for (const n of r.envVarsPresent) lines.push(`  \u2713 ${n}`);
+  }
+  lines.push("");
+  lines.push(chalk15.bold("Health probe"));
+  if (r.health.reachable) {
+    const statusColor = r.health.status === "ok" ? chalk15.green : r.health.status === "degraded" ? chalk15.yellow : chalk15.red;
+    lines.push(`  Reachable: ${chalk15.green("yes")}`);
+    lines.push(`  Status:    ${statusColor(r.health.status ?? "?")}`);
+    lines.push(`  Latency:   ${r.health.latencyMs}ms`);
+  } else {
+    lines.push(`  Reachable: ${chalk15.red("no")}`);
+    lines.push(`  Error:     ${r.health.error}`);
+  }
+  lines.push("");
+  if (r.validateProbe) {
+    lines.push(chalk15.bold("sessions.validate probe ($14.99 USD dry-run)"));
+    if (r.validateProbe.ok) {
+      lines.push(`  Result:    ${chalk15.green("valid")}`);
+    } else {
+      lines.push(`  Result:    ${chalk15.red("invalid")}`);
+      if (r.validateProbe.error) {
+        lines.push(`  Code:      ${r.validateProbe.error.code}`);
+        lines.push(`  Action:    ${r.validateProbe.error.nextAction}`);
+      }
+    }
+    if (r.validateProbe.warnings && r.validateProbe.warnings.length > 0) {
+      lines.push(`  Warnings:`);
+      for (const w of r.validateProbe.warnings) lines.push(`    - ${w}`);
+    }
+    lines.push("");
+  }
+  if (r.hints.length > 0) {
+    lines.push(chalk15.bold("Hints"));
+    for (const h of r.hints) lines.push(`  \u2022 ${h}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderForLlm(r) {
+  const out = [];
+  out.push("# vonpay doctor \u2014 diagnostic report (LLM-readable)");
+  out.push("");
+  out.push("This is a structured environment + live-API diagnostic from the");
+  out.push("Von Payments CLI. An LLM agent reading this should determine the");
+  out.push("most-likely root cause of the integrator's problem and produce");
+  out.push("specific next-step instructions.");
+  out.push("");
+  out.push(`generated_at: ${r.generatedAt}`);
+  out.push("");
+  out.push("## Runtime");
+  out.push(`- vonpay-cli: ${r.cli.version}`);
+  out.push(`- node: ${r.runtime.node}`);
+  out.push(`- platform: ${r.runtime.platform} (${r.runtime.arch})`);
+  out.push("");
+  out.push("## API key");
+  if (r.apiKeyPrefix) {
+    out.push(`- prefix: \`${r.apiKeyPrefix}\` (first 4 chars of payload only \u2014 full key never printed)`);
+    out.push(`- mode: ${r.apiKeyMode}`);
+  } else {
+    out.push("- no key found in env or `~/.vonpay/config.json`");
+    out.push("- LLM-action: ask the human to set `VON_PAY_SECRET_KEY` or run `vonpay checkout login`");
+  }
+  out.push("");
+  out.push("## Env vars present (names only \u2014 values never printed)");
+  if (r.envVarsPresent.length === 0) {
+    out.push("- (none of the expected vonpay env vars are set)");
+  } else {
+    for (const n of r.envVarsPresent) out.push(`- \`${n}\``);
+  }
+  out.push("");
+  out.push("## Health probe");
+  out.push(`- base_url: ${r.health.baseUrl}`);
+  out.push(`- reachable: ${r.health.reachable}`);
+  if (r.health.latencyMs !== void 0) {
+    out.push(`- latency_ms: ${r.health.latencyMs}`);
+  }
+  if (r.health.status) out.push(`- status: ${r.health.status}`);
+  if (r.health.error) out.push(`- error: ${r.health.error}`);
+  out.push("");
+  if (r.validateProbe) {
+    out.push("## sessions.validate probe ($14.99 USD dry-run)");
+    out.push(`- ok: ${r.validateProbe.ok}`);
+    if (r.validateProbe.warnings && r.validateProbe.warnings.length > 0) {
+      out.push("- warnings:");
+      for (const w of r.validateProbe.warnings) out.push(`  - ${w}`);
+    }
+    if (r.validateProbe.error) {
+      out.push("- error:");
+      out.push(`  - code: \`${r.validateProbe.error.code}\``);
+      out.push(`  - status: ${r.validateProbe.error.status}`);
+      out.push(`  - next_action: \`${r.validateProbe.error.nextAction}\``);
+      out.push(`  - llm_hint: ${r.validateProbe.error.llmHint}`);
+    }
+    out.push("");
+  }
+  if (r.hints.length > 0) {
+    out.push("## Hints (in priority order)");
+    for (const h of r.hints) out.push(`- ${h}`);
+    out.push("");
+  }
+  out.push("## Suggested LLM next steps");
+  out.push("1. Determine which of the three categories applies: missing-config / unreachable-api / failing-validation.");
+  out.push("2. For each hint above, propose ONE specific code or env change to the human.");
+  out.push("3. Suggest the human re-run `vonpay checkout doctor --for-llm` after applying changes and paste the new output.");
+  out.push("4. If the report shows everything healthy but the integrator still has a problem, the issue is likely in their own code (not vonpay) \u2014 ask them to share the failing call site.");
+  out.push("");
+  return out.join("\n");
+}
+function doctorCommand() {
+  return new Command12("doctor").description(
+    "Diagnose your Von Payments environment \u2014 runtime, env vars, live API probe; outputs human / JSON / LLM-readable formats"
+  ).option("--json", "Output JSON (machine-parseable)").option(
+    "--for-llm",
+    "Output LLM-friendly markdown (paste into Claude, ChatGPT, Cursor)"
+  ).action(async (opts) => {
+    const spinner = ora3({
+      text: "Running diagnostics...",
+      // suppress spinner output when emitting JSON / LLM markdown so the
+      // output remains pipeable
+      isSilent: opts.json || opts.forLlm
+    }).start();
+    const report = await gather();
+    spinner.stop();
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else if (opts.forLlm) {
+      console.log(renderForLlm(report));
+    } else {
+      console.log(renderHuman(report));
+    }
+  });
+}
+
+// src/commands/checkout.ts
+function registerCheckout(program2) {
+  const checkout = program2.command("checkout").description("Checkout integration tools");
+  checkout.hook("preAction", (_checkout, actionCommand) => {
+    setJsonErrors(actionCommand.opts().json === true);
+  });
+  checkout.addCommand(loginCommand());
+  checkout.addCommand(logoutCommand());
+  checkout.addCommand(initCommand());
+  checkout.addCommand(sessionsCommand());
+  checkout.addCommand(paymentIntentsCommand());
+  checkout.addCommand(refundsCommand());
+  checkout.addCommand(tokensCommand());
+  checkout.addCommand(capabilitiesCommand());
+  checkout.addCommand(triggerCommand());
+  checkout.addCommand(listenCommand());
+  checkout.addCommand(healthCommand());
+  checkout.addCommand(doctorCommand());
+}
+
+// src/index.ts
+var __dirname = dirname2(fileURLToPath2(import.meta.url));
+var pkg2 = JSON.parse(
+  readFileSync4(join3(__dirname, "..", "package.json"), "utf-8")
+);
+var program = new Command13();
+program.name("vonpay").description("Von Payments developer tools").version(pkg2.version);
 registerCheckout(program);
 program.parse();
-//# sourceMappingURL=index.js.map