@sorit/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# Sorit CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Discover and call commerce, social and search APIs through your Sorit account.
+
+```sh
+bun install --global @sorit/cli
+export SORIT_API_KEY='<YOUR_API_KEY>'
+sorit discover --tool tiktok
+sorit inspect '<API_ID>'
+export SORIT_REQUEST_KEY="$(bun -e 'console.log(crypto.randomUUID())')"
+sorit run '<API_ID>' --input @input.json --idempotency-key "$SORIT_REQUEST_KEY" --wait
+sorit get '<REQUEST_ID>' --wait
+```
+
+Requires Bun 1.2+. The API server defaults to production at `https://sorit.dev`; no server configuration is needed. Create an API key at https://sorit.dev/app/keys and set `SORIT_API_KEY`. For local development, override the origin with an environment variable, for example `SORIT_URL=http://localhost:3010 sorit tools`. Failures exit with code 1. `run --wait` writes the accepted request ID to stderr before polling, so interrupted waits can be resumed.
+
+## Output
+
+Commands display readable summaries by default: API names and prices, schema details, request status and business data, or balance. `sorit balance` shows the USD equivalent and credit amount, without prices or payment settings. Dollar values retain up to six decimal places so small credit balances are not rounded away.
+
+For scripts and agents, append `--json` to any command. Successful responses go to stdout; HTTP and command errors go to stderr. Terminal failed requests still exit with code 1. `balance --json` returns only `balance` (credits), `creditsPerUsd`, `balanceUsd` and `currency`; other commands retain their REST JSON envelopes. Pending requests label the reserved credits; completed requests show net spending after refunds.
+
+```sh
+sorit balance
+sorit balance --json
+sorit discover --tool tiktok --json
+sorit get '<REQUEST_ID>' --wait --json
+```
+
+## Commands and help
+
+| Command | Purpose |
+| --- | --- |
+| `sorit tools` | List data tools and platforms. |
+| `sorit discover` | Search APIs by tool or keywords. |
+| `sorit inspect <api-id>` | Read the input schema, price and availability. |
+| `sorit run <api-id>` | Create a paid request; optionally wait for results. |
+| `sorit get <request-id>` | Fetch status and results, or resume waiting. |
+| `sorit balance` | Read the account credit balance. |
+
+Run `sorit --help` for the command list. Each command has its own arguments, options and examples: `sorit run --help` or `sorit help run`. Help and version commands work offline without credentials; `--version`, `-V` and `-v` print the version. Discovery and inspection do not require an API key. `run`, `get` and `balance` do.
+
+Use `--search` for keyword filtering. Discovery always returns callable APIs only: the adapter must be ready, pricing and the endpoint enabled, and the provider enabled with configured credentials. `--status` accepts only `available`; unavailable APIs are managed in the admin console. Discovery supports `--page` from 1 to 10000. `run` and `get` accept `--timeout` in milliseconds with `--wait` (default 120000). Unsupported command options fail before making an API request.
+
+Calls use your account's credits. Reuse the same idempotency key and input for retries. A polling timeout does not cancel the request. Keep API keys in the environment.
+
+Agent instructions: https://sorit.dev/SKILL.md. REST reference: https://sorit.dev/en/docs/api/jobs.

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@sorit/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Discover and call Sorit data APIs from your terminal or AI agent",
+  "type": "module",
+  "bin": {
+    "sorit": "src/cli.mjs"
+  },
+  "files": [
+    "src/cli.mjs",
+    "src/client.mjs",
+    "src/output.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "homepage": "https://sorit.dev",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "@sorit:registry": "https://registry.npmjs.org"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { SoritClient } from "./client.mjs";
+import { balanceSummary, formatError, formatResult } from "./output.mjs";
+
+const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+const flags = {
+  search: { syntax: "--search <text>", description: "Filter by keywords." },
+  status: { syntax: "--status <status>", description: "Only available is supported; unavailable APIs are excluded." },
+  tool: { syntax: "--tool <tool-id>", description: "Filter by a tool ID, such as tiktok or twitter." },
+  page: { syntax: "--page <number>", description: "Page number, 1–10000. Default: 1." },
+  input: { syntax: "--input <json|@file>", description: "Input JSON object or @file.json. Required." },
+  "idempotency-key": { syntax: "--idempotency-key <key>", description: "Unique request key; reuse it with the same input on retries. Required." },
+  wait: { syntax: "--wait", description: "Poll until the request finishes." },
+  timeout: { syntax: "--timeout <milliseconds>", description: "Polling time limit with --wait. Default: 120000." },
+};
+const commands = {
+  tools: {
+    description: "List data tools and platforms.",
+    usage: "tools [options]", options: ["search", "status"],
+    notes: "Only tools with callable APIs are returned. No API key required.",
+    examples: ["sorit tools", 'sorit tools --search "social"'],
+  },
+  discover: {
+    description: "Search for data APIs by tool or keywords.",
+    usage: "discover [options]", options: ["tool", "search", "status", "page"],
+    notes: "Only callable APIs are returned. Disabled, unconfigured and unmapped APIs are excluded.\nNo API key required.",
+    examples: ["sorit discover --tool tiktok", 'sorit discover --search "search volume" --page 1'],
+  },
+  inspect: {
+    description: "Show an API's input schema, price and availability.",
+    usage: "inspect <api-id>", options: [],
+    argument: ["<api-id>", "Registered API ID returned by discover."],
+    notes: "Inspect an API before calling it. No API key required.",
+    examples: ["sorit inspect <api-id>"],
+  },
+  run: {
+    description: "Create a paid API request and optionally wait for results.",
+    usage: "run <api-id> --input <json|@file> --idempotency-key <key> [options]",
+    options: ["input", "idempotency-key", "wait", "timeout"],
+    argument: ["<api-id>", "Registered API ID returned by discover or a supported recipe ID."],
+    notes: "Requires SORIT_API_KEY and account credits. Use the same key and input for retries.\nA wait timeout does not cancel the request; resume with sorit get <request-id> --wait.",
+    examples: [
+      "sorit run <api-id> --input @input.json --idempotency-key research-001 --wait",
+      `sorit run <api-id> --input '{"query":{"limit":10}}' --idempotency-key research-002`,
+    ],
+  },
+  get: {
+    description: "Fetch a request's status and results, or resume waiting.",
+    usage: "get <request-id> [options]", options: ["wait", "timeout"],
+    argument: ["<request-id>", "request_id returned by run."],
+    notes: "Requires SORIT_API_KEY. Polling does not create another paid request.\nA wait timeout does not cancel the request.",
+    examples: ["sorit get <request-id>", "sorit get <request-id> --wait --timeout 120000"],
+  },
+  balance: {
+    description: "Show your account's credit balance.",
+    usage: "balance [options]", options: [],
+    notes: "Requires SORIT_API_KEY. Shows USD equivalent and credits; no checkout configuration.", examples: ["sorit balance", "sorit balance --json"],
+  },
+};
+const rows = entries => entries.map(([label, description]) => `  ${label.padEnd(30)} ${description}`).join("\n");
+const section = (title, body) => `${title}:\n${body}`;
+const globalOptions = [
+  ["-h, --help", "Show help for this command."],
+  ["-V, --version", "Show the version number (-v also supported)."],
+  ["--json", "Output structured JSON for scripts and agents."],
+];
+function help(command) {
+  const spec = commands[command];
+  return [
+    section("Usage", `  sorit ${spec?.usage ?? "<command> [options]"}`),
+    section("Version", `  ${version}`),
+    section("Description", `  ${spec?.description ?? "Sorit CLI — discover, inspect and run data APIs."}`),
+    ...(spec?.argument ? [section("Arguments", rows([spec.argument]))] : []),
+    section("Options", rows([...(spec?.options ?? []).map(name => [flags[name].syntax, flags[name].description]), ...globalOptions])),
+    ...(!spec ? [section("Commands", rows([...Object.entries(commands).map(([name, value]) => [name, value.description]), ["help [command]", "Show help for a command."]]))] : []),
+    section("Environment", rows([
+      ["SORIT_API_KEY", "API key for run, get and balance."],
+      ["SORIT_URL", "Optional origin override for local deployments."],
+    ])),
+    "API server: https://sorit.dev (default; no configuration required).",
+    ...(spec?.notes ? [section("Notes", spec.notes.split("\n").map(line => `  ${line}`).join("\n"))] : []),
+    section("Examples", (spec?.examples ?? ["sorit discover --tool tiktok", "sorit inspect <api-id>", "sorit run --help"]).map(line => `  ${line}`).join("\n")),
+    "Docs: https://sorit.dev/en/docs/integrations",
+  ].join("\n\n");
+}
+
+let jsonOutput = process.argv.slice(2).includes("--json");
+try {
+  const { values, positionals } = parseArgs({ args: process.argv.slice(2).map(arg => arg === "-v" ? "-V" : arg), allowPositionals: true, options: {
+    version: { type: "boolean", short: "V" }, help: { type: "boolean", short: "h" }, wait: { type: "boolean" },
+    input: { type: "string" }, "idempotency-key": { type: "string" },
+    tool: { type: "string" }, search: { type: "string" }, page: { type: "string" },
+    status: { type: "string" }, timeout: { type: "string" },
+    json: { type: "boolean" },
+  } });
+  jsonOutput = Boolean(values.json);
+  const explicitHelp = positionals[0] === "help";
+  const [command, id] = explicitHelp ? positionals.slice(1) : positionals;
+  const spec = commands[command];
+  if (command && !Object.hasOwn(commands, command)) throw new Error(`Unknown command "${command}". Use sorit --help.`);
+  for (const name of Object.keys(values)) {
+    if (!["version", "help", "json"].includes(name) && !spec?.options.includes(name)) throw new Error(`--${name} is not supported here. Use sorit ${command ? `${command} ` : ""}--help.`);
+  }
+  if (explicitHelp && positionals.length > 2) throw new Error("Usage: sorit help [command].");
+  if (values.version) console.log(version);
+  else if (values.help || explicitHelp || !command) console.log(help(command));
+  else {
+    if (positionals.length !== (spec.argument ? 2 : 1) || spec.argument && !id?.trim()) throw new Error(`Usage: sorit ${spec.usage}. See sorit ${command} --help.`);
+    if (values.timeout !== undefined && !values.wait) throw new Error("--timeout requires --wait.");
+    const timeoutMs = Number(values.timeout ?? 120000);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 4294967295) throw new Error("--timeout must be an integer between 1 and 4294967295 milliseconds.");
+    if (values.page !== undefined && (!/^\d+$/.test(values.page) || Number(values.page) < 1 || Number(values.page) > 10000)) throw new Error("--page must be an integer between 1 and 10000.");
+    if (values.status !== undefined && values.status !== "available") throw new Error("Search only returns available APIs. --status must be available.");
+    const client = new SoritClient({ baseUrl: process.env.SORIT_URL?.trim() || undefined, apiKey: process.env.SORIT_API_KEY ?? process.env.SELLERTOOL_API_KEY });
+    const filters = { q: values.search, page: values.page, status: values.status };
+    let result;
+    if (command === "balance") result = balanceSummary(await client.request("/api/credits", { authenticated: true }));
+    if (command === "tools") result = await client.tools(filters);
+    if (command === "discover") result = await client.endpoints({ ...filters, tool: values.tool });
+    if (command === "inspect") result = await client.describe(id);
+    if (command === "run") {
+      if (!values.input) throw new Error("Supply --input @input.json or a JSON object string. See sorit run --help.");
+      const input = JSON.parse(values.input.startsWith("@") ? await readFile(values.input.slice(1), "utf8") : values.input);
+      if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("Input must be a JSON object.");
+      result = await client.create(id, input, { idempotencyKey: values["idempotency-key"] });
+      // Print the accepted ID before polling so interrupted calls can be resumed.
+      if (values.wait && ["queued", "running"].includes(result.status)) {
+        console.error(`Accepted request_id: ${result.request_id}`);
+        result = await client.wait(result.request_id, { timeoutMs });
+      }
+    }
+    if (command === "get") result = values.wait ? await client.wait(id, { timeoutMs }) : await client.get(id);
+    const failed = ["failed", "rejected"].includes(result?.status);
+    const write = failed && !jsonOutput ? console.error : console.log;
+    write(jsonOutput ? JSON.stringify(result, null, 2) : formatResult(command, result));
+    if (failed) process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(jsonOutput ? JSON.stringify(error.result ?? { error: error.message }, null, 2) : formatError(error));
+  process.exitCode = 1;
+}

package/src/client.mjs

@@ -0,0 +1,68 @@
+/** Internal HTTP transport for the Sorit CLI. */
+export class SoritError extends Error {
+  constructor(message, { status = 0, result = null } = {}) {
+    super(message);
+    this.name = "SoritError";
+    this.status = status;
+    this.result = result;
+  }
+}
+
+export class SoritClient {
+  /** @param {{baseUrl?: string, apiKey?: string, timeoutMs?: number}} [options] */
+  constructor({ baseUrl = "https://sorit.dev", apiKey, timeoutMs = 30_000 } = {}) {
+    const url = new URL(baseUrl);
+    if (!(["https:"].includes(url.protocol) || url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname))) throw new Error("Use HTTPS, or HTTP on localhost.");
+    if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) throw new Error("baseUrl must be an origin.");
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("timeoutMs must be positive.");
+    this.baseUrl = url.origin;
+    this.apiKey = apiKey;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async request(path, { method = "GET", body, idempotencyKey, authenticated = false, timeoutMs = this.timeoutMs } = {}) {
+    if (!path.startsWith("/") || path.startsWith("//")) throw new Error("Use a Sorit API path.");
+    if (authenticated && !this.apiKey) throw new Error(`Set SORIT_API_KEY. Create an API key at ${this.baseUrl}/app/keys.`);
+    const headers = { Accept: "application/json" };
+    if (authenticated) headers.Authorization = `Bearer ${this.apiKey}`;
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+    // Never forward a bearer key through a redirect, or automatically retry a paid POST.
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      method, headers, redirect: "error", signal: AbortSignal.timeout(timeoutMs),
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    let result;
+    try { result = await response.json(); }
+    catch { throw new SoritError("Sorit returned a non-JSON response.", { status: response.status }); }
+    if (!response.ok) throw new SoritError((typeof result.error === "string" ? result.error : result.error?.message) ?? "Sorit request failed.", { status: response.status, result });
+    return result;
+  }
+
+  tools({ q = "", page = 1 } = {}) {
+    return this.request(`/api/tools?${new URLSearchParams({ q, status: "available", page: String(page) })}`);
+  }
+  endpoints({ tool = "", q = "", page = 1 } = {}) {
+    return this.request(`/api/endpoints?${new URLSearchParams({ tool, q, status: "available", page: String(page) })}`);
+  }
+  describe(apiId) { return this.request(`/api/tools/${encodeURIComponent(apiId)}`); }
+  create(apiId, input, { idempotencyKey } = {}) {
+    if (!idempotencyKey || !/^[A-Za-z0-9._:-]{1,128}$/.test(idempotencyKey)) throw new Error("Supply a unique idempotencyKey (1–128 letters, numbers, dots, underscores, colons or hyphens); reuse it for retries.");
+    return this.request(apiId.includes(".") ? `/api/v1/run/${encodeURIComponent(apiId)}` : "/api/jobs", { method: "POST", authenticated: true, body: apiId.includes(".") ? input : { kind: apiId, input }, idempotencyKey });
+  }
+  get(requestId, { timeoutMs } = {}) {
+    return this.request(`/api/jobs/${encodeURIComponent(requestId)}`, { authenticated: true, timeoutMs });
+  }
+  async wait(requestId, { intervalMs = 1500, timeoutMs = 120_000 } = {}) {
+    if (!Number.isFinite(intervalMs) || intervalMs < 100 || !Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("Use intervalMs >= 100 and timeoutMs > 0.");
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.get(requestId, { timeoutMs: Math.max(1, Math.min(this.timeoutMs, deadline - Date.now())) });
+      if (["succeeded", "failed", "rejected"].includes(result.status)) return result;
+      if (!["queued", "running"].includes(result.status)) throw new SoritError("Unexpected request status.", { result });
+      const remaining = deadline - Date.now();
+      if (remaining > 0) await new Promise(resolve => setTimeout(resolve, Math.min(intervalMs, remaining)));
+    }
+    throw new SoritError(`Polling timed out for request_id ${requestId}. Resume with sorit get <request-id> --wait; the request may still be running.`);
+  }
+}

