TypeScript SDK

A single dependency-free file that wraps the REST API in typed calls.

The TypeScript client is one dependency-free source file over the REST API. It runs anywhere fetch exists: Node 18+, Deno, Bun, Cloudflare Workers and modern browsers.

Install the source#

Download the exact file exercised by Omniio's test suite:

bash

curl -O https://omniio.dev/sdk/omniio.ts

Import it from wherever you saved it:

import { Omniio, OmniioError } from "./omniio";
const omniio = new Omniio({
  apiKey: process.env.OMNIIO_API_KEY!,
});

The API supports browser CORS, but a key embedded in front-end code is a published credential. Use the client from a server, worker or local script unless the person running the browser supplies their own short-lived copy.

Options#

apiKeystring · required: An `omn_…` key created in Settings.
baseUrlstring: Defaults to `https://omniio.dev/api/v1`; override it for a local or test deployment.
fetchtypeof fetch: Inject a bound runtime fetch or a test double.
maxRetriesinteger · default 3: How many 429 responses to wait out. Set zero to surface the first one.

On 429 the client obeys Retry-After, adds one second for clock-boundary skew, and repeats until the retry budget is spent. It does not guess an exponential delay when the server has already stated the reset.

Methods#

activity(params?)Promise<ActivityPage>: One newest-first page. Accepts limit, cursor and client.
activityAll(params?)AsyncGenerator<ToolCall>: Walks cursor pages through the whole retained window without loading them all into memory.
servers(params?)Promise<Server[]>: The resolved library, optionally filtered by status or category.
server(slug)Promise<Server>: One server by slug.
setServerEnabled(slug, enabled)Promise<Server>: Switch a credential-free server and return its new resolved state.
tools(params?)Promise<Tool[]>: One offset page of qualified tools; accepts server, limit, offset and schema.
toolsAll(params?)AsyncGenerator<Tool>: Walks the tool catalogue to its end.
usage()Promise<Usage>: The current pooled or solo usage snapshot.
clients(params?)Promise<Client[]>: Connections, optionally filtered by active state.

Stream a retained export#

The *All methods are async iterators rather than arrays. A busy retention window can contain millions of rows with payloads; the iterator keeps memory bounded to one page.

for await (const call of omniio.activityAll({ limit: 200 })) {
  await warehouse.write(call);
}

Handle failures#

Every non-success becomes OmniioError, carrying the HTTP status, stable code, readable message, and retryAfter for a rate-limit failure.

try {
  await omniio.setServerEnabled("github", true);
} catch (error) {
  if (error instanceof OmniioError && error.code === "invalid_request") {
    console.error("That server needs a credential connected in the app.");
  } else {
    throw error;
  }
}

Next: Webhooks.