@agenzo/token-cli 0.3.0 → 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)
-```