@agenzo/token-cli 0.1.2

package/README.md

@@ -0,0 +1,190 @@
+# @agenzo/token-cli
+
+> 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.
+
+Binary: `agenzo-token-cli` ｜ Auth: API Key (`X-Api-Key`)
+
+## Installation
+
+```bash
+npm install -g @agenzo/token-cli
+```
+
+The `agenzo-token-cli` command is available after installation. Requires Node.js ≥ 18.
+
+## Authentication
+
+token-cli is a **runtime-plane** tool. Every command authenticates with `--api-key <api_key>` (prompted interactively when omitted).
+
+API Keys are issued by the control-plane tool [`agenzo-admin-cli`](https://www.npmjs.com/package/@agenzo/admin-cli):
+
+```bash
+agenzo-admin-cli keys create --developer-id <dev_id> --key-name "Prod Key" --scope token
+```
+
+- The key's scope must include `token`, otherwise calls return `KEY_SCOPE_DENIED`.
+- API Keys and admin-cli's Bearer Token are **not interchangeable**.
+
+## Environment configuration
+
+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 show                                       # show current host / path
+```
+
+## Global options
+
+| 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) |
+| `--verbose` | Print verbose logs to stderr |
+| `--version` | Print the CLI version |
+
+> Prompts and logs for write operations go to stderr; under `--format json`, stdout emits structured data only. Exit code `0` on success, `1`–`5` for different error categories.
+
+## Command matrix
+
+| Noun | Verb | Purpose | Write/Read |
+|---|---|---|---|
+| `payment-methods` | `add` | Add a payment method, then auto-poll 3DS verification (up to 15 min) | 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 |
+| `payment-tokens` | `create` | Issue a payment token (VCN / Network Token / X402, pick one) | W |
+| `payment-tokens` | `list` | List payment tokens under the current API Key | R |
+| `payment-tokens` | `get <payment_token_id>` | Show details of a single payment token | R |
+| `payment-tokens` | `revoke <payment_token_id>` | Revoke a payment token (X402 uses delayed revocation) | W |
+
+## payment-methods
+
+### add — add a payment method + 3DS verification
+
+```bash
+agenzo-token-cli payment-methods add \
+  --api-key <api_key> \
+  --type card \
+  --email user@example.com \
+  --card-number 4111111111111234 \
+  --expiry 1230 \
+  --cvv 123
+```
+
+| Flag | Required | Description |
+|---|---|---|
+| `--api-key` | Yes | Prompted interactively when omitted |
+| `--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 |
+
+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`.
+
+### list
+
+```bash
+agenzo-token-cli payment-methods list --api-key <api_key> [--member <member_id>]
+```
+
+Outputs a table of `ID / Type / Brand / First 6 / Last 4 / Status`; prints `No payment methods found` when empty.
+
+### get
+
+```bash
+agenzo-token-cli payment-methods get <pm_id> --api-key <api_key>
+```
+
+### disable
+
+```bash
+agenzo-token-cli payment-methods disable <pm_id> --api-key <api_key> [--idempotency-key <key>]
+```
+
+Disables the payment method and cascades to revoke its issued payment tokens, printing `Status` and the `Revoked tokens` count. `--idempotency-key` is required in `--yes` mode.
+
+## payment-tokens
+
+### create — issue a payment token
+
+The three types branch via `--type`: `vcn` / `network-token` / `x402`.
+
+```bash
+# VCN (Virtual Card Number)
+agenzo-token-cli payment-tokens create \
+  --api-key <api_key> --type vcn \
+  --payment-method-id <pm_id> \
+  --amount 25.00 \
+  --idempotency-key <unique_key>
+
+# Network Token
+agenzo-token-cli payment-tokens create \
+  --api-key <api_key> --type network-token \
+  --card 1234 \
+  --idempotency-key <unique_key>
+
+# X402 (on-chain USDC payment signature)
+agenzo-token-cli payment-tokens create \
+  --api-key <api_key> --type x402 \
+  --payment-method-id <pm_id> \
+  --amount 1.50 --pay-to 0x... --nonce <n> --network base-sepolia --deadline <unix_ts> \
+  --idempotency-key <unique_key>
+```
+
+| Flag | Applies to | Description |
+|---|---|---|
+| `--api-key` | all | Prompted interactively when omitted |
+| `--type` | all | `vcn` / `network-token` / `x402` |
+| `--payment-method-id` | vcn / network-token | One of this or `--card`; takes priority over `--card` |
+| `--card` | vcn / network-token | Match a payment method by its last 4 digits |
+| `--member` | all | Associate a member (optional) |
+| `--amount` | vcn / x402 | VCN: USD (`0.01`–`500.00`); X402: USDC amount |
+| `--currency` | vcn | Omitted by default; the server applies its default currency |
+| `--pay-to` / `--nonce` / `--network` / `--deadline` | x402 | Required X402 quadruple; `--deadline` is a Unix timestamp |
+| `--external-tx-id` | all | Forwarded to the request body as `external_tx_id` (optional) |
+| `--idempotency-key` | all | **Required**; forwarded verbatim as the `Idempotency-Key` HTTP header, retrying the same key returns the first result |
+
+> Before writing, the freeze amount and service fee are shown and confirmation is requested; `--yes` skips confirmation (in which case `--idempotency-key` must be supplied explicitly).
+
+### list
+
+```bash
+agenzo-token-cli payment-tokens list --api-key <api_key> [--type <type>] [--member <member_id>]
+```
+
+### get
+
+```bash
+agenzo-token-cli payment-tokens get <payment_token_id> --api-key <api_key>
+```
+
+### revoke
+
+```bash
+agenzo-token-cli payment-tokens revoke <payment_token_id> --api-key <api_key> [--idempotency-key <key>]
+```
+
+Revokes immediately and prints `REVOKED` plus the revocation time; X402 tokens use delayed revocation (the cryptogram expires naturally), printing `ACTIVE` plus the expiry time. `--idempotency-key` is required in `--yes` mode.
+
+## Output and errors
+
+- **Success**: `table` mode prints human-readable 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`).
+
+Common error codes: `KEY_INVALID` (invalid API Key), `KEY_SCOPE_DENIED` (scope lacks `token`), `TOKEN_FEATURE_DISABLED` (token type not enabled), `PARAM_IDEMPOTENCY_KEY_REQUIRED` (missing `--idempotency-key`), `CLIENT_NO_PAYMENT_METHOD` / `CLIENT_CARD_NOT_MATCHED` (no usable payment method matched locally).
+
+## 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.d.ts

@@ -0,0 +1,2 @@
+
+export {  }