xapi-to 0.1.17 → 0.1.19

package/dist/index.js

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
 
 // src/format.ts
 function getFormat() {
@@ -143,11 +143,18 @@ var CONFIG_FILE = join(CONFIG_DIR, "config.json");
 function loadFileConfig() {
   if (!existsSync(CONFIG_FILE)) return {};
   try {
-    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    const parsed = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return {};
+    return typeof parsed.apiKey === "string" && parsed.apiKey.trim() ? { apiKey: parsed.apiKey } : {};
   } catch {
     return {};
   }
 }
+function getApiKeySource() {
+  if (process.env.XAPI_KEY) return "XAPI_KEY";
+  if (process.env.XAPI_API_KEY) return "XAPI_API_KEY";
+  return loadFileConfig().apiKey ? "file" : "none";
+}
 function getConfig() {
   const file = loadFileConfig();
   return {
@@ -164,24 +171,31 @@ function saveConfig(updates) {
   const current = loadFileConfig();
   const merged = { ...current, ...updates };
   if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  if (process.platform !== "win32") chmodSync(CONFIG_DIR, 448);
   writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 384 });
+  if (process.platform !== "win32") chmodSync(CONFIG_FILE, 384);
 }
 function showConfig() {
   const cfg = getConfig();
-  const file = loadFileConfig();
-  console.log(JSON.stringify({
+  return {
     actionHost: cfg.actionHost,
     apiKey: cfg.apiKey ? `${cfg.apiKey.slice(0, 8)}...` : void 0,
     source: {
-      apiKey: process.env.XAPI_KEY || process.env.XAPI_API_KEY ? "env" : file.apiKey ? "file" : "none"
+      apiKey: getApiKeySource()
     },
     configFile: CONFIG_FILE
-  }, null, 2));
+  };
 }
 
 // src/client.ts
+import { open, rm } from "fs/promises";
+import { once } from "events";
+import { resolve } from "path";
+import { Readable, Transform } from "stream";
+import { pipeline } from "stream/promises";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var EXECUTE_TIMEOUT_MS = 6e4;
+var TRANSFER_IDLE_TIMEOUT_MS = 6e4;
 var IDEMPOTENT_RETRIES = 2;
 var RETRY_BASE_DELAY_MS = 500;
 var RETRY_MAX_DELAY_MS = 8e3;
@@ -221,6 +235,10 @@ function retryBaseDelayMs() {
   const override = Number(process.env.XAPI_RETRY_BASE_MS);
   return Number.isFinite(override) && override > 0 ? override : RETRY_BASE_DELAY_MS;
 }
+function transferIdleTimeoutMs() {
+  const override = Number(process.env.XAPI_TRANSFER_IDLE_TIMEOUT_MS);
+  return Number.isFinite(override) && override > 0 ? override : TRANSFER_IDLE_TIMEOUT_MS;
+}
 function backoffDelayMs(attempt, retryAfterMs) {
   if (retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
     return Math.min(retryAfterMs, RETRY_MAX_DELAY_MS);
@@ -237,7 +255,7 @@ function parseRetryAfterMs(res) {
   return Number.isFinite(at) ? Math.max(0, at - Date.now()) : void 0;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0) {
   assertAllowedHost(url);
@@ -292,7 +310,13 @@ async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0
       return body;
     } catch (e) {
       if (timedOut) {
-        throw new RequestTimeoutError(timeoutMs);
+        const timeoutError = new RequestTimeoutError(timeoutMs);
+        if (attempt < retries) {
+          await sleep(backoffDelayMs(attempt));
+          attempt++;
+          continue;
+        }
+        throw timeoutError;
       }
       if (isRetryableNetworkError(e) && attempt < retries) {
         clearTimeout(timer);
@@ -335,6 +359,8 @@ async function actionSearch(query, opts, params = {}) {
   if (params.source) url.searchParams.set("source", params.source);
   if (params.page) url.searchParams.set("page", String(params.page));
   if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
+  if (params.include_all_versions) url.searchParams.set("include_all_versions", "true");
+  if (params.sort) url.searchParams.set("sort", params.sort);
   return request(
     url.toString(),
     { method: "GET", headers: headers(opts.apiKey) },
@@ -360,6 +386,19 @@ async function actionGet(id, opts) {
     IDEMPOTENT_RETRIES
   );
 }
+async function actionBatch(ids, opts) {
+  return request(
+    `${baseUrl(opts)}/v1/actions/batch`,
+    {
+      method: "POST",
+      headers: headers(opts.apiKey),
+      body: JSON.stringify({ ids })
+    },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
+    // read-only metadata fetch — safe to retry
+  );
+}
 async function actionCall(actionId, input, opts, httpMethod, retries = 0, timeoutMs = EXECUTE_TIMEOUT_MS) {
   return request(
     `${baseUrl(opts)}/v1/actions/execute`,
@@ -372,6 +411,161 @@ async function actionCall(actionId, input, opts, httpMethod, retries = 0, timeou
     retries
   );
 }
+async function actionStream(actionId, input, opts, httpMethod) {
+  const controller = new AbortController();
+  let timedOut = false;
+  let activeTimeoutMs = EXECUTE_TIMEOUT_MS;
+  let timer;
+  const resetTimeout = (timeoutMs) => {
+    if (timer) clearTimeout(timer);
+    activeTimeoutMs = timeoutMs;
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+  };
+  resetTimeout(EXECUTE_TIMEOUT_MS);
+  const url = `${baseUrl(opts)}/v1/actions/execute`;
+  assertAllowedHost(url);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        ...headers(opts.apiKey),
+        Accept: "text/event-stream"
+      },
+      body: JSON.stringify({
+        action_id: actionId,
+        ...httpMethod ? { method: httpMethod } : {},
+        input,
+        stream: true
+      }),
+      redirect: "manual",
+      signal: controller.signal
+    });
+    if (res.status >= 300 && res.status < 400) {
+      throw new Error(
+        `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
+      );
+    }
+    if (!res.ok) {
+      const text = await res.text();
+      throw new HttpError(
+        res.status,
+        text.slice(0, 300),
+        isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0
+      );
+    }
+    const contentType = res.headers.get("content-type") || "";
+    if (!contentType.toLowerCase().includes("text/event-stream")) {
+      const text = await res.text();
+      throw new Error(
+        `expected an SSE response but received "${contentType || "unknown"}": ${text.slice(0, 300)}`
+      );
+    }
+    if (!res.body) return;
+    const idleTimeoutMs = transferIdleTimeoutMs();
+    resetTimeout(idleTimeoutMs);
+    const source = Readable.fromWeb(res.body);
+    for await (const chunk of source) {
+      resetTimeout(idleTimeoutMs);
+      if (!process.stdout.write(chunk)) await once(process.stdout, "drain");
+    }
+  } catch (error) {
+    if (timedOut) throw new RequestTimeoutError(activeTimeoutMs);
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function actionDownload(actionId, input, opts, outputPath, httpMethod) {
+  const controller = new AbortController();
+  let timedOut = false;
+  let activeTimeoutMs = EXECUTE_TIMEOUT_MS;
+  let timer;
+  const resetTimeout = (timeoutMs) => {
+    if (timer) clearTimeout(timer);
+    activeTimeoutMs = timeoutMs;
+    timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+  };
+  resetTimeout(EXECUTE_TIMEOUT_MS);
+  const target = resolve(outputPath);
+  let file;
+  let complete = false;
+  try {
+    try {
+      file = await open(target, "wx");
+    } catch (error) {
+      if (error?.code === "EEXIST") {
+        throw new Error(`Output file already exists: ${target}`);
+      }
+      throw error;
+    }
+    const url = `${baseUrl(opts)}/v1/actions/execute`;
+    assertAllowedHost(url);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: headers(opts.apiKey),
+      body: JSON.stringify({
+        action_id: actionId,
+        ...httpMethod ? { method: httpMethod } : {},
+        input,
+        response_mode: "raw"
+      }),
+      redirect: "manual",
+      signal: controller.signal
+    });
+    if (res.status >= 300 && res.status < 400) {
+      throw new Error(
+        `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
+      );
+    }
+    if (!res.ok) {
+      const text = await res.text();
+      throw new HttpError(
+        res.status,
+        text.slice(0, 300),
+        isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0
+      );
+    }
+    let bytes = 0;
+    if (res.body) {
+      const idleTimeoutMs = transferIdleTimeoutMs();
+      resetTimeout(idleTimeoutMs);
+      const source = Readable.fromWeb(res.body);
+      const counter = new Transform({
+        transform(chunk, _encoding, callback) {
+          resetTimeout(idleTimeoutMs);
+          bytes += Buffer.isBuffer(chunk) ? chunk.length : Buffer.byteLength(chunk);
+          callback(null, chunk);
+        }
+      });
+      await pipeline(source, counter, file.createWriteStream());
+    } else {
+      await file.close();
+    }
+    complete = true;
+    return {
+      output: target,
+      bytes,
+      contentType: res.headers.get("content-type") || void 0,
+      contentDisposition: res.headers.get("content-disposition") || void 0,
+      status: res.status
+    };
+  } catch (error) {
+    if (timedOut) throw new RequestTimeoutError(activeTimeoutMs);
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (!complete && file) {
+      await file.close().catch(() => void 0);
+      await rm(target, { force: true }).catch(() => void 0);
+    }
+  }
+}
 async function actionServices(opts, params = {}) {
   const url = new URL(`${baseUrl(opts)}/v1/actions/services`);
   if (params.page) url.searchParams.set("page", String(params.page));
@@ -719,6 +913,7 @@ function generateCode(target, params) {
 
 // src/commands/action.ts
 var VALID_SOURCES = ["capability", "api"];
+var VALID_SEARCH_SORTS = ["default", "relevance", "price"];
 var LIST_HELP = `xapi-to list - List all actions
 
 USAGE
@@ -747,12 +942,50 @@ FLAGS
   --category <name>         Filter by category
   --page N                  Page number (default: 1)
   --page-size N             Results per page
+  --sort default|relevance|price
+                            Recommended (default), strongest match, or lowest
+                            comparable price after exact-id/local-match guards
+  --include-all-versions    Include active non-default major versions
   --format json|pretty|table  Output format
 
 EXAMPLES
   xapi-to search twitter
   xapi-to search "tweet detail" --source api
+  xapi-to search "tweet detail" --sort relevance
+  xapi-to search weather --sort price
   xapi-to search weather --category utility --format table
+  xapi-to search twitter --include-all-versions
+`;
+var CATEGORIES_HELP = `xapi-to categories - List action categories
+
+USAGE
+  xapi-to categories [flags]
+
+FLAGS
+  --source capability|api   Filter by source type
+  --format json|pretty|table  Output format
+`;
+var SERVICES_HELP = `xapi-to services - List services
+
+USAGE
+  xapi-to services [flags]
+
+FLAGS
+  --category <name>         Filter by category
+  --page N                  Page number
+  --page-size N             Results per page
+  --format json|pretty|table  Output format
+`;
+var GET_BATCH_HELP = `xapi-to get-batch - Get multiple action schemas
+
+USAGE
+  xapi-to get-batch <id> [id ...] [flags]
+
+FLAGS
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi-to get-batch twitter.tweet_detail crypto.token.price
 `;
 var GET_HELP = `xapi-to get - Get action schema
 
@@ -795,6 +1028,8 @@ USAGE
 FLAGS
   --input <json>            Input payload as JSON (required for execution)
   --method GET|POST|...     Override HTTP method
+  --output <path>           Save a raw binary response to a new file
+  --stream                  Forward the action's HTTP SSE response unchanged
   --code <target>           Generate code snippet instead of executing
   --format json|pretty|table  Output format
 
@@ -817,6 +1052,8 @@ CODE TARGETS
 
 EXAMPLES
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi-to call openrouter.audio_speech --input '{"body":{"input":"Hello"}}' --output speech.mp3
+  xapi-to call ai.text.chat.fast --input '{"messages":[{"role":"user","content":"Hello"}]}' --stream
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"123"}' --code py
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"123"}' --code curl --format pretty
 `;
@@ -847,6 +1084,31 @@ function getSource(flags) {
   }
   return flags.source;
 }
+function getSearchSort(flags) {
+  const value = flags.sort;
+  if (value === void 0) return void 0;
+  if (value === "true") {
+    err("--sort requires a value: default, relevance, or price");
+  }
+  if (!VALID_SEARCH_SORTS.includes(value)) {
+    err(`invalid --sort value: "${value}". Must be default, relevance, or price.`);
+  }
+  return value;
+}
+function positiveIntegerFlag(value, name) {
+  if (value === void 0) return void 0;
+  if (!/^\d+$/.test(value) || Number(value) < 1) {
+    err(`${name} must be a positive integer`);
+  }
+  return Number(value);
+}
+function httpMethodFlag(value) {
+  if (value === void 0) return void 0;
+  if (value === "true" || !/^[A-Za-z]+$/.test(value)) {
+    err("--method requires an HTTP method, e.g. --method POST");
+  }
+  return value.toUpperCase();
+}
 async function actionList2(args, flags) {
   showHelpIfRequested(flags, LIST_HELP);
   const cfg = getConfig();
@@ -854,8 +1116,8 @@ async function actionList2(args, flags) {
   try {
     const res = await actionList(cfg, {
       source: getSource(flags),
-      page: flags.page ? parseInt(flags.page) : void 0,
-      page_size: flags["page-size"] ? parseInt(flags["page-size"]) : void 0,
+      page: positiveIntegerFlag(flags.page, "--page"),
+      page_size: positiveIntegerFlag(flags["page-size"], "--page-size"),
       category: flags.category,
       service_id: flags["service-id"]
     });
@@ -881,15 +1143,23 @@ async function actionSearch2(args, flags) {
   showHelpIfRequested(flags, SEARCH_HELP);
   const query = args[0];
   if (!query) err("usage: xapi-to search <query>");
+  const requestedSort = getSearchSort(flags);
   const cfg = getConfig();
   const fmt = flags.format || getFormat();
   try {
     const res = await actionSearch(query, cfg, {
       source: getSource(flags),
       category: flags.category,
-      page: flags.page ? parseInt(flags.page) : void 0,
-      page_size: flags["page-size"] ? parseInt(flags["page-size"]) : void 0
+      page: positiveIntegerFlag(flags.page, "--page"),
+      page_size: positiveIntegerFlag(flags["page-size"], "--page-size"),
+      include_all_versions: flags["include-all-versions"] === "true",
+      sort: requestedSort
     });
+    if (requestedSort && res.sort !== requestedSort) {
+      throw new Error(
+        res.sort ? `backend applied sort "${res.sort}" instead of requested "${requestedSort}"` : "backend does not support search sorting yet; deploy the updated backend before using --sort"
+      );
+    }
     const results = res.results || [];
     if (fmt === "table") {
       output(results.map((a) => ({
@@ -899,7 +1169,8 @@ async function actionSearch2(args, flags) {
         source: a.source ?? "",
         category: a.meta?.category ?? "",
         status: a.status ?? "",
-        cost: a.meta?.cost ?? ""
+        price: a.meta?.pricing?.comparable ? a.meta.pricing.listed_price : "",
+        pricing: a.meta?.pricing?.billing_type ?? ""
       })), "table");
     } else {
       output(res, flags.format);
@@ -909,6 +1180,7 @@ async function actionSearch2(args, flags) {
   }
 }
 async function actionCategories2(args, flags) {
+  showHelpIfRequested(flags, CATEGORIES_HELP);
   const cfg = getConfig();
   const fmt = flags.format || getFormat();
   try {
@@ -923,12 +1195,13 @@ async function actionCategories2(args, flags) {
   }
 }
 async function actionServices2(args, flags) {
+  showHelpIfRequested(flags, SERVICES_HELP);
   const cfg = getConfig();
   const fmt = flags.format || getFormat();
   try {
     const res = await actionServices(cfg, {
-      page: flags.page ? parseInt(flags.page) : void 0,
-      page_size: flags["page-size"] ? parseInt(flags["page-size"]) : void 0,
+      page: positiveIntegerFlag(flags.page, "--page"),
+      page_size: positiveIntegerFlag(flags["page-size"], "--page-size"),
       category: flags.category
     });
     const services = res.services || [];
@@ -953,11 +1226,11 @@ async function actionGet2(args, flags) {
   const id = args[0];
   if (!id) err("usage: xapi-to get <id> [--method GET|POST|DELETE|...]");
   if (flags.code) validateCodeFlag(flags);
+  const methodFilter = httpMethodFlag(flags.method);
   const cfg = getConfig();
   try {
     const res = await actionGet(id, cfg);
     const actions = Array.isArray(res) ? res : [res];
-    const methodFilter = flags.method?.toUpperCase();
     const filtered = methodFilter ? actions.filter((a) => a.method?.toUpperCase() === methodFilter) : actions;
     if (filtered.length === 0) {
       err(`no endpoint found for method "${methodFilter}" in action "${id}"`);
@@ -980,11 +1253,30 @@ async function actionGet2(args, flags) {
     err("get failed", e.message);
   }
 }
+async function actionBatchGet(args, flags) {
+  showHelpIfRequested(flags, GET_BATCH_HELP);
+  if (args.length === 0) err("usage: xapi-to get-batch <id> [id ...]");
+  if (args.length > 100) err("get-batch accepts at most 100 action IDs");
+  const cfg = getConfig();
+  try {
+    const res = await actionBatch(args, cfg);
+    output(res, flags.format);
+  } catch (e) {
+    err("get-batch failed", e.message);
+  }
+}
 async function actionCall2(args, flags) {
   showHelpIfRequested(flags, CALL_HELP);
   const id = args[0];
   if (!id) err(`usage: xapi-to call <id> --input '{"key":"val"}'`);
   if (flags.code) validateCodeFlag(flags);
+  if (flags.output === "true") err("--output requires a file path");
+  const stream = flags.stream === "true" || flags.stream === "1" || flags.stream === "yes";
+  if (flags.code && flags.output) {
+    err("--output cannot be combined with --code");
+  }
+  if (stream && flags.output) err("--stream cannot be combined with --output");
+  if (stream && flags.code) err("--stream cannot be combined with --code");
   const cfg = getConfig();
   let input = {};
   if (flags.input) {
@@ -998,7 +1290,7 @@ async function actionCall2(args, flags) {
     }
   }
   const { method: inputMethod, ...cleanInput } = input;
-  const method = flags.method?.toUpperCase() || (typeof inputMethod === "string" ? inputMethod.toUpperCase() : void 0);
+  const method = httpMethodFlag(flags.method) || (typeof inputMethod === "string" ? inputMethod.toUpperCase() : void 0);
   if (flags.code) {
     const result = generateCode(flags.code, { actionId: id, input: cleanInput, actionHost: cfg.actionHost, method });
     outputCode(result, flags);
@@ -1006,6 +1298,31 @@ async function actionCall2(args, flags) {
   }
   requireApiKey(cfg);
   try {
+    if (stream) {
+      await actionStream(id, cleanInput, cfg, method);
+      return;
+    }
+    if (flags.output) {
+      const result = await actionDownload(
+        id,
+        cleanInput,
+        cfg,
+        flags.output,
+        method
+      );
+      output(
+        {
+          success: true,
+          output: result.output,
+          bytes: result.bytes,
+          status: result.status,
+          content_type: result.contentType,
+          content_disposition: result.contentDisposition
+        },
+        flags.format
+      );
+      return;
+    }
     const res = await actionCall(id, cleanInput, cfg, method);
     output(res, flags.format);
   } catch (e) {
@@ -1017,6 +1334,7 @@ async function actionCall2(args, flags) {
 var config_exports = {};
 __export(config_exports, {
   CONFIG_HELP: () => CONFIG_HELP,
+  HEALTH_HELP: () => HEALTH_HELP,
   configHealth: () => configHealth,
   configSet: () => configSet,
   configShow: () => configShow
@@ -1035,14 +1353,23 @@ COMMANDS
 FLAGS
   --format json|pretty|table   Output format
 
+ENVIRONMENT OVERRIDES
+  XAPI_KEY takes precedence over XAPI_API_KEY, which takes precedence over the file.
+  Saving a file key does not replace an active environment-variable key.
+
 EXAMPLES
   xapi-to config show
   xapi-to config set apiKey=xapi_abc123
   echo "$XAPI_KEY" | xapi-to config set apiKey=-   # keeps the key out of shell history
   xapi-to config health
 `;
+var HEALTH_HELP = `xapi-to health - Check backend connectivity
+
+USAGE
+  xapi-to health [--format json|pretty|table]
+`;
 async function configShow(args, flags) {
-  showConfig();
+  output(showConfig(), flags.format);
 }
 async function configSet(args, flags) {
   if (args.length === 0) err("usage: xapi-to config set apiKey=<key>");
@@ -1060,10 +1387,22 @@ async function configSet(args, flags) {
     if (!value) err("apiKey is empty");
     updates.apiKey = value;
   }
+  const sourceBeforeSave = getApiKeySource();
   saveConfig(updates);
-  console.log(JSON.stringify({ ok: true, updated: Object.keys(updates) }));
+  const source = sourceBeforeSave === "XAPI_KEY" || sourceBeforeSave === "XAPI_API_KEY" ? sourceBeforeSave : "file";
+  output({
+    ok: true,
+    updated: Object.keys(updates),
+    effective: source === "file",
+    source,
+    ...source === "XAPI_KEY" || source === "XAPI_API_KEY" ? { warning: `${source} still overrides the saved file key` } : {}
+  }, flags.format);
 }
 async function configHealth(args, flags) {
+  if (flags.help) {
+    console.log(HEALTH_HELP);
+    return;
+  }
   const cfg = getConfig();
   const start = Date.now();
   try {
@@ -1076,6 +1415,30 @@ async function configHealth(args, flags) {
 }
 
 // src/commands/register.ts
+var REGISTER_HELP = `xapi-to register - Create a new xAPI account
+
+USAGE
+  xapi-to register [referral-code] [flags]
+
+FLAGS
+  --referral-code <code>    Submit an inviter's referral code
+  --referralCode <code>     Alias for --referral-code
+  --force                   Replace an existing file-based API key
+  --format json|pretty|table  Output format
+
+The API key is saved to ~/.xapi/config.json. If XAPI_KEY or XAPI_API_KEY is set,
+unset it before registering because environment variables override the saved file.
+`;
+function validateRegisterResponse(value) {
+  const res = value;
+  if (!res || typeof res.apiKey !== "string" || !res.apiKey.trim()) {
+    throw new Error("invalid register response: missing apiKey");
+  }
+  if (typeof res.referralCode !== "string" || !res.user || typeof res.user.id !== "string") {
+    throw new Error("invalid register response: missing account details");
+  }
+  return res;
+}
 async function registerAccount(referralCode) {
   assertAllowedHost(XAPI_API_HOST);
   const controller = new AbortController();
@@ -1085,39 +1448,57 @@ async function registerAccount(referralCode) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(referralCode ? { referralCode } : {}),
-      signal: controller.signal
+      signal: controller.signal,
+      redirect: "manual"
     });
+    if (res.status >= 300 && res.status < 400) {
+      throw new Error(`refusing to follow redirect to "${res.headers.get("location") ?? "?"}"`);
+    }
     if (!res.ok) {
       const text = await res.text();
       throw new Error(`HTTP ${res.status}: ${text.slice(0, 300)}`);
     }
-    return res.json();
+    return validateRegisterResponse(await res.json());
   } finally {
     clearTimeout(timer);
   }
 }
 async function register(args, flags) {
+  if (flags.help) {
+    console.log(REGISTER_HELP);
+    return;
+  }
   try {
     const cfg = getConfig();
     const force = flags.force === "true" || flags.force === "1" || flags.force === "yes";
+    const source = getApiKeySource();
+    if (source === "XAPI_KEY" || source === "XAPI_API_KEY") {
+      err(
+        "register cannot replace an API key supplied by an environment variable",
+        `Unset ${source} first; it would continue to override the newly saved key.`
+      );
+    }
     if (cfg.apiKey && !force) {
       err("register would overwrite existing apiKey", 'Run "xapi-to register --force" to create a new account and replace the saved key.');
     }
     const rawReferral = flags["referral-code"] ?? flags["referralCode"] ?? args[0];
-    const referralCode = typeof rawReferral === "string" && rawReferral !== "true" && rawReferral.length > 0 ? rawReferral : void 0;
+    if (rawReferral === "true") {
+      err("--referral-code requires a code");
+    }
+    const referralCode = typeof rawReferral === "string" && rawReferral.length > 0 ? rawReferral : void 0;
     const res = await registerAccount(referralCode);
+    const bindUrl = res.bindUrl || res.claimUrl;
     saveConfig({ apiKey: res.apiKey });
     output({
       apiKey: res.apiKey,
       user: res.user,
       referralCode: res.referralCode,
-      claim: {
-        code: res.claimCode,
-        sessionId: res.claimSessionId,
-        url: res.claimUrl
-      },
-      tweetTemplate: res.tweetTemplate,
-      ...referralCode ? { referredBy: referralCode } : {},
+      bindUrl,
+      // Keep the backend's legacy field visible while clients migrate to bindUrl.
+      claimUrl: res.claimUrl || bindUrl,
+      // The backend may accept the registration while ignoring an invalid code,
+      // so only report that the code was submitted, not that a referral exists.
+      ...referralCode ? { referralCodeProvided: referralCode } : {},
       note: force && cfg.apiKey ? "apiKey replaced in ~/.xapi/config.json" : "apiKey saved to ~/.xapi/config.json"
     }, flags.format);
   } catch (e) {
@@ -1127,23 +1508,50 @@ async function register(args, flags) {
 
 // src/commands/topup.ts
 var TOPUP_BASE_URL = "https://www.xapi.to/topup/payment";
+var TOPUP_HELP = `xapi-to topup - Generate a private payment URL
+
+USAGE
+  xapi-to topup [--amount <usd>] [--method stripe|x402]
+
+The generated URL can contain your API key. Do not log or share it.
+`;
 async function topup(args, flags) {
+  if (flags.help) {
+    console.log(TOPUP_HELP);
+    return;
+  }
   const cfg = getConfig();
   const url = new URL(TOPUP_BASE_URL);
   if (cfg.apiKey) url.searchParams.set("apikey", cfg.apiKey);
-  if (flags.method) url.searchParams.set("method", flags.method);
+  if (flags.method) {
+    if (!["stripe", "x402"].includes(flags.method)) {
+      err("invalid --method value", "Expected stripe or x402.");
+    }
+    url.searchParams.set("method", flags.method);
+  }
   const amountStr = flags.amount || args[0];
   if (amountStr) {
-    const amountUsd = parseFloat(amountStr);
-    if (!isNaN(amountUsd) && amountUsd > 0) {
-      url.searchParams.set("amount", String(amountUsd));
+    const normalizedAmount = amountStr.trim();
+    const amountUsd = Number(normalizedAmount);
+    if (!/^(?:\d+(?:\.\d*)?|\.\d+)$/.test(normalizedAmount) || !Number.isFinite(amountUsd) || amountUsd <= 0) {
+      err("invalid top-up amount", "Expected a positive USD number, e.g. --amount 10.");
     }
+    url.searchParams.set("amount", String(amountUsd));
   }
   output({ url: url.toString() }, flags.format);
 }
 
 // src/commands/balance.ts
+var BALANCE_HELP = `xapi-to balance - Show the current account balance
+
+USAGE
+  xapi-to balance [--format json|pretty|table]
+`;
 async function balance(args, flags) {
+  if (flags.help) {
+    console.log(BALANCE_HELP);
+    return;
+  }
   const cfg = getConfig();
   requireApiKey(cfg);
   let token;
@@ -1180,9 +1588,10 @@ __export(oauth_exports, {
 });
 import { spawnSync } from "child_process";
 function openBrowser(url) {
-  const cmd = process.platform === "win32" ? "start" : process.platform === "darwin" ? "open" : "xdg-open";
+  const cmd = process.platform === "win32" ? "rundll32.exe" : process.platform === "darwin" ? "open" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
   try {
-    spawnSync(cmd, [url], { stdio: "ignore" });
+    spawnSync(cmd, args, { stdio: "ignore" });
   } catch {
   }
 }
@@ -1226,9 +1635,11 @@ async function findCurrentKeyRecord(plaintextKey, jwtToken) {
     throw new Error("No API keys found for this account");
   }
   const prefix = plaintextKey.substring(0, 7);
-  const match = keys.find((k) => k.keyPreview.startsWith(prefix));
+  const suffix = plaintextKey.slice(-4);
+  const expectedPreview = `${prefix}****${suffix}`;
+  const match = keys.find((k) => k.keyPreview === expectedPreview);
   if (match) return match;
-  if (keys.length === 1) return keys[0];
+  if (keys.length === 1 && !keys[0].keyPreview.includes("****")) return keys[0];
   throw new Error(
     `Current API key (${prefix}...) was not found in your account keys. Run "xapi-to config set apiKey=<key>" with a valid key before binding OAuth.`
   );
@@ -1283,7 +1694,7 @@ async function selectScopesInteractive(provider) {
     out.write("\x1B[J");
     out.write(buildFrame());
   };
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     const { stdin } = process;
     const wasRaw = stdin.isRaw;
     stdin.setRawMode(true);
@@ -1294,7 +1705,7 @@ async function selectScopesInteractive(provider) {
       stdin.pause();
       out.write("\x1B[?25h");
       out.write("\n");
-      resolve(result);
+      resolve2(result);
     };
     const onData = (buf) => {
       const key = buf.toString();
@@ -1345,13 +1756,20 @@ FLAGS
 EXAMPLES
   xapi-to oauth bind
   xapi-to oauth bind --provider twitter
-  xapi-to oauth bind --scopes "tweet.read users.read"
+  xapi-to oauth providers                    # inspect current default scopes
+  xapi-to oauth bind --scopes "<scope list>"  # override only when needed
   xapi-to oauth status
   xapi-to oauth status --format pretty
   xapi-to oauth unbind abc123
   xapi-to oauth providers
 `;
 async function oauthBind(args, flags) {
+  if (flags.provider === "true") {
+    err("--provider requires a provider name, e.g. --provider twitter");
+  }
+  if (flags.scopes === "true") {
+    err("--scopes requires a space-separated scope list");
+  }
   const cfg = getConfig();
   requireApiKey(cfg);
   const apiKey = cfg.apiKey;
@@ -1409,6 +1827,16 @@ async function oauthBind(args, flags) {
     const authorizationStartedAt = /* @__PURE__ */ new Date();
     const result = await initiateOAuth(keyRecord.id, provider.id, jwtToken, XAPI_API_HOST, scopes);
     const { authorizationUrl } = result;
+    let authorizationTarget;
+    try {
+      authorizationTarget = new URL(authorizationUrl);
+    } catch {
+      throw new Error("OAuth provider returned an invalid authorization URL");
+    }
+    const localHttp = authorizationTarget.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(authorizationTarget.hostname);
+    if (authorizationTarget.protocol !== "https:" && !localHttp) {
+      throw new Error(`OAuth provider returned an unsupported authorization URL protocol: ${authorizationTarget.protocol}`);
+    }
     if (isTTY) {
       if (!headerPrinted) {
         console.error(`
@@ -1597,7 +2025,7 @@ function parsePositiveInt(raw, flagName) {
 }
 function sleep2(ms) {
   if (ms <= 0) return Promise.resolve();
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 function extractTaskPayload(res) {
   if (res && typeof res === "object") {
@@ -1754,6 +2182,8 @@ COMMANDS
     --source capability|api         Filter by source type
     --category <name>               Filter by category
     --page N  --page-size N         Pagination
+    --sort default|relevance|price  Recommended, strongest match, or comparable price
+    --include-all-versions          Include active non-default major versions
   categories                        List all action categories
     --source capability|api         Filter by source type
   services                          List all services
@@ -1761,8 +2191,11 @@ COMMANDS
     --category <name>               Filter by category
   get <id> [--method GET|POST|...]   Get action schema (filter by HTTP method)
     --code <target>                  Generate code snippet (curl, py, js, ts, go)
+  get-batch <id> [id ...]           Get up to 100 action schemas
   call <id> --input '{"key":"val"}'  Execute an action
     --method GET|POST|...            Override HTTP method
+    --output <path>                   Save a raw binary response to a new file
+    --stream                          Forward HTTP SSE frames unchanged
     --code <target>                  Generate code snippet instead of executing
     Variants: python.requests, python.httpx, javascript.fetch, javascript.axios
 
@@ -1779,7 +2212,7 @@ COMMANDS
 
   register [referral-code]          Create a new user account (apiKey saved automatically)
     --referral-code <code>          Register with an inviter's referral code (also: --referralCode, or as positional arg)
-    --force                         Replace an existing saved apiKey
+    --force                         Replace an existing file-based apiKey
   balance                           Show current account balance
   topup [--amount <usd>] [--method stripe|x402]   Generate payment URL
 
@@ -1794,9 +2227,12 @@ GLOBAL FLAGS
   --help                            Show help (use with a command for details, e.g. xapi-to get --help)
 
 ENV VARS
-  XAPI_KEY       API key (header: XAPI-Key)
+  XAPI_KEY          API key (highest precedence; header: XAPI-Key)
+  XAPI_API_KEY      Compatible API key alias
   XAPI_ACTION_HOST   Action service host (default: action.xapi.to)
+  XAPI_API_HOST      Auth/account service host (default: api.xapi.to)
   XAPI_OUTPUT        Default output format
+  XAPI_TRANSFER_IDLE_TIMEOUT_MS  SSE/download idle timeout (default: 60000)
 
 EXAMPLES
   xapi-to register
@@ -1806,9 +2242,11 @@ EXAMPLES
   xapi-to list --source capability
   xapi-to search twitter --source api
   xapi-to get twitter.tweet_detail
+  xapi-to get-batch twitter.tweet_detail crypto.token.price
   xapi-to get twitter.tweet_detail --code curl
   xapi-to get twitter.tweet_detail --code py --format pretty
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi-to call openrouter.audio_speech --input '{"body":{"input":"Hello"}}' --output speech.mp3
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}' --code python
   xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
   xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 2s --timeout 10m
@@ -1823,7 +2261,16 @@ async function main() {
     console.log(HELP);
     process.exit(0);
   }
-  if (flags.format) process.env.XAPI_OUTPUT = flags.format;
+  if (flags.format) {
+    if (!["json", "pretty", "table"].includes(flags.format)) {
+      console.error(JSON.stringify({
+        error: `invalid --format value: ${flags.format}`,
+        hint: "expected json, pretty, or table"
+      }));
+      process.exit(1);
+    }
+    process.env.XAPI_OUTPUT = flags.format;
+  }
   const [cmd, ...rest] = positional;
   switch (cmd) {
     // ── Action commands (top-level) ──
@@ -1837,6 +2284,8 @@ async function main() {
       return actionServices2(rest, flags);
     case "get":
       return actionGet2(rest, flags);
+    case "get-batch":
+      return actionBatchGet(rest, flags);
     case "call":
       return actionCall2(rest, flags);
     case "task": {