npm - @bankofai/x402-cli - Versions diffs - 1.0.0-beta.5 → 1.0.0-beta.7 - Mend

@bankofai/x402-cli 1.0.0-beta.5 → 1.0.0-beta.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/cli.js CHANGED Viewed

@@ -10,8 +10,19 @@ import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import { createPaymentPayload, decodeRequired, decodeResponse, decodeSignature, encodeRequired, encodeResponse, encodeSignature, headers } from "./x402.js";
 import { assertRawAmount, findTokenByAddress, getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
-const BOOLEAN_FLAGS = new Set(["daemon", "dry-run", "force", "help", "human", "include-blocked", "json", "version"]);
+const BOOLEAN_FLAGS = new Set(["daemon", "dry-run", "force", "help", "human", "include-blocked", "json", "raw", "version"]);
 const require = createRequire(import.meta.url);
+class CliError extends Error {
+    code;
+    hint;
+    exitCode;
+    constructor(code, message, hint, exitCode = 1) {
+        super(message);
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+    }
+}
 function parseArgs(argv) {
     const [command = "help", ...rest] = argv;
     const positional = [];
@@ -88,8 +99,17 @@ function hasFlag(options, key) {
     return options[key] === true;
 }
 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";
 }
+function requireArgument(value, name, usage) {
+    if (value === undefined || value === "") {
+        throw new CliError("MISSING_ARGUMENT", `${name} is required`, `Usage: ${usage}`, 2);
+    }
+    return value;
+}
 function optAll(options, key) {
     const value = options[key];
     if (Array.isArray(value))
@@ -144,6 +164,13 @@ function emit(args) {
 }
 function classify(error) {
     const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof CliError) {
+        return {
+            code: error.code,
+            message,
+            hint: error.hint,
+        };
+    }
     const lower = message.toLowerCase();
     if (lower.includes("missing private key") || lower.includes("could not find a wallet")) {
         return {
@@ -243,6 +270,13 @@ function classify(error) {
             hint: "Check the URL, local server, proxy, and network connectivity.",
         };
     }
+    if (lower.includes(" is required") || lower.includes("must be") || lower.includes("invalid --") || lower.includes("mutually exclusive")) {
+        return {
+            code: lower.includes("required") ? "MISSING_ARGUMENT" : "INVALID_ARGUMENT",
+            message,
+            hint: "Run the command with --help to see valid usage and options.",
+        };
+    }
     return {
         code: "IO_ERROR",
         message,
@@ -275,24 +309,28 @@ Global options:
 Options:
   --method <method>         HTTP method (default: GET)
   --header "Name: Value"    Request header, repeatable
-  --body <body>             Request body for non-GET methods
+  --body <body>             Request body for non-GET/HEAD methods
   --network <caip2>         Require a specific network
   --token <symbol>          Require a specific token
   --scheme <scheme>         Require a specific x402 scheme
   --max-amount <amount>     Maximum human-readable payment amount
-  --max-rawAmount <amount>  Maximum smallest-unit payment amount
+  --max-raw-amount <amount> Maximum smallest-unit payment amount
   --dry-run                 Read requirements but do not sign or pay
-  --private-key <hex>       Explicit payer private key
+  --private-key <hex>       Explicit payer private key (or PRIVATE_KEY/TRON_PRIVATE_KEY/EVM_PRIVATE_KEY)
   --rpc-url <url>           Explicit network RPC URL
   --json                    Print JSON envelope
+Examples:
+  x402-cli pay https://api.example.com/paid --dry-run --json
+  x402-cli pay https://api.example.com/paid --max-amount 0.01
 `,
         serve: `Usage:
   x402-cli serve --pay-to <address> [options]
 Options:
   --pay-to <address>        Recipient wallet address
-  --amount <amount>         Human-readable token amount
-  --rawAmount <amount>      Smallest-unit amount
+  --amount <amount>         Human-readable token amount (default: 0.0001)
+  --raw-amount <amount>     Smallest-unit amount
   --network <caip2>         Payment network (default: tron:nile)
   --token <symbol>          Token symbol (default: USDT)
   --asset <address>         Explicit token address
@@ -303,6 +341,10 @@ Options:
   --facilitator-url <url>   Facilitator base URL
   --daemon                  Run in background and print the child pid
   --json                    Print JSON envelope
+Examples:
+  x402-cli serve --pay-to T... --network tron:nile --token USDT
+  x402-cli serve --pay-to 0x... --network eip155:97 --token USDT --amount 0.0001
 `,
         roundtrip: `Usage:
   x402-cli roundtrip --pay-to <address> [serve/pay options]
@@ -316,6 +358,15 @@ Commands:
   check <providers>         Validate provider.yml files
   scaffold <name>           Write a starter provider.yml
   catalog <command>         Build/check/search gateway catalog assets
+`,
+        "gateway-catalog": `Usage:
+  x402-cli gateway catalog <build|check|pay-assets|search> [options]
+Commands:
+  build <providers>         Build a local catalog from provider.yml files
+  check <providers>         Validate local provider.yml files
+  pay-assets <providers>    List payable endpoint assets
+  search <query>            Search a catalog artifact
 `,
         catalog: `Usage:
   x402-cli catalog <update|search|show|endpoints|pay-json|export-gateway|build> [options]
@@ -335,7 +386,47 @@ Options:
   --output-dir <dir>        Output directory for generated files
   -n, --limit <count>       Search result limit
   --include-blocked         Include blocked providers in search
-  --json                    Print JSON envelope where supported
+  --json                    Print JSON envelope
+`,
+        "catalog-search": `Usage:
+  x402-cli catalog search <query> [--catalog <source>] [options]
+Options:
+  --catalog <source>        catalog.json path or URL
+  -n, --limit <count>       Search result limit
+  --include-blocked         Include blocked providers in search
+  --json                    Print JSON envelope
+`,
+        "catalog-show": `Usage:
+  x402-cli catalog show <provider> [--catalog <source>] [options]
+Options:
+  --catalog <source>        catalog.json path or URL
+  --json                    Print JSON envelope
+`,
+        "catalog-pay-json": `Usage:
+  x402-cli catalog pay-json <provider> [--catalog <source>] [options]
+Options:
+  --catalog <source>        catalog.json path or URL
+  --raw                     Print raw pay payload instead of JSON envelope
+  --json                    Print JSON envelope
+`,
+        "catalog-endpoints": `Usage:
+  x402-cli catalog endpoints <provider> [--catalog <source>] [options]
+Options:
+  --catalog <source>        catalog.json path or URL
+  --json                    Print JSON envelope
+`,
+        "catalog-export-gateway": `Usage:
+  x402-cli catalog export-gateway <gateway-url> --provider <fqn> [options]
+Options:
+  --provider <fqn>          Provider FQN to export
+  --output-dir <dir>        Output directory for generated files
+  --force                   Overwrite existing files
+  --json                    Print JSON envelope
 `,
     };
     return sections[topic] ?? sections.root;
@@ -616,10 +707,10 @@ function defaultCatalogSource() {
 function positiveIntegerOption(options, key, fallback) {
     const value = opt(options, key, String(fallback));
     if (!/^\d+$/.test(value))
-        throw new Error(`--${key} must be a positive integer`);
+        throw new CliError("INVALID_ARGUMENT", `--${key} must be a positive integer`, `Pass --${key} with a value greater than zero.`, 2);
     const parsed = Number(value);
     if (!Number.isSafeInteger(parsed) || parsed <= 0)
-        throw new Error(`--${key} must be a positive integer`);
+        throw new CliError("INVALID_ARGUMENT", `--${key} must be a positive integer`, `Pass --${key} with a value greater than zero.`, 2);
     return parsed;
 }
 function remoteBaseFromCatalogPayload(payload) {
@@ -808,9 +899,8 @@ function payMarkdownFromDetail(detail) {
     return lines.join("\n");
 }
 async function catalogExportGateway(gatewayUrl, options) {
-    const providerFqn = opt(options, "provider");
-    if (!providerFqn)
-        throw new Error("--provider is required");
+    requireArgument(gatewayUrl, "gateway-url", "x402-cli catalog export-gateway <gateway-url> --provider <fqn> [options]");
+    const providerFqn = requireArgument(opt(options, "provider"), "--provider", "x402-cli catalog export-gateway <gateway-url> --provider <fqn> [options]");
     sanitizeProviderName(providerFqn);
     const base = gatewayUrl.replace(/\/+$/, "");
     const detail = await readJson(`${base}/__402/catalog/providers/${providerFilename(providerFqn)}`);
@@ -846,8 +936,8 @@ function buildRequirement(options) {
     const rawAmount = opt(options, "rawAmount") ?? opt(options, "raw-amount");
     const humanAmount = opt(options, "amount");
     if (rawAmount && humanAmount)
-        throw new Error("--amount and --rawAmount are mutually exclusive");
-    const amount = rawAmount ? assertRawAmount(rawAmount, "--rawAmount") : toSmallestUnit(humanAmount ?? "0.0001", decimals);
+        throw new CliError("INVALID_ARGUMENT", "--amount and --raw-amount are mutually exclusive", "Pass either --amount or --raw-amount, not both.", 2);
+    const amount = rawAmount ? assertRawAmount(rawAmount, "--raw-amount") : toSmallestUnit(humanAmount ?? "0.0001", decimals);
     const assetAddress = explicitAsset ?? registryToken.address;
     const assetTransferMethod = registryToken?.assetTransferMethod ?? "permit2";
     return {
@@ -916,14 +1006,14 @@ function serveDaemon(argv, options) {
 function validateAmountLimits(selected, options) {
     const maxRaw = opt(options, "max-rawAmount") ?? opt(options, "max-raw-amount");
     const maxAmount = opt(options, "max-amount");
-    if (maxRaw && BigInt(selected.amount) > BigInt(assertRawAmount(maxRaw, "--max-rawAmount"))) {
-        throw new Error(`payment raw amount ${selected.amount} exceeds --max-rawAmount ${maxRaw}`);
+    if (maxRaw && BigInt(selected.amount) > BigInt(assertRawAmount(maxRaw, "--max-raw-amount"))) {
+        throw new Error(`payment raw amount ${selected.amount} exceeds --max-raw-amount ${maxRaw}`);
     }
     if (maxAmount) {
         const token = findTokenByAddress(selected.network, selected.asset);
         const decimalsOption = opt(options, "decimals");
         if (!token && decimalsOption === undefined) {
-            throw new Error("cannot evaluate --max-amount for an unknown asset; pass --max-rawAmount or --decimals");
+            throw new Error("cannot evaluate --max-amount for an unknown asset; pass --max-raw-amount or --decimals");
         }
         const decimals = decimalsOption !== undefined ? Number(decimalsOption) : token.decimals;
         if (!Number.isInteger(decimals) || decimals < 0)
@@ -1047,8 +1137,7 @@ function selectRequirement(accepts, options) {
     return selected;
 }
 async function pay(url, options) {
-    if (!url)
-        throw new Error("URL is required");
+    requireArgument(url, "URL", "x402-cli pay <url> [options]");
     const method = opt(options, "method", "GET");
     const baseHeaders = requestHeaders(options);
     const probe = await fetch(url, {
@@ -1259,6 +1348,9 @@ function catalogBuild(target, options) {
             result: { output, count: providers.length },
         });
     }
+    else if (outputMode(options) === "json") {
+        emit({ command: "catalog build", mode: "json", result: catalog });
+    }
     else {
         printJson(catalog);
     }
@@ -1274,16 +1366,11 @@ function catalogPayAssets(target, options) {
         scheme: "exact",
         assetTransferMethod: providerAssetTransferMethod(provider),
     })));
-    if (outputMode(options) === "json") {
-        printJson({ assets: rows, count: rows.length });
-    }
-    else {
-        emit({
-            command: "gateway catalog pay-assets",
-            mode: "human",
-            result: { count: rows.length, assets: rows },
-        });
-    }
+    emit({
+        command: "gateway catalog pay-assets",
+        mode: outputMode(options),
+        result: { count: rows.length, assets: rows },
+    });
 }
 async function readProviderDetailForSearch(source, fqn) {
     try {
@@ -1382,10 +1469,11 @@ function searchHitToJson(hit) {
     };
 }
 async function catalogSearch(source, query, options) {
+    positiveIntegerOption(options, "limit", 10);
     const hits = await searchCatalog(source, query, options);
     const results = hits.map(searchHitToJson);
     if (outputMode(options) === "json") {
-        printJson({ ok: true, command: "catalog search", query, catalog: source, count: hits.length, results });
+        emit({ command: "catalog search", mode: "json", result: { query, catalog: source, count: hits.length, results } });
         return;
     }
     if (!hits.length) {
@@ -1415,9 +1503,10 @@ async function catalogSearch(source, query, options) {
     }
 }
 async function catalogShow(source, name, options) {
+    requireArgument(name, "provider", "x402-cli catalog show <provider> [--catalog <source>]");
     const provider = await readCatalogProvider(source, name);
     if (outputMode(options) === "json") {
-        printJson({ ok: true, command: "catalog show", result: provider });
+        emit({ command: "catalog show", mode: "json", result: provider });
         return;
     }
     process.stdout.write(`${provider.fqn ?? provider.name} - ${provider.title ?? provider.main_title ?? provider.name}\n`);
@@ -1429,10 +1518,11 @@ async function catalogShow(source, name, options) {
         process.stdout.write(`chains: ${provider.chains.join(", ")}\n`);
 }
 async function catalogEndpoints(source, name, options) {
+    requireArgument(name, "provider", "x402-cli catalog endpoints <provider> [--catalog <source>]");
     const provider = await readCatalogProvider(source, name);
     const endpoints = provider.endpoints ?? [];
     if (outputMode(options) === "json") {
-        printJson({ ok: true, command: "catalog endpoints", provider: provider.fqn ?? provider.name, endpoints });
+        emit({ command: "catalog endpoints", mode: "json", result: { provider: provider.fqn ?? provider.name, endpoints } });
         return;
     }
     for (const endpoint of endpoints) {
@@ -1441,28 +1531,33 @@ async function catalogEndpoints(source, name, options) {
             process.stdout.write(`  ${String(endpoint.description).split("\n")[0]}\n`);
     }
 }
-async function catalogPayJson(source, name) {
+async function catalogPayJson(source, name, options) {
+    requireArgument(name, "provider", "x402-cli catalog pay-json <provider> [--catalog <source>]");
     const provider = await readCatalogPayProvider(source, name);
     const endpoint = (provider.endpoints ?? []).find((item) => item.paid || item.x402_routes?.length || item.x402Routes?.length) ?? provider.endpoints?.[0];
     if (!endpoint)
         throw new Error(`provider has no endpoints: ${name}`);
-    printJson({
+    const result = {
         provider: provider.fqn ?? provider.name,
         url: endpoint.url ?? endpoint.path,
         method: endpoint.method,
         paid: endpoint.paid,
         x402_routes: endpoint.x402_routes ?? endpoint.x402Routes ?? [],
         endpoint,
-    });
+    };
+    if (hasFlag(options, "raw"))
+        printJson(result);
+    else
+        emit({ command: "catalog pay-json", mode: outputMode(options), result });
 }
 async function handleGateway(args) {
     const { command, positional, options } = parseArgs(args);
     if (hasFlag(options, "help") || command === "help") {
-        process.stdout.write(helpText("gateway"));
+        process.stdout.write(helpText(command === "catalog" || positional[0] === "catalog" ? "gateway-catalog" : "gateway"));
         return;
     }
     if (command === "search")
-        await catalogSearch(opt(options, "catalog", defaultCatalogSource()), positional.join(" "), options);
+        await catalogSearch(opt(options, "catalog", defaultCatalogSource()), requireArgument(positional.join(" "), "query", "x402-cli gateway search <query> [options]"), options);
     else if (command === "start")
         await gatewayStart(["--providers", opt(options, "providers", opt(options, "providers-dir", positional[0] ?? "providers")), "--host", opt(options, "host", "127.0.0.1"), "--port", opt(options, "port", "4020")], options);
     else if (command === "check")
@@ -1472,7 +1567,7 @@ async function handleGateway(args) {
     else if (command === "catalog")
         await handleGatewayCatalog(positional, options);
     else
-        throw new Error("Usage: x402-cli gateway <search|start|check|scaffold|catalog>");
+        throw new CliError("UNKNOWN_COMMAND", `Unknown gateway command: ${command}`, "Run x402-cli gateway --help to list commands.", 2);
 }
 async function handleGatewayCatalog(positional, options) {
     const sub = positional[0] ?? "build";
@@ -1484,37 +1579,46 @@ async function handleGatewayCatalog(positional, options) {
     else if (sub === "pay-assets")
         catalogPayAssets(target, options);
     else if (sub === "search")
-        await catalogSearch(opt(options, "catalog", defaultCatalogSource()), positional.slice(2).join(" ") || opt(options, "query", ""), options);
+        await catalogSearch(opt(options, "catalog", defaultCatalogSource()), requireArgument(positional.slice(2).join(" ") || opt(options, "query"), "query", "x402-cli gateway catalog search <query> [options]"), options);
     else
-        throw new Error("Usage: x402-cli gateway catalog <build|check|pay-assets|search>");
+        throw new CliError("UNKNOWN_COMMAND", `Unknown gateway catalog command: ${sub}`, "Run x402-cli gateway catalog --help to list commands.", 2);
 }
 async function handleCatalog(args) {
     const { command, positional, options } = parseArgs(args);
     if (hasFlag(options, "help") || command === "help") {
-        process.stdout.write(helpText("catalog"));
+        const topic = command === "help" ? positional[0] : command;
+        process.stdout.write(helpText(topic ? `catalog-${topic}` : "catalog"));
         return;
     }
     const source = opt(options, "catalog", defaultCatalogSource());
     if (command === "update")
         await catalogUpdate(source, options);
     else if (command === "search")
-        await catalogSearch(source, positional.join(" "), options);
+        await catalogSearch(source, requireArgument(positional.join(" "), "query", "x402-cli catalog search <query> [options]"), options);
     else if (command === "show")
         await catalogShow(source, positional[0], options);
     else if (command === "endpoints")
         await catalogEndpoints(source, positional[0], options);
     else if (command === "pay-json")
-        await catalogPayJson(source, positional[0]);
+        await catalogPayJson(source, positional[0], options);
     else if (command === "export-gateway")
         await catalogExportGateway(positional[0], options);
     else if (command === "build")
         catalogBuild(positional[0] ?? "providers", options);
     else
-        throw new Error("Usage: x402-cli catalog <update|search|show|endpoints|pay-json|export-gateway|build>");
+        throw new CliError("UNKNOWN_COMMAND", `Unknown catalog command: ${command}`, "Run x402-cli catalog --help to list commands.", 2);
 }
 async function main() {
     const argv = process.argv.slice(2);
     const { command, positional, options } = parseArgs(argv);
+    if (hasFlag(options, "help") && command === "gateway") {
+        await handleGateway(argv.slice(1));
+        return;
+    }
+    if (hasFlag(options, "help") && command === "catalog") {
+        await handleCatalog(argv.slice(1));
+        return;
+    }
     if (command === "--help" || command === "-h" || command === "help" || hasFlag(options, "help")) {
         const topic = command === "help" ? positional[0] : command.startsWith("-") ? undefined : command;
         process.stdout.write(helpText(topic));
@@ -1539,14 +1643,20 @@ async function main() {
     else if (command === "catalog")
         await handleCatalog(argv.slice(1));
     else {
-        process.stdout.write(helpText());
+        throw new CliError("UNKNOWN_COMMAND", `Unknown command: ${command}`, "Run x402-cli --help to list commands.", 2);
     }
 }
+function errorCommandName(argv) {
+    const [first, second] = argv;
+    if ((first === "catalog" || first === "gateway") && second && !second.startsWith("-"))
+        return `${first} ${second}`;
+    return first ?? "x402-cli";
+}
 main().catch(error => {
     emit({
-        command: process.argv[2] ?? "x402-cli",
+        command: errorCommandName(process.argv.slice(2)),
         mode: process.argv.includes("--json") ? "json" : "human",
         error: classify(error),
     });
-    process.exit(1);
+    process.exit(error instanceof CliError ? error.exitCode : 1);
 });

package/dist/gateway/cli.js CHANGED Viewed

@@ -1,33 +1,218 @@
 #!/usr/bin/env node
+import fs from "node:fs";
 import { loadProviders } from "./config.js";
 import { createGatewayServer } from "./server.js";
+class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 2) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+const VALUE_OPTIONS = new Set(["provider", "providers", "host", "port"]);
+const BOOLEAN_OPTIONS = new Set(["debug", "help", "json", "quiet", "version"]);
+const ALL_OPTIONS = new Set([...VALUE_OPTIONS, ...BOOLEAN_OPTIONS]);
 function parseArgs(argv) {
+    const explicitCommand = Boolean(argv[0] && !argv[0].startsWith("-"));
+    const command = explicitCommand ? argv[0] : "start";
+    const rest = explicitCommand ? argv.slice(1) : argv;
     const options = {};
-    for (let i = 0; i < argv.length; i += 1) {
-        const item = argv[i];
-        if (!item.startsWith("--"))
+    if (command !== "start" && command !== "check") {
+        throw new CliError(`Unknown command: ${command}`);
+    }
+    for (let i = 0; i < rest.length; i += 1) {
+        const item = rest[i];
+        if (item === "-h") {
+            options.help = true;
             continue;
-        const key = item.slice(2);
-        const next = argv[i + 1];
-        if (!next || next.startsWith("--"))
+        }
+        if (item === "-v" || item === "-V") {
+            options.version = true;
+            continue;
+        }
+        if (!item.startsWith("--"))
+            throw new CliError(`Unexpected argument: ${item}`);
+        const eq = item.indexOf("=");
+        const key = eq > 2 ? item.slice(2, eq) : item.slice(2);
+        if (!ALL_OPTIONS.has(key))
+            throw new CliError(`Unknown option: --${key}`);
+        if (BOOLEAN_OPTIONS.has(key)) {
+            if (eq > 2)
+                throw new CliError(`Option --${key} does not take a value`);
             options[key] = true;
+            continue;
+        }
+        const inline = eq > 2 ? item.slice(eq + 1) : undefined;
+        const next = rest[i + 1];
+        if (inline !== undefined) {
+            if (!inline)
+                throw new CliError(`Option --${key} requires a value`);
+            options[key] = inline;
+        }
         else {
+            if (!next || next.startsWith("--"))
+                throw new CliError(`Option --${key} requires a value`);
             options[key] = next;
             i += 1;
         }
     }
-    return options;
+    return { command, options };
 }
 function opt(options, key, fallback) {
     const value = options[key];
     return typeof value === "string" ? value : fallback;
 }
-const options = parseArgs(process.argv.slice(2));
-const providersPath = opt(options, "providers", opt(options, "provider", process.env.X402_GATEWAY_PROVIDERS_DIR || "/app/providers"));
-const host = opt(options, "host", process.env.X402_GATEWAY_HOST || "0.0.0.0");
-const port = Number(opt(options, "port", process.env.PORT || "8080"));
-const providers = loadProviders(providersPath);
-const server = createGatewayServer(providers);
-server.listen(port, host, () => {
-    process.stdout.write(JSON.stringify({ ok: true, host, port, providers: [...providers.keys()] }, null, 2) + "\n");
+function flag(options, key) {
+    return options[key] === true;
+}
+function version() {
+    try {
+        const url = new URL("../package.json", import.meta.url);
+        return String(JSON.parse(fs.readFileSync(url, "utf8")).version ?? "0.0.0");
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function help() {
+    return `x402-gateway ${version()}
+Usage:
+  x402-gateway start --providers <dir> [options]
+  x402-gateway --providers <dir> [options]
+  x402-gateway check --providers <dir>
+  x402-gateway check --provider <file>
+Commands:
+  start                  Start the x402 gateway server (default)
+  check                  Validate provider YAML and print a summary
+Options:
+  --provider <file>      Load one provider YAML file
+  --providers <dir>      Load provider.yml/provider.yaml files from a directory
+  --host <host>          Bind host (default: 127.0.0.1)
+  --port <port>          Bind port (default: 8080)
+  --json                 Print machine-readable JSON
+  --quiet                Suppress startup/shutdown messages
+  --debug                Print stack traces for startup errors
+  -h, --help             Show help
+  -v, -V, --version      Show version
+Examples:
+  x402-gateway --provider examples/provider.yml --host 127.0.0.1 --port 4020
+  x402-gateway start --providers providers --port 4020
+  x402-gateway check --providers providers --json
+`;
+}
+function providerPath(options) {
+    const source = opt(options, "providers", opt(options, "provider", process.env.X402_GATEWAY_PROVIDERS_DIR));
+    if (!source)
+        throw new CliError("No provider source configured. Use --provider <file> or --providers <dir>.");
+    return source;
+}
+function parsePort(value) {
+    const raw = value ?? process.env.PORT ?? "8080";
+    if (!/^\d+$/.test(raw))
+        throw new CliError(`Invalid --port ${raw}; expected an integer between 1 and 65535`);
+    const port = Number(raw);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new CliError(`Invalid --port ${raw}; expected an integer between 1 and 65535`);
+    }
+    return port;
+}
+function publicHost(host) {
+    return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+function printStartup(options, host, port, providers) {
+    if (flag(options, "quiet"))
+        return;
+    if (flag(options, "json")) {
+        process.stdout.write(JSON.stringify({ ok: true, host, port, providers }, null, 2) + "\n");
+        return;
+    }
+    const base = `http://${publicHost(host)}:${port}`;
+    process.stdout.write(`x402-gateway listening on ${base}\n`);
+    process.stdout.write(`providers: ${providers.length} loaded\n`);
+    process.stdout.write(`health: ${base}/__402/health\n`);
+    process.stdout.write(`ready: ${base}/__402/ready\n`);
+}
+function check(options) {
+    const source = providerPath(options);
+    const providers = loadProviders(source);
+    const summary = [...providers.values()].map(entry => ({
+        name: entry.config.name,
+        network: entry.config.operator.network,
+        endpoints: entry.config.endpoints?.length ?? 0,
+    }));
+    if (flag(options, "json")) {
+        process.stdout.write(JSON.stringify({ ok: true, source, count: summary.length, providers: summary }, null, 2) + "\n");
+        return;
+    }
+    process.stdout.write(`ok: ${summary.length} provider${summary.length === 1 ? "" : "s"} loaded from ${source}\n`);
+    for (const item of summary) {
+        process.stdout.write(`  ${item.name} (${item.network}) endpoints=${item.endpoints}\n`);
+    }
+}
+async function start(options) {
+    const source = providerPath(options);
+    const host = opt(options, "host", process.env.X402_GATEWAY_HOST || "127.0.0.1");
+    const port = parsePort(opt(options, "port"));
+    const providers = loadProviders(source);
+    const server = createGatewayServer(providers);
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            printStartup(options, host, port, [...providers.keys()]);
+            resolve();
+        });
+    });
+    const shutdown = (signal) => {
+        if (!flag(options, "quiet") && !flag(options, "json"))
+            process.stderr.write(`received ${signal}, shutting down...\n`);
+        server.close(() => {
+            if (!flag(options, "quiet") && !flag(options, "json"))
+                process.stderr.write("server closed\n");
+            process.exit(0);
+        });
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+}
+async function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (flag(parsed.options, "help")) {
+        process.stdout.write(help());
+        return;
+    }
+    if (flag(parsed.options, "version")) {
+        process.stdout.write(`${version()}\n`);
+        return;
+    }
+    if (parsed.command === "check")
+        check(parsed.options);
+    else
+        await start(parsed.options);
+}
+main().catch(error => {
+    const parsed = (() => {
+        try {
+            return parseArgs(process.argv.slice(2));
+        }
+        catch {
+            return { options: {} };
+        }
+    })();
+    const message = error instanceof Error ? error.message : String(error);
+    if (flag(parsed.options, "json")) {
+        process.stdout.write(JSON.stringify({ ok: false, error: { message } }, null, 2) + "\n");
+    }
+    else {
+        process.stderr.write(`x402-gateway: ${message}\n`);
+        process.stderr.write("Run `x402-gateway --help` for usage.\n");
+        if (flag(parsed.options, "debug") && error instanceof Error && error.stack) {
+            process.stderr.write(`${error.stack}\n`);
+        }
+    }
+    process.exit(error instanceof CliError ? error.exitCode : 1);
 });

