xapi-to 0.1.7

package/README.md

@@ -0,0 +1,160 @@
+# xapi-cli
+
+Agent-friendly command-line interface for [xAPI](https://xapi.to) — discover and call capabilities and APIs from your terminal or AI agent.
+
+## Installation
+
+```bash
+# Via npx (no install needed)
+npx @xapi-to/xapi --help
+
+# Or install globally with bun
+bun add -g @xapi-to/xapi
+
+# Or from source
+cd xapi-cli && bun install
+```
+
+## Quick Start
+
+```bash
+# 1. Register a new account (apiKey saved automatically)
+xapi register
+
+# 2. Or set an existing key
+xapi config set apiKey=sk-xxx
+
+# 3. Or via env var
+export XAPI_API_KEY=sk-xxx
+
+# 4. Verify connectivity
+xapi config health
+```
+
+## Usage
+
+```
+xapi <command> [args] [flags]
+```
+
+### Action Commands
+
+Unified interface for capabilities (built-in) and APIs (third-party). Use `--source capability|api` to filter.
+
+```bash
+xapi list                                            # list all actions
+xapi list --source capability                        # only built-in capabilities
+xapi list --source api --category DeFi               # filter by source and category
+xapi list --page 2 --page-size 20                    # pagination
+xapi list --service-id <id>                          # filter by service
+
+xapi search "twitter"                                # search by keyword
+xapi search "token price" --source api               # search APIs only
+
+xapi categories                                      # list all categories
+xapi categories --source capability                  # categories for capabilities only
+
+xapi services                                        # list all services
+xapi services --category Social --page-size 10       # filter and paginate
+
+xapi get twitter.tweet_detail                        # get action schema
+xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'  # execute
+```
+
+### OAuth
+
+Bind third-party OAuth accounts (e.g. Twitter) to your API key.
+
+```bash
+xapi oauth bind --provider twitter                   # bind Twitter account
+xapi oauth status                                    # list current bindings
+xapi oauth unbind <binding-id>                       # remove a binding
+xapi oauth providers                                 # list available providers
+```
+
+### Account
+
+```bash
+xapi register                                        # create account, saves apiKey automatically
+xapi balance                                         # show xToken balance
+xapi topup                                           # generate payment URL
+xapi topup --method stripe --amount 10               # stripe, $10
+xapi topup --method x402                             # x402 (USDC on Base)
+```
+
+### Config
+
+```bash
+xapi config show                                     # show current config
+xapi config set apiKey=sk-xxx                        # save API key
+xapi config health                                   # check backend connectivity
+```
+
+## Workflow: Always GET before CALL
+
+Before calling any action, always read its schema first to understand required parameters:
+
+```bash
+# 1. Find the action
+xapi search "twitter"
+
+# 2. Read its schema
+xapi get twitter.tweet_detail
+
+# 3. Call with correct parameters
+xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+```
+
+## Output Formats
+
+All output is JSON by default — designed for agent consumption.
+
+```bash
+xapi list --format json                              # default, machine-readable
+xapi list --format pretty                            # pretty-printed JSON
+xapi list --format table                             # human-readable table
+```
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `XAPI_API_KEY` | API key (overrides config file) |
+| `XAPI_ACTION_HOST` | Action service host (default: `action.xapi.to`) |
+| `XAPI_OUTPUT` | Default output format (`json`\|`pretty`\|`table`) |
+
+Config is stored at `~/.xapi/config.json`.
+
+## Built-in Capabilities
+
+| ID | Description |
+|---|---|
+| `twitter.tweet_detail` | Get tweet details and replies |
+| `twitter.user_by_screen_name` | Get user profile by username |
+| `twitter.user_by_screen_names` | Batch get user profiles by usernames |
+| `twitter.user_tweets` | Get tweets from a user |
+| `twitter.user_media` | Get media posts from a user |
+| `twitter.following` | Get user following list |
+| `twitter.followers` | Get user followers |
+| `twitter.retweeters` | Get tweet retweeters |
+| `twitter.search_timeline` | Search tweets, users, photos, videos |
+| `ai.text.chat.fast` | Fast AI chat completion |
+| `ai.text.chat.reasoning` | Advanced reasoning chat |
+| `ai.text.summarize` | Summarize long text |
+| `ai.text.rewrite` | Rewrite text with different styles |
+| `ai.embedding.generate` | Generate vector embeddings |
+| `web.search` | Web search |
+| `web.search.realtime` | Realtime web search with time filters |
+| `news.search.latest` | Latest news search |
+| `crypto.token.price` | Crypto token price and changes |
+| `crypto.token.metadata` | Crypto token metadata |
+
+## Security
+
+- **NEVER send your API key to any domain other than `*.xapi.to`**
+- The key is stored at `~/.xapi/config.json` — do not expose this file
+- `topup` outputs a payment URL containing the API key — do not share publicly
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "xapi-to",
+  "version": "0.1.7",
+  "description": "Agent-friendly CLI for xapi - discover and call capabilities and APIs",
+  "type": "module",
+  "bin": {
+    "xapi": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/tests",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "XAPI_ACTION_HOST=localhost:3003 bun run src/index.ts",
+    "test": "bun test src/tests"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/client.ts

@@ -0,0 +1,264 @@
+/**
+ * HTTP client - thin wrapper around fetch with timeout/retry
+ */
+
+import { scheme } from './config.ts';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const EXECUTE_TIMEOUT_MS = 60_000;
+
+export interface ClientOptions {
+  actionHost: string;
+  apiKey?: string;
+}
+
+export async function request<T>(
+  url: string,
+  options: RequestInit,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+): Promise<T> {
+  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() as T;
+    // Detect business-level auth errors (HTTP 200 but unauthorized)
+    if (body && typeof body === 'object' && 'success' in body && (body as any).success === false) {
+      const data = (body as any).data;
+      if (data?.statusCode === 401 || data?.error === 'Unauthorized') {
+        throw new Error(
+          'Authentication failed: ' + (data.message || 'Invalid or missing API key')
+          + '. Run "npx @xapi-to/xapi 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?: string): Record<string, string> {
+  const h: Record<string, string> = { 'Content-Type': 'application/json' };
+  if (apiKey) h['XAPI-Key'] = apiKey;
+  return h;
+}
+
+function baseUrl(opts: ClientOptions): string {
+  return `${scheme(opts.actionHost)}://${opts.actionHost}`;
+}
+
+// ── Actions (unified: capabilities + APIs) ───────────────────────────────────
+
+export async function actionList(
+  opts: ClientOptions,
+  params: { page?: number; page_size?: number; category?: string; source?: string; service_id?: string } = {},
+) {
+  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<{ actions: unknown[]; pagination: unknown }>(
+    url.toString(),
+    { method: 'GET', headers: headers(opts.apiKey) },
+  );
+}
+
+export async function actionSearch(
+  query: string,
+  opts: ClientOptions,
+  params: { category?: string; source?: string; page?: number; page_size?: number } = {},
+) {
+  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<{ results: unknown[]; query: string; pagination: unknown }>(
+    url.toString(),
+    { method: 'GET', headers: headers(opts.apiKey) },
+  );
+}
+
+export async function actionCategories(opts: ClientOptions, params: { source?: string } = {}) {
+  const url = new URL(`${baseUrl(opts)}/v1/actions/categories`);
+  if (params.source) url.searchParams.set('source', params.source);
+  return request<{ categories: string[]; total: number }>(
+    url.toString(),
+    { method: 'GET', headers: headers(opts.apiKey) },
+  );
+}
+
+export async function actionGet(id: string, opts: ClientOptions) {
+  return request<unknown[]>(
+    `${baseUrl(opts)}/v1/actions/${encodeURIComponent(id)}`,
+    { method: 'GET', headers: headers(opts.apiKey) },
+  );
+}
+
+export async function actionBatch(ids: string[], opts: ClientOptions) {
+  return request<{ actions: unknown[]; missing_ids: string[] }>(
+    `${baseUrl(opts)}/v1/actions/batch`,
+    {
+      method: 'POST',
+      headers: headers(opts.apiKey),
+      body: JSON.stringify({ ids }),
+    },
+  );
+}
+
+export async function actionCall(
+  actionId: string,
+  input: Record<string, unknown>,
+  opts: ClientOptions,
+) {
+  return request<unknown>(
+    `${baseUrl(opts)}/v1/actions/execute`,
+    {
+      method: 'POST',
+      headers: headers(opts.apiKey),
+      body: JSON.stringify({ action_id: actionId, input }),
+    },
+    EXECUTE_TIMEOUT_MS,
+  );
+}
+
+export async function actionServices(
+  opts: ClientOptions,
+  params: { page?: number; page_size?: number; category?: string } = {},
+) {
+  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<{ services: unknown[]; pagination: unknown }>(
+    url.toString(),
+    { method: 'GET', headers: headers(opts.apiKey) },
+  );
+}
+
+export async function healthCheck(opts: ClientOptions) {
+  return request<unknown>(
+    `${baseUrl(opts)}/health`,
+    { method: 'GET', headers: headers(opts.apiKey) },
+    5_000,
+  );
+}
+
+// ── Auth ──────────────────────────────────────────────────────────────────────
+
+export async function loginWithApiKey(apiKey: string, apiHost: string) {
+  return request<{ accessToken: string; user: unknown }>(
+    `${scheme(apiHost)}://${apiHost}/api/auth/login/apikey`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ apiKey }),
+    },
+  );
+}
+
+// ── OAuth ──────────────────────────────────────────────────────────────────────
+
+function jwtHeaders(jwtToken: string): Record<string, string> {
+  return { 'Content-Type': 'application/json', Authorization: `Bearer ${jwtToken}` };
+}
+
+export async function listKeys(jwtToken: string, apiHost: string) {
+  return request<Array<{
+    id: string;
+    name: string;
+    keyPreview: string;
+    oauthEnabled: boolean;
+    createdAt: string;
+  }>>(
+    `${scheme(apiHost)}://${apiHost}/api/keys`,
+    { method: 'GET', headers: jwtHeaders(jwtToken) },
+  );
+}
+
+export async function enableOAuthForKey(
+  keyId: string,
+  plaintextKey: string,
+  jwtToken: string,
+  apiHost: string,
+) {
+  return request<{ success: boolean; message: string }>(
+    `${scheme(apiHost)}://${apiHost}/api/keys/${keyId}/enable-oauth`,
+    {
+      method: 'POST',
+      headers: jwtHeaders(jwtToken),
+      body: JSON.stringify({ plaintextKey }),
+    },
+  );
+}
+
+export async function listOAuthProviders(apiHost: string) {
+  return request<Array<{
+    id: string;
+    name: string;
+    type: string;
+    grantType: string;
+    defaultScopes: string;
+  }>>(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/providers`,
+    { method: 'GET', headers: { 'Content-Type': 'application/json' } },
+  );
+}
+
+export async function initiateOAuth(
+  apiKeyId: string,
+  providerId: string,
+  jwtToken: string,
+  apiHost: string,
+) {
+  return request<{ authorizationUrl: string; state: string }>(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/authorize`,
+    {
+      method: 'POST',
+      headers: jwtHeaders(jwtToken),
+      body: JSON.stringify({ apiKeyId, providerId }),
+    },
+  );
+}
+
+export async function listOAuthBindings(jwtToken: string, apiHost: string) {
+  return request<Array<{
+    id: string;
+    apiKeyId: string;
+    providerId: string;
+    providerAccountId: string;
+    providerAccountName: string | null;
+    scopes: string;
+    createdAt: string;
+    updatedAt: string;
+    provider: { id: string; name: string; type: string };
+  }>>(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings`,
+    { method: 'GET', headers: jwtHeaders(jwtToken) },
+  );
+}
+
+export async function deleteOAuthBinding(
+  bindingId: string,
+  jwtToken: string,
+  apiHost: string,
+) {
+  return request<{ success: boolean }>(
+    `${scheme(apiHost)}://${apiHost}/api/oauth/bindings/${bindingId}`,
+    { method: 'DELETE', headers: jwtHeaders(jwtToken) },
+  );
+}

package/src/commands/action.ts

@@ -0,0 +1,163 @@
+/**
+ * Top-level action commands: list, search, categories, services, get, call
+ * Unified interface for all actions (capabilities + APIs).
+ * Use --source capability|api to filter by source type.
+ */
+
+import { getConfig, requireApiKey } from '../config.ts';
+import * as client from '../client.ts';
+import { output, err } from '../format.ts';
+
+const VALID_SOURCES = ['capability', 'api'];
+
+/** Validate and return source filter from --source flag */
+function getSource(flags: Record<string, string>): string | undefined {
+  if (!flags.source) return undefined;
+  if (!VALID_SOURCES.includes(flags.source)) {
+    err(`invalid --source value: "${flags.source}". Must be "capability" or "api".`);
+  }
+  return flags.source;
+}
+
+export async function actionList(args: string[], flags: Record<string, string>) {
+  const cfg = getConfig();
+  try {
+    const res = await client.actionList(cfg, {
+      source: getSource(flags),
+      page: flags.page ? parseInt(flags.page) : undefined,
+      page_size: flags['page-size'] ? parseInt(flags['page-size']) : undefined,
+      category: flags.category,
+      service_id: flags['service-id'],
+    });
+    const actions = (res.actions || []) as any[];
+    if (flags.format === 'table') {
+      output(actions.map((a: any) => ({
+        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 as any);
+    }
+  } catch (e: any) {
+    err('list failed', e.message);
+  }
+}
+
+export async function actionSearch(args: string[], flags: Record<string, string>) {
+  const query = args[0];
+  if (!query) err('usage: xapi search <query>');
+  const cfg = getConfig();
+  try {
+    const res = await client.actionSearch(query, cfg, {
+      source: getSource(flags),
+      category: flags.category,
+      page: flags.page ? parseInt(flags.page) : undefined,
+      page_size: flags['page-size'] ? parseInt(flags['page-size']) : undefined,
+    });
+    const results = (res.results || []) as any[];
+    if (flags.format === 'table') {
+      output(results.map((a: any) => ({
+        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 as any);
+    }
+  } catch (e: any) {
+    err('search failed', e.message);
+  }
+}
+
+export async function actionCategories(args: string[], flags: Record<string, string>) {
+  const cfg = getConfig();
+  try {
+    const res = await client.actionCategories(cfg, { source: getSource(flags) });
+    if (flags.format === 'table') {
+      output(res.categories.map(c => ({ category: c })), 'table');
+    } else {
+      output(res, flags.format as any);
+    }
+  } catch (e: any) {
+    err('categories failed', e.message);
+  }
+}
+
+export async function actionServices(args: string[], flags: Record<string, string>) {
+  const cfg = getConfig();
+  try {
+    const res = await client.actionServices(cfg, {
+      page: flags.page ? parseInt(flags.page) : undefined,
+      page_size: flags['page-size'] ? parseInt(flags['page-size']) : undefined,
+      category: flags.category,
+    });
+    const services = (res.services || []) as any[];
+    if (flags.format === 'table') {
+      output(services.map((s: any) => ({
+        id: s.id,
+        name: s.name ?? '',
+        category: s.category ?? '',
+        source: s.source ?? '',
+        endpoints: s.endpointCount ?? '',
+        status: s.status ?? '',
+      })), 'table');
+    } else {
+      output(res, flags.format as any);
+    }
+  } catch (e: any) {
+    err('services failed', e.message);
+  }
+}
+
+export async function actionGet(args: string[], flags: Record<string, string>) {
+  const id = args[0];
+  if (!id) err('usage: xapi get <id> [--method GET|POST|DELETE|...]');
+  const cfg = getConfig();
+  try {
+    const res = await client.actionGet(id, cfg);
+    const actions = Array.isArray(res) ? res : [res];
+    const methodFilter = flags.method?.toUpperCase();
+    const filtered = methodFilter
+      ? actions.filter((a: any) => a.method?.toUpperCase() === methodFilter)
+      : actions;
+    if (filtered.length === 0) {
+      err(`no endpoint found for method "${methodFilter}" in action "${id}"`);
+    }
+    output(filtered.length === 1 ? filtered[0] : filtered, flags.format as any);
+  } catch (e: any) {
+    err('get failed', e.message);
+  }
+}
+
+export async function actionCall(args: string[], flags: Record<string, string>) {
+  const id = args[0];
+  if (!id) err('usage: xapi call <id> --input \'{"key":"val"}\'');
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  let input: Record<string, unknown> = {};
+  if (flags.input) {
+    try {
+      input = JSON.parse(flags.input);
+    } catch {
+      err('--input must be valid JSON');
+    }
+  }
+  if (flags.method) {
+    input = { ...input, method: flags.method.toUpperCase() };
+  }
+  try {
+    const res = await client.actionCall(id, input, cfg);
+    output(res, flags.format as any);
+  } catch (e: any) {
+    err('call failed', e.message);
+  }
+}

package/src/commands/balance.ts

@@ -0,0 +1,35 @@
+/**
+ * balance command
+ * Fetches xTokenBalance from GET /auth/me
+ */
+
+import { getConfig, requireApiKey, XAPI_API_HOST, scheme } from '../config.ts';
+import { loginWithApiKey, request } from '../client.ts';
+import { output, err } from '../format.ts';
+
+export async function balance(args: string[], flags: Record<string, string>) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+
+  let token: string;
+  try {
+    const res = await loginWithApiKey(cfg.apiKey!, XAPI_API_HOST);
+    token = res.accessToken;
+  } catch (e: any) {
+    err('login failed', e.message);
+  }
+
+  try {
+    const me = await request<{ xTokenBalance: string; accountType: string; tier: string }>(
+      `${scheme(XAPI_API_HOST)}://${XAPI_API_HOST}/api/auth/me`,
+      { method: 'GET', headers: { Authorization: `Bearer ${token!}` } },
+    );
+    output({
+      balance: me.xTokenBalance,
+      accountType: me.accountType,
+      tier: me.tier,
+    }, flags.format as any);
+  } catch (e: any) {
+    err('balance fetch failed', e.message);
+  }
+}

package/src/commands/config.ts

@@ -0,0 +1,39 @@
+/**
+ * config commands: show, set, health
+ */
+
+import { getConfig, saveConfig, showConfig } from '../config.ts';
+import { healthCheck } from '../client.ts';
+import { output, err } from '../format.ts';
+
+export async function configShow(args: string[], flags: Record<string, string>) {
+  showConfig();
+}
+
+export async function configSet(args: string[], flags: Record<string, string>) {
+  // xapi config set apiKey=xapi_xxx
+  if (args.length === 0) err('usage: xapi config set apiKey=<key>');
+  const updates: { apiKey?: string } = {};
+  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) }));
+}
+
+export async function configHealth(args: string[], flags: Record<string, string>) {
+  const cfg = getConfig();
+  const start = Date.now();
+  try {
+    await healthCheck(cfg);
+    output({ status: 'ok', host: cfg.actionHost, latency_ms: Date.now() - start }, flags.format as any);
+  } catch (e: any) {
+    output({ status: 'error', host: cfg.actionHost, error: e.message }, flags.format as any);
+    process.exit(1);
+  }
+}

package/src/commands/oauth.ts

@@ -0,0 +1,271 @@
+/**
+ * oauth commands: bind, status, unbind
+ *
+ * Flow for `xapi oauth bind [--provider twitter]`:
+ *  1. Login with current API key → get JWT
+ *  2. List API keys → find the one matching the current key by prefix
+ *  3. Enable OAuth on the key if not already (POST /keys/:id/enable-oauth)
+ *  4. List OAuth providers → find the requested provider
+ *  5. POST /oauth/authorize → get authorizationUrl
+ *  6. Open browser (macOS/Linux/Windows) and poll for binding completion
+ *
+ * `xapi oauth status`: list current OAuth bindings for the API key
+ * `xapi oauth unbind <binding-id>`: delete an OAuth binding
+ */
+
+import { spawnSync } from 'child_process';
+import { XAPI_API_HOST, getConfig, requireApiKey } from '../config.ts';
+import {
+  loginWithApiKey,
+  listKeys,
+  enableOAuthForKey,
+  listOAuthProviders,
+  initiateOAuth,
+  listOAuthBindings,
+  deleteOAuthBinding,
+} from '../client.ts';
+import { output, err } from '../format.ts';
+
+/** Try to open a URL in the default browser. Silent on failure. */
+function openBrowser(url: string): void {
+  const cmd = process.platform === 'win32' ? 'start'
+    : process.platform === 'darwin' ? 'open'
+    : 'xdg-open';
+  try {
+    spawnSync(cmd, [url], { stdio: 'ignore' });
+  } catch {
+    // ignore — user can open manually
+  }
+}
+
+/**
+ * Poll bindings until one for (apiKeyId, providerId) appears.
+ * Shows a live countdown in TTY mode.
+ * Returns the matched binding or null on timeout.
+ */
+async function pollForBinding(
+  apiKeyId: string,
+  providerId: string,
+  jwtToken: string,
+  timeoutMs = 5 * 60 * 1000,
+  intervalMs = 3000,
+): Promise<{ providerAccountName: string | null } | null> {
+  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 {
+      // transient error — keep polling
+    }
+
+    if (isTTY) {
+      const remaining = Math.ceil((deadline - Date.now()) / 1000);
+      process.stdout.write(`\r  Waiting for authorization... (${remaining}s remaining)  `);
+    }
+  }
+
+  if (process.stdout.isTTY) process.stdout.write('\n');
+  return null;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+async function loginAndGetJwt(apiKey: string): Promise<string> {
+  const result = await loginWithApiKey(apiKey, XAPI_API_HOST) as any;
+  if (!result?.accessToken) {
+    throw new Error('Login failed: no access token returned');
+  }
+  return result.accessToken;
+}
+
+/**
+ * Find the API key record that corresponds to the current plaintext API key.
+ * Matches by key prefix (first 7 chars of the plaintext key = keyPrefix).
+ */
+async function findCurrentKeyRecord(
+  plaintextKey: string,
+  jwtToken: string,
+): Promise<{ id: string; name: string; keyPreview: string; oauthEnabled: boolean }> {
+  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];
+  // Match by prefix: keyPreview starts with the key's prefix
+  const prefix = plaintextKey.substring(0, 7);
+  const match = keys.find((k) => k.keyPreview.startsWith(prefix));
+  if (!match) {
+    // Fallback: use the first key
+    return keys[0];
+  }
+  return match;
+}
+
+// ── Commands ───────────────────────────────────────────────────────────────────
+
+/**
+ * xapi oauth bind [--provider twitter]
+ *
+ * Initiates OAuth binding for the current API key.
+ * Prints the authorization URL for the user to open in a browser.
+ */
+export async function oauthBind(args: string[], flags: Record<string, string>) {
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const apiKey = cfg.apiKey!;
+  const providerName = (flags.provider || 'twitter').toLowerCase();
+
+  try {
+    // 1. Login to get JWT
+    const jwtToken = await loginAndGetJwt(apiKey);
+
+    // 2. Find the API key record
+    const keyRecord = await findCurrentKeyRecord(apiKey, jwtToken);
+
+    // 3. Enable OAuth on the key if needed
+    if (!keyRecord.oauthEnabled) {
+      await enableOAuthForKey(keyRecord.id, apiKey, jwtToken, XAPI_API_HOST);
+    }
+
+    // 4. Find the requested OAuth provider
+    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}`,
+      );
+    }
+
+    // 5. Initiate OAuth authorization
+    const result = await initiateOAuth(keyRecord.id, provider.id, jwtToken, XAPI_API_HOST);
+    const { authorizationUrl } = result;
+
+    const isTTY = process.stdout.isTTY;
+
+    if (isTTY) {
+      // Interactive mode: open browser + poll
+      console.error(`\n  Provider : ${provider.name}`);
+      console.error(`  API Key  : ${keyRecord.keyPreview}`);
+      console.error(`\n  Authorization URL:\n  ${authorizationUrl}\n`);
+      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 as any).providerAccountName || 'unknown';
+        console.error(`\n  Authorization complete! Bound to @${account}\n`);
+        output({ status: 'success', provider: provider.name, account }, flags.format as any);
+      } else {
+        err('oauth bind timed out', 'Authorization was not completed within 5 minutes. Run "xapi oauth bind" again.');
+      }
+    } else {
+      // Non-interactive / agent mode: just output the URL
+      output({
+        status: 'pending',
+        provider: provider.name,
+        apiKey: keyRecord.keyPreview,
+        authorizationUrl,
+      }, flags.format as any);
+    }
+  } catch (e: any) {
+    err('oauth bind failed', e.message);
+  }
+}
+
+/**
+ * xapi oauth status
+ *
+ * Lists all OAuth bindings for the current account.
+ */
+export async function oauthStatus(args: string[], flags: Record<string, string>) {
+  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 as any);
+      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 as any);
+  } catch (e: any) {
+    err('oauth status failed', e.message);
+  }
+}
+
+/**
+ * xapi oauth unbind <binding-id>
+ *
+ * Deletes an OAuth binding. Get the ID from `xapi oauth status`.
+ */
+export async function oauthUnbind(args: string[], flags: Record<string, string>) {
+  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 as any);
+  } catch (e: any) {
+    err('oauth unbind failed', e.message);
+  }
+}
+
+/**
+ * xapi oauth providers
+ *
+ * Lists available OAuth providers.
+ */
+export async function oauthProviders(args: string[], flags: Record<string, string>) {
+  try {
+    const providers = await listOAuthProviders(XAPI_API_HOST);
+    output(providers, flags.format as any);
+  } catch (e: any) {
+    err('oauth providers failed', e.message);
+  }
+}

package/src/commands/register.ts

@@ -0,0 +1,59 @@
+/**
+ * register command: create a new user account
+ *
+ * POST /auth/register — no auth required
+ * Returns apiKey (shown once), claimCode, claimUrl, tweetTemplate
+ * Automatically saves apiKey to ~/.xapi/config.json
+ */
+
+import { XAPI_API_HOST, saveConfig, scheme } from '../config.ts';
+import { output, err } from '../format.ts';
+
+async function registerAccount() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 15_000);
+  try {
+    const res = await fetch(`${scheme(XAPI_API_HOST)}://${XAPI_API_HOST}/api/auth/register`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`HTTP ${res.status}: ${text.slice(0, 300)}`);
+    }
+    return res.json() as Promise<{
+      apiKey: string;
+      claimCode: string;
+      claimSessionId: string;
+      claimUrl: string;
+      tweetTemplate: string;
+      user: { id: string; accountType: string };
+    }>;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function register(args: string[], flags: Record<string, string>) {
+  try {
+    const res = await registerAccount();
+
+    // auto-save apiKey
+    saveConfig({ apiKey: res.apiKey });
+
+    output({
+      apiKey: res.apiKey,
+      user: res.user,
+      claim: {
+        code: res.claimCode,
+        sessionId: res.claimSessionId,
+        url: res.claimUrl,
+      },
+      tweetTemplate: res.tweetTemplate,
+      note: 'apiKey saved to ~/.xapi/config.json',
+    }, flags.format as any);
+  } catch (e: any) {
+    err('register failed', e.message);
+  }
+}

package/src/commands/topup.ts

@@ -0,0 +1,33 @@
+/**
+ * topup command
+ *
+ * Generates a payment URL pointing to the xapi frontend topup page.
+ * All params are optional.
+ *
+ * Usage:
+ *   xapi topup [--amount <usd>] [--method stripe|x402]
+ */
+
+import { getConfig } from '../config.ts';
+import { output } from '../format.ts';
+
+const TOPUP_BASE_URL = 'https://www.xapi.to/topup/payment';
+
+export async function topup(args: string[], flags: Record<string, string>) {
+  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 as any);
+}

package/src/config.ts

@@ -0,0 +1,69 @@
+/**
+ * Config management
+ * Only apiKey is user-configurable. Host is built-in.
+ * Reads from env var XAPI_API_KEY or ~/.xapi/config.json
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from 'fs';
+import { err } from './format.ts';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const XAPI_ACTION_HOST = process.env.XAPI_ACTION_HOST || 'action.xapi.to'; // action service (capabilities + APIs)
+export const XAPI_API_HOST = process.env.XAPI_API_HOST || 'api.xapi.to';          // auth + agent API
+
+/** Returns https:// for remote hosts, http:// for localhost */
+export function scheme(host: string): string {
+  return host.startsWith('localhost') || host.startsWith('127.') ? 'http' : 'https';
+}
+
+export interface XapiConfig {
+  actionHost: string;
+  apiKey?: string;
+}
+
+const CONFIG_DIR = join(homedir(), '.xapi');
+const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
+
+function loadFileConfig(): { apiKey?: string } {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function getConfig(): XapiConfig {
+  const file = loadFileConfig();
+  return {
+    actionHost: XAPI_ACTION_HOST,
+    apiKey: process.env.XAPI_API_KEY || file.apiKey,
+  };
+}
+
+export function requireApiKey(cfg: XapiConfig): void {
+  if (!cfg.apiKey) {
+    err('API key not configured', 'Run "npx @xapi-to/xapi register" to create an account, or "npx @xapi-to/xapi config set apiKey=<key>" to set an existing key.');
+  }
+}
+
+export function saveConfig(updates: { apiKey?: string }): void {
+  const current = loadFileConfig();
+  const merged = { ...current, ...updates };
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 0o600 });
+}
+
+export function showConfig(): void {
+  const cfg = getConfig();
+  const file = loadFileConfig();
+  console.log(JSON.stringify({
+    actionHost: cfg.actionHost,
+    apiKey: cfg.apiKey ? `${cfg.apiKey.slice(0, 8)}...` : undefined,
+    source: {
+      apiKey: process.env.XAPI_API_KEY ? 'env' : file.apiKey ? 'file' : 'none',
+    },
+    configFile: CONFIG_FILE,
+  }, null, 2));
+}

