@bankofai/x402-gateway 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -45,6 +45,11 @@ x402-gateway check --providers providers
 x402-gateway check --provider examples/provider.yml --json
 ```
 
+`check` validates provider YAML syntax, required fields, environment expansion,
+network aliases, endpoint shape, and duplicate provider names. It does not call
+upstream APIs, facilitator services, RPC endpoints, recipient addresses, or the
+full payment path.
+
 Run from source during development:
 
 ```bash
@@ -81,10 +86,11 @@ Options:
 
 - `--provider <file>`: load one provider YAML file.
 - `--providers <dir>`: recursively load `provider.yml` / `provider.yaml`.
+  `--provider` and `--providers` are mutually exclusive.
 - `--host <host>`: bind host. The CLI default is `127.0.0.1`; Docker passes `0.0.0.0`.
 - `--port <port>`: bind port, default `8080`.
 - `--json`: machine-readable startup/check/error output.
-- `--quiet`: suppress startup and shutdown messages.
+- `--quiet`: suppress startup, shutdown, and successful `check` output.
 - `--debug`: include stack traces for startup errors.
 - `--help`, `--version`: inspect usage and installed version.
 
@@ -97,6 +103,10 @@ health: http://127.0.0.1:4020/__402/health
 ready: http://127.0.0.1:4020/__402/ready
 ```
 
+With `--json`, startup output includes `source`, `host`, `port`, `count`,
+`providers`, `health`, and `ready` for deployment scripts. CLI errors also
+honor `--json`, including argument parsing errors such as unknown options.
+
 Admin endpoints such as `/__402/providers`, `/__402/endpoints`, and `/metrics`
 are protected by default. Set `X402_GATEWAY_ADMIN_TOKEN` in deployed
 environments and call them with `Authorization: Bearer <token>`. For a

package/dist/cli.js

@@ -65,17 +65,21 @@ function opt(options, key, fallback) {
 function flag(options, key) {
     return options[key] === true;
 }
-function version() {
+function rawHasFlag(argv, name, short) {
+    return argv.some(item => item === `--${name}` || item.startsWith(`--${name}=`) || (short ? item === short : false));
+}
+function readVersion() {
     try {
         const url = new URL("../package.json", import.meta.url);
-        return String(JSON.parse(fs.readFileSync(url, "utf8")).version ?? "0.0.0");
+        const version = JSON.parse(fs.readFileSync(url, "utf8")).version;
+        return typeof version === "string" && version ? version : undefined;
     }
     catch {
-        return "0.0.0";
+        return undefined;
     }
 }
 function help() {
-    return `x402-gateway ${version()}
+    return `x402-gateway ${readVersion() ?? "unknown"}
 
 Usage:
   x402-gateway start --providers <dir> [options]
@@ -105,6 +109,9 @@ Examples:
 `;
 }
 function providerPath(options) {
+    if (opt(options, "provider") && opt(options, "providers")) {
+        throw new CliError("Options --provider and --providers are mutually exclusive.");
+    }
     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>.");
@@ -120,25 +127,56 @@ function parsePort(value) {
     }
     return port;
 }
+function parseHost(value) {
+    const host = value ?? process.env.X402_GATEWAY_HOST ?? "127.0.0.1";
+    if (!host.trim())
+        throw new CliError("Invalid --host; expected a non-empty host.");
+    return host;
+}
+function listenErrorMessage(error, host, port) {
+    const err = error;
+    if (err?.code === "EADDRINUSE")
+        return `Port ${port} is already in use on ${host}. Choose another --port or stop the existing process.`;
+    if (err?.code === "EADDRNOTAVAIL")
+        return `Host ${host} is not available on this machine. Use --host 127.0.0.1 for local runs or --host 0.0.0.0 in containers.`;
+    return error instanceof Error ? error.message : String(error);
+}
 function publicHost(host) {
     return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
 }
