@sorit/cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,49 @@
-# 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.
+
+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: 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. 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
+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 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. `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,6 +1,26 @@
 {
   "name": "@sorit/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Discover and call Sorit data APIs from your terminal or AI agent",
+  "type": "module",
+  "bin": {
+    "sorit": "src/cli.ts"
+  },
+  "files": [
+    "src/*.ts",
+    "tsconfig.json",
+    "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"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,164 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { SoritClient, SoritError } from "./client";
+import { balanceSummary, formatError, formatResult } from "./output";
+import { isObject } from "./contracts";
+import type { CommandName, CommandResults } from "./types";
+
+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." },
+  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." },
+};
+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"],
+    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 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 '{"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: 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?: 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): [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."],
+    ])),
+    "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");
+}
+
+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: {
+    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 [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.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);
+    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 };
+    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;
+      }
+    }
+  }
+} catch (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"]
+}