package/src/format.ts

@@ -0,0 +1,61 @@
+/**
+ * Output formatting
+ * Supports: json (default, machine-readable), pretty (human-readable), table
+ */
+
+export type OutputFormat = 'json' | 'pretty' | 'table';
+
+export function getFormat(): OutputFormat {
+  const f = process.env.XAPI_OUTPUT || 'json';
+  if (f === 'pretty' || f === 'table') return f;
+  return 'json';
+}
+
+export function output(data: unknown, format?: OutputFormat): void {
+  const fmt = format || getFormat();
+  if (fmt === 'json') {
+    console.log(JSON.stringify(data));
+    return;
+  }
+  if (fmt === 'pretty') {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  // table: try to render arrays of objects as a table
+  if (fmt === 'table' && Array.isArray(data)) {
+    printTable(data as Record<string, unknown>[]);
+    return;
+  }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function printTable(rows: Record<string, unknown>[]): void {
+  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);
+  }
+}
+
+export function err(msg: string, detail?: unknown): never {
+  if (process.stderr.isTTY) {
+    console.error(`Error: ${msg}`);
+    if (detail !== undefined) console.error(`  ${detail}`);
+  } else {
+    const out: Record<string, unknown> = { error: msg };
+    if (detail !== undefined) out.detail = detail;
+    console.error(JSON.stringify(out));
+  }
+  process.exit(1);
+}