-function printStartup(options, host, port, providers) {
+function localUrls(host, port) {
+    const base = `http://${publicHost(host)}:${port}`;
+    return {
+        base,
+        health: `${base}/__402/health`,
+        ready: `${base}/__402/ready`,
+    };
+}
+function printStartup(options, source, host, port, providers) {
     if (flag(options, "quiet"))
         return;
+    const urls = localUrls(host, port);
     if (flag(options, "json")) {
-        process.stdout.write(JSON.stringify({ ok: true, host, port, providers }, null, 2) + "\n");
+        process.stdout.write(JSON.stringify({ ok: true, source, host, port, count: providers.length, providers, health: urls.health, ready: urls.ready }, null, 2) + "\n");
         return;
     }
-    const base = `http://${publicHost(host)}:${port}`;
-    process.stdout.write(`x402-gateway listening on ${base}\n`);
+    process.stdout.write(`x402-gateway listening on ${urls.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`);
+    process.stdout.write(`health: ${urls.health}\n`);
+    process.stdout.write(`ready: ${urls.ready}\n`);
+}
+function loadProvidersForCli(action, source) {
+    try {
+        return loadProviders(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`failed to load providers from ${source} for ${action}: ${message}`);
+    }
 }
 function check(options) {
     const source = providerPath(options);
-    const providers = loadProviders(source);
+    const providers = loadProvidersForCli("check", source);
     const summary = [...providers.values()].map(entry => ({
         name: entry.config.name,
         network: entry.config.operator.network,
@@ -148,6 +186,8 @@ function check(options) {
         process.stdout.write(JSON.stringify({ ok: true, source, count: summary.length, providers: summary }, null, 2) + "\n");
         return;
     }
+    if (flag(options, "quiet"))
+        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`);
@@ -155,22 +195,29 @@ function check(options) {
 }
 async function start(options) {
     const source = providerPath(options);
-    const host = opt(options, "host", process.env.X402_GATEWAY_HOST || "127.0.0.1");
+    const host = parseHost(opt(options, "host"));
     const port = parsePort(opt(options, "port"));
-    const providers = loadProviders(source);
+    const providers = loadProvidersForCli("start", source);
     const server = createGatewayServer(providers);
     await new Promise((resolve, reject) => {
-        server.once("error", reject);
+        server.once("error", error => reject(new Error(listenErrorMessage(error, host, port))));
         server.listen(port, host, () => {
             server.off("error", reject);
-            printStartup(options, host, port, [...providers.keys()]);
+            printStartup(options, source, host, port, [...providers.keys()]);
             resolve();
         });
     });
     const shutdown = (signal) => {
         if (!flag(options, "quiet") && !flag(options, "json"))
             process.stderr.write(`received ${signal}, shutting down...\n`);
+        const timeout = setTimeout(() => {
+            if (!flag(options, "quiet") && !flag(options, "json"))
+                process.stderr.write("server close timed out; exiting\n");
+            process.exit(1);
+        }, 10_000);
+        timeout.unref();
         server.close(() => {
+            clearTimeout(timeout);
             if (!flag(options, "quiet") && !flag(options, "json"))
                 process.stderr.write("server closed\n");
             process.exit(0);
@@ -186,7 +233,10 @@ async function main() {
         return;
     }
     if (flag(parsed.options, "version")) {
-        process.stdout.write(`${version()}\n`);
+        const version = readVersion();
+        if (!version)
+            throw new Error("Unable to read package version.");
+        process.stdout.write(`${version}\n`);
         return;
     }
     if (parsed.command === "check")
@@ -195,22 +245,17 @@ async function main() {
         await start(parsed.options);
 }
 main().catch(error => {
-    const parsed = (() => {
-        try {
-            return parseArgs(process.argv.slice(2));
-        }
-        catch {
-            return { options: {} };
-        }
-    })();
+    const argv = process.argv.slice(2);
+    const json = rawHasFlag(argv, "json");
+    const debug = rawHasFlag(argv, "debug");
     const message = error instanceof Error ? error.message : String(error);
-    if (flag(parsed.options, "json")) {
+    if (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) {
+        if (debug && error instanceof Error && error.stack) {
             process.stderr.write(`${error.stack}\n`);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bankofai/x402-gateway",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": false,
   "type": "module",
   "files": [