@sorit/cli 0.1.0 → 0.1.1

package/README.md

@@ -14,11 +14,13 @@ 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.
 
+The CLI is written in TypeScript and runs directly on Bun without a separate build step. Source types cover each command's result, while HTTP response validation checks actual server data. From the repository root, check it independently with `pnpm exec tsc -p packages/cli/tsconfig.json`.
+
 ## 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.
+Commands display readable summaries by default: platform tools and their API counts, API names and prices, schema details, request status and business data, or balance. `inspect` handles localized titles/descriptions and shows the POST path plus input and output schemas. `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.
+For scripts and agents, append `--json` to any command. Successful responses go to stdout; HTTP and command errors go to stderr. A successfully retrieved terminal failed/rejected request is also written to stdout in JSON mode, with exit code 1; human mode writes that failure to stderr. `balance --json` returns only `balance` (credits), `creditsPerUsd`, `balanceUsd` and `currency`. `tools --json` returns platform groups (`id`, `platform`, `name`, `apiCount`). `discover --json` returns the filtered data-API listing with `total`, `page`, `pageSize` and `apis`. Inspection and request reads retain their REST JSON objects, including localized descriptions and normalized business data. Pending requests label the reserved credits; completed requests show net spending after refunds.
 
 ```sh
 sorit balance
@@ -40,8 +42,8 @@ sorit get '<REQUEST_ID>' --wait --json
 
 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.
+Use `--search` for keyword filtering in English or Chinese. `tools` groups available APIs by platform; `discover --tool twitter` filters that platform's APIs. Both read the server's complete available-only `/api/v1/apis` snapshot; the CLI performs tool/keyword filtering and 24-item pagination because the current server catalog has no tool/page query contract. Discovery never requests disabled items. Malformed or non-available catalog entries fail validation instead of silently appearing in search. `--status` accepts only `available`; unavailable APIs are managed in the admin console. Discovery supports `--page` from 1 to 10000, and reports an empty page without inventing results. `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.
+Calls use your account's credits. `run` sends flat input to `POST /api/v1/run/{api-id}`; `get` reads `GET /api/v1/requests/{request-id}`. Reuse the same idempotency key and input for retries. Paid submissions are never automatically retried; a timeout or invalid submission response may mean the request was accepted, so preserve its identity. A polling timeout does not cancel the request and reports the exact resume command. Keep API keys in the environment; discovery and inspection do not transmit them.
 
 Agent instructions: https://sorit.dev/SKILL.md. REST reference: https://sorit.dev/en/docs/api/jobs.

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@sorit/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Discover and call Sorit data APIs from your terminal or AI agent",
   "type": "module",
   "bin": {
-    "sorit": "src/cli.mjs"
+    "sorit": "src/cli.ts"
   },
   "files": [
-    "src/cli.mjs",
-    "src/client.mjs",
-    "src/output.mjs",
+    "src/*.ts",
+    "tsconfig.json",
     "README.md"
   ],
   "engines": {
@@ -20,5 +19,8 @@
     "access": "public",
     "registry": "https://registry.npmjs.org",
     "@sorit:registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
   }
 }

package/src/{cli.mjs → cli.ts}

@@ -1,10 +1,14 @@
 #!/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";
+import { SoritClient, SoritError } from "./client";
+import { balanceSummary, formatError, formatResult } from "./output";
+import { isObject } from "./contracts";
+import type { CommandName, CommandResults } from "./types";
 
-const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+const metadata: unknown = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+if (!isObject(metadata) || typeof metadata.version !== "string") throw new Error("Invalid CLI package metadata.");
+const version = metadata.version;
 const flags = {
   search: { syntax: "--search <text>", description: "Filter by keywords." },
   status: { syntax: "--status <status>", description: "Only available is supported; unavailable APIs are excluded." },
@@ -15,7 +19,9 @@ const flags = {
   wait: { syntax: "--wait", description: "Poll until the request finishes." },
   timeout: { syntax: "--timeout <milliseconds>", description: "Polling time limit with --wait. Default: 120000." },
 };
-const commands = {
+type Flag = keyof typeof flags;
+type CommandSpec = { description: string; usage: string; options: Flag[]; notes: string; examples: string[]; argument?: [string, string] };
+const commands: Record<CommandName, CommandSpec> = {
   tools: {
     description: "List data tools and platforms.",
     usage: "tools [options]", options: ["search", "status"],
@@ -39,11 +45,11 @@ const commands = {
     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."],
+    argument: ["<api-id>", "Registered Sorit data API ID returned by discover."],
     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`,
