@agenzo/token-cli 0.3.1 → 0.3.2

package/README.md

@@ -1,7 +1,11 @@
 # @agenzo/token-cli
 
+[![npm](https://img.shields.io/npm/v/@agenzo/token-cli.svg)](https://www.npmjs.com/package/@agenzo/token-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE) ![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)
+
 > The **payment credential CLI** (runtime plane) for the Agenzo platform. Agents use it to manage payment methods (card details + 3DS verification) and to issue payment tokens (VCN / Network Token / X402) before a transaction.
 
+**[Installation](#installation)** · **[Authentication](#authentication)** · **[Commands](#command-matrix)** · **[payment-methods](#payment-methods)** · **[payment-tokens](#payment-tokens)** · **[Errors](#output-and-errors)**
+
 Binary: `agenzo-token-cli` ｜ Auth: API Key (`X-Api-Key`)
 
 ## Installation
@@ -10,7 +14,7 @@ Binary: `agenzo-token-cli` ｜ Auth: API Key (`X-Api-Key`)
 npm install -g @agenzo/token-cli
 ```
 
-The `agenzo-token-cli` command is available after installation. Requires Node.js ≥ 18.
+The `agenzo-token-cli` command is available after installation. Requires Node.js ≥ 22. Upgrade later with `npm install -g @agenzo/token-cli@latest`.
 
 ## Authentication
 
@@ -30,7 +34,7 @@ agenzo-admin-cli keys create --developer-id <dev_id> --key-name "Prod Key" --sco
 token-cli reuses the environment configuration (API host / path) written by admin-cli; it has no environment-management commands of its own. The default target is production `https://agent.everonet.com`. Switch environments via admin-cli:
 
 ```bash
-agenzo-admin-cli config set-host https://agent-test.everonet.com   # switch to test
+agenzo-admin-cli config set-host https://agent-dev.agenzo.com   # switch to the test environment
 agenzo-admin-cli config show                                       # show current host / path
 ```
 
@@ -38,8 +42,8 @@ agenzo-admin-cli config show                                       # show curren
 
 | Option | Description |
 |---|---|
-| `--format <json\|table>` | Output format. Default `table` (human-readable); `json` for Agent / script parsing. Can also be set via the `AGENZO_FORMAT` environment variable |
-| `--yes` | Skip all confirmation prompts (for automation / AI Agents) |
+| `--format <json\|table>` | Output format. Defaults to `table`; pass `json` (or set `AGENZO_FORMAT=json`) for machine-readable output |
+| `--yes` | Skip all confirmation prompts (non-interactive automation) |
 | `--verbose` | Print verbose logs to stderr |
 | `--version` | Print the CLI version |
 
@@ -49,7 +53,7 @@ agenzo-admin-cli config show                                       # show curren
 
 | Noun | Verb | Purpose | Write/Read |
 |---|---|---|---|
-| `payment-methods` | `add` | Add a payment method, then auto-poll 3DS verification (up to 15 min) | W |
+| `payment-methods` | `add` | Add a payment method via `--mode manual` (collect card + 3DS, default) or `--mode dropin` (Drop-in session), then auto-poll verification | W |
 | `payment-methods` | `list` | List payment methods under the current API Key | R |
 | `payment-methods` | `get <pm_id>` | Show details of a single payment method | R |
 | `payment-methods` | `disable <pm_id>` | Disable a payment method (cascades to revoke its issued tokens) | W |
@@ -60,7 +64,14 @@ agenzo-admin-cli config show                                       # show curren
 
 ## payment-methods
 
-### add — add a payment method + 3DS verification
+### add — add a payment method
+
+Two modes, selected with `--mode`:
+
+- **`manual`** (default): the CLI collects card details and polls 3DS verification.
+- **`dropin`**: the CLI mints a Drop-in session and polls until the user finishes adding the payment method in their browser — no card details are entered at the terminal.
+
+#### Manual mode (default)
 
 ```bash
 agenzo-token-cli payment-methods add \
@@ -75,14 +86,33 @@ agenzo-token-cli payment-methods add \
 | Flag | Required | Description |
 |---|---|---|
 | `--api-key` | Yes | Prompted interactively when omitted |
+| `--mode` | No | `manual` (default) or `dropin` |
 | `--type` | No | Payment method type, defaults to `card` |
 | `--email` | Yes | Used to deliver the 3DS email challenge |
 | `--card-number` | Yes | Card number |
 | `--expiry` | Yes | Expiry date in `MMYY` format (note: not `MM/YY`) |
 | `--cvv` | Yes | CVV; piping via stdin is recommended to keep it out of shell history |
+| `--idempotency-key` | Yes (in `--yes`) | Forwarded verbatim as the `Idempotency-Key` header |
 
 Returns a `PM ID` with `PENDING` status immediately, then auto-polls 3DS verification (3s interval, 15 min timeout). On success it prints `ACTIVE` status plus card brand, first six and last four. On timeout it suggests continuing with `payment-methods get`.
 
+#### Drop-in mode
+
+```bash
+agenzo-token-cli payment-methods add \
+  --api-key <api_key> \
+  --mode dropin \
+  --email user@example.com
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--api-key` | Yes | Prompted interactively when omitted |
+| `--mode` | Yes | Set to `dropin` |
+| `--email` | Yes | Reference for the Drop-in session |
+
+Mints a Drop-in session and prints a `Session ID`. Initialise the add-payment UI in your own front-end with that `Session ID` (the user enters card details and completes verification in the browser). The CLI then polls the same verification endpoint (5s interval, 30 min timeout) and prints `ACTIVE` with brand / first six / last four on success. If the payment method is not added it reports `FAILED` / `EXPIRED` (or a 30-minute timeout) with the `PM ID` and exits non-zero — re-run with the same email to resume. Card flags (`--card-number` / `--expiry` / `--cvv`) and `--idempotency-key` are not used in this mode.
+
 ### list
 
 ```bash
@@ -170,7 +200,7 @@ Revokes immediately and prints `REVOKED` plus the revocation time; X402 tokens u
 
 ## Output and errors
 
-- **Success**: `table` mode prints human-readable text; `json` mode emits the structured payload to stdout.
+- **Success**: `table` mode prints formatted text; `json` mode emits the structured payload to stdout.
 - **Failure**: an error envelope is written to stderr. In `json` mode it is `{ "error": { "code", "code_num", "message", "request_id?" } }`; in `table` mode it is `✗ [<code_num>] <message>`.
 - **Exit codes**: `0` on success, `1`–`5` for different error categories (e.g. user cancellation = `5`).
 
@@ -178,13 +208,4 @@ Common error codes: `KEY_INVALID` (invalid API Key), `KEY_SCOPE_DENIED` (scope l
 
 ## Related
 
-- Full field-level specification: internal design doc `architecture-upgrade/v1/cli-design.md` §3.
 - Control plane (login / organizations / developers / API Key management): [`@agenzo/admin-cli`](https://www.npmjs.com/package/@agenzo/admin-cli).
-
-## Development
-
-```bash
-npm install      # install dependencies from the monorepo root
-npm run build    # build (tsup, output at dist/index.js)
-npm test         # run tests (vitest)
-```

package/dist/index.js

@@ -744,136 +744,231 @@ async function collectPaymentMethodParams(type, flags) {
 }
 
 // src/payment-methods/add.ts
-var POLL_INTERVAL_MS = 3e3;
-var POLL_TIMEOUT_MS = 15 * 60 * 1e3;
+var MANUAL_POLL_INTERVAL_MS = 3e3;
+var MANUAL_POLL_TIMEOUT_MS = 15 * 60 * 1e3;
+var DROPIN_POLL_INTERVAL_MS = 5e3;
+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 (with 3DS verification)").option("--api-key <key>", "API Key for authentication").option("--type <type>", "Payment method type (default: card)", "card").option("--email <email>", "Email for 3DS verification").option("--card-number <number>", "Card number").option("--expiry <mmyy>", "Expiry date (MMYY format)").option("--cvv <cvv>", "Card CVV").option(
+  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(
+    "--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"
+  ).option(
+    "--email <email>",
+    "Manual mode: email for 3DS verification. Dropin mode: email used as the Drop-in session reference."
+  ).option("--card-number <number>", "Card number (manual mode only)").option("--expiry <mmyy>", "Expiry date (MMYY format) (manual mode only)").option("--cvv <cvv>", "Card CVV (manual mode only)").option(
     "--idempotency-key <key>",
-    "Idempotency key forwarded verbatim as the Idempotency-Key header"
+    "Idempotency key forwarded verbatim as the Idempotency-Key header (manual mode only)"
   );
   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"
-    });
-    const type = opts.type || "card";
-    const flags = {
-      email: opts.email,
-      cardNumber: opts.cardNumber,
-      expiry: opts.expiry,
-      cvv: opts.cvv
-    };
-    const params = await collectPaymentMethodParams(type, flags);
-    let idempotencyKey = opts.idempotencyKey;
-    if (!idempotencyKey) {
-      if (isYes) {
-        throw new IdempotencyKeyRequiredError("payment-methods add");
-      }
-      idempotencyKey = await PromptEngine.resolveInput(void 0, {
-        message: "Idempotency key (unique per write, for safe retry):",
-        validate: (v) => v.trim().length > 0 || "Idempotency key is required"
-      });
+    const mode = String(opts.mode ?? "manual").toLowerCase();
+    if (mode !== "manual" && mode !== "dropin") {
+      throw new CliError(
+        "PARAM_INVALID",
+        `Unknown --mode "${opts.mode}". Expected "manual" or "dropin".`
+      );
     }
-    const extraHeaders = {
-      "Idempotency-Key": idempotencyKey
-    };
-    const result = await deps.apiClient.post(
-      "/payment-methods/create",
-      { type: "api-key", key: apiKey },
-      params,
-      extraHeaders
-    );
-    if (!result.success) {
-      throw CliError.fromApi(result, { auth: "api-key" });
+    if (mode === "dropin") {
+      await handleDropinMode(deps, opts, format);
+      return;
     }
-    const pm = result.data;
-    notify(format, "success", "Payment method created");
-    const createdResult = {
-      data: pm,
-      text: () => {
-        const lines = [
-          ["ID", pm.id],
-          ["Type", pm.type],
-          ["Status", pm.status]
-        ];
-        if (pm.brand) lines.push(["Brand", pm.brand]);
-        if (pm.first6) lines.push(["First 6", pm.first6]);
-        if (pm.last4) lines.push(["Last 4", pm.last4]);
-        return Formatter.keyValue(lines);
-      }
-    };
-    const configManager = new ConfigManager();
-    await renderWithContext(createdResult, { format }, configManager);
-    notify(format, "info", "Complete 3DS verification via email to activate");
-    if (type === "card" && pm.status === "PENDING") {
-      const finalStatus = await poll3dsVerification(
-        deps.apiClient,
-        apiKey,
-        pm.id,
-        format
+    await handleManualMode(deps, opts, format, isYes);
+  });
+}
+async function handleManualMode(deps, opts, format, isYes) {
+  const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
+    message: "API Key:",
+    type: "password"
+  });
+  const type = opts.type || "card";
+  const flags = {
+    email: opts.email,
+    cardNumber: opts.cardNumber,
+    expiry: opts.expiry,
+    cvv: opts.cvv
+  };
+  const params = await collectPaymentMethodParams(type, flags);
+  let idempotencyKey = opts.idempotencyKey;
+  if (!idempotencyKey) {
+    if (isYes) {
+      throw new IdempotencyKeyRequiredError("payment-methods add");
+    }
+    idempotencyKey = await PromptEngine.resolveInput(void 0, {
+      message: "Idempotency key (unique per write, for safe retry):",
+      validate: (v) => v.trim().length > 0 || "Idempotency key is required"
+    });
+  }
+  const extraHeaders = {
+    "Idempotency-Key": idempotencyKey
+  };
+  const result = await deps.apiClient.post(
+    "/payment-methods/create",
+    { type: "api-key", key: apiKey },
+    params,
+    extraHeaders
+  );
+  if (!result.success) {
+    throw CliError.fromApi(result, { auth: "api-key" });
+  }
+  const pm = result.data;
+  notify(format, "success", "Payment method created");
+  const createdResult = {
+    data: pm,
+    text: () => {
+      const lines = [
+        ["ID", pm.id],
+        ["Type", pm.type],
+        ["Status", pm.status]
+      ];
+      if (pm.brand) lines.push(["Brand", pm.brand]);
+      if (pm.first6) lines.push(["First 6", pm.first6]);
+      if (pm.last4) lines.push(["Last 4", pm.last4]);
+      return Formatter.keyValue(lines);
+    }
+  };
+  const configManager = new ConfigManager();
+  await renderWithContext(createdResult, { format }, configManager);
+  notify(format, "info", "Complete 3DS verification via email to activate");
+  if (type === "card" && pm.status === "PENDING") {
+    const finalStatus = await poll3dsVerification(deps.apiClient, apiKey, pm.id, format);
+    if (finalStatus === "ACTIVE") {
+      const getResult = await deps.apiClient.get(
+        `/payment-methods/${pm.id}`,
+        { type: "api-key", key: apiKey }
       );
-      if (finalStatus === "ACTIVE") {
-        const getResult = await deps.apiClient.get(
-          `/payment-methods/${pm.id}`,
-          { type: "api-key", key: apiKey }
-        );
-        if (getResult.success) {
-          const activatedPm = getResult.data;
-          notify(format, "success", "Payment method activated");
-          const activatedResult = {
-            data: activatedPm,
-            text: () => {
-              const lines = [
-                ["ID", activatedPm.id],
-                ["Type", activatedPm.type],
-                ["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);
-        } else {
-          notify(format, "success", "Payment method activated");
-          const degraded = { ...pm, status: "ACTIVE" };
-          const degradedResult = {
-            data: degraded,
-            text: () => {
-              const lines = [
-                ["ID", degraded.id],
-                ["Type", degraded.type],
-                ["Status", degraded.status]
-              ];
-              if (degraded.brand) lines.push(["Brand", degraded.brand]);
-              if (degraded.first6) lines.push(["First 6", degraded.first6]);
-              if (degraded.last4) lines.push(["Last 4", degraded.last4]);
-              return Formatter.keyValue(lines);
-            }
-          };
-          await renderWithContext(degradedResult, { format }, configManager);
-        }
-      } else if (finalStatus === "FAILED") {
-        notify(format, "error", "3DS verification failed");
-      } else if (finalStatus === "TIMEOUT") {
-        notify(
-          format,
-          "info",
-          `Verification timed out (15 min). Check status with: agenzo-token-cli payment-methods get ${pm.id} --api-key <your_key>`
-        );
+      if (getResult.success) {
+        const activatedPm = getResult.data;
+        notify(format, "success", "Payment method activated");
+        const activatedResult = {
+          data: activatedPm,
+          text: () => {
+            const lines = [
+              ["ID", activatedPm.id],
+              ["Type", activatedPm.type],
+              ["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);
+      } else {
+        notify(format, "success", "Payment method activated");
+        const degraded = { ...pm, status: "ACTIVE" };
+        const degradedResult = {
+          data: degraded,
+          text: () => {
+            const lines = [
+              ["ID", degraded.id],
+              ["Type", degraded.type],
+              ["Status", degraded.status]
+            ];
+            if (degraded.brand) lines.push(["Brand", degraded.brand]);
+            if (degraded.first6) lines.push(["First 6", degraded.first6]);
+            if (degraded.last4) lines.push(["Last 4", degraded.last4]);
+            return Formatter.keyValue(lines);
+          }
+        };
+        await renderWithContext(degradedResult, { format }, configManager);
       }
+    } else if (finalStatus === "FAILED") {
+      notify(format, "error", "3DS verification failed");
+    } else if (finalStatus === "TIMEOUT") {
+      notify(
+        format,
+        "info",
+        `Verification timed out (15 min). Check status with: agenzo-token-cli payment-methods get ${pm.id} --api-key <your_key>`
+      );
     }
+  }
+}
+async function handleDropinMode(deps, opts, format) {
+  const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
+    message: "API Key:",
+    type: "password"
+  });
+  const email = await PromptEngine.resolveInput(opts.email, {
+    message: "Email:"
   });
+  const configManager = new ConfigManager();
+  const sessionResult = await deps.apiClient.post(
+    "/payment-methods/dropin/create",
+    { type: "api-key", key: apiKey },
+    { email }
+  );
+  if (!sessionResult.success) {
+    throw CliError.fromApi(sessionResult, { auth: "api-key" });
+  }
+  const session = sessionResult.data;
+  const pmId = session.id;
+  notify(format, "success", "Drop-in session created");
+  const createdResult = {
+    data: session,
+    text: () => Formatter.keyValue([["Session ID", session.session_id || "-"]])
+  };
+  await renderWithContext(createdResult, { format }, configManager);
+  notify(
+    format,
+    "info",
+    "Use the Session ID to add the payment method in the browser via the Drop-in SDK"
+  );
+  const finalPm = await pollVerificationStatus(deps.apiClient, apiKey, pmId, {
+    intervalMs: DROPIN_POLL_INTERVAL_MS,
+    timeoutMs: DROPIN_POLL_TIMEOUT_MS
+  });
+  if (finalPm.status === "ACTIVE") {
+    notify(format, "success", "Payment method activated");
+    const activated = {
+      data: finalPm,
+      text: () => Formatter.keyValue([
+        ["PM ID", finalPm.id],
+        ["Brand", finalPm.brand ?? "-"],
+        ["First 6", finalPm.first6 ?? "-"],
+        ["Last 4", finalPm.last4 ?? "-"],
+        ["Status", finalPm.status]
+      ])
+    };
+    await renderWithContext(activated, { format }, configManager);
+    return;
+  }
+  if (finalPm.status === "FAILED") {
+    notify(format, "error", "Failed to add payment method");
+    await renderPmId(finalPm.id, format, configManager);
+    process.exitCode = 1;
+    return;
+  }
+  if (finalPm.status === "EXPIRED") {
+    notify(format, "error", "Session expired before the payment method was added");
+    await renderPmId(finalPm.id, format, configManager);
+    process.exitCode = 1;
+    return;
+  }
+  notify(
+    format,
+    "error",
+    "Adding payment method did not complete within 30 minutes. Re-run with the same email to resume."
+  );
+  await renderPmId(pmId, format, configManager);
+  process.exitCode = 1;
+}
+async function renderPmId(id, format, configManager) {
+  const result = {
+    data: { id },
+    text: () => Formatter.keyValue([["PM ID", id]])
+  };
+  await renderWithContext(result, { format }, configManager);
 }
 async function poll3dsVerification(apiClient, apiKey, paymentMethodId, format) {
   const startTime = Date.now();
   notify(format, "info", "Waiting for 3DS verification...");
-  while (Date.now() - startTime < POLL_TIMEOUT_MS) {
-    await sleep(POLL_INTERVAL_MS);
+  while (Date.now() - startTime < MANUAL_POLL_TIMEOUT_MS) {
+    await sleep(MANUAL_POLL_INTERVAL_MS);
     const result = await apiClient.get(
       "/payment-methods/verification/status",
       { type: "api-key", key: apiKey },
@@ -891,6 +986,21 @@ async function poll3dsVerification(apiClient, apiKey, paymentMethodId, format) {
   }
   return "TIMEOUT";
 }
+async function pollVerificationStatus(apiClient, apiKey, pmId, options) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < options.timeoutMs) {
+    const result = await apiClient.get(
+      "/payment-methods/verification/status",
+      { type: "api-key", key: apiKey },
+      { payment_method_id: pmId }
+    );
+    if (result.success && TERMINAL_STATUSES.has(result.data.status)) {
+      return result.data;
+    }
+    await sleep(options.intervalMs);
+  }
+  return { id: pmId, status: "PENDING" };
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }