Quickstart: SDK

This guide walks you through installing @warmhub/sdk-ts, creating a client, and writing your first data programmatically.

Install the SDK

The SDK is currently published to GitHub Packages. You’ll need a GitHub personal access token (classic) with read:packages scope — create one here. Set it as GITHUB_TOKEN in your environment, then configure npm:

echo "@warmhub:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc

Note: This GITHUB_TOKEN is only for downloading the package from GitHub’s npm registry. It is separate from the WarmHub API token you’ll create in step 1 below. Make sure .npmrc is in your .gitignore to avoid committing the token.

npm install @warmhub/sdk-ts

1. Create a Token

You need the WarmHub CLI and a personal access token to authenticate. Log in and create one:

wh auth login
wh token create --name my-script

Save the printed token — it’s shown only once. Export it as WARMHUB_TOKEN:

export WARMHUB_TOKEN=eyJhbGciOi...

2. Create a Client

import { WarmHubClient } from "@warmhub/sdk-ts";

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

3. Create an Organization and Repository

const org = await client.org.create("myorg");
const repo = await client.repo.create("myorg", "world", "My first repo");

4. Create a Shape

Shapes define the structure of your data:

await client.shape.create("myorg", "world", "Location", {
  x: "number",
  y: "number",
  label: "string",
});

5. Add a Thing via Commit

All data writes go through commits. Add a thing named cave under the Location shape:

const result = await client.commit.apply("myorg", "world", "sdk", "Add first location", [
  {
    operation: "add",
    kind: "thing",
    name: "Location/cave",
    data: { x: 3, y: 7, label: "Dark Cave" },
  },
]);

6. View HEAD (Latest State)

See all active things in the repository:

const head = await client.thing.head("myorg", "world");
console.log(head.items);

7. Query by Shape

Retrieve things filtered by shape:

const locations = await client.thing.head("myorg", "world", {
  shape: "Location",
});
console.log(locations.items);

8. Use CommitBuilder

For multi-operation commits with client-side validation, use CommitBuilder:

import { CommitBuilder } from "@warmhub/sdk-ts";

const cb = new CommitBuilder();
cb.add({ name: "Location/forest", data: { x: 5, y: 2, label: "Dense Forest" } });
cb.add({ name: "Location/river", data: { x: 1, y: 9, label: "Wide River" } });

const result = await cb.commit({
  client,
  orgName: "myorg",
  repoName: "world",
  author: "sdk",
  message: "Add more locations",
});

CommitBuilder is single-use: after a successful commit(), the builder is sealed and cannot be modified or reused.

9. Error Handling

WarmHubClient methods throw WarmHubError on failure. (CommitBuilder throws standard Error for validation and lifecycle issues.)

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;
}

Next Steps

• SDK Overview — client options, entrypoints, and error kinds
• Client Surfaces — method reference for all ten client surfaces
• Core Concepts — the mental model behind orgs, repos, shapes, things, assertions, and commits
• Data Modeling — learn about wrefs, shapes, things, and assertions in detail
• API Reference — auto-generated TypeDoc reference for all types