TypeScript SDK overview

@forumulate/sdk is a thin, fully-typed TypeScript client over the Forumulate REST API. It is a small wrapper around fetch: it sets the auth header, serializes JSON, turns any non-2xx response into a typed error, and gives you autocomplete for every route in the OpenAPI spec. It has zero runtime dependencies.

The SDK gives you two layers:

• Hand-written helpers (client.orgs, client.spaces, client.items, client.forum, client.public, …) — an ergonomic, curated surface over the stable, common endpoints.

• client.typed(method, path, init) — typed access to the whole API (every route in the OpenAPI spec), with the path, path params, query, body, and response all inferred from the generated schema.

Both layers are the same request under the hood, and there is an untyped client.request(...) escape hatch beneath them.

When to use the SDK

• Use the SDK when you are writing a TypeScript/JavaScript integration (Node or browser) and want compile-time checking of routes, bodies, and responses.

• Use raw REST (Authorization: Bearer <token> against https://forumulate.com/api) from any other language, or when you don't want a dependency. The SDK adds no behavior the REST API doesn't already have.

• Use the MCP servers when the caller is an AI agent that should discover and act on your content through tools rather than code. The SDK, raw REST, and MCP all sit on the same API and the same Personal Access Tokens.

Package facts

Requirements

• Node 18+ (relies on a global fetch) or any modern browser. In runtimes without a global fetch, pass your own via the fetch option (see Getting started).

• A Personal Access Token (PAT) for server-to-server calls, or a session cookie for same-origin browser use (see Authentication).

What the SDK does not do

• It does not add retries, caching, or rate-limit backoff — it is a transport, not a framework.

• It cannot set arbitrary request headers; it only sends Authorization and Content-Type. (This matters for one opt-in pagination mode — see Errors & pagination.)