package/src/output.mjs

@@ -0,0 +1,120 @@
+/** Terminal presentation, separate from the REST response envelopes. */
+const number = value => new Intl.NumberFormat("en-US", { maximumFractionDigits: 6 }).format(value);
+const usd = value => new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", minimumFractionDigits: 2, maximumFractionDigits: 6 }).format(value);
+const text = value => String(value ?? "").replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+const json = value => JSON.stringify(value, null, 2);
+const indent = value => String(value).split("\n").map(line => `  ${line}`).join("\n");
+const heading = (label, body) => `  ${label}: ${text(body)}`;
+const next = command => `  Next: ${command}`;
+const creditPrice = api => {
+  const credits = api.pricing?.credits ?? api.policy?.credits;
+  if (typeof credits !== "number") return "Price unavailable";
+  return `${number(credits)} credits ${api.billing || api.pricing?.billing ? "maximum reservation" : `/ ${api.pricing?.unit ?? "request"}`}`;
+};
+
+export function balanceSummary(result) {
+  if (typeof result?.balance !== "number" || !Number.isFinite(result.balance) || typeof result.creditsPerUsd !== "number" || !Number.isFinite(result.creditsPerUsd) || result.creditsPerUsd <= 0) throw new Error("Sorit returned an invalid balance response.");
+  return { balance: result.balance, creditsPerUsd: result.creditsPerUsd, balanceUsd: Number((result.balance / result.creditsPerUsd).toFixed(6)), currency: "USD" };
+}
+
+function apiRows(apis) {
+  return apis.map(api => [
+    `  ${text(api.title?.en || api.name || api.id)}`,
+    `    ${api.providerName || api.provider ? text(api.providerName || api.provider) + " · " : ""}${creditPrice(api)}`,
+    `    ID: ${text(api.id)}`,
+  ].join("\n")).join("\n\n");
+}
+
+function discover(result) {
+  const apis = result.apis ?? result.tools ?? [];
+  const total = result.total ?? apis.length;
+  if (!apis.length) return "No available APIs found.\n\n  Try broader keywords or run sorit tools to browse platforms.";
+  return [
+    `✔ ${number(total)} available API${total === 1 ? "" : "s"} found`,
+    apiRows(apis),
+    `  Page ${result.page ?? 1} / ${Math.ceil(total / (result.pageSize ?? apis.length))}`,
+    next(`sorit inspect ${text(apis[0].id)}`),
+  ].join("\n\n");
+}
+
+function inspect(result) {
+  if (result.layer === "tool") return `  ${text(result.id)}\n\n${discover(result.endpoints)}`;
+  const rates = result.pricing?.billing;
+  const unit = { limit: "result", keywords: "keyword", asins: "ASIN" }[rates?.measure];
+  const lines = [
+    `  ${text(result.title?.en || result.name || result.id)}`,
+    ...(typeof result.description === "string" && result.description.trim() !== result.name?.trim() ? [indent(text(result.description))] : []),
+    [
+      heading("ID", result.id),
+      heading("Status", result.status),
+      ...(result.providerName || result.provider ? [heading("Provider", result.providerName || result.provider)] : []),
+      ...(result.method && result.endpoint ? [heading("Endpoint", `${result.method} ${result.endpoint}`)] : []),
+      heading("Price", creditPrice(result)),
+      ...(rates && unit ? [heading("Base fee", `${number(rates.base)} credits / request`), heading("Unit fee", `${number(rates.perUnit)} credits / ${unit}`)] : []),
+      ...(rates?.measure === "budget" ? [heading("Usage", "Settled from provider cost; unused reservation is refunded.")] : []),
+      ...(result.limits?.maxItems != null ? [heading("Maximum items", result.limits.maxItems)] : []),
+    ].join("\n"),
+    ...(result.inputSchema ? ["  Input schema:\n" + indent(json(result.inputSchema))] : []),
+    next(`sorit run ${text(result.id)} --input @input.json --idempotency-key <unique-key> --wait`),
+  ];
+  return lines.join("\n\n");
+}
+
+function requestResult(result) {
+  const pending = ["queued", "running"].includes(result.status);
+  const failed = ["failed", "rejected"].includes(result.status);
+  const lines = [
+    `${failed ? "✖" : "✔"} Request ${text(result.status)}`,
+    [heading("Request", result.request_id), ...(result.api_id ? [heading("API", result.api_id)] : [])].join("\n"),
+  ];
+  if (result.credits) {
+    const { charged, refunded } = result.credits;
+    if (typeof charged === "number" && typeof refunded === "number") {
+      lines.push(pending ? heading("Reserved", `${number(charged)} credits`) : heading("Spent", `${number(Number((charged - refunded).toFixed(2)))} credits`));
+      if (refunded > 0) lines.push(heading("Refunded", `${number(refunded)} credits`));
+    }
+  }
+  if (result.error) lines.push(errorDetails(result.error));
+  if (result.data !== undefined && result.data !== null) lines.push("  Data:\n" + indent(json(result.data)));
+  if (pending) lines.push(next(`sorit get ${text(result.request_id)} --wait`));
+  return lines.join("\n\n");
+}
+
+const hints = {
+  UNAUTHORIZED: "Set SORIT_API_KEY to a valid key from your Sorit console.",
+  FORBIDDEN: "Use the account that owns this request.",
+  INSUFFICIENT_CREDITS: "Top up your Sorit account before creating another request.",
+  NOT_FOUND: "Run sorit discover to find an available API, or check the request ID.",
+  INVALID_INPUT: "Run sorit inspect <api-id> to check required parameters and limits.",
+  IDEMPOTENCY_CONFLICT: "Use the original idempotency key and identical input to resume the existing request.",
+  SERVICE_UNAVAILABLE: "Run sorit discover to find another available API, or retry later.",
+};
+function errorDetails(error) {
+  const code = text(typeof error === "string" ? error : error?.code).toUpperCase();
+  const message = text(typeof error === "string" ? code === "UNAUTHORIZED" ? "Authentication failed." : error : error?.message || error?.code || "Request failed.");
+  const fields = Array.isArray(error?.fields) ? error.fields.map(field => heading(Array.isArray(field.path) && field.path.length ? field.path.join(".") : text(field.field || "Input"), field.message || field.code || "Invalid value")) : [];
+  return [indent(message), ...(code && code !== message.toUpperCase() ? [heading("Code", code)] : []), ...fields, ...(hints[code] ? [indent(hints[code])] : [])].join("\n");
+}
+
+export function formatError(error) {
+  const result = error?.result;
+  if (result?.request_id && result.status) return requestResult(result);
+  return `✖ ${errorDetails(result?.error ?? error?.message ?? "Request failed.").trimStart()}`;
+}
+
+export function formatResult(command, result) {
+  if (command === "balance") return `✔ Balance retrieved\n\n  Balance: ${usd(result.balanceUsd)} USD\n  Credits: ${number(result.balance)}`;
+  if (command === "discover") return discover(result);
+  if (command === "inspect") return inspect(result);
+  if (command === "tools") {
+    const tools = result.tools ?? [];
+    if (result.apis) return discover(result);
+    if (!tools.length) return "No available tools found.\n\n  Try broader keywords or run sorit tools without filters.";
+    return [
+      `✔ ${number(result.total ?? tools.length)} available tools found`,
+      tools.map(tool => `  ${text(tool.name || tool.id)}\n    ${number(tool.endpointCount)} APIs · ${(tool.providers ?? []).map(provider => text(provider.name)).join(", ")}\n    ID: ${text(tool.id)}`).join("\n\n"),
+      next(`sorit discover --tool ${text(tools[0].id)}`),
+    ].join("\n\n");
+  }
+  return requestResult(result);
+}