@agenzo/token-cli 0.4.0 → 0.5.0

package/dist/index.js

@@ -18,6 +18,9 @@ var CODE_NUM = {
   AUTH_INVITE_CODE_INVALID: 1004,
   KEY_INVALID: 1101,
   KEY_SCOPE_DENIED: 1102,
+  PAYMENT_METHOD_NOT_FOUND: 1401,
+  PAYMENT_METHOD_DISABLED: 1402,
+  INVALID_PAYMENT_METHOD: 1403,
   RESOURCE_NOT_FOUND: 2001,
   RESOURCE_CONFLICT: 2002,
   RESOURCE_STATE_INVALID: 2003,
@@ -38,6 +41,23 @@ var CODE_NUM = {
   QUOTE_EXPIRED: 4202,
   BOOKING_FAILED: 4203,
   CANCELLATION_NOT_ALLOWED: 4204,
+  PRICE_MISMATCH: 4205,
+  VEHICLE_CLASS_MISMATCH: 4206,
+  PAYMENT_METHOD_REQUIRED: 4207,
+  QUOTE_CACHE_UNAVAILABLE: 4208,
+  ARREARS_OUTSTANDING: 4209,
+  CONTACT_REQUIRED: 4210,
+  INVALID_PHONE: 4211,
+  SEAT_LIMIT_EXCEEDED: 4213,
+  RIDE_NOT_FOUND: 4212,
+  NO_AVAILABILITY: 4301,
+  PRICE_CHANGED: 4302,
+  NAME_FORMAT_INVALID: 4303,
+  HOTEL_ORDER_NOT_FOUND: 4304,
+  ALREADY_CANCELLED: 4305,
+  CHECKOUT_NOT_ALLOWED: 4306,
+  CHECKOUT_TASK_NOT_FOUND: 4307,
+  PAY_PER_CALL_NOT_AVAILABLE: 4308,
   RATE_LIMITED: 5001,
   UPSTREAM_ERROR: 5101,
   INTERNAL_ERROR: 5201,
@@ -55,23 +75,29 @@ function codeNum(code) {
   return CODE_NUM[code];
 }
 var CliError = class _CliError extends Error {
-  constructor(code, message, statusCode, requestId, upstream) {
+  constructor(code, message, statusCode, requestId, upstream, backendMessage) {
     super(message);
     this.code = code;
     this.statusCode = statusCode;
     this.requestId = requestId;
     this.upstream = upstream;
+    this.backendMessage = backendMessage;
     this.name = "CliError";
   }
   code;
   statusCode;
   requestId;
   upstream;
+  backendMessage;
   /**
    * Map a backend ApiError to a CLI-facing code (§8.5 transitional mapping).
-   * Backend numeric codes / HTTP status are translated to §8.4 string codes;
-   * the raw backend message is NOT passed through (§8.1 principle 4) — a
-   * stable, fixed message per code is used instead.
+   * Backend numeric codes / HTTP status are translated to §8.4 string codes.
+   * The top-level `message` is always the stable, catalog-owned text for the
+   * resolved code (§8.1 principle 4 — never let raw backend text become the
+   * primary/stable message). The backend's own message is NOT discarded,
+   * though: it is preserved on `backendMessage` and surfaced in the envelope
+   * as `backend_message` so the caller can see the real reason (e.g. which
+   * field failed validation) alongside the stable code/message.
    *
    * The optional `opts.auth` selects the auth semantics for the 401 mapping:
    * - `'bearer'` (default, admin-cli Bearer Token): 401 → `AUTH_SESSION_EXPIRED`.
@@ -95,7 +121,8 @@ var CliError = class _CliError extends Error {
         STABLE_MESSAGE[error.code] ?? "Request failed. Please check your input and retry.",
         error.statusCode,
         error.requestId,
-        error.upstream
+        error.upstream,
+        error.errorMessage
       );
     }
     const status = error.statusCode;
@@ -112,7 +139,8 @@ var CliError = class _CliError extends Error {
       STABLE_MESSAGE[code] ?? "Request failed. Please check your input and retry.",
       status,
       error.requestId,
-      error.upstream
+      error.upstream,
+      error.errorMessage
     );
   }
 };
@@ -167,6 +195,9 @@ var STABLE_MESSAGE = {
   AUTH_INVITE_CODE_INVALID: "The invitation code is invalid.",
   KEY_INVALID: "The API key is invalid or has been revoked. Please check your --api-key and retry.",
   KEY_SCOPE_DENIED: "This API key does not have the required scope for this command.",
+  PAYMENT_METHOD_NOT_FOUND: "Payment method not found.",
+  PAYMENT_METHOD_DISABLED: "This payment method has been disabled.",
+  INVALID_PAYMENT_METHOD: "The payment method is not available for this operation.",
   RESOURCE_NOT_FOUND: "The resource was not found or does not belong to the current organization.",
   RESOURCE_CONFLICT: "A resource with the same unique value already exists.",
   RESOURCE_STATE_INVALID: "The resource is in a state that does not permit this operation.",
@@ -188,18 +219,38 @@ var STABLE_MESSAGE = {
   VEHICLE_UNAVAILABLE: "No vehicle is available for the requested trip. Please try a different time or class.",
   QUOTE_EXPIRED: "The quote has expired. Please request a new quote and retry.",
   BOOKING_FAILED: "The booking could not be completed. Please retry.",
+  PRICE_MISMATCH: "The price does not match the quote. Re-quote and use the exact amount from the quote response.",
+  VEHICLE_CLASS_MISMATCH: "The vehicle class does not match the quote. Use the vehicle class from the quote response.",
+  PAYMENT_METHOD_REQUIRED: "Pay-per-call billing requires an active payment method. Please add a card first.",
+  QUOTE_CACHE_UNAVAILABLE: "Quote cache is temporarily unavailable. Please request a new quote and retry.",
+  ARREARS_OUTSTANDING: "You have outstanding arrears. Please settle your balance before booking a new ride.",
+  CONTACT_REQUIRED: "Passenger contact information is required. Please provide a passenger name and phone number.",
+  INVALID_PHONE: "The passenger phone number is not valid. Please provide a valid international number.",
+  SEAT_LIMIT_EXCEEDED: "The number of child/infant/toddler seats exceeds the vehicle capacity. Reduce seats or choose a larger vehicle.",
+  RIDE_NOT_FOUND: "The ride order was not found or does not belong to you.",
   CANCELLATION_NOT_ALLOWED: "This order cannot be cancelled in its current state.",
+  NO_AVAILABILITY: "No rooms available for the selected hotel and dates.",
+  PRICE_CHANGED: "The price changed since the quote. Re-quote and confirm.",
+  NAME_FORMAT_INVALID: "The guest name format is not accepted; use Latin letters.",
+  HOTEL_ORDER_NOT_FOUND: "Hotel order not found.",
+  ALREADY_CANCELLED: "This hotel order is already cancelled.",
+  CHECKOUT_NOT_ALLOWED: "A partial check-out is not allowed in the current state.",
+  CHECKOUT_TASK_NOT_FOUND: "Check-out application not found.",
+  PAY_PER_CALL_NOT_AVAILABLE: "Pay-per-call billing is not available; use monthly_settlement.",
   NOT_IMPLEMENTED: "This operation is not implemented yet."
 };
 function toErrorEnvelope(error) {
   if (error instanceof CliError) {
+    const stableMessage = error.message || "Unknown error";
+    const backendMessage = error.backendMessage && error.backendMessage !== stableMessage ? error.backendMessage : void 0;
     return {
       error: {
         code: error.code,
         code_num: codeNum(error.code),
-        message: error.message || "Unknown error",
+        message: stableMessage,
         ...error.requestId ? { request_id: error.requestId } : {},
-        ...error.upstream ? { upstream: error.upstream } : {}
+        ...error.upstream ? { upstream: error.upstream } : {},
+        ...backendMessage ? { backend_message: backendMessage } : {}
       }
     };
   }
@@ -262,13 +313,27 @@ function isBelow(current, minimum) {
 var ApiClient = class {
   baseUrl;
   timeout;
+  /**
+   * Correlation id for this CLI invocation. Generated once per `ApiClient`
+   * instance (i.e. once per command execution — each `apps/*` entrypoint
+   * constructs exactly one `ApiClient` per process run) and sent as
+   * `X-Request-Id` on every request this client makes. The backend's
+   * `RequestIdMiddleware` adopts a client-supplied `X-Request-Id` verbatim as
+   * both `trace_id` and `request_id` (only generating its own when the header
+   * is absent), so every HTTP call belonging to one CLI operation — including
+   * multi-step flows like `payment-methods add`'s create + poll + get — shares
+   * a single trace_id server-side and can be followed as one chain in logs.
+   */
+  requestId;
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/+$/, "");
     this.timeout = config.timeout ?? 6e4;
+    this.requestId = crypto.randomUUID();
   }
   buildHeaders(auth) {
     const headers = {
-      "User-Agent": `agenzo-admin-cli/${getCurrentVersion()}`
+      "User-Agent": `agenzo-admin-cli/${getCurrentVersion()}`,
+      "X-Request-Id": this.requestId
     };
     if (auth.type === "bearer") {
       headers["Authorization"] = `Bearer ${auth.token}`;
@@ -560,29 +625,6 @@ var STATUS_ICONS = {
   warning: "\u26A0",
   loading: "\u280B"
 };
-var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
-function createSpinner(message, intervalMs = 60) {
-  let frameIdx = 0;
-  let currentMessage = message;
-  const render2 = () => {
-    process.stdout.write(`\r\x1B[K${SPINNER_FRAMES[frameIdx]} ${currentMessage}`);
-    frameIdx = (frameIdx + 1) % SPINNER_FRAMES.length;
-  };
-  render2();
-  const timer = setInterval(render2, intervalMs);
-  return {
-    update(msg) {
-      currentMessage = msg;
-    },
-    stop(type, finalMessage) {
-      clearInterval(timer);
-      process.stdout.write("\r\x1B[K");
-      if (type && finalMessage) {
-        console.log(Formatter.status(type, finalMessage));
-      }
-    }
-  };
-}
 var Formatter = class _Formatter {
   /** Get display width of a string (CJK characters count as 2) */
   static displayWidth(str) {
@@ -768,6 +810,8 @@ async function collectPaymentMethodParams(type, flags) {
 
 // src/verb-schema.ts
 var CLI_NAME = "agenzo-token-cli";
+var PAYMENT_METHODS_NOUN = "payment-methods";
+var PAYMENT_TOKENS_NOUN = "payment-tokens";
 function wantsJsonSchema(argv = process.argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -790,140 +834,236 @@ function attachSchemaHelp(cmd, schema) {
 }
 var pmAddSchema = {
   cli: CLI_NAME,
-  noun: "payment-methods",
+  noun: PAYMENT_METHODS_NOUN,
   verb: "add",
-  description: "Add a payment method. --payment-brand evo (default): card binding + 3DS via Drop-in session. --payment-brand unionpay: UPI Agent Pay enrollment (requires --member); returns enroll_url, result arrives asynchronously via webhook.",
+  description: "Add a payment method (manual 3DS or Drop-in session)",
   flags: {
-    "payment-brand": {
-      type: "string",
-      required: false,
-      default: "evo",
-      description: 'Payment brand: "evo" (default; 3DS/Drop-in binding) or "unionpay" (UPI Agent Pay enrollment)',
-      constraints: "evo | unionpay"
-    },
-    member: {
-      type: "string",
-      required: "conditional",
-      description: "End-user member id (required when --payment-brand unionpay; identifies which user this card belongs to). Ignored for evo payment brand.",
-      source: "from_previous_step",
-      from: "user.member_id or auth context"
-    },
+    type: { type: "string", required: false, default: "card", description: "Payment method type" },
     mode: {
       type: "string",
       required: false,
-      default: "dropin",
-      description: 'Add mode (evo payment brand only): "manual" (CLI collects card details) or "dropin" (mint a Drop-in session)',
+      default: "manual",
+      description: 'Add mode: "manual" (CLI collects card details and polls 3DS) or "dropin" (mint a Drop-in session; the app opens the Drop-in SDK for the user to enter card details securely \u2014 use this mode when the user wants to bind/add a card from chat)',
       constraints: "manual | dropin"
     },
     email: {
+      type: "string",
+      required: "conditional",
+      description: "Manual mode: email for 3DS verification. Dropin mode: email used as the Drop-in session reference. Use the user's login profile email \u2014 never ask in chat."
+    },
+    "idempotency-key": {
       type: "string",
       required: false,
-      description: "Email for 3DS verification (evo/manual) or Drop-in session reference (evo/dropin)"
+      description: "Idempotency key forwarded verbatim as the Idempotency-Key header (manual mode only)"
     },
     "no-poll": {
       type: "bool",
       required: false,
       default: false,
-      description: "Dropin mode: mint session and exit immediately without polling verification status"
+      description: "Dropin mode: mint the session, print it, and exit immediately without polling verification status (for server/SDK-driven flows where the front-end completes the binding). Agents integrating with a UI card flow should set this."
     }
   },
   response: {
     id: { type: "string", description: "Payment method id" },
-    status: {
-      type: "string",
-      description: "PENDING (awaiting enrollment/3DS) / ACTIVE / FAILED / DISABLED"
-    },
-    "payment-brand": { type: "string", description: "evo or unionpay" },
-    session_id: {
-      type: "string|absent",
-      description: "Drop-in session id (evo/dropin mode only)"
-    },
-    enroll_url: {
-      type: "string|absent",
-      description: "UnionPay enrollment URL (unionpay payment brand only) \u2014 user opens this to bind card"
-    },
-    correlation_id: {
-      type: "string|absent",
-      description: "src_correlation_id for tracking enrollment result (unionpay payment brand only)"
-    }
+    session_id: { type: "string|absent", description: "Drop-in session id (dropin mode only) \u2014 pass to the front-end Drop-in SDK, never read aloud to the user" },
+    status: { type: "string", description: "PENDING | ACTIVE | FAILED | EXPIRED" },
+    brand: { type: "string|absent", description: "Card brand, once known" },
+    last4: { type: "string|absent", description: "Card last 4 digits, once known" }
   },
   example: {
-    command: "agenzo-token-cli payment-methods add --payment-brand unionpay --member usr_abc123 --format json",
-    output_summary: "Returns enroll_url. User opens the URL in a browser to complete card binding. Result arrives async via webhook; poll with `payment-methods list` or `payment-methods get`."
+    command: "agenzo-token-cli payment-methods add --mode dropin --email user@example.com --no-poll",
+    output_summary: "Dropin mode returns { id, session_id }. Never read card numbers/CVV/expiry to or from the user (PCI) \u2014 the Drop-in SDK collects them securely."
   },
   error_recovery: {
-    PARAM_INVALID: "Fix the offending flag (--payment-brand must be evo|unionpay; --member required for unionpay).",
-    UPSTREAM_ERROR: "UPI enrollment initiation failed. Retry after a short delay (may be transient network).",
-    MEMBER_REQUIRED: "UnionPay payment brand requires --member <id>. Supply the end-user member identifier."
+    PARAM_INVALID: 'Fix the offending flag (mode must be "manual" or "dropin"), then retry.'
   }
 };
 var pmListSchema = {
   cli: CLI_NAME,
-  noun: "payment-methods",
+  noun: PAYMENT_METHODS_NOUN,
   verb: "list",
-  description: "List all payment methods for the authenticated developer",
-  flags: {},
+  description: "List payment methods",
+  flags: {
+    member: { type: "string", required: false, description: "Filter by member ID" }
+  },
   response: {
     payment_methods: {
       type: "array",
-      description: "List of payment methods",
+      description: "Payment methods for the developer (optionally scoped to --member)",
       items: {
         id: { type: "string", description: "Payment method id" },
-        status: { type: "string", description: "PENDING / ACTIVE / FAILED / DISABLED" },
-        payment_brand: { type: "string", description: "evo or unionpay" },
-        brand: { type: "string|null", description: "Card brand (Visa, Mastercard, UnionPay, etc.)" },
-        last4: { type: "string|null", description: "Last 4 digits of card" },
-        exp_month: { type: "int|null", description: "Expiry month" },
-        exp_year: { type: "int|null", description: "Expiry year" }
+        type: { type: "string", description: "Payment method type (e.g. card)" },
+        status: { type: "string", description: "PENDING | ACTIVE | FAILED | DISABLED | EXPIRED" },
+        brand: { type: "string|null", description: "Card brand" },
+        first6: { type: "string|null", description: "Card first 6 digits" },
+        last4: { type: "string|null", description: "Card last 4 digits" }
       }
     }
   },
   example: {
-    command: "agenzo-token-cli payment-methods list --format json",
-    output_summary: "Returns array of payment methods with status and card info."
+    command: "agenzo-token-cli payment-methods list",
+    output_summary: "Returns payment_methods[]. Check for status=ACTIVE before assuming the user has a usable card."
   }
 };
 var pmGetSchema = {
   cli: CLI_NAME,
-  noun: "payment-methods",
+  noun: PAYMENT_METHODS_NOUN,
   verb: "get",
   description: "Get a payment method by ID",
   flags: {
-    id: { type: "string", required: true, description: "Payment method id", source: "from_previous_step", from: "payment_methods[].id" }
+    pm_id: { type: "string", required: true, description: "Payment method id (positional argument)" }
   },
   response: {
     id: { type: "string", description: "Payment method id" },
-    status: { type: "string", description: "PENDING / ACTIVE / FAILED / DISABLED" },
-    payment_brand: { type: "string", description: "evo or unionpay" },
+    type: { type: "string", description: "Payment method type" },
+    status: { type: "string", description: "PENDING | ACTIVE | FAILED | DISABLED | EXPIRED" },
     brand: { type: "string|null", description: "Card brand" },
-    last4: { type: "string|null", description: "Last 4 digits" },
-    exp_month: { type: "int|null", description: "Expiry month" },
-    exp_year: { type: "int|null", description: "Expiry year" }
+    first6: { type: "string|null", description: "Card first 6 digits" },
+    last4: { type: "string|null", description: "Card last 4 digits" },
+    created_at: { type: "string", description: "Creation time" }
   },
   example: {
-    command: "agenzo-token-cli payment-methods get --id pm_abc123 --format json",
-    output_summary: "Returns full payment method details including card info and status."
+    command: "agenzo-token-cli payment-methods get pm_01H...",
+    output_summary: "Returns the payment method detail including status."
   }
 };
 var pmDisableSchema = {
   cli: CLI_NAME,
-  noun: "payment-methods",
+  noun: PAYMENT_METHODS_NOUN,
   verb: "disable",
-  description: "Disable a payment method (cascades revoke on active tokens)",
+  description: "Disable a payment method",
   flags: {
-    id: { type: "string", required: true, description: "Payment method id to disable", source: "from_previous_step", from: "payment_methods[].id" }
+    pm_id: { type: "string", required: true, description: "Payment method id (positional argument)" },
+    "idempotency-key": {
+      type: "string",
+      required: true,
+      description: "Idempotency key forwarded verbatim as the Idempotency-Key header"
+    }
   },
   response: {
-    id: { type: "string", description: "Payment method id" },
-    status: { type: "string", description: "DISABLED" }
+    status: { type: "string", description: "Status after disabling (typically DISABLED)" },
+    revoked_tokens_count: { type: "int", description: "Number of payment tokens revoked as a side effect" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-methods disable pm_01H... --idempotency-key disable-123",
+    output_summary: "Disables the card and revokes any payment tokens issued against it. Only use when the user explicitly requests it."
+  },
+  error_recovery: {
+    PARAM_IDEMPOTENCY_KEY_REQUIRED: "Supply --idempotency-key (1-128 chars [A-Za-z0-9_-]); the CLI never generates one under --yes."
+  }
+};
+var ptCreateSchema = {
+  cli: CLI_NAME,
+  noun: PAYMENT_TOKENS_NOUN,
+  verb: "create",
+  description: "Create a payment token (VCN / Network Token / X402)",
+  flags: {
+    type: { type: "string", required: true, description: "Token type", constraints: "vcn | network-token | x402" },
+    "payment-method-id": { type: "string", required: "conditional", description: "Payment method ID to use (or resolved via --card / auto-select from ACTIVE cards)" },
+    card: { type: "string", required: false, description: "Match payment method by last 4 digits" },
+    member: { type: "string", required: false, description: "Member ID" },
+    amount: { type: "string", required: "conditional", description: "Amount in USD (vcn) or USDC (x402)" },
+    currency: { type: "string", required: false, description: "Currency (vcn only; server default applies if omitted)" },
+    "pay-to": { type: "string", required: "conditional", description: "Pay-to address (x402 only)" },
+    nonce: { type: "string", required: "conditional", description: "Nonce (x402 only)" },
+    network: { type: "string", required: "conditional", description: "Network (x402 only)" },
+    deadline: { type: "string", required: "conditional", description: "Deadline as a Unix timestamp in seconds (x402 only)" },
+    "external-tx-id": { type: "string", required: false, description: "External transaction ID" },
+    "idempotency-key": {
+      type: "string",
+      required: true,
+      description: "Idempotency key forwarded verbatim as the Idempotency-Key header"
+    }
+  },
+  response: {
+    id: { type: "string", description: "Payment token id" },
+    type: { type: "string", description: "vcn | network_token | x402" },
+    status: { type: "string", description: "Token status" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-tokens create --type vcn --card 1234 --amount 25.00 --idempotency-key tok-123",
+    output_summary: "Creates a token; response shape varies by type (nested under vcn / network_token / x402)."
+  },
+  error_recovery: {
+    TOKEN_FEATURE_DISABLED: "This token type is not enabled yet. Tell the user and suggest an alternative type if applicable.",
+    CLIENT_NO_PAYMENT_METHOD: "The user has no ACTIVE payment method. Guide them to add one first (payment-methods add --mode dropin).",
+    CLIENT_CARD_NOT_MATCHED: "The --card last-4 did not match any ACTIVE card. Call payment-methods list to see available cards."
+  }
+};
+var ptListSchema = {
+  cli: CLI_NAME,
+  noun: PAYMENT_TOKENS_NOUN,
+  verb: "list",
+  description: "List payment tokens",
+  flags: {
+    type: { type: "string", required: false, description: "Filter by token type" },
+    member: { type: "string", required: false, description: "Filter by member ID" }
+  },
+  response: {
+    payment_tokens: {
+      type: "array",
+      description: "Payment tokens for the developer (optionally filtered)",
+      items: {
+        id: { type: "string", description: "Token id" },
+        type: { type: "string", description: "vcn | network_token | x402" },
+        status: { type: "string", description: "Token status" }
+      }
+    }
   },
   example: {
-    command: "agenzo-token-cli payment-methods disable --id pm_abc123 --format json",
-    output_summary: "Disables the payment method and revokes any active tokens."
+    command: "agenzo-token-cli payment-tokens list --type vcn",
+    output_summary: "Returns payment_tokens[]."
+  }
+};
+var ptGetSchema = {
+  cli: CLI_NAME,
+  noun: PAYMENT_TOKENS_NOUN,
+  verb: "get",
+  description: "Get a payment token by ID",
+  flags: {
+    payment_token_id: { type: "string", required: true, description: "Payment token id (positional argument)" },
+    reveal: {
+      type: "bool",
+      required: false,
+      default: false,
+      description: "Reveal full VCN card number and CVC in the output. NEVER pass this or read revealed card data aloud to the user (PCI) unless explicitly required by a payment flow."
+    }
+  },
+  response: {
+    id: { type: "string", description: "Token id" },
+    type: { type: "string", description: "vcn | network_token | x402" },
+    status: { type: "string", description: "Token status" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-tokens get pt_01H...",
+    output_summary: "Returns the token detail. VCN PAN/CVC are masked unless --reveal is set."
+  }
+};
+var ptRevokeSchema = {
+  cli: CLI_NAME,
+  noun: PAYMENT_TOKENS_NOUN,
+  verb: "revoke",
+  description: "Revoke a payment token",
+  flags: {
+    payment_token_id: { type: "string", required: true, description: "Payment token id (positional argument)" },
+    "idempotency-key": {
+      type: "string",
+      required: true,
+      description: "Idempotency key forwarded verbatim as the Idempotency-Key header"
+    }
+  },
+  response: {
+    id: { type: "string", description: "Token id" },
+    status: { type: "string", description: "Status after revocation" },
+    revoked_at: { type: "string|absent", description: "Revocation time (immediate revoke)" },
+    expires_at: { type: "string|absent", description: "Expiry time (delayed revoke \u2014 x402 cryptogram auto-expires)" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-tokens revoke pt_01H... --idempotency-key revoke-123",
+    output_summary: "Revokes the token immediately, or schedules a delayed revoke for x402 (status stays ACTIVE until expires_at)."
   },
   error_recovery: {
-    NOT_FOUND: "Payment method id does not exist. Check the id with `payment-methods list`.",
-    ALREADY_DISABLED: "Card is already disabled. No action needed."
+    PARAM_IDEMPOTENCY_KEY_REQUIRED: "Supply --idempotency-key (1-128 chars [A-Za-z0-9_-]); the CLI never generates one under --yes."
   }
 };
 
@@ -935,13 +1075,6 @@ var DROPIN_POLL_TIMEOUT_MS = 30 * 60 * 1e3;
 var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["ACTIVE", "FAILED", "EXPIRED"]);
 function registerAddCommand(parent, deps) {
   const cmd = parent.command("add").description("Add a payment method (manual 3DS or Drop-in session)").option("--api-key <key>", "API Key for authentication").option("--type <type>", "Payment method type (default: card)", "card").option(
-    "--payment-brand <brand>",
-    'Payment brand: "evo" (default; existing 3DS/Drop-in binding) or "unionpay" (UPI Agent Pay enrollment)',
-    "evo"
-  ).option(
-    "--member <id>",
-    "End-user member id (required when --payment-brand unionpay; identifies which end-user this card belongs to)"
-  ).option(
     "--mode <mode>",
     'Add mode: "manual" (default; CLI collects card details and polls 3DS) or "dropin" (mint a Drop-in session and poll until the user finishes adding the payment method in the browser)',
     "manual"
@@ -960,17 +1093,6 @@ function registerAddCommand(parent, deps) {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
-    const paymentBrand = String(opts.paymentBrand ?? "evo").toLowerCase();
-    if (paymentBrand !== "evo" && paymentBrand !== "unionpay") {
-      throw new CliError(
-        "PARAM_INVALID",
-        `Unknown --payment-brand "${opts.paymentBrand}". Expected "evo" or "unionpay".`
-      );
-    }
-    if (paymentBrand === "unionpay") {
-      await handleUnionpayPaymentBrand(deps, opts, format);
-      return;
-    }
     const mode = String(opts.mode ?? "manual").toLowerCase();
     if (mode !== "manual" && mode !== "dropin") {
       throw new CliError(
@@ -1094,96 +1216,6 @@ async function handleManualMode(deps, opts, format, isYes) {
     }
   }
 }
-async function handleUnionpayPaymentBrand(deps, opts, format) {
-  const isYes = Boolean(opts.yes);
-  let member;
-  if (opts.member) {
-    member = String(opts.member);
-  } else if (isYes) {
-    throw new CliError(
-      "PARAM_INVALID",
-      "Missing required --member <id> for --payment-brand unionpay (required in --yes mode)"
-    );
-  } else {
-    member = await PromptEngine.resolveInput(void 0, {
-      message: "Member ID (end-user identity this card belongs to):",
-      validate: (v) => v.trim().length > 0 || "Member ID is required for --payment-brand unionpay"
-    });
-  }
-  const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
-    message: "API Key:",
-    type: "password"
-  });
-  const email = await PromptEngine.resolveInput(opts.email, {
-    message: "Email:"
-  });
-  const result = await deps.apiClient.post(
-    "/payment-methods/create",
-    { type: "api-key", key: apiKey },
-    { type: "card", payment_brand: "unionpay", member_id: member, email }
-  );
-  if (!result.success) {
-    throw CliError.fromApi(result, { auth: "api-key" });
-  }
-  const pm = result.data;
-  notify(format, "success", "Card binding initiated");
-  const createdResult = {
-    data: pm,
-    text: () => Formatter.keyValue([
-      ["ID", pm.id],
-      ["Status", pm.status],
-      ["Enroll URL", pm.enroll_url ?? "-"],
-      ["Correlation ID", pm.correlation_id ?? "-"]
-    ])
-  };
-  const configManager = new ConfigManager();
-  await renderWithContext(createdResult, { format }, configManager);
-  notify(
-    format,
-    "info",
-    "Open the Enroll URL in a browser to complete card binding. Waiting for result..."
-  );
-  const UNIONPAY_POLL_INTERVAL_MS = 5e3;
-  const UNIONPAY_POLL_TIMEOUT_MS = 6e4;
-  const startTime = Date.now();
-  const spinner = format !== "json" ? createSpinner("Waiting for card binding result...") : null;
-  while (Date.now() - startTime < UNIONPAY_POLL_TIMEOUT_MS) {
-    await sleep(UNIONPAY_POLL_INTERVAL_MS);
-    const pollResult = await deps.apiClient.get(
-      `/payment-methods/${pm.id}`,
-      { type: "api-key", key: apiKey }
-    );
-    if (pollResult.success) {
-      const status = pollResult.data.status;
-      if (status === "ACTIVE") {
-        spinner?.stop();
-        notify(format, "success", "Payment method activated");
-        const activatedPm = pollResult.data;
-        const activatedResult = {
-          data: activatedPm,
-          text: () => {
-            const lines = [
-              ["ID", activatedPm.id],
-              ["Type", activatedPm.type ?? "card"],
-              ["Status", activatedPm.status]
-            ];
-            if (activatedPm.brand) lines.push(["Brand", activatedPm.brand]);
-            if (activatedPm.first6) lines.push(["First 6", activatedPm.first6]);
-            if (activatedPm.last4) lines.push(["Last 4", activatedPm.last4]);
-            return Formatter.keyValue(lines);
-          }
-        };
-        await renderWithContext(activatedResult, { format }, configManager);
-        return;
-      }
-      if (status === "FAILED") {
-        spinner?.stop("error", "Card binding failed.");
-        return;
-      }
-    }
-  }
-  spinner?.stop("info", "Timed out waiting for card binding result. Check status later with: payment-methods get " + pm.id);
-}
 async function handleDropinMode(deps, opts, format) {
   const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
     message: "API Key:",
@@ -1528,9 +1560,8 @@ function registerDropinStatusCommand(parent, deps) {
 
 // src/payment-tokens/create.ts
 import { confirm, select as select2 } from "@inquirer/prompts";
-var DEFAULT_NT_FEE_CENTS = 500;
+var DEFAULT_NT_FEE_CENTS = 50;
 var USDC_UNIT = 1e6;
-var DECIMAL_AMOUNT_RE = /^\d+(\.\d+)?$/;
 function mapTokenType(cliType) {
   if (cliType === "network-token") return "network_token";
   return cliType;
@@ -1608,23 +1639,14 @@ function formatPaymentToken(data) {
     lines.push(["Currency", String(vcn.currency || "USD")]);
     lines.push(["Status", String(vcn.status || data.status || "")]);
   } else if (type === "network_token") {
-    if (data.status === "PENDING" && data.checkout_url) {
-      lines.push(["Payment Token ID", String(data.id || "")]);
-      lines.push(["Type", "Network Token"]);
-      lines.push(["Status", "PENDING"]);
-      lines.push(["Checkout URL", String(data.checkout_url || "")]);
-      lines.push(["Correlation ID", String(data.correlation_id || "")]);
-    } else {
-      const nt = data.network_token ?? data;
-      lines.push(["Payment Token ID", String(data.id || nt.id || "")]);
-      lines.push(["Type", "Network Token"]);
-      lines.push(["Brand", String(nt.payment_brand || nt.brand || "")]);
-      const eci = nt.eci || "";
-      if (eci) lines.push(["ECI", String(eci)]);
-      lines.push(["Cryptogram", String(nt.token_cryptogram || nt.cryptogram || "")]);
-      lines.push(["Expiry", String(nt.expiry_date || nt.expiry || "")]);
-      lines.push(["Token Number", String(nt.value || "")]);
-    }
+    const nt = data.network_token ?? data;
+    lines.push(["Payment Token ID", String(data.id || nt.id || "")]);
+    lines.push(["Type", "Network Token"]);
+    lines.push(["Brand", String(nt.payment_brand || nt.brand || "")]);
+    lines.push(["ECI", String(nt.eci || "")]);
+    lines.push(["Cryptogram", String(nt.token_cryptogram || nt.cryptogram || "")]);
+    lines.push(["Expiry", String(nt.expiry_date || nt.expiry || "")]);
+    lines.push(["Value", String(nt.value || "")]);
   } else if (type === "x402") {
     const x402 = data.x402 ?? data;
     lines.push(["Payment Token ID", String(data.id || x402.id || "")]);
@@ -1644,16 +1666,12 @@ function formatCentsToUsd(cents) {
   const remainder = cents % 100;
   return `${dollars}.${String(remainder).padStart(2, "0")}`;
 }
-function isValidUnionpayAmount(amountStr) {
-  const trimmed = amountStr.trim();
-  if (!DECIMAL_AMOUNT_RE.test(trimmed)) return false;
-  return parseFloat(trimmed) > 0;
-}
 function registerCreateCommand(parent, deps) {
-  const cmd = parent.command("create").description("Create a payment token (VCN / Network Token / X402)").option("--api-key <key>", "API Key for authentication").option("--type <type>", "Token type: vcn | network-token | x402").option("--payment-method-id <id>", "Payment method ID to use").option("--card <last4>", "Match payment method by last 4 digits").option("--member <member_id>", "Member ID").option("--amount <amount>", "Amount in USD (VCN / X402)").option("--currency <currency>", "Currency (default: USD)").option("--pay-to <address>", "Pay-to address (X402)").option("--nonce <nonce>", "Nonce (X402)").option("--network <network>", "Network (X402)").option("--deadline <deadline>", "Deadline (X402)").option("--external-tx-id <id>", "External transaction ID").option("--recipient-first-name <name>", "UnionPay network token: recipient first name (order delivery details)").option("--recipient-last-name <name>", "UnionPay network token: recipient last name (order delivery details)").option("--recipient-email <email>", "UnionPay network token: recipient email (recipient-email or recipient-phone required)").option("--recipient-phone <phone>", "UnionPay network token: recipient phone (recipient-email or recipient-phone required)").option("--unionpay-amount <amount>", 'UnionPay network token: intent amount as a decimal string, e.g. "174.58"').option(
+  const cmd = parent.command("create").description("Create a payment token (VCN / Network Token / X402)").option("--api-key <key>", "API Key for authentication").option("--type <type>", "Token type: vcn | network-token | x402").option("--payment-method-id <id>", "Payment method ID to use").option("--card <last4>", "Match payment method by last 4 digits").option("--member <member_id>", "Member ID").option("--amount <amount>", "Amount in USD (VCN / X402)").option("--currency <currency>", "Currency (default: USD)").option("--pay-to <address>", "Pay-to address (X402)").option("--nonce <nonce>", "Nonce (X402)").option("--network <network>", "Network (X402)").option("--deadline <deadline>", "Deadline (X402)").option("--external-tx-id <id>", "External transaction ID").option(
     "--idempotency-key <key>",
     "Idempotency key forwarded verbatim as the Idempotency-Key header"
   );
+  attachSchemaHelp(cmd, ptCreateSchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
@@ -1677,24 +1695,6 @@ function registerCreateCommand(parent, deps) {
       card: opts.card,
       yes: isYes
     });
-    let selectedPmPaymentBrand;
-    if (serverType === "network_token") {
-      const pmResult = await deps.apiClient.get(
-        `/payment-methods/${paymentMethodId}`,
-        { type: "api-key", key: apiKey }
-      );
-      if (!pmResult.success) {
-        throw CliError.fromApi(pmResult, { auth: "api-key" });
-      }
-      selectedPmPaymentBrand = pmResult.data.payment_brand;
-      if (selectedPmPaymentBrand === "unionpay" && opts.card && !opts.paymentMethodId) {
-        throw new CliError(
-          "PARAM_INVALID",
-          "UnionPay cards must be selected via --payment-method-id; --card (last4 matching) is not supported for unionpay payment brand."
-        );
-      }
-    }
-    const isUnionpayNetworkToken = serverType === "network_token" && selectedPmPaymentBrand === "unionpay";
     let member = opts.member;
     if (!member && !isYes) {
       const memberInput = await PromptEngine.resolveInput(void 0, {
@@ -1743,66 +1743,10 @@ function registerCreateCommand(parent, deps) {
         typeBody.currency = opts.currency;
       }
     } else if (serverType === "network_token") {
-      if (isUnionpayNetworkToken) {
-        const unionpayAmountStr = await PromptEngine.resolveInput(
-          opts.unionpayAmount,
-          {
-            message: "UnionPay intent amount (USD, e.g. 174.58):",
-            validate: (v) => isValidUnionpayAmount(v) || 'Amount must be a positive decimal, e.g. "174.58"'
-          }
-        );
-        if (!isValidUnionpayAmount(unionpayAmountStr)) {
-          throw new CliError(
-            "PARAM_INVALID",
-            `Invalid --unionpay-amount "${unionpayAmountStr}". Expected a positive decimal string, e.g. "174.58".`
-          );
-        }
-        typeBody.unionpay_amount = unionpayAmountStr.trim();
-        typeBody.recipient_first_name = await PromptEngine.resolveInput(
-          opts.recipientFirstName,
-          {
-            message: "Recipient first name:",
-            validate: (v) => v.trim().length > 0 || "Recipient first name is required"
-          }
-        );
-        typeBody.recipient_last_name = await PromptEngine.resolveInput(
-          opts.recipientLastName,
-          {
-            message: "Recipient last name:",
-            validate: (v) => v.trim().length > 0 || "Recipient last name is required"
-          }
-        );
-        let recipientEmail = opts.recipientEmail;
-        let recipientPhone = opts.recipientPhone;
-        if (!recipientEmail && !recipientPhone) {
-          if (isYes) {
-            throw new CliError(
-              "PARAM_INVALID",
-              "--recipient-email or --recipient-phone is required for unionpay network tokens."
-            );
-          }
-          const emailInput = await PromptEngine.resolveInput(void 0, {
-            message: "Recipient email (optional, press Enter to skip and enter phone instead):",
-            validate: () => true
-          });
-          if (emailInput.trim()) {
-            recipientEmail = emailInput.trim();
-          } else {
-            const phoneInput = await PromptEngine.resolveInput(void 0, {
-              message: "Recipient phone (required, since no email was given):",
-              validate: (v) => v.trim().length > 0 || "Recipient email or phone is required"
-            });
-            recipientPhone = phoneInput.trim();
-          }
-        }
-        if (recipientEmail) typeBody.recipient_email = recipientEmail;
-        if (recipientPhone) typeBody.recipient_phone = recipientPhone;
-      } else {
-        feeCents = await fetchNetworkTokenFee(deps.apiClient, apiKey);
-        freezeAmountCents = feeCents;
-        feeDisplay = `$${formatCentsToUsd(feeCents)}`;
-        freezeDisplay = feeDisplay;
-      }
+      feeCents = await fetchNetworkTokenFee(deps.apiClient, apiKey);
+      freezeAmountCents = feeCents;
+      feeDisplay = `$${formatCentsToUsd(feeCents)}`;
+      freezeDisplay = feeDisplay;
     } else if (serverType === "x402") {
       const amountStr = await PromptEngine.resolveInput(opts.amount, {
         message: "Amount (USDC):",
@@ -1844,15 +1788,10 @@ function registerCreateCommand(parent, deps) {
       typeBody.deadline = deadlineNum;
     }
     if (!isYes) {
-      if (freezeDisplay !== void 0 && feeDisplay !== void 0) {
-        const warningLines = [`Freeze: ${freezeDisplay}`, `Fee: ${feeDisplay}`];
-        notify(format, "warning", warningLines.join(" | "));
-      } else if (isUnionpayNetworkToken) {
-        notify(format, "info", "UnionPay: no fee (clearing network not yet enabled)");
-      }
-      const confirmMessage = isUnionpayNetworkToken ? "Proceed with UnionPay network token request?" : "Proceed with token creation?";
+      const warningLines = [`Freeze: ${freezeDisplay}`, `Fee: ${feeDisplay}`];
+      notify(format, "warning", warningLines.join(" | "));
       const confirmed = await confirm({
-        message: confirmMessage,
+        message: "Proceed with token creation?",
         default: true
       });
       if (!confirmed) {
@@ -1909,42 +1848,6 @@ function registerCreateCommand(parent, deps) {
       }
     };
     await renderWithContext(commandResult, { format }, configManager);
-    if (isUnionpayNetworkToken) {
-      notify(
-        format,
-        "info",
-        "Open the Checkout URL to complete the UnionPay payment verification. Waiting for result..."
-      );
-      const UNIONPAY_TOKEN_POLL_INTERVAL_MS = 5e3;
-      const UNIONPAY_TOKEN_POLL_TIMEOUT_MS = 6e4;
-      const pollStart = Date.now();
-      const tokenId = tokenData.id;
-      while (Date.now() - pollStart < UNIONPAY_TOKEN_POLL_TIMEOUT_MS) {
-        await new Promise((resolve) => setTimeout(resolve, UNIONPAY_TOKEN_POLL_INTERVAL_MS));
-        const pollResult = await deps.apiClient.get(
-          `/payment-tokens/${tokenId}`,
-          { type: "api-key", key: apiKey }
-        );
-        if (pollResult.success) {
-          const status = pollResult.data.status;
-          if (status === "ACTIVE") {
-            notify(format, "success", "UnionPay network token activated!");
-            if (!pollResult.data.type) pollResult.data.type = serverType;
-            const activatedResult = {
-              data: pollResult.data,
-              text: () => formatPaymentToken(pollResult.data)
-            };
-            await renderWithContext(activatedResult, { format }, configManager);
-            return;
-          }
-          if (status === "FAILED") {
-            notify(format, "error", "UnionPay network token failed.");
-            return;
-          }
-        }
-      }
-      notify(format, "info", `Timed out waiting for token activation. Check status later with: payment-tokens get ${tokenId}`);
-    }
   });
 }
 async function checkVcnFeatureEnabled(apiClient, apiKey) {
@@ -2000,6 +1903,7 @@ function getSummary(token) {
 }
 function registerListCommand2(parent, deps) {
   const cmd = parent.command("list").description("List payment tokens").option("--api-key <key>", "API Key for authentication").option("--type <type>", "Filter by token type").option("--member <member_id>", "Filter by member ID");
+  attachSchemaHelp(cmd, ptListSchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
@@ -2136,6 +2040,7 @@ function formatCentsPlain(cents) {
 }
 function registerGetCommand2(parent, deps) {
   const cmd = parent.command("get <payment_token_id>").description("Get a payment token by ID").option("--api-key <key>", "API key for authentication").option("--reveal", "Reveal full VCN card number and CVC in the output");
+  attachSchemaHelp(cmd, ptGetSchema);
   cmd.action(async (paymentTokenId) => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
@@ -2167,6 +2072,7 @@ function registerRevokeCommand(parent, deps) {
     "--idempotency-key <key>",
     "Idempotency key forwarded verbatim as the Idempotency-Key header"
   );
+  attachSchemaHelp(cmd, ptRevokeSchema);
   cmd.action(async (paymentTokenId) => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
@@ -2277,6 +2183,9 @@ function reportError(error) {
     console.error(
       Formatter.status("error", `[${envelope.error.code_num}] ${envelope.error.message}`)
     );
+    if (envelope.error.upstream) {
+      console.error(`  \u21B3 [${envelope.error.upstream.code}] ${envelope.error.upstream.message}`);
+    }
     if (!(error instanceof CliError) && process.argv.includes("--verbose")) {
       console.error(error);
     }