xapi-to 0.1.15 → 0.1.17

package/README.md

@@ -66,6 +66,16 @@ xapi-to get twitter.tweet_detail                        # get action schema
 xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'  # execute
 ```
 
+### Async Task Commands
+
+Task helpers built on top of the `task.poll` capability.
+
+```bash
+xapi-to task poll 550e8400-e29b-41d4-a716-446655440000                 # poll once
+xapi-to task wait 550e8400-e29b-41d4-a716-446655440000                 # wait until terminal status
+xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 1s --timeout 10m
+```
+
 ### OAuth
 
 Bind third-party OAuth accounts (e.g. Twitter) to your API key.
@@ -140,6 +150,7 @@ Config is stored at `~/.xapi/config.json`.
 | `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_tweets_and_replies` | Get tweets and replies from a user |
 | `twitter.user_media` | Get media posts from a user |
 | `twitter.following` | Get user following list |
 | `twitter.followers` | Get user followers |

package/dist/index.js

@@ -24,12 +24,46 @@ function output(data, format) {
     console.log(JSON.stringify(data, null, 2));
     return;
   }
-  if (fmt === "table" && Array.isArray(data)) {
-    printTable(data);
-    return;
+  if (fmt === "table") {
+    const rows = tableRows(data);
+    if (rows) {
+      printTable(rows);
+      return;
+    }
   }
   console.log(JSON.stringify(data, null, 2));
 }
+function tableRows(data) {
+  if (Array.isArray(data)) return normalizeRows(data, "value");
+  if (!data || typeof data !== "object") return null;
+  const obj = data;
+  const preferredKeys = ["items", "actions", "results", "services", "categories", "bindings", "providers"];
+  for (const key of preferredKeys) {
+    const value = obj[key];
+    if (Array.isArray(value)) return normalizeRows(value, singularKey(key));
+  }
+  const firstArray = Object.entries(obj).find(([, value]) => Array.isArray(value));
+  return firstArray ? normalizeRows(firstArray[1], singularKey(firstArray[0])) : null;
+}
+function normalizeRows(rows, primitiveKey) {
+  return rows.map((row) => {
+    if (row && typeof row === "object" && !Array.isArray(row)) {
+      return row;
+    }
+    return { [primitiveKey]: row };
+  });
+}
+function singularKey(key) {
+  if (key === "categories") return "category";
+  if (key.endsWith("ies")) return `${key.slice(0, -3)}y`;
+  if (key.endsWith("s")) return key.slice(0, -1);
+  return "value";
+}
+function formatCell(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "object") return JSON.stringify(value);
+  return String(value);
+}
 function printTable(rows) {
   if (rows.length === 0) {
     console.log("(empty)");
@@ -37,14 +71,14 @@ function printTable(rows) {
   }
   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)))
+    (k) => Math.min(40, Math.max(k.length, ...rows.map((r) => formatCell(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("  ");
+    const line = keys.map((k, i) => formatCell(row[k]).slice(0, widths[i]).padEnd(widths[i])).join("  ");
     console.log(line);
   }
 }
@@ -66,7 +100,43 @@ 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";
+  return isLoopbackHost(host) ? "http" : "https";
+}
+var ALLOWED_HOST_EXACT = ["xapi.to", "xapi.xyz"];
+var ALLOWED_HOST_SUFFIXES = [".xapi.to", ".xapi.xyz"];
+function hostnameOf(hostOrUrl) {
+  const raw = hostOrUrl.includes("://") ? hostOrUrl : `http://${hostOrUrl}`;
+  try {
+    return new URL(raw).hostname.toLowerCase();
+  } catch {
+    return "";
+  }
+}
+function isLoopbackIPv4(h) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(h);
+  if (!m) return false;
+  const octets = m.slice(1).map(Number);
+  return octets.every((o) => o <= 255) && octets[0] === 127;
+}
+function isLoopbackHostname(h) {
+  return h === "localhost" || h.endsWith(".localhost") || h === "::1" || h === "[::1]" || isLoopbackIPv4(h);
+}
+function isLoopbackHost(hostOrUrl) {
+  return isLoopbackHostname(hostnameOf(hostOrUrl));
+}
+function isAllowedHost(hostOrUrl) {
+  const h = hostnameOf(hostOrUrl);
+  if (!h) return false;
+  if (isLoopbackHostname(h)) return true;
+  if (ALLOWED_HOST_EXACT.includes(h)) return true;
+  return ALLOWED_HOST_SUFFIXES.some((suffix) => h.endsWith(suffix));
+}
+function assertAllowedHost(hostOrUrl) {
+  if (!isAllowedHost(hostOrUrl)) {
+    throw new Error(
+      `refusing to contact untrusted host "${hostnameOf(hostOrUrl) || hostOrUrl}": the xapi API key may only be sent to *.xapi.to, *.xapi.xyz, or localhost`
+    );
+  }
 }
 var CONFIG_DIR = join(homedir(), ".xapi");
 var CONFIG_FILE = join(CONFIG_DIR, "config.json");
