SDK Overview

The @warmhub/sdk-ts package is the typed TypeScript client for WarmHub. It provides promise-based methods for managing organizations, repositories, and data (shapes, things, assertions). It also covers commits, workspaces, changesets, subscriptions, actions, and diagnostics.

Installation

See the SDK Quickstart for full install instructions. In short:

npm install @warmhub/sdk-ts

react is an optional peer dependency — only needed if you use @warmhub/sdk-ts/react.

Client Setup

Install the WarmHub CLI, then create a personal access token and export it as WARMHUB_TOKEN:

wh auth login
wh token create --name my-app
export WARMHUB_TOKEN=eyJhbGciOi...

Then create a client:

import { WarmHubClient } from '@warmhub/sdk-ts'

const client = new WarmHubClient({
  auth: { getToken: async () => process.env.WARMHUB_TOKEN },
})

Client Options

Option	Type	Description
auth.getToken	() => Promise<string | undefined>	Token acquisition hook — required for authenticated endpoints
accessToken	string | () => string | undefined | Promise<string | undefined>	Static token or sync/async provider (alternative to auth.getToken)
apiUrl	string	Override the API URL (defaults to https://api.warmhub.ai)
fetch	typeof fetch	Custom fetch implementation
functionLogs	'raw' | 'off'	Server function log forwarding (defaults to 'off')

Entrypoints

Import path	Description
@warmhub/sdk-ts	Core client, types, errors, CommitBuilder
@warmhub/sdk-ts/react	React provider and hooks for WarmHubClient and backend-ready auth state
@warmhub/sdk-ts/advanced	Low-level AdvancedClient with WebSocket subscriptions
@warmhub/sdk-ts/test	Test utilities (canonicalDataHash, validateAgainstShape)

For a comparison of when to use the SDK vs the CLI or MCP, see How to Get Started.

Surfaces at a Glance

A surface is a property on the client that groups related methods for a domain (e.g., client.thing for reading things and assertions).

Surface	Description	Key Methods
client.org	Organization management	list(), get(), create(), getOrCreate(), addMember(), removeMember(), listMembers(), changeMemberRole(), archive(), unarchive()
client.repo	Repository management	list(), get(), create(), resolve(), archive(), unarchive()
client.shape	Schema definitions	list(), get(), create(), revise(), remove()
client.thing	Read things and assertions	head(), get(), query(), about(), refs(), resolve(), search(), history(), count()
client.commit	Atomic writes	apply(), log()
client.workspace	Workspace isolation	create(), list(), get(), remove(), status(), validate(), rebase(), revert(), discard()
client.changeset	Changeset review	publish(), list(), get(), accept(), reject(), withdraw(), validate()
client.subscription	Webhook/sprite subscriptions	create(), update(), list(), get(), pause(), resume(), remove()
client.actions	Action lease coordination	acquireLease(), claimDelivery(), completeDelivery(), liveFeed()
client.diagnostics	Health and capabilities	ping(), capabilities()

Permission Checks

Two lightweight access methods are available for frontend UI gating. They return boolean on success. Like all SDK methods, they throw WarmHubError on network, backend, or auth failures.

Method	Args	Description
client.access.checkRepoPermission	orgName, repoName, permission	Check whether the caller has a repo-scoped permission (e.g., "things:write")
client.access.checkOrgPermission	orgName, permission	Check whether the caller has an org-scoped permission

const canWrite = await client.access.checkRepoPermission(
  'acme',
  'world',
  'things:write',
)

The React app wraps these with TanStack Query hooks. Under the hood they use the same auth and permission resolution as the rest of the WarmHub API.

Error Handling

All SDK methods throw WarmHubError on failure. Use isWarmHubError() and isRetryable() for error handling:

import { isRetryable, isWarmHubError } from '@warmhub/sdk-ts'

try {
  await client.repo.get('acme', 'world')
} catch (err) {
  if (isWarmHubError(err) && err.kind === 'NOT_FOUND') {
    // handle missing repo
  }
  if (isRetryable(err)) {
    // safe to retry (NETWORK, CANCELLED, BACKEND, RATE_LIMITED)
  }
  throw err
}

Error kinds: NOT_FOUND, VALIDATION, CONFLICT (includes ALREADY_EXISTS and ARCHIVED), UNAUTHENTICATED, FORBIDDEN, RATE_LIMITED, CANCELLED, NETWORK, BACKEND.

Next Steps

• SDK Quickstart — install, create a client, and write your first commit
• Client Surfaces — method reference for all ten client surfaces
• API Reference — auto-generated TypeDoc reference for all types
• CLI Quickstart — terminal-first approach
• MCP Server — agent integration via Model Context Protocol