@warmhub/sdk-ts weekly downloads statistics

@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.

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

Install

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

Get a Token

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

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

Quickstart

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:

Entrypoints

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

Error Handling

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:

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.

A builder can also submit itself with ops.commit({ client, orgName, repoName }). Either way it is single-use: once submitted it is sealed. Every local refusal, per operation or for the whole batch ("already submitted", "in flight"), is a WriteOperationError with code VALIDATION_ERROR unless it names another; operationIndex is unset for a whole-batch one.

legacy-wrefs: the SDK is v2-only. With clientFlags: ['legacy-wrefs'] it refuses every call, read or write, before any request (the compatibility probe included) with LEGACY_WREFS_REFUSAL. To write v1 during the compatibility window, use the wh CLI.

API Docs

Generated API reference is published at docs.warmhub.ai/sdk-reference/readme/ — the landing page lists every public class, interface, type alias, variable, and function exported from the main @warmhub/sdk-ts entrypoint.