package/dist/gateway/config.js CHANGED Viewed

@@ -3,7 +3,11 @@ import path from "node:path";
 import YAML from "yaml";
 import { getToken, normalizeNetwork, toSmallestUnit } from "./tokens.js";
 function expandEnv(value) {
-    return value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? "");
+    return value.replace(/\$\{([^}]+)\}/g, (_, name) => {
+        if (!(name in process.env))
+            throw new Error(`environment variable \${${name}} is not set`);
+        return process.env[name] ?? "";
+    });
 }
 function expandDeep(value) {
     if (typeof value === "string")
@@ -19,11 +23,63 @@ function assertString(value, name) {
     if (typeof value !== "string" || !value.trim())
         throw new Error(`${name} is required`);
 }
+function assertHttpUrl(value, name) {
+    if (!value)
+        return;
+    try {
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol))
+            throw new Error("unsupported protocol");
+    }
+    catch {
+        throw new Error(`${name} must be a valid http(s) URL`);
+    }
+}
+function validateTiers(tiers, file, path) {
+    if (!Array.isArray(tiers) || !tiers.length)
+        throw new Error(`${file}: ${path}.tiers must contain at least one tier`);
+    for (const [tierIndex, tier] of tiers.entries()) {
+        const price = tier?.price_usd;
+        if (typeof price !== "number" || !Number.isFinite(price) || price < 0) {
+            throw new Error(`${file}: ${path}.tiers[${tierIndex}].price_usd must be a finite number >= 0`);
+        }
+    }
+}
+function validateDimensions(dimensions, file, path) {
+    if (!Array.isArray(dimensions) || !dimensions.length) {
+        throw new Error(`${file}: ${path}.dimensions must contain at least one dimension`);
+    }
+    if (dimensions.length !== 1)
+        throw new Error(`${file}: ${path}.dimensions currently supports exactly one dimension`);
+    for (const [dimensionIndex, dimension] of dimensions.entries()) {
+        validateTiers(dimension?.tiers, file, `${path}.dimensions[${dimensionIndex}]`);
+    }
+}
+function validateMetering(endpoint, file, path) {
+    if (!endpoint.metering)
+        return;
+    validateDimensions(endpoint.metering.dimensions, file, `${path}.metering`);
+    for (const [variantIndex, variant] of (endpoint.metering.variants ?? []).entries()) {
+        assertString(variant.param, `${file}: ${path}.metering.variants[${variantIndex}].param`);
+        assertString(variant.value, `${file}: ${path}.metering.variants[${variantIndex}].value`);
+        validateDimensions(variant.dimensions, file, `${path}.metering.variants[${variantIndex}]`);
+    }
+}
 function validateProvider(config, file) {
     assertString(config.name, `${file}: name`);
     assertString(config.forward_url, `${file}: forward_url`);
     assertString(config.operator?.network, `${file}: operator.network`);
     assertString(config.operator?.recipient, `${file}: operator.recipient`);
+    assertHttpUrl(config.forward_url, `${file}: forward_url`);
+    assertHttpUrl(config.operator?.facilitator_url, `${file}: operator.facilitator_url`);
+    if (config.operator?.valid_for_seconds !== undefined &&
+        (!Number.isFinite(config.operator.valid_for_seconds) || config.operator.valid_for_seconds <= 0)) {
+        throw new Error(`${file}: operator.valid_for_seconds must be > 0`);
+    }
+    const authMethod = config.routing?.auth?.method;
+    if (authMethod && !["header", "query_param", "access_token", "oauth2"].includes(authMethod)) {
+        throw new Error(`${file}: unsupported routing.auth.method ${authMethod}`);
+    }
     if (!config.endpoints?.length)
         throw new Error(`${file}: endpoints must contain at least one endpoint`);
     const seen = new Set();
@@ -40,11 +96,7 @@ function validateProvider(config, file) {
         if (seen.has(key))
             throw new Error(`${file}: duplicate endpoint ${key}`);
         seen.add(key);
-        for (const [tierIndex, tier] of (endpoint.metering?.dimensions?.[0]?.tiers ?? []).entries()) {
-            if (typeof tier.price_usd !== "number" || tier.price_usd < 0) {
-                throw new Error(`${file}: endpoints[${index}].metering tier ${tierIndex} price_usd must be >= 0`);
-            }
-        }
+        validateMetering(endpoint, file, `endpoints[${index}]`);
     }
 }
 export function loadProvider(file) {
@@ -111,8 +163,14 @@ function pathMatches(template, routePath) {
     });
 }
 export function priceUsd(endpoint, params = {}) {
+    if (!endpoint?.metering)
+        return 0;
     const variant = endpoint?.metering?.variants?.find(item => params[item.param] === item.value);
-    return (variant?.dimensions ?? endpoint?.metering?.dimensions)?.[0]?.tiers?.[0]?.price_usd ?? 0;
+    const price = (variant?.dimensions ?? endpoint.metering.dimensions)?.[0]?.tiers?.[0]?.price_usd;
+    if (typeof price !== "number" || !Number.isFinite(price) || price < 0) {
+        throw new Error(`invalid metering price for ${endpoint.method} ${endpoint.path}`);
+    }
+    return price;
 }
 export function paymentRequirements(provider, price) {
     if (price <= 0)
@@ -123,10 +181,13 @@ export function paymentRequirements(provider, price) {
     return symbols.map(symbol => {
         const token = getToken(network, symbol);
         const transferMethod = provider.operator.assetTransferMethod || provider.operator.asset_transfer_method || token.assetTransferMethod;
+        const amount = toSmallestUnit(price, token.decimals);
+        if (amount === "0")
+            throw new Error(`positive price produced zero amount for ${symbol} on ${network}`);
         return {
             scheme: "exact",
             network,
-            amount: toSmallestUnit(price, token.decimals),
+            amount,
             asset: token.address,
             payTo,
             maxTimeoutSeconds: provider.operator.valid_for_seconds ?? 300,

package/dist/gateway/server.js CHANGED Viewed

@@ -2,37 +2,106 @@ import http from "node:http";
 import { URL } from "node:url";
 import { endpointFor, paymentRequirements, priceUsd } from "./config.js";
 import { decodeSignature, encodeRequired, encodeResponse, headers, matchRequirement } from "./x402.js";
+class HttpError extends Error {
+    status;
+    publicMessage;
+    constructor(status, publicMessage, message = publicMessage) {
+        super(message);
+        this.status = status;
+        this.publicMessage = publicMessage;
+    }
+}
+class RequestTooLargeError extends HttpError {
+    constructor() {
+        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);
+const STRIP_REQUEST_HEADERS = new Set([
+    "host",
+    "connection",
+    "transfer-encoding",
+    "content-length",
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "x-auth-token",
+    "x-access-token",
+    "x-payment",
+    "payment-signature",
+    "payment-required",
+    "x-payment-required",
+    "accept-encoding",
+]);
+const STRIP_RESPONSE_HEADERS = new Set([
+    "connection",
+    "transfer-encoding",
+    "content-encoding",
+    "content-length",
+    "authorization",
+    "proxy-authorization",
+    "set-cookie",
+]);
 const metrics = {
     requests: 0,
     paidRequests: 0,
     verifyFailures: 0,
     settleFailures: 0,
+    feeQuoteFailures: 0,
     upstreamFailures: 0,
 };
 async function readBody(request) {
     const chunks = [];
-    for await (const chunk of request)
-        chunks.push(Buffer.from(chunk));
+    let total = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.from(chunk);
+        total += buffer.length;
+        if (total > MAX_BODY_BYTES)
+            throw new RequestTooLargeError();
+        chunks.push(buffer);
+    }
     return Buffer.concat(chunks);
 }
 function json(response, status, body, extraHeaders = {}) {
     response.writeHead(status, { "content-type": "application/json", ...extraHeaders });
     response.end(JSON.stringify(body));
 }
+async function fetchWithTimeout(url, init, timeoutMs, label = "upstream") {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (error?.name === "AbortError")
+            throw new HttpError(504, `${label} request timed out`);
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function facilitatorPost(entry, path, body) {
     const headers = { "content-type": "application/json" };
     if (entry.facilitatorApiKey) {
         headers.authorization = `Bearer ${entry.facilitatorApiKey}`;
     }
-    const response = await fetch(new URL(path, entry.facilitatorUrl), {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-    });
+    const response = await fetchWithTimeout(new URL(path, entry.facilitatorUrl), { method: "POST", headers, body: JSON.stringify(body) }, FACILITATOR_TIMEOUT_MS, "facilitator");
     const text = await response.text();
-    const data = text ? JSON.parse(text) : {};
+    let data = {};
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new HttpError(502, "facilitator returned invalid response");
+    }
     if (!response.ok)
-        throw new Error(`facilitator ${path} failed: ${response.status} ${text}`);
+        throw new HttpError(502, "facilitator request failed", `facilitator ${path} failed: ${response.status} ${text}`);
     return data;
 }
 async function attachFeeQuotes(entry, requirements, context) {
@@ -49,14 +118,25 @@ async function attachFeeQuotes(entry, requirements, context) {
             return quote?.fee ? { ...requirement, extra: { ...requirement.extra, fee: quote.fee } } : requirement;
         });
     }
-    catch {
+    catch (error) {
+        metrics.feeQuoteFailures += 1;
+        console.warn("fee quote failed", error);
         return requirements;
     }
 }
+function isVerifySuccess(verify) {
+    return verify?.valid === true || verify?.isValid === true;
+}
+function isSettleSuccess(settle) {
+    return (settle?.success === true ||
+        settle?.settled === true ||
+        (typeof settle?.transaction === "string" && settle.transaction.length > 0) ||
+        (typeof settle?.txHash === "string" && settle.txHash.length > 0));
+}
 function isAdminAllowed(request) {
     const token = process.env.X402_GATEWAY_ADMIN_TOKEN;
     if (!token)
-        return true;
+        return process.env.X402_GATEWAY_ADMIN_ALLOW_PUBLIC === "true";
     const auth = request.headers.authorization ?? "";
     return auth === `Bearer ${token}`;
 }
@@ -89,7 +169,7 @@ function upstreamHeaders(request, entry) {
         if (!value)
             continue;
         const lower = key.toLowerCase();
-        if (["host", "connection", "content-length", "authorization", "payment-signature"].includes(lower))
+        if (STRIP_REQUEST_HEADERS.has(lower))
             continue;
         headersOut.set(key, Array.isArray(value) ? value.join(",") : value);
     }
@@ -114,14 +194,23 @@ function upstreamUrl(entry, request, routePath) {
 }
 async function forward(entry, request, response, routePath, body, paymentResponse) {
     const upstream = upstreamUrl(entry, request, routePath);
-    const upstreamResponse = await fetch(upstream, {
-        method: request.method,
-        headers: upstreamHeaders(request, entry),
-        body: ["GET", "HEAD"].includes(request.method ?? "GET") ? undefined : new Uint8Array(body),
-    });
+    let upstreamResponse;
+    try {
+        upstreamResponse = await fetchWithTimeout(upstream, {
+            method: request.method,
+            headers: upstreamHeaders(request, entry),
+            body: ["GET", "HEAD"].includes(request.method ?? "GET") ? undefined : new Uint8Array(body),
+        }, UPSTREAM_TIMEOUT_MS);
+    }
+    catch (error) {
+        metrics.upstreamFailures += 1;
+        if (error instanceof HttpError)
+            throw error;
+        throw new HttpError(502, "upstream request failed");
+    }
     const responseHeaders = {};
     upstreamResponse.headers.forEach((value, key) => {
-        if (!["connection", "transfer-encoding", "content-encoding", "content-length"].includes(key.toLowerCase())) {
+        if (!STRIP_RESPONSE_HEADERS.has(key.toLowerCase())) {
             responseHeaders[key] = value;
         }
     });
@@ -140,7 +229,7 @@ export function createGatewayServer(providers) {
                 return;
             }
             if (url.pathname === "/__402/ready") {
-                json(response, 200, { ok: true, providers: providers.size });
+                json(response, providers.size ? 200 : 503, { ok: providers.size > 0, providers: providers.size });
                 return;
             }
             if (url.pathname === "/__402/providers") {
@@ -168,12 +257,15 @@ export function createGatewayServer(providers) {
                 return;
             }
             if (url.pathname === "/metrics") {
+                if (!isAdminAllowed(request))
+                    return json(response, 401, { error: "unauthorized" });
                 response.writeHead(200, { "content-type": "text/plain; version=0.0.4" });
                 response.end([
                     `x402_gateway_requests_total ${metrics.requests}`,
                     `x402_gateway_paid_requests_total ${metrics.paidRequests}`,
                     `x402_gateway_verify_failures_total ${metrics.verifyFailures}`,
                     `x402_gateway_settle_failures_total ${metrics.settleFailures}`,
+                    `x402_gateway_fee_quote_failures_total ${metrics.feeQuoteFailures}`,
                     `x402_gateway_upstream_failures_total ${metrics.upstreamFailures}`,
                     "",
                 ].join("\n"));
@@ -213,7 +305,14 @@ export function createGatewayServer(providers) {
                 json(response, 402, challenge, { [headers.required]: encodeRequired(challenge) });
                 return;
             }
-            const payload = decodeSignature(paymentHeader);
+            let payload;
+            try {
+                payload = decodeSignature(paymentHeader);
+            }
+            catch {
+                json(response, 400, { error: "invalid payment signature" });
+                return;
+            }
             const requirement = requirements.find(item => matchRequirement(payload, item));
             if (!requirement) {
                 json(response, 400, { error: "payment does not match any requirement" });
@@ -223,9 +322,9 @@ export function createGatewayServer(providers) {
                 paymentPayload: payload,
                 paymentRequirements: requirement,
             });
-            if (verify?.valid === false || verify?.isValid === false) {
+            if (!isVerifySuccess(verify)) {
                 metrics.verifyFailures += 1;
-                json(response, 400, { error: "payment verification failed", verify });
+                json(response, 400, { error: "payment verification failed" });
                 return;
             }
             let settle;
@@ -239,11 +338,21 @@ export function createGatewayServer(providers) {
                 metrics.settleFailures += 1;
                 throw error;
             }
+            if (!isSettleSuccess(settle)) {
+                metrics.settleFailures += 1;
+                json(response, 502, { error: "settlement failed" });
+                return;
+            }
             metrics.paidRequests += 1;
             await forward(entry, request, response, routePath, body, settle);
         }
         catch (error) {
-            json(response, 500, { error: error instanceof Error ? error.message : String(error) });
+            if (error instanceof HttpError) {
+                json(response, error.status, { error: error.publicMessage });
+                return;
+            }
+            console.error(error);
+            json(response, 500, { error: "internal server error" });
         }
     });
 }

package/dist/gateway/tokens.js CHANGED Viewed

@@ -31,8 +31,37 @@ export function getToken(network, symbol) {
         throw new Error(`unknown token ${symbol} on ${network}`);
     return token;
 }
+function numberToDecimalString(amount) {
+    const value = amount.toString();
+    const match = value.match(/^(\d+(?:\.\d+)?)[eE]([+-]?\d+)$/);
+    if (!match)
+        return value;
+    const [, coefficient, exponentText] = match;
+    const exponent = Number(exponentText);
+    const [whole, fraction = ""] = coefficient.split(".");
+    const digits = whole + fraction;
+    const decimalIndex = whole.length + exponent;
+    if (decimalIndex <= 0)
+        return `0.${"0".repeat(Math.abs(decimalIndex))}${digits}`.replace(/0+$/, "");
+    if (decimalIndex >= digits.length)
+        return `${digits}${"0".repeat(decimalIndex - digits.length)}`;
+    return `${digits.slice(0, decimalIndex)}.${digits.slice(decimalIndex)}`.replace(/0+$/, "").replace(/\.$/, "");
+}
 export function toSmallestUnit(amount, decimals) {
-    const [whole, fraction = ""] = String(amount).split(".");
+    if (!Number.isInteger(decimals) || decimals < 0)
+        throw new Error(`invalid token decimals ${decimals}`);
+    const numeric = typeof amount === "number" ? amount : Number(amount);
+    if (!Number.isFinite(numeric) || numeric < 0)
+        throw new Error(`invalid amount ${amount}`);
+    const value = typeof amount === "number" ? numberToDecimalString(amount) : String(amount);
+    if (!/^\d+(\.\d+)?$/.test(value))
+        throw new Error(`invalid decimal amount ${amount}`);
+    const [whole, fraction = ""] = value.split(".");
     const padded = (fraction + "0".repeat(decimals)).slice(0, decimals);
-    return (BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(padded || "0")).toString();
+    let units = BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(padded || "0");
+    if (fraction.length > decimals && /[1-9]/.test(fraction.slice(decimals)))
+        units += 1n;
+    if (numeric > 0 && units === 0n)
+        units = 1n;
+    return units.toString();
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-cli",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "type": "module",
   "files": [
     "dist"
@@ -24,7 +24,7 @@
     "@bankofai/x402-evm": "1.0.0",
     "@bankofai/x402-gateway": "^1.0.0-beta.1",
     "@bankofai/x402-tron": "1.0.0",
-    "tronweb": "6.0.2",
+    "tronweb": "6.4.0",
     "viem": "^2.55.0",
     "yaml": "^2.8.2"
   },