@bankofai/x402-cli 1.0.1-beta.0 → 1.0.1-beta.10

package/README.md

@@ -3,9 +3,9 @@
 TypeScript command-line client for BankofAI x402 payments. This version uses
 the npm TypeScript SDK packages only:
 
-- `@bankofai/x402-core@1.0.1-beta.2`
-- `@bankofai/x402-evm@1.0.1-beta.2`
-- `@bankofai/x402-tron@1.0.1-beta.2`
+- `@bankofai/x402-core@1.0.1`
+- `@bankofai/x402-evm@1.0.1`
+- `@bankofai/x402-tron@1.0.1`
 
 Stablecoin payments support `scheme=exact` and TRON `scheme=exact_gasfree`.
 The GasFree flow lets the relayer pay network energy while deducting its fee
@@ -13,6 +13,15 @@ from the payment token, so the payer does not need TRX.
 
 ## Install
 
+Install the CLI package:
+
+```bash
+npm install -g @bankofai/x402-cli@beta
+x402-cli --version
+```
+
+For repository development:
+
 ```bash
 npm install
 npm run build
@@ -21,7 +30,7 @@ npm run build
 Run from source during development:
 
 ```bash
-npm run dev -- serve --pay-to <recipient> --amount 0.0001 --network tron:nile --token USDT
+npm run dev -- serve --pay-to <recipient> --amount 0.0001 --network tron:0xcd8690dc --token USDT
 ```
 
 Run the compiled CLI:
@@ -49,10 +58,10 @@ envelope with `ok`, `command`, `result`, or structured `error` fields.
 Start a local x402 paywall endpoint:
 
 ```bash
-node dist/cli.js serve \
+x402-cli serve \
   --pay-to <recipient> \
   --amount 0.0001 \
-  --network tron:nile \
+  --network tron:0xcd8690dc \
   --token USDT \
   --port 4020
 ```
@@ -61,8 +70,8 @@ The server exposes:
 
 - `GET /health`
 - `GET /.well-known/x402`
-- `GET /pay` returns `402 Payment Required`
-- `POST /pay` verifies and settles with the facilitator
+- `/pay` returns `402 Payment Required` without a payment signature
+- The signed retry uses the same HTTP method, then verifies and settles with the facilitator
 
 ### Pay
 
@@ -70,18 +79,21 @@ Pay an x402-protected URL:
 
 ```bash
 TRON_PRIVATE_KEY=<hex> \
-node dist/cli.js pay http://127.0.0.1:4020/pay \
-  --network tron:nile \
+x402-cli pay http://127.0.0.1:4020/pay \
+  --network tron:0xcd8690dc \
   --token USDT
 ```
 
+For automated or unfamiliar endpoints, set `--max-amount` or
+`--max-raw-amount` before allowing the CLI to sign a payment.
+
 Pay a TRON GasFree endpoint (the CLI normally selects this automatically from
 the server challenge):
 
 ```bash
 TRON_PRIVATE_KEY=<hex> \
-node dist/cli.js pay https://api.example.com/pay \
-  --network tron:nile \
+x402-cli pay https://api.example.com/pay \
+  --network tron:0xcd8690dc \
   --token USDT \
   --scheme exact_gasfree
 ```
@@ -89,7 +101,31 @@ node dist/cli.js pay https://api.example.com/pay \
 Use `--gasfree-api-url <url>` or `X402_GASFREE_API_URL` to override the SDK's
 default relayer endpoint.
 
+GasFree fees are separate from the advertised payment amount. Set a fee limit
+so the CLI estimates the relayer fee and rejects the payment before signing if
+the estimate is too high:
+
+```bash
+x402-cli pay https://api.example.com/pay \
+  --scheme exact_gasfree \
+  --max-amount 0.01 \
+  --max-gasfree-fee 0.5 \
+  --json
+```
+
+Use `--max-gasfree-fee-raw` to express the fee limit in the token's smallest
+unit. Successful and failed paid responses distinguish `settled` (payment
+completed) from `delivered` (HTTP business response succeeded). A settled
+upstream failure has `paid=true`, `settled=true`, and `delivered=false` and
+includes its transaction information.
+
 For EVM networks use `EVM_PRIVATE_KEY` or `PRIVATE_KEY`.
+Prefer environment variables over `--private-key` in shared environments,
+because command-line arguments may be visible to other local processes.
+
+If the gateway settles a payment but the upstream request fails, JSON error
+output includes `error.details.paymentResponse` for reconciliation. Do not retry
+such a request blindly; inspect the transaction and provider behavior first.
 
 ### Roundtrip
 
@@ -97,10 +133,10 @@ Start a temporary local server and immediately pay it:
 
 ```bash
 TRON_PRIVATE_KEY=<hex> \