package/src/index.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env bun
+/**
+ * xapi CLI - agent-friendly command-line interface for xapi
+ *
+ * Usage:
+ *   xapi list [--source capability|api] [--page N] [--page-size N] [--category X]
+ *   xapi search <query> [--source capability|api] [--category X] [--page N] [--page-size N]
+ *   xapi categories [--source capability|api]
+ *   xapi services [--page N] [--page-size N] [--category X]
+ *   xapi get <id>
+ *   xapi call <id> --input '{"k":"v"}'
+ *
+ *   xapi config show
+ *   xapi config set apiKey=<key>
+ *   xapi config health
+ *
+ * Global flags:
+ *   --format json|pretty|table   output format (default: json)
+ *   --help                       show help
+ *
+ * Env vars:
+ *   XAPI_API_KEY       API key
+ *   XAPI_ACTION_HOST   Action service host (default: action.xapi.to)
+ *   XAPI_OUTPUT        default output format (json|pretty|table)
+ */
+
+import * as actionCmds from './commands/action.ts';
+import * as cfgCmds from './commands/config.ts';
+import * as regCmds from './commands/register.ts';
+import * as topupCmds from './commands/topup.ts';
+import * as balanceCmds from './commands/balance.ts';
+import * as oauthCmds from './commands/oauth.ts';
+
+// ── Argument parser ───────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+  positional: string[];
+  flags: Record<string, string>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+  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 };
+}
+
+// ── Help ──────────────────────────────────────────────────────────────────────
+
+const 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)
+  call <id> --input '{"key":"val"}'  Execute an action
+
+  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                          Create a new user account (apiKey saved automatically)
+  balance                           Show current account balance
+  topup [--amount <usd>] [--method stripe|x402]   Generate payment URL
+
+  config show                       Show current config
+  config set apiKey=<key>           Save API key to ~/.xapi/config.json
+  config health                     Check backend connectivity
+
+GLOBAL FLAGS
+  --format json|pretty|table        Output format (default: json)
+  --help                            Show this help
+
+ENV VARS
+  XAPI_API_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 list --format table
+  xapi list --source capability
+  xapi search twitter --source api
+  xapi get twitter.tweet_detail
+  xapi call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
+  xapi categories
+  xapi services --format table
+  xapi config set apiKey=xapi_abc123
+  xapi config health
+`;
+
+// ── Router ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+
+  if (flags.help || positional.length === 0) {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  // inject format from flag into env so format.ts picks it up
+  if (flags.format) process.env.XAPI_OUTPUT = flags.format;
+
+  const [cmd, ...rest] = positional;
+
+  switch (cmd) {
+    // ── Action commands (top-level) ──
+    case 'list':       return actionCmds.actionList(rest, flags);
+    case 'search':     return actionCmds.actionSearch(rest, flags);
+    case 'categories': return actionCmds.actionCategories(rest, flags);
+    case 'services':   return actionCmds.actionServices(rest, flags);
+    case 'get':        return actionCmds.actionGet(rest, flags);
+    case 'call':       return actionCmds.actionCall(rest, flags);
+
+    // ── OAuth commands ──
+    case 'oauth': {
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case 'bind':      return oauthCmds.oauthBind(subRest, flags);
+        case 'status':    return oauthCmds.oauthStatus(subRest, flags);
+        case 'unbind':    return oauthCmds.oauthUnbind(subRest, flags);
+        case 'providers': return oauthCmds.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 regCmds.register(rest, flags);
+    case 'balance':    return balanceCmds.balance(rest, flags);
+    case 'topup':      return topupCmds.topup(rest, flags);
+
+    // ── Config commands ──
+    case 'config': {
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case 'show':   return cfgCmds.configShow(subRest, flags);
+        case 'set':    return cfgCmds.configSet(subRest, flags);
+        case 'health': return cfgCmds.configHealth(subRest, flags);
+        default:
+          console.error(JSON.stringify({ error: `unknown config command: ${subCmd}` }));
+          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);
+});