@agenzo/token-cli 0.2.1 → 0.3.0

package/dist/index.js

@@ -270,6 +270,10 @@ var ApiClient = class {
     const headers = {
       "User-Agent": `agenzo-admin-cli/${getCurrentVersion()}`
     };
+    const traceparent = process.env.TRACEPARENT;
+    if (traceparent) {
+      headers["traceparent"] = traceparent;
+    }
     if (auth.type === "bearer") {
       headers["Authorization"] = `Bearer ${auth.token}`;
     } else if (auth.type === "api-key") {
@@ -692,11 +696,17 @@ async function renderWithContext(result, opts, configManager) {
   render({ ...result, data: payload }, opts);
 }
 var PromptEngine = class {
-  /** Return flagValue directly if provided, otherwise prompt interactively */
+  /** Return flagValue if provided, else env fallback, else prompt interactively */
   static async resolveInput(flagValue, config) {
     if (flagValue !== void 0) {
       return flagValue;
     }
+    if (config.envVar) {
+      const envValue = process.env[config.envVar];
+      if (envValue !== void 0 && envValue !== "") {
+        return envValue;
+      }
+    }
     if (config.type === "password") {
       return password({ message: config.message, mask: "*" });
     }
@@ -743,6 +753,230 @@ async function collectPaymentMethodParams(type, flags) {
   return params;
 }
 
+// src/verb-schema.ts
+var CLI_NAME = "agenzo-token-cli";
+function wantsJsonSchema(argv = process.argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--format=json") return true;
+    if (a === "--format" && argv[i + 1] === "json") return true;
+  }
+  return false;
+}
+function emitSchema(schema) {
+  console.log(JSON.stringify(schema, null, 2));
+}
+function attachSchemaHelp(cmd, schema) {
+  const baseHelp = cmd.helpInformation.bind(cmd);
+  cmd.helpInformation = (context) => {
+    if (!wantsJsonSchema()) return baseHelp(context);
+    emitSchema(schema);
+    return "";
+  };
+  return cmd;
+}
+var pmAddSchema = {
+  cli: CLI_NAME,
+  noun: "payment-methods",
+  verb: "add",
+  description: "Add a payment method (card binding + 3DS verification)",
+  flags: {
+    "card-number": { type: "string", required: true, description: "Card number (PAN)" },
+    "exp-month": { type: "string", required: true, description: "Expiration month (MM)" },
+    "exp-year": { type: "string", required: true, description: "Expiration year (YY or YYYY)" },
+    "cardholder-name": { type: "string", required: true, description: "Name on the card" },
+    "member-id": { type: "string", required: false, description: "Member ID to associate the card with" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    id: { type: "string", description: "Payment method ID" },
+    status: { type: "string", description: "PENDING / ACTIVE / FAILED" },
+    card_brand: { type: "string", description: "visa / mastercard / ..." },
+    last_four: { type: "string", description: "Last 4 digits of card" },
+    verification_url: { type: "string|null", description: "3DS verification URL (when PENDING)" }
+  },
+  example: {
+    command: 'agenzo-token-cli payment-methods add --card-number 4111111111111111 --exp-month 12 --exp-year 2027 --cardholder-name "Alice Test"',
+    output_summary: "Returns payment method ID and 3DS verification URL. Complete 3DS to activate."
+  },
+  error_recovery: {
+    INVALID_CARD: "Card number failed Luhn check or is not supported. Verify and retry.",
+    EVO_ERROR: "Upstream payment processor error. Retry after a short delay."
+  }
+};
+var pmListSchema = {
+  cli: CLI_NAME,
+  noun: "payment-methods",
+  verb: "list",
+  description: "List payment methods for the authenticated developer",
+  flags: {
+    "member": { type: "string", required: false, description: "Filter by member ID" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    payment_methods: {
+      type: "array",
+      description: "List of payment methods",
+      items: {
+        id: { type: "string", description: "Payment method ID" },
+        status: { type: "string", description: "PENDING / ACTIVE / DISABLED" },
+        card_brand: { type: "string", description: "Card brand" },
+        last_four: { type: "string", description: "Last 4 digits" },
+        created_at: { type: "string", description: "Creation time (ISO 8601)" }
+      }
+    }
+  },
+  example: {
+    command: "agenzo-token-cli payment-methods list",
+    output_summary: "Returns array of payment methods with status and card info."
+  }
+};
+var pmGetSchema = {
+  cli: CLI_NAME,
+  noun: "payment-methods",
+  verb: "get",
+  description: "Get a payment method by ID",
+  flags: {
+    "pm-id": { type: "string", required: true, description: "Payment method ID" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    id: { type: "string", description: "Payment method ID" },
+    status: { type: "string", description: "PENDING / ACTIVE / DISABLED / FAILED / EXPIRED" },
+    card_brand: { type: "string", description: "Card brand" },
+    last_four: { type: "string", description: "Last 4 digits" },
+    member_id: { type: "string|null", description: "Associated member ID" },
+    created_at: { type: "string", description: "Creation time" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-methods get pm_01HZXD...",
+    output_summary: "Returns full payment method details including 3DS verification status."
+  }
+};
+var pmDisableSchema = {
+  cli: CLI_NAME,
+  noun: "payment-methods",
+  verb: "disable",
+  description: "Disable a payment method (cascades revoke on active payment tokens)",
+  flags: {
+    "pm-id": { type: "string", required: true, description: "Payment method ID to disable" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    id: { type: "string", description: "Disabled payment method ID" },
+    status: { type: "string", description: "DISABLED" },
+    revoked_tokens_count: { type: "int", description: "Number of payment tokens revoked by cascade" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-methods disable pm_01HZXD...",
+    output_summary: "Disables the payment method and revokes any active tokens bound to it."
+  }
+};
+var ptCreateSchema = {
+  cli: CLI_NAME,
+  noun: "payment-tokens",
+  verb: "create",
+  description: "Create a payment token (VCN, Network Token cryptogram, or x402 USDC signature)",
+  flags: {
+    "type": { type: "string", required: true, description: "Token type: vcn / network_token / x402", constraints: "vcn | network_token | x402" },
+    "payment-method-id": { type: "string", required: true, description: "Source payment method ID (must be ACTIVE)" },
+    "amount": { type: "string", required: "conditional", description: "Amount in minor units (required for vcn and x402)" },
+    "currency": { type: "string", required: false, default: "USD", description: "ISO 4217 currency code" },
+    "member-id": { type: "string", required: false, description: "Member ID" },
+    "external-transaction-id": { type: "string", required: false, description: "External reference for reconciliation" },
+    "pay-to": { type: "string", required: "conditional", description: "Recipient address (required for x402)" },
+    "nonce": { type: "string", required: "conditional", description: "Nonce bytes32 hex (required for x402)" },
+    "network": { type: "string", required: "conditional", description: "Chain network (required for x402, e.g. base-sepolia)" },
+    "deadline": { type: "int", required: "conditional", description: "Epoch seconds deadline (required for x402)" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    id: { type: "string", description: "Payment token ID" },
+    type: { type: "string", description: "vcn / network_token / x402" },
+    status: { type: "string", description: "ACTIVE / REVOKED / EXPIRED" },
+    token_data: { type: "object", description: "Type-specific token payload (cryptogram / VCN number / x402 signature)" },
+    expires_at: { type: "string|null", description: "Expiration time (ISO 8601)" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-tokens create --type network_token --payment-method-id pm_01HZXD...",
+    output_summary: "Returns token ID and cryptogram/VCN/signature data for payment execution."
+  },
+  error_recovery: {
+    INVALID_PAYMENT_METHOD: "Payment method is not ACTIVE or not found. Verify status with payment-methods get.",
+    UNSUPPORTED_TOKEN_TYPE: "Use vcn, network_token, or x402."
+  }
+};
+var ptListSchema = {
+  cli: CLI_NAME,
+  noun: "payment-tokens",
+  verb: "list",
+  description: "List payment tokens for the authenticated developer",
+  flags: {
+    "type": { type: "string", required: false, description: "Filter by token type (vcn / network_token / x402)" },
+    "member-id": { type: "string", required: false, description: "Filter by member ID" },
+    "payment-method-id": { type: "string", required: false, description: "Filter by source payment method" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    payment_tokens: {
+      type: "array",
+      description: "List of payment tokens",
+      items: {
+        id: { type: "string", description: "Token ID" },
+        type: { type: "string", description: "Token type" },
+        status: { type: "string", description: "ACTIVE / REVOKED / EXPIRED" },
+        payment_method_id: { type: "string", description: "Source payment method" },
+        created_at: { type: "string", description: "Creation time" }
+      }
+    }
+  },
+  example: {
+    command: "agenzo-token-cli payment-tokens list --type network_token",
+    output_summary: "Returns array of payment tokens filtered by type."
+  }
+};
+var ptGetSchema = {
+  cli: CLI_NAME,
+  noun: "payment-tokens",
+  verb: "get",
+  description: "Get a payment token by ID",
+  flags: {
+    "payment-token-id": { type: "string", required: true, description: "Payment token ID" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    id: { type: "string", description: "Token ID" },
+    type: { type: "string", description: "Token type" },
+    status: { type: "string", description: "ACTIVE / REVOKED / EXPIRED" },
+    token_data: { type: "object", description: "Type-specific payload" },
+    payment_method_id: { type: "string", description: "Source payment method" },
+    created_at: { type: "string", description: "Creation time" },
+    expires_at: { type: "string|null", description: "Expiration time" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-tokens get pt_01HZXD...",
+    output_summary: "Returns full token details including token_data payload."
+  }
+};
+var ptRevokeSchema = {
+  cli: CLI_NAME,
+  noun: "payment-tokens",
+  verb: "revoke",
+  description: "Revoke an active payment token",
+  flags: {
+    "payment-token-id": { type: "string", required: true, description: "Payment token ID to revoke" },
+    "api-key": { type: "string", required: true, description: "API Key for authentication", source: "config" }
+  },
+  response: {
+    id: { type: "string", description: "Revoked token ID" },
+    status: { type: "string", description: "REVOKED" }
+  },
+  example: {
+    command: "agenzo-token-cli payment-tokens revoke pt_01HZXD...",
+    output_summary: "Marks the token as REVOKED. Cannot be undone."
+  }
+};
+
 // src/payment-methods/add.ts
 var POLL_INTERVAL_MS = 3e3;
 var POLL_TIMEOUT_MS = 15 * 60 * 1e3;
@@ -751,13 +985,15 @@ function registerAddCommand(parent, deps) {
     "--idempotency-key <key>",
     "Idempotency key forwarded verbatim as the Idempotency-Key header"
   );
+  attachSchemaHelp(cmd, pmAddSchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const isYes = Boolean(opts.yes);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     const type = opts.type || "card";
     const flags = {
@@ -898,12 +1134,14 @@ function sleep(ms) {
 // src/payment-methods/list.ts
 function registerListCommand(parent, deps) {
   const cmd = parent.command("list").description("List payment methods").option("--api-key <key>", "API Key for authentication").option("--member <member_id>", "Filter by member ID");
+  attachSchemaHelp(cmd, pmListSchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     const params = {};
     if (opts.member) {
@@ -944,12 +1182,14 @@ function registerListCommand(parent, deps) {
 // src/payment-methods/get.ts
 function registerGetCommand(parent, deps) {
   const cmd = parent.command("get <pm_id>").description("Get a payment method by ID").option("--api-key <key>", "API key for authentication");
+  attachSchemaHelp(cmd, pmGetSchema);
   cmd.action(async (pmId) => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     const result = await deps.apiClient.get(
       `/payment-methods/${pmId}`,
@@ -989,12 +1229,14 @@ function registerDisableCommand(parent, deps) {
     "--idempotency-key <key>",
     "Idempotency key forwarded verbatim as the Idempotency-Key header"
   );
+  attachSchemaHelp(cmd, pmDisableSchema);
   cmd.action(async (pmId) => {
     const opts = cmd.optsWithGlobals();
     const format = resolveFormat(opts.format);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     let idempotencyKey = opts.idempotencyKey;
     if (!idempotencyKey) {
@@ -1145,13 +1387,15 @@ function registerCreateCommand(parent, deps) {
     "--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);
     const isYes = Boolean(opts.yes);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     const cliType = await PromptEngine.resolveInput(opts.type, {
       message: "Token type:",
@@ -1290,7 +1534,7 @@ function registerCreateCommand(parent, deps) {
       body.member_id = member;
     }
     if (opts.externalTxId) {
-      body.external_tx_id = opts.externalTxId;
+      body.external_transaction_id = opts.externalTxId;
     }
     const extraHeaders = {
       "Idempotency-Key": idempotencyKey
@@ -1376,12 +1620,14 @@ 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);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     const params = {};
     if (opts.type) {
@@ -1512,12 +1758,14 @@ 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);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     const result = await deps.apiClient.get(
       `/payment-tokens/${paymentTokenId}`,
@@ -1543,12 +1791,14 @@ 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);
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
-      type: "password"
+      type: "password",
+      envVar: "AGENZO_API_KEY"
     });
     let idempotencyKey = opts.idempotencyKey;
     if (!idempotencyKey) {
@@ -1636,6 +1886,54 @@ async function main() {
   registerListCommand2(ptCmd, deps);
   registerGetCommand2(ptCmd, deps);
   registerRevokeCommand(ptCmd, deps);
+  const svcCmd = program.command("services").description("Token service discovery");
+  svcCmd.command("list").description("List available token services from platform catalog").option("--api-key <key>", "API Key for authentication").action(async () => {
+    const opts = svcCmd.parent.optsWithGlobals();
+    const format = resolveFormat(opts.format);
+    const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
+      message: "API Key:",
+      type: "password",
+      envVar: "AGENZO_API_KEY"
+    });
+    const host = (await configManager.load()).api_host || "http://localhost:8001";
+    const discoveryClient = new ApiClient({ baseUrl: `${host}/api/discovery/v1` });
+    const result = await discoveryClient.get(
+      "/catalog",
+      { type: "api-key", key: apiKey },
+      { category: "payment" }
+    );
+    if (!result.success) {
+      throw CliError.fromApi(result, { auth: "api-key" });
+    }
+    const cmdResult = {
+      text: () => JSON.stringify(result.data, null, 2),
+      data: result.data
+    };
+    await renderWithContext(cmdResult, { format }, configManager);
+  });
+  svcCmd.command("get <service_id>").description("Get a token service capability by ID").option("--api-key <key>", "API Key for authentication").action(async (serviceId) => {
+    const opts = svcCmd.parent.optsWithGlobals();
+    const format = resolveFormat(opts.format);
+    const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
+      message: "API Key:",
+      type: "password",
+      envVar: "AGENZO_API_KEY"
+    });
+    const host2 = (await configManager.load()).api_host || "http://localhost:8001";
+    const discoveryClient2 = new ApiClient({ baseUrl: `${host2}/api/discovery/v1` });
+    const result = await discoveryClient2.get(
+      `/catalog/${serviceId}`,
+      { type: "api-key", key: apiKey }
+    );
+    if (!result.success) {
+      throw CliError.fromApi(result, { auth: "api-key" });
+    }
+    const cmdResult = {
+      text: () => JSON.stringify(result.data, null, 2),
+      data: result.data
+    };
+    await renderWithContext(cmdResult, { format }, configManager);
+  });
   await program.parseAsync(process.argv);
 }
 function resolveActiveFormat() {