-node dist/cli.js roundtrip \
+x402-cli roundtrip \
   --pay-to <recipient> \
   --amount 0.0001 \
-  --network tron:nile \
+  --network tron:0xcd8690dc \
   --token USDT
 ```
 
@@ -108,16 +144,16 @@ node dist/cli.js roundtrip \
 
 Supported built-in token registry:
 
-- `tron:mainnet` USDT, USDD
-- `tron:nile` USDT, USDD
-- `tron:shasta` USDT
+- `tron:0x2b6653dc` USDT, USDD
+- `tron:0xcd8690dc` USDT, USDD
+- `tron:0x94a9059e` USDT
 - `eip155:56` USDT
 - `eip155:97` USDT, USDC
 
-Aliases accepted:
+Non-CAIP TRON aliases are rejected. Use the canonical TRON IDs above.
+
+EVM convenience aliases accepted:
 
-- `tron-mainnet` -> `tron:mainnet`
-- `tron-nile` -> `tron:nile`
 - `bsc-mainnet` -> `eip155:56`
 - `bsc-testnet` -> `eip155:97`
 

package/dist/args.js

@@ -0,0 +1,96 @@
+const BOOLEAN_FLAGS = new Set([
+    "daemon", "dry-run", "force", "help", "human", "include-blocked", "json", "raw", "version",
+]);
+export class CliError extends Error {
+    code;
+    hint;
+    exitCode;
+    details;
+    constructor(code, message, hint, exitCode = 1, details) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export function parseArgs(argv) {
+    const [command = "help", ...rest] = argv;
+    const positional = [];
+    const options = {};
+    for (let i = 0; i < rest.length; i += 1) {
+        const item = rest[i];
+        if (item === "-h") {
+            options.help = true;
+            continue;
+        }
+        if (item === "-V") {
+            options.version = true;
+            continue;
+        }
+        if (item === "-d") {
+            options.daemon = true;
+            continue;
+        }
+        if (item === "-n") {
+            const next = rest[i + 1];
+            if (!next || next.startsWith("-"))
+                options.limit = true;
+            else {
+                options.limit = next;
+                i += 1;
+            }
+            continue;
+        }
+        if (!item.startsWith("--")) {
+            positional.push(item);
+            continue;
+        }
+        const eq = item.indexOf("=");
+        const key = eq > 2 ? item.slice(2, eq) : item.slice(2);
+        const inline = eq > 2 ? item.slice(eq + 1) : undefined;
+        const next = rest[i + 1];
+        if (inline !== undefined)
+            options[key] = inline;
+        else if (BOOLEAN_FLAGS.has(key))
+            options[key] = true;
+        else if (!next || next.startsWith("--")) {
+            throw new CliError("MISSING_ARGUMENT", `--${key} requires a value`, `Pass --${key} <value>.`, 2);
+        }
+        else {
+            if (key === "header") {
+                const current = options[key];
+                options[key] = Array.isArray(current) ? [...current, next] : current ? [String(current), next] : [next];
+            }
+            else
+                options[key] = next;
+            i += 1;
+        }
+    }
+    return { command, positional, options };
+}
+export function opt(options, key, fallback) {
+    const value = options[key];
+    return typeof value === "string" ? value : fallback;
+}
+export function hasFlag(options, key) {
+    return options[key] === true;
+}
+export function outputMode(options) {
+    if (hasFlag(options, "json") && hasFlag(options, "human")) {
+        throw new CliError("INVALID_ARGUMENT", "--json and --human are mutually exclusive", "Pass either --json or --human, not both.", 2);
+    }
+    return hasFlag(options, "json") ? "json" : "human";
+}
+export function requireArgument(value, name, usage) {
+    if (value === undefined || value === "") {
+        throw new CliError("MISSING_ARGUMENT", `${name} is required`, `Usage: ${usage}`, 2);
+    }
+    return value;
+}
+export function optAll(options, key) {
+    const value = options[key];
+    if (Array.isArray(value))
+        return value;
+    return typeof value === "string" ? [value] : [];
+}