xapi-to 0.1.12 → 0.1.14

package/dist/index.js

@@ -0,0 +1,1335 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/config.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+
+// src/format.ts
+function getFormat() {
+  const f = process.env.XAPI_OUTPUT || "json";
+  if (f === "pretty" || f === "table") return f;
+  return "json";
+}
+function output(data, format) {
+  const fmt = format || getFormat();
+  if (fmt === "json") {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  if (fmt === "pretty") {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  if (fmt === "table" && Array.isArray(data)) {
+    printTable(data);
+    return;
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+function printTable(rows) {
+  if (rows.length === 0) {
+    console.log("(empty)");
+    return;
+  }
+  const keys = Object.keys(rows[0]);
+  const widths = keys.map(
+    (k) => Math.min(40, Math.max(k.length, ...rows.map((r) => String(r[k] ?? "").length)))
+  );
+  const sep = widths.map((w) => "-".repeat(w)).join("  ");
+  const header = keys.map((k, i) => k.padEnd(widths[i])).join("  ");
+  console.log(header);
+  console.log(sep);
+  for (const row of rows) {
+    const line = keys.map((k, i) => String(row[k] ?? "").slice(0, widths[i]).padEnd(widths[i])).join("  ");
+    console.log(line);
+  }
+}
+function err(msg, detail) {
+  if (process.stderr.isTTY) {
+    console.error(`Error: ${msg}`);
+    if (detail !== void 0) console.error(`  ${detail}`);
+  } else {
+    const out = { error: msg };
+    if (detail !== void 0) out.detail = detail;
+    console.error(JSON.stringify(out));
+  }
+  process.exit(1);
+}
+
+// src/config.ts
+import { homedir } from "os";
+import { join } from "path";
+var XAPI_ACTION_HOST = process.env.XAPI_ACTION_HOST || "action.xapi.to";
+var XAPI_API_HOST = process.env.XAPI_API_HOST || "api.xapi.to";
+function scheme(host) {
+  return host.startsWith("localhost") || host.startsWith("127.") ? "http" : "https";
+}
+var CONFIG_DIR = join(homedir(), ".xapi");
+var CONFIG_FILE = join(CONFIG_DIR, "config.json");
+function loadFileConfig() {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function getConfig() {
+  const file = loadFileConfig();
+  return {
+    actionHost: XAPI_ACTION_HOST,
+    apiKey: process.env.XAPI_KEY || process.env.XAPI_API_KEY || file.apiKey
+  };
+}
+function requireApiKey(cfg) {
+  if (!cfg.apiKey) {
+    err("API key not configured", 'Run "npx xapi-to register" to create an account, or "npx xapi-to config set apiKey=<key>" to set an existing key.');
+  }
+}
+function saveConfig(updates) {
+  const current = loadFileConfig();
+  const merged = { ...current, ...updates };
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 448 });
+  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 384 });
+}
+function showConfig() {
+  const cfg = getConfig();
+  const file = loadFileConfig();
+  console.log(JSON.stringify({
+    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"
+    },
+    configFile: CONFIG_FILE
+  }, null, 2));
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var EXECUTE_TIMEOUT_MS = 6e4;
+async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...options, signal: controller.signal });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`HTTP ${res.status}: ${text.slice(0, 300)}`);
+    }
+    const body = await res.json();
+    if (body && typeof body === "object" && "success" in body && body.success === false) {
+      const data = body.data;
+      if (data?.statusCode === 401 || data?.error === "Unauthorized") {
+        throw new Error(
+          "Authentication failed: " + (data.message || "Invalid or missing API key") + '. Run "npx xapi-to config set apiKey=<key>" to update your key.'
+        );
+      }
+      if (data?.error === "OAuth Required" || data?.statusCode === 403 && data?.message?.includes("OAuth")) {
+        throw new Error(
+          (data.message || "OAuth authorization required") + '. Run "xapi oauth bind" to connect your account.'
+        );
+      }
+    }
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function headers(apiKey) {
+  const h = { "Content-Type": "application/json" };
+  if (apiKey) h["XAPI-Key"] = apiKey;
+  return h;
+}
+function baseUrl(opts) {
+  return `${scheme(opts.actionHost)}://${opts.actionHost}`;
+}
+async function actionList(opts, params = {}) {
+  const url = new URL(`${baseUrl(opts)}/v1/actions`);
+  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.category) url.searchParams.set("category", params.category);
+  if (params.source) url.searchParams.set("source", params.source);
+  if (params.service_id) url.searchParams.set("service_id", params.service_id);
+  return request(
+    url.toString(),
+    { method: "GET", headers: headers(opts.apiKey) }
+  );
+}
+async function actionSearch(query, opts, params = {}) {
+  const url = new URL(`${baseUrl(opts)}/v1/actions/search`);
+  url.searchParams.set("q", query);
+  if (params.category) url.searchParams.set("category", params.category);
+  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));
+  return request(
+    url.toString(),
+    { method: "GET", headers: headers(opts.apiKey) }
+  );
+}
+async function actionCategories(opts, params = {}) {
+  const url = new URL(`${baseUrl(opts)}/v1/actions/categories`);
+  if (params.source) url.searchParams.set("source", params.source);
+  return request(
+    url.toString(),
+    { method: "GET", headers: headers(opts.apiKey) }
+  );
+}
+async function actionGet(id, opts) {
+  return request(
+    `${baseUrl(opts)}/v1/actions/${encodeURIComponent(id)}`,
+    { method: "GET", headers: headers(opts.apiKey) }
+  );
+}
+async function actionCall(actionId, input, opts, httpMethod) {
+  return request(
+    `${baseUrl(opts)}/v1/actions/execute`,
+    {
+      method: "POST",
+      headers: headers(opts.apiKey),
+      body: JSON.stringify({ action_id: actionId, ...httpMethod ? { method: httpMethod } : {}, input })
+    },
+    EXECUTE_TIMEOUT_MS
+  );
+}
+async function actionServices(opts, params = {}) {
+  const url = new URL(`${baseUrl(opts)}/v1/actions/services`);
+  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.category) url.searchParams.set("category", params.category);
+  return request(
+    url.toString(),
+    { method: "GET", headers: headers(opts.apiKey) }
+  );
+}
+async function healthCheck(opts) {
+  return request(
+    `${baseUrl(opts)}/health`,
+    { method: "GET", headers: headers(opts.apiKey) },
+    5e3
+  );
+}
+async function loginWithApiKey(apiKey, apiHost) {
+  return request(
+    `${scheme(apiHost)}://${apiHost}/api/auth/login/apikey`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ apiKey })
+    }
+  );
+}
+function jwtHeaders(jwtToken) {
+  return { "Content-Type": "application/json", Authorization: `Bearer ${jwtToken}` };
+}
+async function listKeys(jwtToken, apiHost) {
+  return request(
+    `${scheme(apiHost)}://${apiHost}/api/keys`,
+    { method: "GET", headers: jwtHeaders(jwtToken) }
+  );
+}
+async function enableOAuthForKey(keyId, plaintextKey, jwtToken, apiHost) {
+  return request(
+    `${scheme(apiHost)}://${apiHost}/api/keys/${keyId}/enable-oauth`,
+    {
+      method: "POST",
+      headers: jwtHeaders(jwtToken),
+      body: JSON.stringify({ plaintextKey })
+    }
+  );
+}
+async function listOAuthProviders(apiHost) {
+  return request(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/providers`,
+    { method: "GET", headers: { "Content-Type": "application/json" } }
+  );
+}
+async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost) {
+  return request(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/authorize`,
+    {
+      method: "POST",
+      headers: jwtHeaders(jwtToken),
+      body: JSON.stringify({ apiKeyId, providerId })
+    }
+  );
+}
+async function listOAuthBindings(jwtToken, apiHost) {
+  return request(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings`,
+    { method: "GET", headers: jwtHeaders(jwtToken) }
+  );
+}
+async function deleteOAuthBinding(bindingId, jwtToken, apiHost) {
+  return request(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings/${bindingId}`,
+    { method: "DELETE", headers: jwtHeaders(jwtToken) }
+  );
+}
+
+// src/codegen.ts
+var TARGET_MAP = {
+  "curl": { lang: "curl", lib: "curl" },
+  "python": { lang: "python", lib: "requests" },
+  "py": { lang: "python", lib: "requests" },
+  "python.requests": { lang: "python", lib: "requests" },
+  "python.httpx": { lang: "python", lib: "httpx" },
+  "py.requests": { lang: "python", lib: "requests" },
+  "py.httpx": { lang: "python", lib: "httpx" },
+  "javascript": { lang: "javascript", lib: "fetch" },
+  "js": { lang: "javascript", lib: "fetch" },
+  "javascript.fetch": { lang: "javascript", lib: "fetch" },
+  "javascript.axios": { lang: "javascript", lib: "axios" },
+  "js.fetch": { lang: "javascript", lib: "fetch" },
+  "js.axios": { lang: "javascript", lib: "axios" },
+  "typescript": { lang: "typescript", lib: "fetch" },
+  "ts": { lang: "typescript", lib: "fetch" },
+  "typescript.fetch": { lang: "typescript", lib: "fetch" },
+  "ts.fetch": { lang: "typescript", lib: "fetch" },
+  "go": { lang: "go", lib: "net/http" }
+};
+var SUPPORTED_TARGETS = [
+  "curl",
+  "python (py) [.requests, .httpx]",
+  "javascript (js) [.fetch, .axios]",
+  "typescript (ts) [.fetch]",
+  "go [net/http]"
+];
+function resolveTarget(raw) {
+  const target = TARGET_MAP[raw.toLowerCase()];
+  if (!target) {
+    throw new Error(
+      `unknown --code target: "${raw}". Supported: ${SUPPORTED_TARGETS.join(", ")}`
+    );
+  }
+  return target;
+}
+function typeDefault(type) {
+  switch (type) {
+    case "string":
+      return "";
+    case "number":
+    case "integer":
+      return 0;
+    case "boolean":
+      return false;
+    case "object":
+      return {};
+    case "array":
+      return [];
+    default:
+      return "";
+  }
+}
+function buildDefaultInput(schema) {
+  if (!schema.properties) return {};
+  const result = {};
+  for (const [key, prop] of Object.entries(schema.properties)) {
+    if (prop.default !== void 0) {
+      const val = prop.default;
+      result[key] = typeof val === "object" && val !== null ? JSON.parse(JSON.stringify(val)) : val;
+    } else {
+      result[key] = typeDefault(prop.type ?? "string");
+    }
+  }
+  return result;
+}
+var SAFE_HOST_PATTERN = /^[a-zA-Z0-9._\-]+(:\d{1,5})?$/;
+function validateHost(host) {
+  if (!SAFE_HOST_PATTERN.test(host)) {
+    throw new Error(`invalid actionHost: "${host}" \u2014 must be a valid hostname with optional port`);
+  }
+}
+function baseUrl2(actionHost) {
+  validateHost(actionHost);
+  return `${scheme(actionHost)}://${actionHost}/v1/actions/execute`;
+}
+function jsonBody(actionId, input, method) {
+  return JSON.stringify({ action_id: actionId, ...method ? { method } : {}, input }, null, 2);
+}
+function indent(text, spaces) {
+  const pad = " ".repeat(spaces);
+  const lines = text.split("\n");
+  return lines.map((line, i) => i === 0 ? line : pad + line).join("\n");
+}
+function shellEscape(s) {
+  return s.replace(/'/g, "'\\''");
+}
+function genCurl(params) {
+  const url = baseUrl2(params.actionHost);
+  const body = jsonBody(params.actionId, params.input, params.method);
+  return [
+    "# Set XAPI_KEY env var or replace with your key",
+    `curl -X POST '${shellEscape(url)}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -H "XAPI-Key: \${XAPI_KEY}" \\`,
+    `  -d '${shellEscape(body)}'`
+  ].join("\n");
+}
+function genPython(lib, params) {
+  const url = baseUrl2(params.actionHost);
+  const payload = { action_id: params.actionId, ...params.method ? { method: params.method } : {}, input: params.input };
+  return [
+    `# pip install ${lib}`,
+    "# Set XAPI_KEY env var or replace with your key",
+    "import os",
+    `import ${lib}`,
+    "",
+    `resp = ${lib}.post(`,
+    `    "${url}",`,
+    `    headers={`,
+    `        "Content-Type": "application/json",`,
+    `        "XAPI-Key": os.environ["XAPI_KEY"],`,
+    `    },`,
+    `    json=${indent(pythonDict(payload), 4)},`,
+    `)`,
+    "print(resp.json())"
+  ].join("\n");
+}
+function genJavaScriptFetch(params) {
+  const url = baseUrl2(params.actionHost);
+  const body = jsonBody(params.actionId, params.input, params.method);
+  return [
+    "// Set XAPI_KEY env var or replace with your key",
+    `const resp = await fetch("${url}", {`,
+    `  method: "POST",`,
+    `  headers: {`,
+    `    "Content-Type": "application/json",`,
+    `    "XAPI-Key": process.env.XAPI_KEY,`,
+    `  },`,
+    `  body: JSON.stringify(${indent(body, 2)}),`,
+    `});`,
+    "console.log(await resp.json());"
+  ].join("\n");
+}
+function genJavaScriptAxios(params) {
+  const url = baseUrl2(params.actionHost);
+  const body = jsonBody(params.actionId, params.input, params.method);
+  return [
+    "// npm install axios",
+    "// Set XAPI_KEY env var or replace with your key",
+    'import axios from "axios";',
+    "",
+    `const resp = await axios.post(`,
+    `  "${url}",`,
+    `  ${indent(body, 2)},`,
+    `  {`,
+    `    headers: {`,
+    `      "Content-Type": "application/json",`,
+    `      "XAPI-Key": process.env.XAPI_KEY,`,
+    `    },`,
+    `  },`,
+    `);`,
+    "console.log(resp.data);"
+  ].join("\n");
+}
+function genTypescriptFetch(params) {
+  const url = baseUrl2(params.actionHost);
+  const body = jsonBody(params.actionId, params.input, params.method);
+  return [
+    "// Set XAPI_KEY env var or replace with your key",
+    `const resp: Response = await fetch("${url}", {`,
+    `  method: "POST",`,
+    `  headers: {`,
+    `    "Content-Type": "application/json",`,
+    `    "XAPI-Key": process.env.XAPI_KEY!,`,
+    `  },`,
+    `  body: JSON.stringify(${indent(body, 2)}),`,
+    `});`,
+    "const data: unknown = await resp.json();",
+    "console.log(data);"
+  ].join("\n");
+}
+function genGo(params) {
+  const url = baseUrl2(params.actionHost);
+  const body = jsonBody(params.actionId, params.input, params.method);
+  const escaped = body.replace(/`/g, '` + "`" + `');
+  return [
+    "// Set XAPI_KEY env var or replace with your key",
+    "package main",
+    "",
+    "import (",
+    '	"fmt"',
+    '	"io"',
+    '	"net/http"',
+    '	"os"',
+    '	"strings"',
+    ")",
+    "",
+    "func main() {",
+    `	body := \`${escaped}\``,
+    `	req, err := http.NewRequest("POST", "${url}", strings.NewReader(body))`,
+    "	if err != nil {",
+    "		panic(err)",
+    "	}",
+    '	req.Header.Set("Content-Type", "application/json")',
+    '	req.Header.Set("XAPI-Key", os.Getenv("XAPI_KEY"))',
+    "",
+    "	resp, err := http.DefaultClient.Do(req)",
+    "	if err != nil {",
+    "		panic(err)",
+    "	}",
+    "	defer resp.Body.Close()",
+    "",
+    "	result, err := io.ReadAll(resp.Body)",
+    "	if err != nil {",
+    "		panic(err)",
+    "	}",
+    "	fmt.Println(string(result))",
+    "}"
+  ].join("\n");
+}
+function pythonDict(obj, depth = 0) {
+  const pad = "    ".repeat(depth);
+  const inner = "    ".repeat(depth + 1);
+  if (obj === null || obj === void 0) return "None";
+  if (typeof obj === "boolean") return obj ? "True" : "False";
+  if (typeof obj === "number") return String(obj);
+  if (typeof obj === "string") return JSON.stringify(obj);
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) return "[]";
+    const items = obj.map((v) => `${inner}${pythonDict(v, depth + 1)}`);
+    return `[
+${items.join(",\n")}
+${pad}]`;
+  }
+  if (typeof obj === "object") {
+    const entries = Object.entries(obj);
+    if (entries.length === 0) return "{}";
+    const items = entries.map(
+      ([k, v]) => `${inner}${JSON.stringify(k)}: ${pythonDict(v, depth + 1)}`
+    );
+    return `{
+${items.join(",\n")}
+${pad}}`;
+  }
+  return String(obj);
+}
+var GENERATORS = {
+  curl: { curl: genCurl },
+  python: { requests: (p) => genPython("requests", p), httpx: (p) => genPython("httpx", p) },
+  javascript: { fetch: genJavaScriptFetch, axios: genJavaScriptAxios },
+  typescript: { fetch: genTypescriptFetch },
+  go: { "net/http": genGo }
+};
+function generateCode(target, params) {
+  const { lang, lib } = resolveTarget(target);
+  const generator = GENERATORS[lang]?.[lib];
+  if (!generator) {
+    throw new Error(`no generator for ${lang}.${lib}`);
+  }
+  return { lang, lib, code: generator(params) };
+}
+
+// src/commands/action.ts
+var VALID_SOURCES = ["capability", "api"];
+var LIST_HELP = `xapi list - List all actions
+
+USAGE
+  xapi list [flags]
+
+FLAGS
+  --source capability|api   Filter by source type
+  --category <name>         Filter by category
+  --service-id <id>         Filter by service
+  --page N                  Page number (default: 1)
+  --page-size N             Results per page
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi list
+  xapi list --source api --format table
+  xapi list --category social --page 2
+`;
+var SEARCH_HELP = `xapi search - Search actions by keyword
+
+USAGE
+  xapi search <query> [flags]
+
+FLAGS
+  --source capability|api   Filter by source type
+  --category <name>         Filter by category
+  --page N                  Page number (default: 1)
+  --page-size N             Results per page
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi search twitter
+  xapi search "tweet detail" --source api
+  xapi search weather --category utility --format table
+`;
+var GET_HELP = `xapi get - Get action schema
+
+USAGE
+  xapi get <id> [flags]
+
+FLAGS
+  --method GET|POST|...     Filter by HTTP method
+  --code <target>           Generate code snippet instead of showing schema
+  --format json|pretty|table  Output format
+
+CODE TARGETS
+  curl                      cURL command
+  py, python                Python (requests)
+  python.requests           Python with requests
+  py.requests               alias for python.requests
+  python.httpx              Python with httpx
+  py.httpx                  alias for python.httpx
+  js, javascript            JavaScript (fetch)
+  javascript.fetch          JavaScript with fetch
+  js.fetch                  alias for javascript.fetch
+  javascript.axios          JavaScript with axios
+  js.axios                  alias for javascript.axios
+  ts, typescript            TypeScript (fetch)
+  typescript.fetch          TypeScript with fetch
+  ts.fetch                  alias for typescript.fetch
+  go                        Go (net/http)
+
+EXAMPLES
+  xapi get twitter.tweet_detail
+  xapi get twitter.tweet_detail --method POST
+  xapi get twitter.tweet_detail --code curl
+  xapi get twitter.tweet_detail --code python.httpx --format pretty
+`;
+var CALL_HELP = `xapi call - Execute an action
+
+USAGE
+  xapi call <id> --input '{"key":"val"}' [flags]
+
+FLAGS
+  --input <json>            Input payload as JSON (required for execution)
+  --method GET|POST|...     Override HTTP method
+  --code <target>           Generate code snippet instead of executing
+  --format json|pretty|table  Output format
+
+CODE TARGETS
+  curl                      cURL command
+  py, python                Python (requests)
+  python.requests           Python with requests
+  py.requests               alias for python.requests
+  python.httpx              Python with httpx
+  py.httpx                  alias for python.httpx
+  js, javascript            JavaScript (fetch)
+  javascript.fetch          JavaScript with fetch
+  js.fetch                  alias for javascript.fetch
+  javascript.axios          JavaScript with axios
+  js.axios                  alias for javascript.axios
+  ts, typescript            TypeScript (fetch)
+  typescript.fetch          TypeScript with fetch
+  ts.fetch                  alias for typescript.fetch
+  go                        Go (net/http)
+
+EXAMPLES
+  xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi call twitter.tweet_detail --input '{"tweet_id":"123"}' --code py
+  xapi call twitter.tweet_detail --input '{"tweet_id":"123"}' --code curl --format pretty
+`;
+function showHelpIfRequested(flags, helpText) {
+  if (flags.help) {
+    console.log(helpText);
+    process.exit(0);
+  }
+}
+function validateCodeFlag(flags) {
+  if (flags.code === "true") {
+    err("--code requires a target language, e.g. --code curl, --code py, --code js");
+  }
+  resolveTarget(flags.code);
+}
+function outputCode(result, flags) {
+  const fmt = flags.format || getFormat();
+  if (fmt === "json") {
+    output({ language: result.lang, library: result.lib, code: result.code }, "json");
+  } else {
+    console.log(result.code);
+  }
+}
+function getSource(flags) {
+  if (!flags.source) return void 0;
+  if (!VALID_SOURCES.includes(flags.source)) {
+    err(`invalid --source value: "${flags.source}". Must be "capability" or "api".`);
+  }
+  return flags.source;
+}
+async function actionList2(args, flags) {
+  showHelpIfRequested(flags, LIST_HELP);
+  const cfg = getConfig();
+  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,
+      category: flags.category,
+      service_id: flags["service-id"]
+    });
+    const actions = res.actions || [];
+    if (flags.format === "table") {
+      output(actions.map((a) => ({
+        id: a.id,
+        method: a.method ?? "",
+        displayName: a.displayName ?? "",
+        source: a.source ?? "",
+        category: a.meta?.category ?? "",
+        status: a.status ?? "",
+        cost: a.meta?.cost ?? ""
+      })), "table");
+    } else {
+      output(res, flags.format);
+    }
+  } catch (e) {
+    err("list failed", e.message);
+  }
+}
+async function actionSearch2(args, flags) {
+  showHelpIfRequested(flags, SEARCH_HELP);
+  const query = args[0];
+  if (!query) err("usage: xapi search <query>");
+  const cfg = getConfig();
+  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
+    });
+    const results = res.results || [];
+    if (flags.format === "table") {
+      output(results.map((a) => ({
+        id: a.id,
+        method: a.method ?? "",
+        displayName: a.displayName ?? "",
+        source: a.source ?? "",
+        category: a.meta?.category ?? "",
+        status: a.status ?? "",
+        cost: a.meta?.cost ?? ""
+      })), "table");
+    } else {
+      output(res, flags.format);
+    }
+  } catch (e) {
+    err("search failed", e.message);
+  }
+}
+async function actionCategories2(args, flags) {
+  const cfg = getConfig();
+  try {
+    const res = await actionCategories(cfg, { source: getSource(flags) });
+    if (flags.format === "table") {
+      output(res.categories.map((c) => ({ category: c })), "table");
+    } else {
+      output(res, flags.format);
+    }
+  } catch (e) {
+    err("categories failed", e.message);
+  }
+}
+async function actionServices2(args, flags) {
+  const cfg = getConfig();
+  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,
+      category: flags.category
+    });
+    const services = res.services || [];
+    if (flags.format === "table") {
+      output(services.map((s) => ({
+        id: s.id,
+        name: s.name ?? "",
+        category: s.category ?? "",
+        source: s.source ?? "",
+        endpoints: s.endpointCount ?? "",
+        status: s.status ?? ""
+      })), "table");
+    } else {
+      output(res, flags.format);
+    }
+  } catch (e) {
+    err("services failed", e.message);
+  }
+}
+async function actionGet2(args, flags) {
+  showHelpIfRequested(flags, GET_HELP);
+  const id = args[0];
+  if (!id) err("usage: xapi get <id> [--method GET|POST|DELETE|...]");
+  if (flags.code) validateCodeFlag(flags);
+  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}"`);
+    }
+    if (flags.code) {
+      if (filtered.length > 1) {
+        process.stderr.write(
+          `Warning: action "${id}" has ${filtered.length} endpoints; using method "${filtered[0].method}". Use --method to select a specific one.
+`
+        );
+      }
+      const action = filtered[0];
+      const { method: _schemaMethod, ...cleanCodeInput } = buildDefaultInput(action.input ?? {});
+      const result = generateCode(flags.code, { actionId: id, input: cleanCodeInput, actionHost: cfg.actionHost, method: action.method });
+      outputCode(result, flags);
+      return;
+    }
+    output(filtered.length === 1 ? filtered[0] : filtered, flags.format);
+  } catch (e) {
+    err("get failed", e.message);
+  }
+}
+async function actionCall2(args, flags) {
+  showHelpIfRequested(flags, CALL_HELP);
+  const id = args[0];
+  if (!id) err(`usage: xapi call <id> --input '{"key":"val"}'`);
+  if (flags.code) validateCodeFlag(flags);
+  const cfg = getConfig();
+  let input = {};
+  if (flags.input) {
+    try {
+      input = JSON.parse(flags.input);
+    } catch {
+      err("--input must be valid JSON");
+    }
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+      err("--input must be a JSON object");
+    }
+  }
+  const { method: inputMethod, ...cleanInput } = input;
+  const method = flags.method?.toUpperCase() || (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);
+    return;
+  }
+  requireApiKey(cfg);
+  try {
+    const res = await actionCall(id, cleanInput, cfg, method);
+    output(res, flags.format);
+  } catch (e) {
+    err("call failed", e.message);
+  }
+}
+
+// src/commands/config.ts
+var config_exports = {};
+__export(config_exports, {
+  CONFIG_HELP: () => CONFIG_HELP,
+  configHealth: () => configHealth,
+  configSet: () => configSet,
+  configShow: () => configShow
+});
+var CONFIG_HELP = `xapi config - Manage CLI configuration
+
+USAGE
+  xapi config <command> [flags]
+
+COMMANDS
+  show                       Show current config (host, apiKey path, etc.)
+  set apiKey=<key>           Save API key to ~/.xapi/config.json
+  health                     Check backend connectivity (alias: xapi health)
+
+FLAGS
+  --format json|pretty|table   Output format
+
+EXAMPLES
+  xapi config show
+  xapi config set apiKey=xapi_abc123
+  xapi config health
+`;
+async function configShow(args, flags) {
+  showConfig();
+}
+async function configSet(args, flags) {
+  if (args.length === 0) err("usage: xapi config set apiKey=<key>");
+  const updates = {};
+  for (const arg of args) {
+    const eq = arg.indexOf("=");
+    if (eq < 1) err(`invalid key=value: ${arg}`);
+    const key = arg.slice(0, eq);
+    if (key === "host") err("host is built-in and cannot be configured");
+    if (key !== "apiKey") err(`unknown config key: ${key} (only apiKey is configurable)`);
+    updates.apiKey = arg.slice(eq + 1);
+  }
+  saveConfig(updates);
+  console.log(JSON.stringify({ ok: true, updated: Object.keys(updates) }));
+}
+async function configHealth(args, flags) {
+  const cfg = getConfig();
+  const start = Date.now();
+  try {
+    await healthCheck(cfg);
+    output({ status: "ok", host: cfg.actionHost, latency_ms: Date.now() - start }, flags.format);
+  } catch (e) {
+    output({ status: "error", host: cfg.actionHost, error: e.message }, flags.format);
+    process.exit(1);
+  }
+}
+
+// src/commands/register.ts
+async function registerAccount(referralCode) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15e3);
+  try {
+    const res = await fetch(`${scheme(XAPI_API_HOST)}://${XAPI_API_HOST}/api/auth/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(referralCode ? { referralCode } : {}),
+      signal: controller.signal
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`HTTP ${res.status}: ${text.slice(0, 300)}`);
+    }
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function register(args, flags) {
+  try {
+    const rawReferral = flags["referral-code"] ?? flags["referralCode"] ?? args[0];
+    const referralCode = typeof rawReferral === "string" && rawReferral !== "true" && rawReferral.length > 0 ? rawReferral : void 0;
+    const res = await registerAccount(referralCode);
+    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 } : {},
+      note: "apiKey saved to ~/.xapi/config.json"
+    }, flags.format);
+  } catch (e) {
+    err("register failed", e.message);
+  }
+}
+
+// src/commands/topup.ts
+var TOPUP_BASE_URL = "https://www.xapi.to/topup/payment";
+async function topup(args, flags) {
+  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);
+  const amountStr = flags.amount || args[0];
+  if (amountStr) {
+    const amountUsd = parseFloat(amountStr);
+    if (!isNaN(amountUsd) && amountUsd > 0) {
+      url.searchParams.set("amount", String(amountUsd));
+    }
+  }
+  output({ url: url.toString() }, flags.format);
+}
+
+// src/commands/balance.ts
+async function balance(args, flags) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  let token;
+  try {
+    const res = await loginWithApiKey(cfg.apiKey, XAPI_API_HOST);
+    token = res.accessToken;
+  } catch (e) {
+    err("login failed", e.message);
+  }
+  try {
+    const me = await request(
+      `${scheme(XAPI_API_HOST)}://${XAPI_API_HOST}/api/auth/me`,
+      { method: "GET", headers: { Authorization: `Bearer ${token}` } }
+    );
+    output({
+      balance: me.balance,
+      accountType: me.accountType,
+      tier: me.tier
+    }, flags.format);
+  } catch (e) {
+    err("balance fetch failed", e.message);
+  }
+}
+
+// src/commands/oauth.ts
+var oauth_exports = {};
+__export(oauth_exports, {
+  OAUTH_HELP: () => OAUTH_HELP,
+  oauthBind: () => oauthBind,
+  oauthProviders: () => oauthProviders,
+  oauthStatus: () => oauthStatus,
+  oauthUnbind: () => oauthUnbind
+});
+import { spawnSync } from "child_process";
+function openBrowser(url) {
+  const cmd = process.platform === "win32" ? "start" : process.platform === "darwin" ? "open" : "xdg-open";
+  try {
+    spawnSync(cmd, [url], { stdio: "ignore" });
+  } catch {
+  }
+}
+async function pollForBinding(apiKeyId, providerId, jwtToken, timeoutMs = 5 * 60 * 1e3, intervalMs = 3e3) {
+  const deadline = Date.now() + timeoutMs;
+  const isTTY = process.stdout.isTTY;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, intervalMs));
+    try {
+      const bindings = await listOAuthBindings(jwtToken, XAPI_API_HOST);
+      const match = Array.isArray(bindings) ? bindings.find((b) => b.apiKeyId === apiKeyId && b.providerId === providerId) : null;
+      if (match) return match;
+    } catch {
+    }
+    if (isTTY) {
+      const remaining = Math.ceil((deadline - Date.now()) / 1e3);
+      process.stdout.write(`\r  Waiting for authorization... (${remaining}s remaining)  `);
+    }
+  }
+  if (process.stdout.isTTY) process.stdout.write("\n");
+  return null;
+}
+async function loginAndGetJwt(apiKey) {
+  const result = await loginWithApiKey(apiKey, XAPI_API_HOST);
+  if (!result?.accessToken) {
+    throw new Error("Login failed: no access token returned");
+  }
+  return result.accessToken;
+}
+async function findCurrentKeyRecord(plaintextKey, jwtToken) {
+  const keys = await listKeys(jwtToken, XAPI_API_HOST);
+  if (!Array.isArray(keys) || keys.length === 0) {
+    throw new Error("No API keys found for this account");
+  }
+  if (keys.length === 1) return keys[0];
+  const prefix = plaintextKey.substring(0, 7);
+  const match = keys.find((k) => k.keyPreview.startsWith(prefix));
+  if (!match) {
+    return keys[0];
+  }
+  return match;
+}
+var OAUTH_HELP = `xapi oauth - Manage OAuth bindings
+
+USAGE
+  xapi oauth <command> [flags]
+
+COMMANDS
+  bind [--provider <name>]   Bind an OAuth account to your API key
+  status                     List current OAuth bindings
+  unbind <binding-id>        Remove an OAuth binding
+  providers                  List available OAuth providers
+
+FLAGS
+  --provider <name>          OAuth provider (default: twitter)
+  --format json|pretty|table   Output format
+
+EXAMPLES
+  xapi oauth bind
+  xapi oauth bind --provider twitter
+  xapi oauth status
+  xapi oauth status --format pretty
+  xapi oauth unbind abc123
+  xapi oauth providers
+`;
+async function oauthBind(args, flags) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const apiKey = cfg.apiKey;
+  const providerName = (flags.provider || "twitter").toLowerCase();
+  try {
+    const jwtToken = await loginAndGetJwt(apiKey);
+    const keyRecord = await findCurrentKeyRecord(apiKey, jwtToken);
+    if (!keyRecord.oauthEnabled) {
+      await enableOAuthForKey(keyRecord.id, apiKey, jwtToken, XAPI_API_HOST);
+    }
+    const providers = await listOAuthProviders(XAPI_API_HOST);
+    if (!Array.isArray(providers) || providers.length === 0) {
+      throw new Error("No OAuth providers available");
+    }
+    const provider = providers.find(
+      (p) => p.type.toLowerCase() === providerName || p.name.toLowerCase().includes(providerName)
+    );
+    if (!provider) {
+      const available = providers.map((p) => p.type).join(", ");
+      throw new Error(
+        `Provider "${providerName}" not found. Available: ${available}`
+      );
+    }
+    const result = await initiateOAuth(keyRecord.id, provider.id, jwtToken, XAPI_API_HOST);
+    const { authorizationUrl } = result;
+    const isTTY = process.stdout.isTTY;
+    if (isTTY) {
+      console.error(`
+  Provider : ${provider.name}`);
+      console.error(`  API Key  : ${keyRecord.keyPreview}`);
+      console.error(`
+  Authorization URL:
+  ${authorizationUrl}
+`);
+      console.error("  Opening browser...");
+      openBrowser(authorizationUrl);
+      console.error("  Waiting for you to complete authorization in the browser...\n");
+      const binding = await pollForBinding(keyRecord.id, provider.id, jwtToken);
+      if (process.stdout.isTTY) process.stdout.write("\n");
+      if (binding) {
+        const account = binding.providerAccountName || "unknown";
+        console.error(`
+  Authorization complete! Bound to @${account}
+`);
+        output({ status: "success", provider: provider.name, account }, flags.format);
+      } else {
+        err("oauth bind timed out", 'Authorization was not completed within 5 minutes. Run "xapi oauth bind" again.');
+      }
+    } else {
+      output({
+        status: "pending",
+        provider: provider.name,
+        apiKey: keyRecord.keyPreview,
+        authorizationUrl
+      }, flags.format);
+    }
+  } catch (e) {
+    err("oauth bind failed", e.message);
+  }
+}
+async function oauthStatus(args, flags) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const apiKey = cfg.apiKey;
+  try {
+    const jwtToken = await loginAndGetJwt(apiKey);
+    const bindings = await listOAuthBindings(jwtToken, XAPI_API_HOST);
+    if (!Array.isArray(bindings) || bindings.length === 0) {
+      output({
+        status: "no_bindings",
+        message: 'No OAuth bindings found. Run "xapi oauth bind" to connect an account.'
+      }, flags.format);
+      return;
+    }
+    output({
+      status: "ok",
+      count: bindings.length,
+      bindings: bindings.map((b) => ({
+        id: b.id,
+        provider: b.provider.name,
+        providerType: b.provider.type,
+        account: b.providerAccountName || b.providerAccountId,
+        apiKeyId: b.apiKeyId,
+        scopes: b.scopes,
+        boundAt: b.createdAt
+      }))
+    }, flags.format);
+  } catch (e) {
+    err("oauth status failed", e.message);
+  }
+}
+async function oauthUnbind(args, flags) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const apiKey = cfg.apiKey;
+  const bindingId = args[0];
+  if (!bindingId) {
+    err("usage: xapi oauth unbind <binding-id>", 'Get the binding ID from "xapi oauth status"');
+  }
+  try {
+    const jwtToken = await loginAndGetJwt(apiKey);
+    const result = await deleteOAuthBinding(bindingId, jwtToken, XAPI_API_HOST);
+    output({ success: result.success, message: "OAuth binding removed" }, flags.format);
+  } catch (e) {
+    err("oauth unbind failed", e.message);
+  }
+}
+async function oauthProviders(args, flags) {
+  try {
+    const providers = await listOAuthProviders(XAPI_API_HOST);
+    output(providers, flags.format);
+  } catch (e) {
+    err("oauth providers failed", e.message);
+  }
+}
+
+// src/index.ts
+var { CONFIG_HELP: CONFIG_HELP2 } = config_exports;
+var { OAUTH_HELP: OAUTH_HELP2 } = oauth_exports;
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i += 2;
+      } else {
+        flags[key] = "true";
+        i++;
+      }
+    } else {
+      positional.push(arg);
+      i++;
+    }
+  }
+  return { positional, flags };
+}
+var HELP = `xapi - agent-friendly CLI for xapi
+
+USAGE
+  xapi <command> [args] [flags]
+
+COMMANDS
+  list                              List all actions
+    --source capability|api         Filter by source type
+    --page N  --page-size N         Pagination
+    --category <name>               Filter by category
+    --service-id <id>               Filter by service
+  search <query>                    Search actions by keyword
+    --source capability|api         Filter by source type
+    --category <name>               Filter by category
+    --page N  --page-size N         Pagination
+  categories                        List all action categories
+    --source capability|api         Filter by source type
+  services                          List all services
+    --page N  --page-size N         Pagination
+    --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)
+  call <id> --input '{"key":"val"}'  Execute an action
+    --method GET|POST|...            Override HTTP method
+    --code <target>                  Generate code snippet instead of executing
+    Variants: python.requests, python.httpx, javascript.fetch, javascript.axios
+
+  oauth bind [--provider twitter]   Bind Twitter OAuth to your API key
+  oauth status                      List current OAuth bindings
+  oauth unbind <binding-id>         Remove an OAuth binding
+  oauth providers                   List available OAuth providers
+
+  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)
+  balance                           Show current account balance
+  topup [--amount <usd>] [--method stripe|x402]   Generate payment URL
+
+  health                            Check backend connectivity
+
+  config show                       Show current config
+  config set apiKey=<key>           Save API key to ~/.xapi/config.json
+  config health                     Check backend connectivity (alias: xapi health)
+
+GLOBAL FLAGS
+  --format json|pretty|table        Output format (default: json)
+  --help                            Show help (use with a command for details, e.g. xapi get --help)
+
+ENV VARS
+  XAPI_KEY       API key (header: XAPI-Key)
+  XAPI_ACTION_HOST   Action service host (default: action.xapi.to)
+  XAPI_OUTPUT        Default output format
+
+EXAMPLES
+  xapi register
+  xapi register --referral-code xapito          # register with an inviter's referral code
+  xapi register xapito                          # positional shorthand
+  xapi list --format table
+  xapi list --source capability
+  xapi search twitter --source api
+  xapi get twitter.tweet_detail
+  xapi get twitter.tweet_detail --code curl
+  xapi get twitter.tweet_detail --code py --format pretty
+  xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}' --code python
+  xapi categories
+  xapi services --format table
+  xapi config set apiKey=xapi_abc123
+  xapi health
+`;
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (positional.length === 0) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (flags.format) process.env.XAPI_OUTPUT = flags.format;
+  const [cmd, ...rest] = positional;
+  switch (cmd) {
+    // ── Action commands (top-level) ──
+    case "list":
+      return actionList2(rest, flags);
+    case "search":
+      return actionSearch2(rest, flags);
+    case "categories":
+      return actionCategories2(rest, flags);
+    case "services":
+      return actionServices2(rest, flags);
+    case "get":
+      return actionGet2(rest, flags);
+    case "call":
+      return actionCall2(rest, flags);
+    // ── OAuth commands ──
+    case "oauth": {
+      if (flags.help || rest.length === 0) {
+        console.log(OAUTH_HELP2);
+        process.exit(0);
+      }
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case "bind":
+          return oauthBind(subRest, flags);
+        case "status":
+          return oauthStatus(subRest, flags);
+        case "unbind":
+          return oauthUnbind(subRest, flags);
+        case "providers":
+          return oauthProviders(subRest, flags);
+        default:
+          console.error(JSON.stringify({ error: `unknown oauth command: ${subCmd}`, hint: "valid commands: bind, status, unbind, providers" }));
+          process.exit(1);
+      }
+      break;
+    }
+    // ── Account commands ──
+    case "register":
+      return register(rest, flags);
+    case "balance":
+      return balance(rest, flags);
+    case "topup":
+      return topup(rest, flags);
+    case "health":
+      return configHealth(rest, flags);
+    // ── Config commands ──
+    case "config": {
+      if (flags.help || rest.length === 0) {
+        console.log(CONFIG_HELP2);
+        process.exit(0);
+      }
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case "show":
+          return configShow(subRest, flags);
+        case "set":
+          return configSet(subRest, flags);
+        case "health":
+          return configHealth(subRest, flags);
+        default:
+          console.error(JSON.stringify({ error: `unknown config command: ${subCmd}`, hint: "valid commands: show, set, health" }));
+          process.exit(1);
+      }
+      break;
+    }
+    default:
+      console.error(JSON.stringify({ error: `unknown command: ${cmd}`, hint: "run xapi --help" }));
+      process.exit(1);
+  }
+}
+main().catch((e) => {
+  console.error(JSON.stringify({ error: "fatal", message: e.message }));
+  process.exit(1);
+});