@warmhub/sdk-ts weekly downloads statistics

<p align="center"> <img src="https://warmhub.ai/logo-light.svg" width="200" alt="WarmHub logo"> </p>

@warmhub/sdk-ts

TypeScript SDK for WarmHub.

📖 Full docs: docs.warmhub.ai/sdk/overview/ · API reference: docs.warmhub.ai/sdk-reference/readme/ · Release notes: docs.warmhub.ai/sdk/typescript/changelog/

Upgrading

CHANGELOG.md ships inside this package. It is migration-guide style: every breaking change is written as what it was, what it is now, and the exact edit with before/after code. Read it before a version bump.

# Installed copy, offline:
cat node_modules/@warmhub/sdk-ts/CHANGELOG.md

It is also browsable on the npm page under Code → CHANGELOG.md.

Install

npm install @warmhub/sdk-ts

Node 22 callers verify downloaded repository checkpoints through the isolated subpath. The verifier consumes caller-supplied bytes and performs no fetch or WarmHub authentication:

import { createReadStream } from 'node:fs'
import { verifyRepositoryCheckpointArchive } from '@warmhub/sdk-ts/checkpoint'

const result = await verifyRepositoryCheckpointArchive(
  createReadStream('repository-checkpoint.zip'),
)

Get a Token

The WH_TOKEN used below is a personal access token. Mint one with the WarmHub CLI:

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

See Personal Access Tokens for scopes, rotation, and CI usage.

Quickstart

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

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

// One-time setup. Skip these three calls (or catch CONFLICT) on re-runs.
await client.org.create('acme')
await client.repo.create('acme', 'world', 'Game world')
await client.shape.create(
  'acme',
  'world',
  'Location',
  { x: 'number', y: 'number', label: 'string' },
  { eventRequestId: crypto.randomUUID() },
)

await client.commit.apply(
  'acme',
  'world',
  'seed cave',
  client.ops().add('cave', {
    shapes: ['Location'],
    data: { x: 0, y: 0, label: 'Dark Cave' },
  }),
)

const head = await client.thing.head('acme', 'world', { shape: 'Location' })

For the connect-and-read flow without setup, see the Quickstart. For reference on shapes, things, and writes, see Data Modeling.

Function Logs

Backend function console.* lines are suppressed by default. SDK consumers can opt into log replay for debugging:

const client = new WarmHubClient({
  auth: { getToken: async () => process.env.WH_TOKEN },
  functionLogs: 'raw',
})

Entrypoints

• @warmhub/sdk-ts: core client, types, errors, OperationBuilder (client.ops())

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)) {
    // retry strategy
  }
  throw err
}

Writing

A write names a Thing by its full name (taken literally, / included) and states its Shapes. Build writes with client.ops(); every add and revise states its Shapes in exactly one way, or the builder throws a WriteOperationError (VALIDATION_ERROR, with operationIndex) before any request:

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

const ops = client
  .ops()
  .add('acme', { shapes: ['Deal'], data: { company: 'Acme' } })
  .add('scratch', { shapeless: true, data: { note: 'free' } })
  .revise('acme', { shapes: ['Deal'], data: { company: 'Acme 2' } })
  .add('r1', { shapes: ['Rating'], data: { about: 'acme', score: 5 } })
  .add('crew', { shapes: ['Set'], data: { members: ['acme'] } })
  .rename('scratch', 'scratch-2')
  .retract('crew', { reason: 'disbanded' })
  // A Shape is the Thing hub/shapes/X, written with shapes: [].
  .add(shapeName('Deal'), { shapes: [], data: { fields: { company: 'string' } } })

await client.commit.apply('acme', 'world', 'seed', ops)

commit.apply, commit.validate and commit.applyStreaming also take plain WriteOperation[] ({ operation: 'add', name, shapes, data }). A v1-shaped operation (kind, Shape/name adds, top-level about, collection type/members) is refused, and the error shows its v2 form. Raw v1 input from typed TypeScript needs a cast: the v1 types are gone.

• An assertion (r1 above) is a Thing one of whose declared Shapes composes Assertion, with its target in data.about.
• shapes: ['Deal', 'Contactable']: bare Shape names. A pin (Deal@v2) is refused: a write always certifies under each Shape's head version.
• shapeless: true (builder option): no Shape; the data is stored but not validated, and the operation result carries warnings.shapeless. A raw operation spells it shapes: []. A Shape (hub/shapes/X) is written with shapes: [], never shapeless.
• keepShapes: true (revise only): the SDK reads the Thing's current Shapes and version and sends both, the version as expectedVersion (a supplied expectedVersion wins). A Thing revised earlier in the same submission carries that revise's Shapes and no version; one added, or renamed to or from, earlier in the same submission is refused before anything is sent (submit it in a later request, or pass shapes). keepShapes pins the version it read; a cross-process resubmit of the same submissionId can conflict; explicit shapes is the retry-safe form. The Shapes are sent bare, so the revise re-certifies under each Shape's head version.…