+      `sorit run <api-id> --input '{"limit":10}' --idempotency-key research-002`,
     ],
   },
   get: {
@@ -59,22 +65,22 @@ const commands = {
     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 = [
+const rows = (entries: ReadonlyArray<readonly [string, string]>) => entries.map(([label, description]) => `  ${label.padEnd(30)} ${description}`).join("\n");
+const section = (title: string, body: string) => `${title}:\n${body}`;
+const globalOptions: [string, string][] = [
   ["-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];
+function help(command?: CommandName) {
+  const spec = command ? commands[command] : undefined;
   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("Options", rows([...(spec?.options ?? []).map((name): [string, string] => [flags[name].syntax, flags[name].description]), ...globalOptions])),
+    ...(!spec ? [section("Commands", rows([...Object.entries(commands).map(([name, value]): [string, string] => [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."],
@@ -86,6 +92,14 @@ function help(command) {
   ].join("\n\n");
 }
 
+function isCommand(value: string | undefined): value is CommandName { return Boolean(value && Object.hasOwn(commands, value)); }
+function printResult<K extends CommandName>(command: K, result: CommandResults[K]) {
+  const failed = "status" in result && (result.status === "failed" || result.status === "rejected");
+  const write = failed && !jsonOutput ? console.error : console.log;
+  write(jsonOutput ? JSON.stringify(result, null, 2) : formatResult(command, result));
+  if (failed) process.exitCode = 1;
+}
+
 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: {
@@ -97,16 +111,19 @@ try {
   } });
   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.`);
+  const [rawCommand, id] = explicitHelp ? positionals.slice(1) : positionals;
+  if (rawCommand && !isCommand(rawCommand)) throw new Error(`Unknown command "${rawCommand}". Use sorit --help.`);
+  const command = isCommand(rawCommand) ? rawCommand : undefined;
+  const spec = command ? commands[command] : undefined;
   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 (!["version", "help", "json"].includes(name) && !spec?.options.some(option => option === 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 {
+    const spec = commands[command];
+    const target = id ?? "";
     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);
@@ -115,29 +132,33 @@ try {
     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 });
+    switch (command) {
+      case "balance": printResult(command, balanceSummary(await client.request("/api/credits", { authenticated: true }))); break;
+      case "tools": printResult(command, await client.tools(filters)); break;
+      case "discover": printResult(command, await client.endpoints({ ...filters, tool: values.tool })); break;
+      case "inspect": printResult(command, await client.describe(target)); break;
+      case "get": printResult(command, values.wait ? await client.wait(target, { timeoutMs }) : await client.get(target)); break;
+      case "run": {
+        if (!values.input) throw new Error("Supply --input @input.json or a JSON object string. See sorit run --help.");
+        let source: string;
+        try { source = values.input.startsWith("@") ? await readFile(values.input.slice(1), "utf8") : values.input; }
+        catch { throw new Error(`Cannot read input file ${values.input.slice(1)}.`); }
+        let input: unknown;
+        try { input = JSON.parse(source); }
+        catch { throw new Error("Input is not valid JSON. Use --input @input.json or a JSON object string."); }
+        if (!isObject(input)) throw new Error("Input must be a JSON object.");
+        let result = await client.create(target, input, { idempotencyKey: values["idempotency-key"] });
+        if (values.wait && ["queued", "running"].includes(result.status)) {
+          // Print the accepted ID before polling so interrupted calls can be resumed.
+          console.error(`Accepted request_id: ${result.request_id}`);
+          result = await client.wait(result.request_id, { timeoutMs });
+        }
+        printResult(command, result); break;
       }
     }
-    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));
+  const result = error instanceof SoritError ? error.result : null;
+  console.error(jsonOutput ? JSON.stringify(result ?? { error: error instanceof Error ? error.message : "Command failed." }, null, 2) : formatError(error));
   process.exitCode = 1;
 }

package/src/client.ts

@@ -0,0 +1,104 @@
+/** Internal HTTP transport for the Sorit CLI. */
+import { isObject, validateApi, validateCatalog, validateRequest, identifier, filters, platformId, searchTerms, apiSearchText, catalogTools } from "./contracts";
+import type { ApiDiscovery, ApiInspection, CatalogFilters, SoritRequest, ToolListing } from "./types";
+type RequestOptions = { method?: string; body?: unknown; idempotencyKey?: string; authenticated?: boolean; timeoutMs?: number };
+export class SoritError extends Error {
+  status: number;
+  result: unknown;
+  constructor(message: string, { status = 0, result = null }: { status?: number; result?: unknown } = {}) {
+    super(message);
+    this.name = "SoritError";
+    this.status = status;
+    this.result = result;
+  }
+}
+
+export class SoritClient {
+  baseUrl: string;
+  apiKey?: string;
+  timeoutMs: number;
+  constructor({ baseUrl = "https://sorit.dev", apiKey, timeoutMs = 30_000 }: { baseUrl?: string; apiKey?: string; timeoutMs?: number } = {}) {
+    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: string, { method = "GET", body, idempotencyKey, authenticated = false, timeoutMs = this.timeoutMs }: RequestOptions = {}): Promise<unknown> {
+    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: Record<string, string> = { 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.
+    let response;
+    try {
+      response = await fetch(`${this.baseUrl}${path}`, {
+        method, headers, redirect: "error", signal: AbortSignal.timeout(timeoutMs),
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      });
+    } catch (error) {
+      const timeout = error instanceof Error && ["TimeoutError", "AbortError"].includes(error.name);
+      throw new SoritError(`${timeout ? "Request timed out" : "Could not reach Sorit"} at ${this.baseUrl}.${method === "POST" ? " Submission is unconfirmed; retry with the same API ID, input and idempotency key." : ""}`);
+    }
+    let result: unknown;
+    try { result = await response.json(); }
+    catch { throw new SoritError(`Sorit returned a non-JSON response (HTTP ${response.status}).${method === "POST" ? " Submission is unconfirmed; retry with the same API ID, input and idempotency key." : ""}`, { status: response.status }); }
+    if (!isObject(result)) throw new SoritError(`Sorit returned an invalid JSON response.${method === "POST" ? " Submission is unconfirmed; retry with the same API ID, input and idempotency key." : ""}`, { status: response.status });
+    if (!response.ok) throw new SoritError(typeof result.error === "string" ? result.error : isObject(result.error) && typeof result.error.message === "string" ? result.error.message : "Sorit request failed.", { status: response.status, result });
+    return result;
+  }
+
+  async tools(input: CatalogFilters = {}): Promise<ToolListing> {
+    const { q } = filters(input), catalog = validateCatalog(await this.request("/api/v1/apis"));
+    const tools = catalogTools(catalog.apis, q);
+    return { schemaVersion: 1, layer: "tools", total: tools.length, tools };
+  }
+  async endpoints(input: CatalogFilters = {}): Promise<ApiDiscovery> {
+    const { tool, q, page } = filters(input), catalog = validateCatalog(await this.request("/api/v1/apis"));
+    // The public catalog currently has no server tool/page filters. Apply these to its complete available snapshot.
+    const terms = searchTerms(q), pageSize = 24;
+    const apis = catalog.apis.filter(api => (!tool || platformId(api.platform) === platformId(tool)) && terms.every(term => apiSearchText(api).includes(term)));
+    return { ...catalog, total: apis.length, page, pageSize, apis: apis.slice((page - 1) * pageSize, page * pageSize),
+      categories: [...new Set(catalog.apis.map(api => api.category))].map(id => ({ id, count: apis.filter(api => api.category === id).length })) };
+  }
+  async describe(apiId: string): Promise<ApiInspection> { return validateApi(await this.request(`/api/v1/apis/${encodeURIComponent(identifier(apiId, "API ID"))}`), true); }
+  create(apiId: string, input: unknown, { idempotencyKey }: { idempotencyKey?: string } = {}): Promise<SoritRequest> {
+    identifier(apiId, "API ID");
+    if (!isObject(input)) throw new Error("Input must be a JSON object.");
+    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(`/api/v1/run/${encodeURIComponent(apiId)}`, { method: "POST", authenticated: true, body: input, idempotencyKey }).then(result => {
+      try { return validateRequest(result); }
+      catch { throw new SoritError(`Sorit returned an invalid submission response${isObject(result) && typeof result.request_id === "string" ? ` for request_id ${result.request_id}` : ""}. Retry with the same API ID, input and idempotency key.`, { status: 200 }); }
+    });
+  }
+  async get(requestId: string, { timeoutMs }: { timeoutMs?: number } = {}): Promise<SoritRequest> {
+    identifier(requestId, "request ID");
+    return validateRequest(await this.request(`/api/v1/requests/${encodeURIComponent(requestId)}`, { authenticated: true, timeoutMs }), requestId);
+  }
+  async wait(requestId: string, { intervalMs = 1500, timeoutMs = 120_000 }: { intervalMs?: number; timeoutMs?: number } = {}): Promise<SoritRequest> {
+    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;
+    const timedOut = () => new SoritError(`Polling timed out for request_id ${requestId}. Resume with sorit get ${requestId} --wait; the request may still be running.`);
+    while (Date.now() < deadline) {
+      let result;
+      try { result = await this.get(requestId, { timeoutMs: Math.max(1, Math.min(this.timeoutMs, deadline - Date.now())) }); }
+      catch (error) {
+        const status = error instanceof SoritError ? error.status : 0;
+        const readUnconfirmed = !status || status >= 200 && status < 300;
+        if (Date.now() >= deadline && readUnconfirmed) throw timedOut();
+        if (readUnconfirmed) throw new SoritError(`${error instanceof Error ? error.message : "Could not read request."} Resume with sorit get ${requestId} --wait.`);
+        throw error;
+      }
+      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 timedOut();
+  }
+}

package/src/contracts.ts

@@ -0,0 +1,82 @@
+/** Runtime validation at the HTTP boundary complements compile-time command/result types. */
+import type { ApiCatalog, ApiInspection, CatalogFilters, DataApi, JsonObject, LocalizedText, SoritRequest, Tool } from "./types";
+
+export const isObject = (value: unknown): value is JsonObject => value !== null && typeof value === "object" && !Array.isArray(value);
+export function localized(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!isObject(value)) return "";
+  return [value.en, value.zh].find((item): item is string => typeof item === "string" && Boolean(item.trim())) ?? "";
+}
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value) && value >= 0;
+const count = (value: unknown): value is number => finite(value) && Number.isSafeInteger(value);
+const validId = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(value);
+const localizedText = (value: unknown): value is LocalizedText => typeof value === "string" || isObject(value) &&
+  (typeof value.en === "string" || typeof value.zh === "string") && (value.en === undefined || typeof value.en === "string") && (value.zh === undefined || typeof value.zh === "string");
+function invalid(kind: string): never { throw new Error(`Sorit returned an invalid ${kind} response.`); }
+function isApi(api: unknown): api is DataApi {
+  return isObject(api) && validId(api.id) && typeof api.platform === "string" && Boolean(api.platform) &&
+    typeof api.category === "string" && localizedText(api.title) && Boolean(localized(api.title)) && localizedText(api.description) &&
+    api.status === "available" && isObject(api.pricing) && finite(api.pricing.credits) && finite(api.pricing.amount) &&
+    api.pricing.currency === "USD" && (api.pricing.unit === "request" || api.pricing.unit === "record") && api.pricing.confirmed === true && api.pricing.failureRefund === true &&
+    isObject(api.limits) && count(api.limits.maxItems) && typeof api.path === "string";
+}
+function isInspection(api: unknown): api is ApiInspection {
+  return isApi(api) && "inputSchema" in api && isObject(api.inputSchema) && "outputSchema" in api && isObject(api.outputSchema) &&
+    "requestProtocol" in api && isObject(api.requestProtocol) && "invocation" in api && isObject(api.invocation) && api.invocation.method === "POST" &&
+    api.invocation.path === `/api/v1/run/${api.id}` && typeof api.invocation.authentication === "string" && typeof api.invocation.idempotencyHeader === "string" && typeof api.invocation.resultPath === "string";
+}
+export function validateApi(api: unknown, inspection: true): ApiInspection;
+export function validateApi(api: unknown, inspection?: false): DataApi;
+export function validateApi(api: unknown, inspection = false): DataApi | ApiInspection {
+  if (inspection) { if (!isInspection(api)) invalid("API inspection"); return api; }
+  if (!isApi(api)) invalid("data API");
+  return api;
+}
+function isCatalog(result: unknown): result is ApiCatalog {
+  return isObject(result) && count(result.schemaVersion) && result.layer === "data_apis" && Array.isArray(result.apis) && result.apis.every(isApi) &&
+    count(result.total) && result.total === result.apis.length && count(result.catalogTotal) && result.catalogTotal >= result.total &&
+    Array.isArray(result.categories) && result.categories.every(category => isObject(category) && typeof category.id === "string" && count(category.count));
+}
+export function validateCatalog(result: unknown): ApiCatalog {
+  if (!isCatalog(result) || new Set(result.apis.map(api => api.id)).size !== result.apis.length) invalid("data catalog");
+  return result;
+}
+function isRequest(result: unknown): result is SoritRequest {
+  if (!isObject(result) || !validId(result.request_id) || !(result.api_id === null || validId(result.api_id)) ||
+    typeof result.status !== "string" || !["queued", "running", "succeeded", "failed", "rejected"].includes(result.status) || !isObject(result.credits) ||
+    !finite(result.credits.charged) || !finite(result.credits.refunded) || result.credits.refunded > result.credits.charged || !Object.hasOwn(result, "data") || !Object.hasOwn(result, "error")) return false;
+  if (!["failed", "rejected"].includes(result.status)) return result.error === null;
+  const error = result.error;
+  return isObject(error) && typeof error.code === "string" && typeof error.message === "string" && (error.fields === undefined || Array.isArray(error.fields) &&
+    error.fields.every(field => isObject(field) && Array.isArray(field.path) && field.path.every(part => typeof part === "string" || typeof part === "number") && typeof field.message === "string"));
+}
+export function validateRequest(result: unknown, expectedId?: string): SoritRequest {
+  if (!isRequest(result) || expectedId !== undefined && result.request_id !== expectedId) invalid("request");
+  return result;
+}
+export function identifier(value: unknown, label: string): string {
+  if (!validId(value)) throw new Error(`Supply a valid ${label}.`);
+  return value;
+}
+export function filters({ q = "", tool = "", page = 1, status = "available" }: CatalogFilters = {}) {
+  const pageNumber = Number(page);
+  if (typeof q !== "string" || q.length > 200) throw new Error("Search must be at most 200 characters.");
+  if (typeof tool !== "string" || tool.length > 100) throw new Error("Supply a valid tool ID.");
+  if (!Number.isSafeInteger(pageNumber) || pageNumber < 1 || pageNumber > 10000) throw new Error("--page must be an integer between 1 and 10000.");
+  if (status !== "available") throw new Error("Discovery only returns available APIs.");
+  return { q, tool, page: pageNumber };
+}
+export const platformId = (value: string) => value.replaceAll("_", "-");
+export const searchTerms = (value: string) => value.toLowerCase().trim().split(/\s+/).filter(Boolean);
+export const apiSearchText = (api: DataApi) => `${api.id} ${api.platform} ${api.category} ${typeof api.title === "string" ? api.title : Object.values(api.title).join(" ")} ${typeof api.description === "string" ? api.description : Object.values(api.description).join(" ")}`.toLowerCase();
+const platformNames: Record<string, string> = { "tiktok-shop": "TikTok Shop", tiktok: "TikTok", twitter: "X / Twitter", linkedin: "LinkedIn", facebook: "Facebook", instagram: "Instagram", reddit: "Reddit", douyin: "Douyin", xiaohongshu: "Xiaohongshu", weibo: "Weibo", amazon: "Amazon", google: "Google Search", "google-ads": "Google Ads", similarweb: "Similarweb", semrush: "Semrush", web: "Web Content", "trade-data": "Trade Data", logistics: "Shipping" };
+export function catalogTools(apis: DataApi[], query: string): Tool[] {
+  const groups = new Map<string, Omit<Tool, "apiCount"> & { apis: DataApi[] }>();
+  for (const api of apis) {
+    const id = platformId(api.platform), tool = groups.get(id) ?? { id, platform: api.platform, name: platformNames[id] ?? api.platform, apis: [] };
+    tool.apis.push(api); groups.set(id, tool);
+  }
+  const terms = searchTerms(query);
+  return [...groups.values()].filter(tool => terms.every(term => `${tool.id} ${tool.name} ${tool.apis.map(apiSearchText).join(" ")}`.toLowerCase().includes(term)))
+    .map(({ apis: children, ...tool }) => ({ ...tool, apiCount: children.length }));
+}

package/src/output.ts

@@ -0,0 +1,122 @@
+/** Terminal presentation, separate from the REST response envelopes. */
+import { localized, isObject, validateRequest } from "./contracts";
+import type { ApiDiscovery, ApiInspection, Balance, CommandName, CommandResults, DataApi, SoritRequest, ToolListing } from "./types";
+const number = (value: number) => new Intl.NumberFormat("en-US", { maximumFractionDigits: 6 }).format(value);
+const usd = (value: number) => new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", minimumFractionDigits: 2, maximumFractionDigits: 6 }).format(value);
+const text = (value: unknown) => String(value ?? "").replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+const json = (value: unknown) => JSON.stringify(value, null, 2);
+const indent = (value: unknown) => String(value).split("\n").map(line => `  ${line}`).join("\n");
+const heading = (label: string, body: unknown) => `  ${label}: ${text(body)}`;
+const next = (command: string) => `  Next: ${command}`;
+const creditPrice = (api: DataApi) => {
+  const credits = api.pricing?.credits;
+  if (typeof credits !== "number") return "Price unavailable";
+  return `${number(credits)} credits / ${api.pricing?.unit ?? "request"}`;
+};
+
+export function balanceSummary(result: unknown): Balance {
+  if (!isObject(result) || 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: DataApi[]) {
+  return apis.map(api => [
+    `  ${text(localized(api.title) || api.id)}`,
+    `    ${creditPrice(api)}`,
+    `    ID: ${text(api.id)}`,
+  ].join("\n")).join("\n\n");
+}
+
+function discover(result: ApiDiscovery) {
+  const apis = result.apis;
+  const total = result.total ?? apis.length;
+  if (!apis.length) return result.total > 0 ? `No APIs on page ${result.page}.\n\n  ${number(result.total)} APIs match; choose a page from 1 to ${Math.ceil(result.total / result.pageSize)}.` : "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: ApiInspection) {
+  const title = localized(result.title) || result.id, description = localized(result.description);
+  const lines = [
+    `  ${text(title)}`,
+    ...(description.trim() && description.trim() !== title.trim() ? [indent(text(description))] : []),
+    [
+      heading("ID", result.id),
+      heading("Status", result.status),
+      heading("Endpoint", `${result.invocation.method} ${result.invocation.path}`),
+      heading("Price", creditPrice(result)),
+      ...(result.limits?.maxItems != null ? [heading("Maximum items", result.limits.maxItems)] : []),
+    ].join("\n"),
+    ...(result.inputSchema ? ["  Input schema:\n" + indent(json(result.inputSchema))] : []),
+    ...(result.outputSchema ? ["  Output schema:\n" + indent(json(result.outputSchema))] : []),
+    next(`sorit run ${text(result.id)} --input @input.json --idempotency-key <unique-key> --wait`),
+  ];
+  return lines.join("\n\n");
+}
+
+function requestResult(result: SoritRequest) {
+  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: Record<string, string> = {
+  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.",
+  RATE_LIMITED: "Wait before retrying. Keep the same input and idempotency key when resubmitting.",
+  SERVICE_TIMEOUT: "The data service timed out. Check this request before creating another one.",
+};
+function errorDetails(error: unknown): string {
+  const detail = isObject(error) ? error : {};
+  const code = text(typeof error === "string" ? error : detail.code).toUpperCase();
+  const message = text(typeof error === "string" ? code === "UNAUTHORIZED" ? "Authentication failed." : error : detail.message || detail.code || "Request failed.");
+  const fields = Array.isArray(detail.fields) ? detail.fields.filter(isObject).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: unknown): string {
+  const detail = isObject(error) ? error : {}, result = isObject(detail.result) ? detail.result : undefined;
+  if (result?.request_id && result.status) {
+    try { return requestResult(validateRequest(result)); } catch { /* An invalid error envelope still gets a readable message. */ }
+  }
+  return `✖ ${errorDetails(result?.error ?? detail.message ?? "Request failed.").trimStart()}`;
+}
+
+function tools(result: ToolListing): string {
+  if (!result.tools.length) return "No available tools found.\n\n  Try broader keywords or run sorit tools without filters.";
+  return [
+    `✔ ${number(result.total)} available tool${result.total === 1 ? "" : "s"} found`,
+    result.tools.map(tool => `  ${text(tool.name)}\n    ${number(tool.apiCount)} APIs\n    ID: ${text(tool.id)}`).join("\n\n"),
+    next(`sorit discover --tool ${text(result.tools[0].id)}`),
+  ].join("\n\n");
+}
+const renderers: { [K in CommandName]: (result: CommandResults[K]) => string } = {
+  tools, discover, inspect, run: requestResult, get: requestResult,
+  balance: result => `✔ Balance retrieved\n\n  Balance: ${usd(result.balanceUsd)} USD\n  Credits: ${number(result.balance)}`,
+};
+export function formatResult<K extends CommandName>(command: K, result: CommandResults[K]): string {
+  return renderers[command](result);
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+export type JsonObject = Record<string, unknown>;
+export type LocalizedText = string | { en?: string; zh?: string };
+export type DataApi = {
+  id: string; platform: string; category: string; title: LocalizedText; description: LocalizedText; status: "available";
+  pricing: { currency: "USD"; amount: number; credits: number; unit: "request" | "record"; confirmed: true; failureRefund: true };
+  limits: { maxItems: number }; path: string;
+};
+export type ApiInspection = DataApi & {
+  inputSchema: JsonObject; outputSchema: JsonObject;
+  invocation: { method: "POST"; path: string; authentication: string; idempotencyHeader: string; resultPath: string };
+  requestProtocol: JsonObject;
+};
+export type ApiCatalog = {
+  schemaVersion: number; layer: "data_apis"; total: number; catalogTotal: number; apis: DataApi[];
+  categories: { id: string; count: number }[];
+};
+export type ApiDiscovery = ApiCatalog & { page: number; pageSize: number };
+export type Tool = { id: string; platform: string; name: string; apiCount: number };
+export type ToolListing = { schemaVersion: number; layer: "tools"; total: number; tools: Tool[] };
+export type RequestStatus = "queued" | "running" | "succeeded" | "failed" | "rejected";
+export type RequestError = { code: string; message: string; fields?: { path: (string | number)[]; message: string }[] };
+export type SoritRequest = {
+  request_id: string; api_id: string | null; status: RequestStatus;
+  credits: { charged: number; refunded: number }; data: unknown; error: RequestError | null;
+};
+export type Balance = { balance: number; creditsPerUsd: number; balanceUsd: number; currency: "USD" };
+export type CatalogFilters = { q?: string; tool?: string; page?: number | string; status?: string };
+export type CommandResults = { tools: ToolListing; discover: ApiDiscovery; inspect: ApiInspection; run: SoritRequest; get: SoritRequest; balance: Balance };
+export type CommandName = keyof CommandResults;

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/src/client.mjs

@@ -1,68 +0,0 @@
-/** 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

@@ -1,120 +0,0 @@
-/** 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);
-}