@@ -112,32 +182,128 @@ function showConfig() {
 // 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") {
+var IDEMPOTENT_RETRIES = 2;
+var RETRY_BASE_DELAY_MS = 500;
+var RETRY_MAX_DELAY_MS = 8e3;
+var HttpError = class extends Error {
+  constructor(status, detail, retryAfterMs) {
+    super(`HTTP ${status}: ${detail}`);
+    this.status = status;
+    this.retryAfterMs = retryAfterMs;
+    this.name = "HttpError";
+  }
+  status;
+  retryAfterMs;
+};
+var RequestTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`request timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+    this.name = "RequestTimeoutError";
+  }
+  timeoutMs;
+};
+function isRetryableStatus(status) {
+  return status === 408 || status === 429 || status === 502 || status === 503 || status === 504;
+}
+function isRetryableNetworkError(e) {
+  if (!(e instanceof Error)) return false;
+  if (e instanceof HttpError || e instanceof RequestTimeoutError) return false;
+  if (e.name === "AbortError") return false;
+  return e instanceof TypeError || /network|fetch failed|econn|etimedout|eai_again|socket|dns/i.test(e.message);
+}
+function isRetryableRequestError(e) {
+  if (e instanceof HttpError) return isRetryableStatus(e.status);
+  if (e instanceof RequestTimeoutError) return true;
+  return isRetryableNetworkError(e);
+}
+function retryBaseDelayMs() {
+  const override = Number(process.env.XAPI_RETRY_BASE_MS);
+  return Number.isFinite(override) && override > 0 ? override : RETRY_BASE_DELAY_MS;
+}
+function backoffDelayMs(attempt, retryAfterMs) {
+  if (retryAfterMs !== void 0 && Number.isFinite(retryAfterMs) && retryAfterMs >= 0) {
+    return Math.min(retryAfterMs, RETRY_MAX_DELAY_MS);
+  }
+  const capped = Math.min(retryBaseDelayMs() * 2 ** attempt, RETRY_MAX_DELAY_MS);
+  return capped / 2 + Math.random() * (capped / 2);
+}
+function parseRetryAfterMs(res) {
+  const header = res.headers.get("retry-after");
+  if (!header) return void 0;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return seconds * 1e3;
+  const at = Date.parse(header);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function request(url, options, timeoutMs = DEFAULT_TIMEOUT_MS, retries = 0) {
+  assertAllowedHost(url);
+  let attempt = 0;
+  while (true) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    try {
+      const res = await fetch(url, { ...options, redirect: "manual", signal: controller.signal });
+      if (res.status >= 300 && res.status < 400) {
         throw new Error(
-          "Authentication failed: " + (data.message || "Invalid or missing API key") + '. Run "npx xapi-to config set apiKey=<key>" to update your key.'
+          `refusing to follow redirect to "${res.headers.get("location") ?? "?"}" (would forward the API key past the host allowlist)`
         );
       }
-      if (data?.error === "OAuth Required" || data?.statusCode === 403 && data?.message?.includes("OAuth")) {
-        throw new Error(
-          (data.message || "OAuth authorization required") + '. Run "xapi-to oauth bind" to connect your account.'
-        );
+      if (!res.ok) {
+        const retryAfterMs = isRetryableStatus(res.status) ? parseRetryAfterMs(res) : void 0;
+        if (isRetryableStatus(res.status) && attempt < retries) {
+          await res.text().catch(() => "");
+          clearTimeout(timer);
+          await sleep(backoffDelayMs(attempt, retryAfterMs));
+          attempt++;
+          continue;
+        }
+        const text2 = await res.text();
+        throw new HttpError(res.status, text2.slice(0, 300), retryAfterMs);
+      }
+      if (res.status === 204) {
+        return void 0;
+      }
+      const text = await res.text();
+      if (!text.trim()) {
+        return void 0;
+      }
+      const body = JSON.parse(text);
+      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-to oauth bind" to connect your account.'
+          );
+        }
       }
+      return body;
+    } catch (e) {
+      if (timedOut) {
+        throw new RequestTimeoutError(timeoutMs);
+      }
+      if (isRetryableNetworkError(e) && attempt < retries) {
+        clearTimeout(timer);
+        await sleep(backoffDelayMs(attempt));
+        attempt++;
+        continue;
+      }
+      throw e;
+    } finally {
+      clearTimeout(timer);
     }
-    return body;
-  } finally {
-    clearTimeout(timer);
   }
 }
 function headers(apiKey) {
@@ -157,7 +323,9 @@ async function actionList(opts, params = {}) {
   if (params.service_id) url.searchParams.set("service_id", params.service_id);
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function actionSearch(query, opts, params = {}) {
@@ -169,7 +337,9 @@ async function actionSearch(query, opts, params = {}) {
   if (params.page_size) url.searchParams.set("page_size", String(params.page_size));
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function actionCategories(opts, params = {}) {
@@ -177,16 +347,20 @@ async function actionCategories(opts, params = {}) {
   if (params.source) url.searchParams.set("source", params.source);
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function actionGet(id, opts) {
   return request(
     `${baseUrl(opts)}/v1/actions/${encodeURIComponent(id)}`,
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
-async function actionCall(actionId, input, opts, httpMethod) {
+async function actionCall(actionId, input, opts, httpMethod, retries = 0, timeoutMs = EXECUTE_TIMEOUT_MS) {
   return request(
     `${baseUrl(opts)}/v1/actions/execute`,
     {
@@ -194,7 +368,8 @@ async function actionCall(actionId, input, opts, httpMethod) {
       headers: headers(opts.apiKey),
       body: JSON.stringify({ action_id: actionId, ...httpMethod ? { method: httpMethod } : {}, input })
     },
-    EXECUTE_TIMEOUT_MS
+    Math.min(timeoutMs, EXECUTE_TIMEOUT_MS),
+    retries
   );
 }
 async function actionServices(opts, params = {}) {
@@ -204,14 +379,18 @@ async function actionServices(opts, params = {}) {
   if (params.category) url.searchParams.set("category", params.category);
   return request(
     url.toString(),
-    { method: "GET", headers: headers(opts.apiKey) }
+    { method: "GET", headers: headers(opts.apiKey) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function healthCheck(opts) {
   return request(
     `${baseUrl(opts)}/health`,
     { method: "GET", headers: headers(opts.apiKey) },
-    5e3
+    5e3,
+    0
+    // health is a quick connectivity probe — fail fast, don't retry
   );
 }
 async function loginWithApiKey(apiKey, apiHost) {
@@ -221,7 +400,10 @@ async function loginWithApiKey(apiKey, apiHost) {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ apiKey })
-    }
+    },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
+    // auth exchange has no side effect — safe to retry
   );
 }
 function jwtHeaders(jwtToken) {
@@ -230,7 +412,9 @@ function jwtHeaders(jwtToken) {
 async function listKeys(jwtToken, apiHost) {
   return request(
     `${scheme(apiHost)}://${apiHost}/api/keys`,
-    { method: "GET", headers: jwtHeaders(jwtToken) }
+    { method: "GET", headers: jwtHeaders(jwtToken) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function enableOAuthForKey(keyId, plaintextKey, jwtToken, apiHost) {
@@ -246,30 +430,37 @@ async function enableOAuthForKey(keyId, plaintextKey, jwtToken, apiHost) {
 async function listOAuthProviders(apiHost) {
   return request(
     `${scheme(apiHost)}://${apiHost}/api/oauth/providers`,
-    { method: "GET", headers: { "Content-Type": "application/json" } }
+    { method: "GET", headers: { "Content-Type": "application/json" } },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
-async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost) {
+async function initiateOAuth(apiKeyId, providerId, jwtToken, apiHost, scopes) {
+  const body = { apiKeyId, providerId };
+  if (scopes) body.scopes = scopes;
   return request(
     `${scheme(apiHost)}://${apiHost}/api/oauth/authorize`,
     {
       method: "POST",
       headers: jwtHeaders(jwtToken),
-      body: JSON.stringify({ apiKeyId, providerId })
+      body: JSON.stringify(body)
     }
   );
 }
 async function listOAuthBindings(jwtToken, apiHost) {
   return request(
     `${scheme(apiHost)}://${apiHost}/api/oauth/bindings`,
-    { method: "GET", headers: jwtHeaders(jwtToken) }
+    { method: "GET", headers: jwtHeaders(jwtToken) },
+    DEFAULT_TIMEOUT_MS,
+    IDEMPOTENT_RETRIES
   );
 }
 async function deleteOAuthBinding(bindingId, jwtToken, apiHost) {
-  return request(
+  const result = await request(
     `${scheme(apiHost)}://${apiHost}/api/oauth/bindings/${bindingId}`,
     { method: "DELETE", headers: jwtHeaders(jwtToken) }
   );
+  return result ?? { success: true };
 }
 
 // src/codegen.ts
@@ -659,6 +850,7 @@ function getSource(flags) {
 async function actionList2(args, flags) {
   showHelpIfRequested(flags, LIST_HELP);
   const cfg = getConfig();
+  const fmt = flags.format || getFormat();
   try {
     const res = await actionList(cfg, {
       source: getSource(flags),
@@ -668,7 +860,7 @@ async function actionList2(args, flags) {
       service_id: flags["service-id"]
     });
     const actions = res.actions || [];
-    if (flags.format === "table") {
+    if (fmt === "table") {
       output(actions.map((a) => ({
         id: a.id,
         method: a.method ?? "",
@@ -690,6 +882,7 @@ async function actionSearch2(args, flags) {
   const query = args[0];
   if (!query) err("usage: xapi-to search <query>");
   const cfg = getConfig();
+  const fmt = flags.format || getFormat();
   try {
     const res = await actionSearch(query, cfg, {
       source: getSource(flags),
@@ -698,7 +891,7 @@ async function actionSearch2(args, flags) {
       page_size: flags["page-size"] ? parseInt(flags["page-size"]) : void 0
     });
     const results = res.results || [];
-    if (flags.format === "table") {
+    if (fmt === "table") {
       output(results.map((a) => ({
         id: a.id,
         method: a.method ?? "",
@@ -717,9 +910,10 @@ async function actionSearch2(args, flags) {
 }
 async function actionCategories2(args, flags) {
   const cfg = getConfig();
+  const fmt = flags.format || getFormat();
   try {
     const res = await actionCategories(cfg, { source: getSource(flags) });
-    if (flags.format === "table") {
+    if (fmt === "table") {
       output(res.categories.map((c) => ({ category: c })), "table");
     } else {
       output(res, flags.format);
@@ -730,6 +924,7 @@ async function actionCategories2(args, flags) {
 }
 async function actionServices2(args, flags) {
   const cfg = getConfig();
+  const fmt = flags.format || getFormat();
   try {
     const res = await actionServices(cfg, {
       page: flags.page ? parseInt(flags.page) : void 0,
@@ -737,7 +932,7 @@ async function actionServices2(args, flags) {
       category: flags.category
     });
     const services = res.services || [];
-    if (flags.format === "table") {
+    if (fmt === "table") {
       output(services.map((s) => ({
         id: s.id,
         name: s.name ?? "",
@@ -826,6 +1021,7 @@ __export(config_exports, {
   configSet: () => configSet,
   configShow: () => configShow
 });
+import { readFileSync as readFileSync2 } from "fs";
 var CONFIG_HELP = `xapi-to config - Manage CLI configuration
 
 USAGE
@@ -833,7 +1029,7 @@ USAGE
 
 COMMANDS
   show                       Show current config (host, apiKey path, etc.)
-  set apiKey=<key>           Save API key to ~/.xapi/config.json
+  set apiKey=<key>           Save API key to ~/.xapi/config.json (apiKey=- reads from stdin)
   health                     Check backend connectivity (alias: xapi-to health)
 
 FLAGS
@@ -842,6 +1038,7 @@ FLAGS
 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
 `;
 async function configShow(args, flags) {
@@ -856,7 +1053,12 @@ async function configSet(args, flags) {
     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);
+    let value = arg.slice(eq + 1);
+    if (value === "-") {
+      value = readFileSync2(0, "utf-8").trim();
+    }
+    if (!value) err("apiKey is empty");
+    updates.apiKey = value;
   }
   saveConfig(updates);
   console.log(JSON.stringify({ ok: true, updated: Object.keys(updates) }));
@@ -875,6 +1077,7 @@ async function configHealth(args, flags) {
 
 // src/commands/register.ts
 async function registerAccount(referralCode) {
+  assertAllowedHost(XAPI_API_HOST);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 15e3);
   try {
@@ -895,6 +1098,11 @@ async function registerAccount(referralCode) {
 }
 async function register(args, flags) {
   try {
+    const cfg = getConfig();
+    const force = flags.force === "true" || flags.force === "1" || flags.force === "yes";
+    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;
     const res = await registerAccount(referralCode);
@@ -910,7 +1118,7 @@ async function register(args, flags) {
       },
       tweetTemplate: res.tweetTemplate,
       ...referralCode ? { referredBy: referralCode } : {},
-      note: "apiKey saved to ~/.xapi/config.json"
+      note: force && cfg.apiKey ? "apiKey replaced in ~/.xapi/config.json" : "apiKey saved to ~/.xapi/config.json"
     }, flags.format);
   } catch (e) {
     err("register failed", e.message);
@@ -967,7 +1175,8 @@ __export(oauth_exports, {
   oauthBind: () => oauthBind,
   oauthProviders: () => oauthProviders,
   oauthStatus: () => oauthStatus,
-  oauthUnbind: () => oauthUnbind
+  oauthUnbind: () => oauthUnbind,
+  pollForBinding: () => pollForBinding
 });
 import { spawnSync } from "child_process";
 function openBrowser(url) {
@@ -977,14 +1186,22 @@ function openBrowser(url) {
   } catch {
   }
 }
-async function pollForBinding(apiKeyId, providerId, jwtToken, timeoutMs = 5 * 60 * 1e3, intervalMs = 3e3) {
+function bindingChangedAfter(binding, startedAtMs, existingBindingIds) {
+  const changedAt = Date.parse(binding.updatedAt || binding.createdAt || "");
+  if (!Number.isFinite(changedAt)) return !existingBindingIds.has(binding.id);
+  return changedAt >= startedAtMs;
+}
+async function pollForBinding(apiKeyId, providerId, jwtToken, startedAt, existingBindingIds = /* @__PURE__ */ new Set(), timeoutMs = 5 * 60 * 1e3, intervalMs = 3e3) {
   const deadline = Date.now() + timeoutMs;
   const isTTY = process.stdout.isTTY;
+  const startedAtMs = startedAt.getTime() - 5e3;
   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;
+      const match = Array.isArray(bindings) ? bindings.find(
+        (b) => b.apiKeyId === apiKeyId && b.providerId === providerId && bindingChangedAfter(b, startedAtMs, existingBindingIds)
+      ) : null;
       if (match) return match;
     } catch {
     }
@@ -1008,13 +1225,106 @@ async function findCurrentKeyRecord(plaintextKey, jwtToken) {
   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];
+  if (match) return match;
+  if (keys.length === 1) 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.`
+  );
+}
+function resolveScopeDefs(provider) {
+  if (Array.isArray(provider.scopeDefinitions) && provider.scopeDefinitions.length > 0) {
+    return provider.scopeDefinitions;
+  }
+  const raw = (provider.defaultScopes || "").split(/[\s,]+/).filter(Boolean);
+  return raw.map((s) => ({
+    scope: s,
+    label: s,
+    description: "",
+    required: false,
+    category: ""
+  }));
+}
+async function selectScopesInteractive(provider) {
+  const defs = resolveScopeDefs(provider);
+  if (defs.length === 0) return "";
+  const required = defs.filter((d) => d.required);
+  const optional = defs.filter((d) => !d.required);
+  const selected = new Set(defs.map((d) => d.scope));
+  if (optional.length === 0) {
+    return required.map((d) => d.scope).join(" ");
   }
-  return match;
+  const out = process.stderr;
+  let cursor = 0;
+  const hint = "  \u2191\u2193 navigate \xB7 space toggle \xB7 a all \xB7 n none \xB7 enter confirm";
+  const buildFrame = () => {
+    const lines = [];
+    for (const d of required) {
+      const desc = d.description ? ` \u2014 ${d.description}` : "";
+      lines.push(`    \x1B[2m[*] ${d.label}${desc} (required)\x1B[0m`);
+    }
+    for (let i = 0; i < optional.length; i++) {
+      const d = optional[i];
+      const ptr = cursor === i ? " \x1B[36m\u276F\x1B[0m" : "  ";
+      const chk = selected.has(d.scope) ? "\x1B[32m\u2714\x1B[0m" : " ";
+      const desc = d.description ? ` \x1B[2m\u2014 ${d.description}\x1B[0m` : "";
+      lines.push(`  ${ptr} [${chk}] ${d.label}${desc}`);
+    }
+    lines.push(`\x1B[2m${hint}\x1B[0m`);
+    return lines.join("\n");
+  };
+  out.write("\n  Scopes:\n");
+  out.write("\x1B[s");
+  out.write("\x1B[?25l");
+  out.write(buildFrame());
+  const redraw = () => {
+    out.write("\x1B[u");
+    out.write("\x1B[J");
+    out.write(buildFrame());
+  };
+  return new Promise((resolve) => {
+    const { stdin } = process;
+    const wasRaw = stdin.isRaw;
+    stdin.setRawMode(true);
+    stdin.resume();
+    const finish = (result) => {
+      stdin.removeListener("data", onData);
+      stdin.setRawMode(wasRaw ?? false);
+      stdin.pause();
+      out.write("\x1B[?25h");
+      out.write("\n");
+      resolve(result);
+    };
+    const onData = (buf) => {
+      const key = buf.toString();
+      if (key === "\r" || key === "\n") {
+        finish(Array.from(selected).join(" "));
+        return;
+      }
+      if (key === "") {
+        finish("");
+        process.exit(130);
+      }
+      if (key === "\x1B[A" || key === "k") {
+        cursor = (cursor - 1 + optional.length) % optional.length;
+      } else if (key === "\x1B[B" || key === "j") {
+        cursor = (cursor + 1) % optional.length;
+      } else if (key === " ") {
+        const scope = optional[cursor].scope;
+        if (selected.has(scope)) selected.delete(scope);
+        else selected.add(scope);
+      } else if (key === "a") {
+        for (const d of optional) selected.add(d.scope);
+      } else if (key === "n") {
+        for (const d of optional) selected.delete(d.scope);
+      } else {
+        return;
+      }
+      redraw();
+    };
+    stdin.on("data", onData);
+  });
 }
 var OAUTH_HELP = `xapi-to oauth - Manage OAuth bindings
 
@@ -1029,11 +1339,13 @@ COMMANDS
 
 FLAGS
   --provider <name>          OAuth provider (default: twitter)
+  --scopes <scopes>          Space-separated scopes (skips interactive selection)
   --format json|pretty|table   Output format
 
 EXAMPLES
   xapi-to oauth bind
   xapi-to oauth bind --provider twitter
+  xapi-to oauth bind --scopes "tweet.read users.read"
   xapi-to oauth status
   xapi-to oauth status --format pretty
   xapi-to oauth unbind abc123
@@ -1063,13 +1375,49 @@ async function oauthBind(args, flags) {
         `Provider "${providerName}" not found. Available: ${available}`
       );
     }
-    const result = await initiateOAuth(keyRecord.id, provider.id, jwtToken, XAPI_API_HOST);
+    let scopes;
+    let headerPrinted = false;
+    const isTTY = Boolean(
+      process.stdout.isTTY && process.stdin.isTTY && typeof process.stdin.setRawMode === "function"
+    );
+    if (flags.scopes) {
+      scopes = flags.scopes;
+    } else if (isTTY) {
+      const defs = resolveScopeDefs(provider);
+      if (defs.length > 0) {
+        console.error(`
+  Provider : ${provider.name}`);
+        console.error(`  API Key  : ${keyRecord.keyPreview}`);
+        headerPrinted = true;
+        scopes = await selectScopesInteractive(provider) || void 0;
+      }
+    }
+    const existingBindingIds = /* @__PURE__ */ new Set();
+    if (isTTY) {
+      try {
+        const existingBindings = await listOAuthBindings(jwtToken, XAPI_API_HOST);
+        if (Array.isArray(existingBindings)) {
+          for (const binding of existingBindings) {
+            if (binding.apiKeyId === keyRecord.id && binding.providerId === provider.id) {
+              existingBindingIds.add(binding.id);
+            }
+          }
+        }
+      } catch {
+      }
+    }
+    const authorizationStartedAt = /* @__PURE__ */ new Date();
+    const result = await initiateOAuth(keyRecord.id, provider.id, jwtToken, XAPI_API_HOST, scopes);
     const { authorizationUrl } = result;
-    const isTTY = process.stdout.isTTY;
     if (isTTY) {
-      console.error(`
+      if (!headerPrinted) {
+        console.error(`
   Provider : ${provider.name}`);
-      console.error(`  API Key  : ${keyRecord.keyPreview}`);
+        console.error(`  API Key  : ${keyRecord.keyPreview}`);
+      }
+      if (scopes) {
+        console.error(`  Scopes   : ${scopes}`);
+      }
       console.error(`
   Authorization URL:
   ${authorizationUrl}
@@ -1077,14 +1425,20 @@ async function oauthBind(args, flags) {
       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);
+      const binding = await pollForBinding(
+        keyRecord.id,
+        provider.id,
+        jwtToken,
+        authorizationStartedAt,
+        existingBindingIds
+      );
       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);
+        output({ status: "success", provider: provider.name, account, scopes }, flags.format);
       } else {
         err("oauth bind timed out", 'Authorization was not completed within 5 minutes. Run "xapi-to oauth bind" again.');
       }
@@ -1093,7 +1447,8 @@ async function oauthBind(args, flags) {
         status: "pending",
         provider: provider.name,
         apiKey: keyRecord.keyPreview,
-        authorizationUrl
+        authorizationUrl,
+        scopes
       }, flags.format);
     }
   } catch (e) {
@@ -1156,19 +1511,217 @@ async function oauthProviders(args, flags) {
   }
 }
 
-// src/index.ts
-var { CONFIG_HELP: CONFIG_HELP2 } = config_exports;
-var { OAUTH_HELP: OAUTH_HELP2 } = oauth_exports;
+// src/commands/task.ts
+var POLL_HELP = `xapi-to task poll - Poll an async task once
+
+USAGE
+  xapi-to task poll <task_id> [flags]
+
+FLAGS
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
+`;
+var WAIT_HELP = `xapi-to task wait - Wait until async task reaches terminal status
+
+USAGE
+  xapi-to task wait <task_id> [flags]
+
+FLAGS
+  --interval <duration>       Poll interval (default: 2s). Supports ms/s/m/h
+  --timeout <duration>        Max wait duration (optional). Supports ms/s/m/h
+  --max-attempts <number>     Max poll attempts (optional)
+  --format json|pretty|table  Output format
+
+EXAMPLES
+  xapi-to task wait 550e8400-e29b-41d4-a716-446655440000
+  xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 1s --timeout 10m
+`;
+var TASK_HELP = `xapi-to task - Async task helpers
+
+USAGE
+  xapi-to task <command> [args] [flags]
+
+COMMANDS
+  poll <task_id>              Poll task status once (wraps action: task.poll)
+  wait <task_id>              Poll repeatedly until terminal status
+
+EXAMPLES
+  xapi-to task poll 550e8400-e29b-41d4-a716-446655440000
+  xapi-to task wait 550e8400-e29b-41d4-a716-446655440000 --interval 2s --timeout 10m
+`;
+function showHelpIfRequested2(flags, helpText) {
+  if (flags.help) {
+    console.log(helpText);
+    process.exit(0);
+  }
+}
+function parseDurationMs(raw) {
+  const text = raw.trim().toLowerCase();
+  const match = text.match(/^(\d+)(ms|s|m|h)?$/);
+  if (!match) {
+    err(`invalid duration "${raw}". Use formats like 500ms, 2s, 5m, 1h.`);
+  }
+  const value = Number(match[1]);
+  const unit = match[2] || "ms";
+  if (!Number.isFinite(value) || value < 0) {
+    err(`invalid duration "${raw}". Duration must be >= 0.`);
+  }
+  switch (unit) {
+    case "ms":
+      return value;
+    case "s":
+      return value * 1e3;
+    case "m":
+      return value * 6e4;
+    case "h":
+      return value * 36e5;
+    default:
+      return value;
+  }
+}
+function parsePositiveDurationMs(raw, flagName) {
+  const ms = parseDurationMs(raw);
+  if (ms <= 0) {
+    err(`${flagName} must be greater than 0`);
+  }
+  return ms;
+}
+function parsePositiveInt(raw, flagName) {
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n <= 0) {
+    err(`${flagName} must be a positive integer`);
+  }
+  return n;
+}
+function sleep2(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function extractTaskPayload(res) {
+  if (res && typeof res === "object") {
+    const obj = res;
+    if (typeof obj.status === "string") return obj;
+    if (obj.data && typeof obj.data === "object" && !Array.isArray(obj.data)) {
+      const dataObj = obj.data;
+      if (typeof dataObj.status === "string") return dataObj;
+    }
+  }
+  return res ?? {};
+}
+function getStatus(payload) {
+  const status = payload.status;
+  if (status === "pending" || status === "processing" || status === "succeeded" || status === "failed" || status === "expired") {
+    return status;
+  }
+  return void 0;
+}
+async function taskPoll(args, flags) {
+  showHelpIfRequested2(flags, POLL_HELP);
+  const taskId = args[0];
+  if (!taskId) err("usage: xapi-to task poll <task_id>");
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  try {
+    const res = await actionCall("task.poll", { task_id: taskId }, cfg, void 0, 2);
+    const payload = extractTaskPayload(res);
+    output(payload, flags.format);
+  } catch (e) {
+    err("task poll failed", e.message);
+  }
+}
+async function taskWait(args, flags) {
+  showHelpIfRequested2(flags, WAIT_HELP);
+  const taskId = args[0];
+  if (!taskId) err("usage: xapi-to task wait <task_id>");
+  const intervalMs = parsePositiveDurationMs(flags.interval || "2s", "--interval");
+  const timeoutMs = flags.timeout ? parseDurationMs(flags.timeout) : void 0;
+  const maxAttempts = flags["max-attempts"] ? parsePositiveInt(flags["max-attempts"], "--max-attempts") : void 0;
+  const cfg = getConfig();
+  requireApiKey(cfg);
+  const startedAt = Date.now();
+  const deadline = timeoutMs !== void 0 ? startedAt + timeoutMs : void 0;
+  let attempts = 0;
+  while (true) {
+    if (deadline !== void 0 && Date.now() >= deadline) {
+      err(
+        "task wait timeout",
+        `task_id=${taskId}, elapsed_ms=${Date.now() - startedAt}, timeout_ms=${timeoutMs}`
+      );
+    }
+    attempts += 1;
+    let retryDelayMs;
+    try {
+      const remaining = deadline !== void 0 ? Math.max(1, deadline - Date.now()) : void 0;
+      const res = await actionCall("task.poll", { task_id: taskId }, cfg, void 0, 0, remaining);
+      const payload = extractTaskPayload(res);
+      const status = getStatus(payload);
+      if (!status) {
+        err("task wait failed", "task.poll returned invalid response: missing status");
+      }
+      if (status === "succeeded") {
+        output(payload, flags.format);
+        return;
+      }
+      if (status === "failed" || status === "expired") {
+        output(payload, flags.format);
+        process.exit(1);
+      }
+    } catch (e) {
+      if (e instanceof Error && e.message === "process.exit") {
+        throw e;
+      }
+      if (deadline !== void 0 && Date.now() >= deadline) {
+        err(
+          "task wait timeout",
+          `task_id=${taskId}, elapsed_ms=${Date.now() - startedAt}, timeout_ms=${timeoutMs}`
+        );
+      }
+      if (isRetryableRequestError(e)) {
+        retryDelayMs = e instanceof HttpError ? e.retryAfterMs : void 0;
+      } else {
+        err("task wait failed", e.message);
+      }
+    }
+    if (maxAttempts && attempts >= maxAttempts) {
+      err(
+        "task wait exceeded max attempts",
+        `task_id=${taskId}, attempts=${attempts}, max_attempts=${maxAttempts}`
+      );
+    }
+    const desiredWaitMs = retryDelayMs ?? intervalMs;
+    const waitMs = deadline !== void 0 ? Math.min(desiredWaitMs, Math.max(0, deadline - Date.now())) : desiredWaitMs;
+    await sleep2(waitMs);
+  }
+}
+function taskHelp() {
+  return TASK_HELP;
+}
+
+// src/args.ts
 function parseArgs(argv) {
   const positional = [];
   const flags = {};
   let i = 0;
+  let onlyPositional = false;
   while (i < argv.length) {
     const arg = argv[i];
-    if (arg.startsWith("--")) {
+    if (!onlyPositional && arg === "--") {
+      onlyPositional = true;
+      i++;
+      continue;
+    }
+    if (!onlyPositional && arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq !== -1) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+        i++;
+        continue;
+      }
       const key = arg.slice(2);
       const next = argv[i + 1];
-      if (next && !next.startsWith("--")) {
+      if (next !== void 0 && !next.startsWith("--")) {
         flags[key] = next;
         i += 2;
       } else {
@@ -1182,6 +1735,10 @@ function parseArgs(argv) {
   }
   return { positional, flags };
 }
+
+// src/index.ts
+var { CONFIG_HELP: CONFIG_HELP2 } = config_exports;
+var { OAUTH_HELP: OAUTH_HELP2 } = oauth_exports;
 var HELP = `xapi-to - agent-friendly CLI for xapi
 
 USAGE
@@ -1209,6 +1766,12 @@ COMMANDS
     --code <target>                  Generate code snippet instead of executing
     Variants: python.requests, python.httpx, javascript.fetch, javascript.axios
 
+  task poll <task_id>                Poll async task once (wraps task.poll)
+  task wait <task_id>                Wait until async task completes
+    --interval <duration>            Poll interval, e.g. 2s (default: 2s)
+    --timeout <duration>             Max wait duration, e.g. 10m
+    --max-attempts <number>          Max poll attempts
+
   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
@@ -1216,6 +1779,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
   balance                           Show current account balance
   topup [--amount <usd>] [--method stripe|x402]   Generate payment URL
 
@@ -1246,6 +1810,8 @@ EXAMPLES
   xapi-to get twitter.tweet_detail --code py --format pretty
   xapi-to call twitter.tweet_detail --input '{"tweet_id":"1234567890"}'
   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
   xapi-to categories
   xapi-to services --format table
   xapi-to config set apiKey=xapi_abc123
@@ -1273,6 +1839,23 @@ async function main() {
       return actionGet2(rest, flags);
     case "call":
       return actionCall2(rest, flags);
+    case "task": {
+      if (rest.length === 0) {
+        console.log(taskHelp());
+        process.exit(0);
+      }
+      const [subCmd, ...subRest] = rest;
+      switch (subCmd) {
+        case "poll":
+          return taskPoll(subRest, flags);
+        case "wait":
+          return taskWait(subRest, flags);
+        default:
+          console.error(JSON.stringify({ error: `unknown task command: ${subCmd}`, hint: "valid commands: poll, wait" }));
+          process.exit(1);
+      }
+      break;
+    }
     // ── OAuth commands ──
     case "oauth": {
       if (flags.help || rest.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xapi-to",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Agent-friendly CLI for xapi - discover and call capabilities and APIs",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm --target node18 --clean --out-dir dist --tsconfig tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
     "dev": "XAPI_ACTION_HOST=localhost:3003 bun run src/index.ts",
     "prepublishOnly": "npm run build",