SDK Overview

The @warmhub/sdk-ts package is the typed TypeScript client for WarmHub. It provides promise-based methods for managing organizations and repositories, reading and writing repository data, and accessing the rest of the WarmHub surface — auth, access checks, commits, components, subscriptions, actions, tokens, credentials, diagnostics, and live feeds.

WarmHub data is modeled as things (versioned named entities), assertions (claims about things), and shapes (schemas that define the structure of both). If those terms are new, skim Core Concepts before continuing.

Installation

See the Quickstart for full install instructions. In short:

npm install @warmhub/sdk-ts

Client Setup

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

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

Then create a client:

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

const client = new WarmHubClient({
  auth: { getToken: async () => process.env.WH_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')

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

API Reference

The SDK groups calls into typed client surfaces such as client.repo, client.thing, and client.commit. The generated WarmHubClient API reference is the reference for method signatures and per-method descriptions.

Use Client Surfaces for a narrative map of the surfaces and the SDK concept pages for behavior shared across methods, such as read semantics, repo statistics, commit retries, and component identity.

Permission Checks

The client.access surface has lightweight permission checks for frontend UI gating. They return boolean on success. Like all SDK methods, they throw WarmHubError on network, backend, or auth failures.

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

These checks use the same credentials as the rest of the client; auth and network errors surface the same way as other SDK methods.

Error Handling

Most SDK methods throw WarmHubError on failure. Streamed writes (client.commit.apply() and OperationBuilder.commit()) may instead throw PartialStreamSubmissionError for ambiguous append outcomes or AllStreamOperationsFailedError when every submitted operation is rejected with per-op failure data — see Streaming Write Failures. 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
}

See the ErrorKind reference for the full per-kind cause, retryability, and corrective action. Common error kinds: NOT_FOUND, VALIDATION_ERROR, CONFLICT, UNAUTHENTICATED, FORBIDDEN, RATE_LIMITED, CANCELLED, NETWORK, BACKEND. Backend domain codes can also pass through unchanged in err.code and err.kind, including UNRESOLVED_TOKEN, ARCHIVED, SHAPE_MISMATCH, and WREF_UNRESOLVABLE.

Next Steps

• SDK Quickstart — install, create a client, and write your first thing
• Client Surfaces — narrative map of the main client surfaces
• WarmHubClient API reference — auto-generated TypeDoc for the main @warmhub/sdk-ts client class
• Write Methods — choose the write API that fits the call site
• Transient Retry — retry and partial-submission behavior for SDK writes
• Read Semantics — filters, glob match, search modes, batch reads, anonymous pagination
• Repo Statistics — exact counts vs dashboard metadata vs per-shape breakdowns
• Component Identity — how componentId attribution works for component-installed records
• CLI Quickstart — terminal-first approach
• MCP Server — agent integration via Model Context Protocol