Skip to content
WarmHub

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, live feeds, and homepage.

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

Section titled “Installation”

See the Quickstart for full install instructions. In short:

Terminal window
npm install @warmhub/sdk-ts

Runtime requirement: Node.js 22 or later is required.

Client Setup

Section titled “Client Setup”

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

Terminal window
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 },
})

The SDK does not read environment variables itself — read WH_TOKEN in your own code and pass it to getToken. See Environment Variables for the variables the CLI honors.

Client Options

Section titled “Client Options”
OptionTypeDescription
auth.getToken() => Promise<string | undefined>Token acquisition hook — required for authenticated endpoints
accessTokenstring | () => string | undefined | Promise<string | undefined>Static token or sync/async provider (alternative to auth.getToken)
apiUrlstringOverride the API URL (defaults to https://api.warmhub.ai)
fetchtypeof fetchCustom fetch implementation
functionLogs'raw' | 'off'Server function log forwarding (defaults to 'off')
client.namestringIdentify requests from your SDK wrapper by name (useful when building a higher-level client on top of @warmhub/sdk-ts)
client.versionstringIdentify requests from your SDK wrapper by version (useful when building a higher-level client on top of @warmhub/sdk-ts)

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

API Reference

Section titled “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

Section titled “Permission Checks”

The client.access surface exposes resolve(input), which returns an AccessResolveResult describing the resolved permissions for the given input. AccessResolveInput accepts optional repos and orgs arrays — repos entries are keyed by orgName and repoName, orgs entries by orgName. The result contains repos[] and orgs[] entries, each with a visible boolean and a scopes array listing the granted permission scopes (repo scopes are repo:read, repo:write, repo:configure, and repo:admin).

For example, to check whether the current token has access to a specific repo:

const result = await client.access.resolve({
  repos: [{ orgName: 'acme', repoName: 'world' }],
})


const repoAccess = result.repos?.[0]
if (repoAccess?.visible) {
  const canWrite = repoAccess.scopes.includes('repo:write')
  // proceed based on canWrite
}

Like all SDK methods, resolve throws WarmHubError on network, backend, or auth failures. 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

Section titled “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 ARCHIVED, SHAPE_MISMATCH, and WREF_UNRESOLVABLE.

Structured Conflict Details

Section titled “Structured Conflict Details”

When a non-streaming write fails with err.kind === 'CONFLICT', the error may carry a structured details payload (WarmHubErrorDetails) that describes the conflict. Use isWarmHubError() to inspect it:

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


try {
  await client.commit.apply(/* ... */)
} catch (err) {
  if (isWarmHubError(err) && err.kind === 'CONFLICT') {
    const details = err.details
    // details contains structured backend conflict metadata;
    // use it to re-read HEAD and build a retry write
  }
  throw err
}

err.details is typed as WarmHubErrorDetails and is undefined when the backend did not return structured conflict metadata. Not all CONFLICT errors include details — always guard with a nullish check before reading fields.

For streamed writes via client.commit.apply(), the normal all-failed conflict path surfaces differently: the SDK throws AllStreamOperationsFailedError, and the structured conflict payload lives on each operation row’s error.details within the SubmittedStreamResult. See Write Methods for the result-level contract.

Next Steps

Section titled “Next Steps”