@warmhub/sdk-ts 0.44.0

package/README.md

@@ -0,0 +1,111 @@
+# @warmhub/sdk-ts
+
+TypeScript SDK for WarmHub.
+
+📖 **Full docs:** [docs.warmhub.ai/sdk/overview/](https://docs.warmhub.ai/sdk/overview/) · **API reference:** [docs.warmhub.ai/sdk-reference/readme/](https://docs.warmhub.ai/sdk-reference/readme/)
+
+## Install
+
+```bash
+npm install @warmhub/sdk-ts
+```
+
+## Get a Token
+
+The `WH_TOKEN` used below is a personal access token. Mint one with the [WarmHub CLI](https://docs.warmhub.ai/get-started/quickstart/#connect-via-cli):
+
+```bash
+wh auth login
+wh token create --name my-app
+export WH_TOKEN=eyJhbGciOi...
+```
+
+See [Personal Access Tokens](https://docs.warmhub.ai/auth/personal-access-tokens/) for scopes, rotation, and CI usage.
+
+## Quickstart
+
+```ts
+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',
+})
+
+await client.commit.apply('acme', 'world', 'seed cave', [
+  {
+    operation: 'add',
+    kind: 'thing',
+    name: 'Location/cave',
+    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](https://docs.warmhub.ai/get-started/quickstart/#connect-via-sdk). For reference on shapes, things, and writes, see [Data Modeling](https://docs.warmhub.ai/data-modeling/wrefs/).
+
+## Function Logs
+
+Backend function `console.*` lines are suppressed by default. SDK consumers can
+opt into log replay for debugging:
+
+```ts
+const client = new WarmHubClient({
+  auth: { getToken: async () => process.env.WH_TOKEN },
+  functionLogs: 'raw',
+})
+```
+
+## Entrypoints
+
+- `@warmhub/sdk-ts`: core client, types, errors, `OperationBuilder`
+
+## Error Handling
+
+```ts
+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
+}
+```
+
+## OperationBuilder
+
+`OperationBuilder` is single-use: after a successful `commit()`, the builder
+is sealed and cannot be modified or reused.
+
+```ts
+import { OperationBuilder } from '@warmhub/sdk-ts'
+
+const ob = new OperationBuilder()
+ob.add({ name: 'Location/cave', data: { x: 0, y: 0 } })
+const result = await ob.commit({
+  client,
+  orgName: 'acme',
+  repoName: 'world',
+  message: 'seed cave',
+})
+```
+
+## API Docs
+
+Generated API reference is published at [docs.warmhub.ai/sdk-reference/readme/](https://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.