@bankofai/x402-cli 1.0.1-beta.4 → 1.0.1-beta.5

package/README.md

@@ -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
+x402-cli --version
+```
+
+For repository development:
+
 ```bash
 npm install
 npm run build
@@ -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
 
@@ -75,6 +84,9 @@ node dist/cli.js pay http://127.0.0.1:4020/pay \
   --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):
 
@@ -90,6 +102,12 @@ Use `--gasfree-api-url <url>` or `X402_GASFREE_API_URL` to override the SDK's
 default relayer endpoint.
 
 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
 

package/dist/cli.js

@@ -18,11 +18,13 @@ class CliError extends Error {
     code;
     hint;
     exitCode;
-    constructor(code, message, hint, exitCode = 1) {
+    details;
+    constructor(code, message, hint, exitCode = 1, details) {
         super(message);
         this.code = code;
         this.hint = hint;
         this.exitCode = exitCode;
+        this.details = details;
     }
 }
 function parseArgs(argv) {
@@ -144,6 +146,8 @@ function emit(args) {
         process.stderr.write(`  ${args.error.message}\n`);
         if (args.error.hint)
             process.stderr.write(`  hint: ${args.error.hint}\n`);
+        if (args.error.details !== undefined)
+            process.stderr.write(`  details: ${JSON.stringify(args.error.details)}\n`);
         return;
     }
     const suffix = [args.network, args.scheme].filter(Boolean).join(" ");
@@ -171,6 +175,7 @@ function classify(error) {
             code: error.code,
             message,
             hint: error.hint,
+            details: error.details,
         };
     }
     const lower = message.toLowerCase();
@@ -737,7 +742,7 @@ async function fetchWithTimeout(input, init = {}, timeout = DEFAULT_TIMEOUT_MS,
         return await fetch(input, { ...init, signal: controller.signal });
     }
     catch (error) {
-        if (error?.name === "AbortError")
+        if (error instanceof Error && error.name === "AbortError")
             throw new Error(`${label} timed out after ${timeout}ms`);
         throw error;
     }
@@ -1182,7 +1187,13 @@ function selectRequirement(accepts, options) {
         if (scheme && scheme !== req.scheme)
             return false;
         if (token) {
-            const tokenInfo = getToken(req.network, token);
+            let tokenInfo;
+            try {
+                tokenInfo = getToken(req.network, token);
+            }
+            catch {
+                return false;
+            }
             if (tokenInfo.address.toLowerCase() !== req.asset.toLowerCase())
                 return false;
         }
@@ -1266,7 +1277,9 @@ async function pay(url, options) {
     };
     if (!paid.ok) {
         const retryAfter = paid.headers.get("retry-after");
-        throw new Error(`HTTP ${paid.status} from ${url}${retryAfter ? ` (retry after ${retryAfter}s)` : ""}: ${typeof body === "string" ? body.slice(0, 500) : JSON.stringify(body).slice(0, 500)}`);
+        throw new CliError(paid.status === 429 ? "RATE_LIMITED" : "HTTP_ERROR", `HTTP ${paid.status} from ${url}${retryAfter ? ` (retry after ${retryAfter}s)` : ""}: ${typeof body === "string" ? body.slice(0, 500) : JSON.stringify(body).slice(0, 500)}`, paymentResponse
+            ? "The gateway reports that payment was settled; retain paymentResponse for support or reconciliation."
+            : "Inspect the HTTP response and retry only when it is safe to do so.", 1, result);
     }
     emit({
         command: "client",
@@ -1278,8 +1291,7 @@ async function pay(url, options) {
 }
 async function roundtrip(options) {
     const port = Number(opt(options, "port", "4020"));
-    serve(options);
-    await delay(500);
+    await serve(options);
     await pay(`http://127.0.0.1:${port}/pay`, options);
     process.exit(0);
 }

package/dist/gateway/config.js

@@ -104,15 +104,21 @@ export function loadProvider(file) {
     validateProvider(config, file);
     config.operator.network = normalizeNetwork(config.operator.network);
     normalizePaymentProtocol(config, file);
+    const facilitatorUrl = config.operator.facilitator_url ||
+        process.env.X402_FACILITATOR_URL ||
+        process.env.FACILITATOR_URL ||
+        "https://facilitator.bankofai.io";
+    assertHttpUrl(facilitatorUrl, `${file}: facilitator URL`);
+    const configuredApiKeyEnv = config.operator.facilitator_api_key_env;
+    if (configuredApiKeyEnv && !process.env[configuredApiKeyEnv]) {
+        throw new Error(`${file}: environment variable ${configuredApiKeyEnv} is not set`);
+    }
     return {
         config,
-        facilitatorUrl: config.operator.facilitator_url ||
-            process.env.X402_FACILITATOR_URL ||
-            process.env.FACILITATOR_URL ||
-            "https://facilitator.bankofai.io",
+        facilitatorUrl,
         facilitatorApiKey: config.operator.facilitator_api_key ||
-            (config.operator.facilitator_api_key_env
-                ? process.env[config.operator.facilitator_api_key_env]
+            (configuredApiKeyEnv
+                ? process.env[configuredApiKeyEnv]
                 : undefined) ||
             process.env.X402_FACILITATOR_API_KEY ||
             process.env.FACILITATOR_API_KEY,

package/dist/gateway/server.js

@@ -18,9 +18,20 @@ class RequestTooLargeError extends HttpError {
         super(413, "request body too large");
     }
 }
-const MAX_BODY_BYTES = Number(process.env.X402_GATEWAY_MAX_BODY_BYTES ?? 1_000_000);
-const FACILITATOR_TIMEOUT_MS = Number(process.env.X402_GATEWAY_FACILITATOR_TIMEOUT_MS ?? 10_000);
-const UPSTREAM_TIMEOUT_MS = Number(process.env.X402_GATEWAY_UPSTREAM_TIMEOUT_MS ?? 30_000);
+function positiveIntegerEnv(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    if (!/^\d+$/.test(raw))
+        throw new Error(`${name} must be a positive integer`);
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${name} must be a positive integer`);
+    return value;
+}
+const MAX_BODY_BYTES = positiveIntegerEnv("X402_GATEWAY_MAX_BODY_BYTES", 1_000_000);
+const FACILITATOR_TIMEOUT_MS = positiveIntegerEnv("X402_GATEWAY_FACILITATOR_TIMEOUT_MS", 10_000);
+const UPSTREAM_TIMEOUT_MS = positiveIntegerEnv("X402_GATEWAY_UPSTREAM_TIMEOUT_MS", 30_000);
 const STRIP_REQUEST_HEADERS = new Set([
     "host",
     "connection",
@@ -48,14 +59,22 @@ const STRIP_RESPONSE_HEADERS = new Set([
     "authorization",
     "proxy-authorization",
     "set-cookie",
+    "payment-required",
+    "x-payment-required",
+    "payment-signature",
+    "x-payment",
+    "payment-response",
+    "x-payment-response",
 ]);
-const metrics = {
-    requests: 0,
-    paidRequests: 0,
-    verifyFailures: 0,
-    settleFailures: 0,
-    upstreamFailures: 0,
-};
+function createMetrics() {
+    return {
+        requests: 0,
+        paidRequests: 0,
+        verifyFailures: 0,
+        settleFailures: 0,
+        upstreamFailures: 0,
+    };
+}
 async function readBody(request) {
     const chunks = [];
     let total = 0;
@@ -79,7 +98,7 @@ async function fetchWithTimeout(url, init, timeoutMs, label = "upstream") {
         return await fetch(url, { ...init, signal: controller.signal });
     }
     catch (error) {
-        if (error?.name === "AbortError")
+        if (error instanceof Error && error.name === "AbortError")
             throw new HttpError(504, `${label} request timed out`);
         throw error;
     }
@@ -112,12 +131,25 @@ async function facilitatorPost(entry, path, body) {
     }
     return data;
 }
-function resourceUrl(url) {
+function configuredPublicBaseUrl() {
+    const value = process.env.X402_GATEWAY_PUBLIC_BASE_URL?.trim();
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol))
+            throw new Error("unsupported protocol");
+        return `${value.replace(/\/+$/, "")}/`;
+    }
+    catch {
+        throw new Error("X402_GATEWAY_PUBLIC_BASE_URL must be a valid http(s) URL");
+    }
+}
+function resourceUrl(url, publicBaseUrl) {
     const path = `${url.pathname}${url.search}`;
-    const publicBaseUrl = process.env.X402_GATEWAY_PUBLIC_BASE_URL?.trim();
     if (!publicBaseUrl)
         return path;
-    return new URL(path, `${publicBaseUrl.replace(/\/+$/, "")}/`).toString();
+    return new URL(path, publicBaseUrl).toString();
 }
 function logFacilitatorFailure(entry, path, response, body, data) {
     const requirement = body?.paymentRequirements;
@@ -205,7 +237,7 @@ function upstreamUrl(entry, request, routePath) {
     }
     return upstream;
 }
-async function forward(entry, request, response, routePath, body, paymentResponse) {
+async function forward(metrics, entry, request, response, routePath, body, paymentResponse) {
     const upstream = upstreamUrl(entry, request, routePath);
     let upstreamResponse;
     try {
@@ -229,10 +261,13 @@ async function forward(entry, request, response, routePath, body, paymentRespons
     });
     if (paymentResponse)
         responseHeaders[headers.response] = encodeResponse(paymentResponse);
+    const responseBody = Buffer.from(await upstreamResponse.arrayBuffer());
     response.writeHead(upstreamResponse.status, responseHeaders);
-    response.end(Buffer.from(await upstreamResponse.arrayBuffer()));
+    response.end(responseBody);
 }
 export function createGatewayServer(providers) {
+    const publicBaseUrl = configuredPublicBaseUrl();
+    const metrics = createMetrics();
     return http.createServer(async (request, response) => {
         try {
             metrics.requests += 1;
@@ -302,7 +337,7 @@ export function createGatewayServer(providers) {
             const body = await readBody(request);
             const requirements = paymentRequirements(entry.config, priceUsd(endpoint, requestParams(url, body, request)));
             if (!requirements.length) {
-                await forward(entry, request, response, routePath, body);
+                await forward(metrics, entry, request, response, routePath, body);
                 return;
             }
             const paymentHeader = request.headers[headers.signature.toLowerCase()];
@@ -311,7 +346,7 @@ export function createGatewayServer(providers) {
                 const challenge = {
                     x402Version: 2,
                     error: "Payment required",
-                    resource: { url: resourceUrl(url) },
+                    resource: { url: resourceUrl(url, publicBaseUrl) },
                     accepts,
                 };
                 json(response, 402, challenge, { [headers.required]: encodeRequired(challenge) });
@@ -356,7 +391,20 @@ export function createGatewayServer(providers) {
                 return;
             }
             metrics.paidRequests += 1;
-            await forward(entry, request, response, routePath, body, settle);
+            try {
+                await forward(metrics, entry, request, response, routePath, body, settle);
+            }
+            catch (error) {
+                const status = error instanceof HttpError ? error.status : 502;
+                const extraHeaders = error instanceof HttpError ? error.responseHeaders : {};
+                json(response, status, {
+                    error: "upstream failed after payment settlement",
+                    settled: true,
+                }, {
+                    ...extraHeaders,
+                    [headers.response]: encodeResponse(settle),
+                });
+            }
         }
         catch (error) {
             if (error instanceof HttpError) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-cli",
-  "version": "1.0.1-beta.4",
+  "version": "1.0.1-beta.5",
   "type": "module",
   "files": [
     "dist"
@@ -22,7 +22,7 @@
   "dependencies": {
     "@bankofai/x402-core": "1.0.1-beta.4",
     "@bankofai/x402-evm": "1.0.1-beta.4",
-    "@bankofai/x402-gateway": "1.0.1-beta.4",
+    "@bankofai/x402-gateway": "1.0.1-beta.5",
     "@bankofai/x402-tron": "1.0.1-beta.4",
     "tronweb": "6.4.0",
     "viem": "^2.55.0",
@@ -32,5 +32,8 @@
     "@types/node": "^24.10.1",
     "tsx": "^4.20.6",
     "typescript": "^5.9.3"
+  },
+  "overrides": {
+    "ws": "8.21.0"
   }
 }