tila-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dawid Leszczyński (@davebream)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,318 @@
+# tila-sdk
+
+TypeScript SDK for [tila](https://github.com/davebream/tila) -- a state-and-coordination engine for multi-machine agentic work.
+
+## Installation
+
+```bash
+npm install tila-sdk
+```
+
+`zod` is an optional peer dependency. Install it to enable opt-in response validation:
+
+```bash
+npm install zod
+```
+
+## Quick Start
+
+```typescript
+import { TilaClient, createEntityMethods } from "tila-sdk";
+
+const client = new TilaClient({
+  baseUrl: process.env.TILA_URL!,
+  token: process.env.TILA_TOKEN!,
+});
+
+const projectId = "my-project";
+const entities = createEntityMethods(client, projectId);
+
+// Create an entity
+const task = await entities.create("task-1", "task", {
+  title: "Process dataset",
+  status: "pending",
+});
+
+// Read it back
+const detail = await entities.get("task-1");
+
+// List entities by type
+const list = await entities.list({ type: "task" });
+
+// Update with new data
+const updated = await entities.update("task-1", {
+  status: "in-progress",
+  assignee: "agent-7",
+});
+
+// Archive when done
+await entities.archive("task-1");
+```
+
+### Constructor Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | `string` | (required) | tila Worker URL |
+| `token` | `string` | (required) | API token or session token |
+| `validate` | `boolean` | `false` | Enable Zod response validation (requires `zod` installed) |
+| `timeoutMs` | `number` | `30000` | Request timeout in milliseconds |
+
+> **Note:** `validate` defaults to `false` to keep the bundle lightweight. Pass `validate: true` to enable Zod schema validation on every response (requires `zod` installed as a peer dependency).
+
+If you have a `.tila/config.toml` project file:
+
+```typescript
+import { TilaClient } from "tila-sdk";
+
+const client = TilaClient.fromConfig(config, process.env.TILA_TOKEN!);
+```
+
+## Claim Lifecycle
+
+tila uses a first-writer-wins coordination model built on fencing tokens. The `withClaim` primitive acquires a resource lock, runs your callback, and releases the lock in `finally` -- preventing resource leaks.
+
+Every `ClaimHandle` carries a monotonic `fence` number. Destructive writes (entity update, artifact upload) carry this fence automatically. The server rejects stale fences with error code `stale-fence`.
+
+```typescript
+import { TilaClient, withClaim } from "tila-sdk";
+
+const client = new TilaClient({
+  baseUrl: process.env.TILA_URL!,
+  token: process.env.TILA_TOKEN!,
+});
+
+const projectId = "my-project";
+
+await withClaim(client, projectId, "dataset/batch-42", "exclusive", 60_000, async (handle) => {
+  // handle.fence is the monotonic fencing token
+  // handle.expiresAt is the claim expiry (epoch ms)
+
+  // Start heartbeat -- auto-renews at 40% of TTL (24s intervals for 60s TTL)
+  const hb = handle.startHeartbeat(60_000);
+
+  // Early-warning timer -- fires 5s before claim expires
+  const expiry = handle.onClaimExpiring(5_000, () => {
+    console.warn("Claim expiring soon -- wrap up!");
+  });
+
+  // Listen for heartbeat errors (409 = lost claim, 401 = auth expired)
+  handle.on("error", (err) => {
+    console.error("Heartbeat failed:", err.message);
+  });
+
+  try {
+    // Fence-threaded entity update -- fence is carried automatically
+    await handle.updateEntity("task-1", { status: "processing" });
+
+    // ... do work ...
+
+    await handle.updateEntity("task-1", { status: "complete" });
+  } finally {
+    expiry.stop();
+    hb.stop();
+  }
+});
+// Claim is released automatically when the callback exits
+```
+
+### Claim Modes
+
+| Mode | Behavior |
+|------|----------|
+| `"exclusive"` | Only one holder at a time. Acquire fails if already held. |
+| `"shared"` | Multiple holders allowed. Each gets a unique fence. |
+
+## Artifacts
+
+### Upload
+
+**Inside a claim context (preferred):** The fence is threaded automatically.
+
+```typescript
+await withClaim(client, projectId, "output/report", "exclusive", 30_000, async (handle) => {
+  const hb = handle.startHeartbeat(30_000);
+  try {
+    // Upload from a File or Blob
+    const result = await handle.uploadArtifact(
+      new Blob(["report content"], { type: "text/plain" }),
+      { kind: "output" },
+    );
+
+    console.log(result.key);          // content-addressed key
+    console.log(result.deduplicated);  // true if content already existed
+  } finally {
+    hb.stop();
+  }
+});
+```
+
+**Standalone upload (no claim):**
+
+```typescript
+import { createArtifactMethods } from "tila-sdk";
+
+const artifacts = createArtifactMethods(client, projectId);
+
+const result = await artifacts.upload(
+  new Blob(["data"], { type: "application/json" }),
+  { kind: "intermediate", mimeType: "application/json" },
+);
+```
+
+**`mimeType` requirement:** When the file's `.type` property is empty (plain `Blob` with no type set), you must pass `mimeType` explicitly. A `TypeError` is thrown synchronously before any network request if `mimeType` is absent and `file.type` is empty.
+
+### Download
+
+`download()` returns a raw `ReadableStream`. The caller owns consumption and cleanup.
+
+```typescript
+const artifacts = createArtifactMethods(client, projectId);
+
+const { body, contentType, contentLength } = await artifacts.download(
+  "artifacts/task-1/abc123.json",
+);
+
+// Pipe to a file (Node.js)
+const file = Bun.file("output.json");
+await Bun.write(file, body);
+
+// Or collect as text
+const text = await new Response(body).text();
+```
+
+## Error Handling
+
+### Typed Catch Pattern
+
+Use `isTilaApiError()` (preferred over `instanceof` for cross-realm/bundled code):
+
+```typescript
+import { isTilaApiError, TILA_ERRORS } from "tila-sdk";
+
+try {
+  await entities.update("task-1", { status: "done" });
+} catch (err) {
+  if (isTilaApiError(err)) {
+    switch (err.code) {
+      case TILA_ERRORS.STALE_FENCE:
+        // Fence was superseded -- re-acquire the claim
+        break;
+      case TILA_ERRORS.UNAUTHORIZED:
+        // Token expired or invalid -- re-authenticate
+        break;
+      case TILA_ERRORS.NOT_FOUND:
+        // Entity does not exist
+        break;
+      default:
+        console.error(`API error ${err.status}: [${err.code}] ${err.message}`);
+    }
+  } else {
+    // Network error, timeout, or malformed response
+    console.error("Non-API error:", err);
+  }
+}
+```
+
+`TilaApiError` fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `number` | HTTP status code |
+| `code` | `string` | Machine-readable error code |
+| `message` | `string` | Human-readable description |
+| `retryable` | `boolean` | Whether the server considers this retryable |
+
+### Error Code Conventions
+
+tila uses two wire-format conventions for error codes:
+
+- **Worker/auth layer:** `SCREAMING_SNAKE_CASE` -- e.g., `"UNAUTHORIZED"`, `"SESSION_EXPIRED"`, `"RATE_LIMITED"`
+- **DO (Durable Object) layer:** `kebab-case` -- e.g., `"stale-fence"`, `"not-found"`, `"already-held"`
+
+The `TILA_ERRORS` constant object normalizes both under typed keys so you never hardcode string literals:
+
+```typescript
+TILA_ERRORS.UNAUTHORIZED    // "UNAUTHORIZED"  (worker layer)
+TILA_ERRORS.STALE_FENCE     // "stale-fence"   (DO layer)
+TILA_ERRORS.NOT_FOUND       // "not-found"     (DO layer)
+TILA_ERRORS.RATE_LIMITED    // "RATE_LIMITED"  (worker layer)
+```
+
+### Retry Wrapper
+
+`withRetry` implements exponential backoff with full jitter (AWS pattern):
+
+```typescript
+import { withRetry, withClaim } from "tila-sdk";
+
+const result = await withRetry(
+  async () => {
+    return await withClaim(client, projectId, "resource", "exclusive", 30_000, async (handle) => {
+      const hb = handle.startHeartbeat(30_000);
+      try {
+        await handle.updateEntity("task-1", { status: "done" });
+        return "success";
+      } finally {
+        hb.stop();
+      }
+    });
+  },
+  { maxRetries: 5, baseDelayMs: 200 },
+);
+```
+
+**Hard stop rule:** A `TilaApiError` with `retryable === false` is never retried, regardless of `maxRetries`. Network errors and timeouts are always retried up to the limit.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxRetries` | `number` | `3` | Maximum retry attempts after first failure |
+| `baseDelayMs` | `number` | `200` | Base delay for exponential backoff |
+| `maxDelayMs` | `number` | `30000` | Maximum delay cap |
+| `jitter` | `boolean` | `true` | Apply full jitter to delay |
+
+## API Reference
+
+### Method Factories
+
+`withClaim` + `ClaimHandle` is the recommended high-level coordination API. The method factories below are lower-level building blocks for advanced use -- e.g., when managing claim acquire/release manually.
+
+| Factory | Primary Methods | Description |
+|---------|----------------|-------------|
+| `createEntityMethods(client, projectId)` | `create`, `get`, `list`, `update`, `archive`, `addRelationship`, `addArtifactRef`, `listArtifactRefs` | Entity CRUD and relationships |
+| `createClaimMethods(client, projectId)` | `acquire`, `renew`, `release`, `list`, `get` | Low-level claim management |
+| `createArtifactMethods(client, projectId)` | `upload`, `download`, `list`, `search`, `addRelationship`, `listRelationships` | Artifact storage and search |
+| `createPresenceMethods(client, projectId)` | `heartbeat`, `list`, `listAll` | Machine presence tracking |
+| `createSignalMethods(client, projectId)` | `inbox`, `send`, `ack` | Inter-machine signaling |
+| `createGateMethods(client, projectId)` | `list`, `create`, `resolve`, `remove` | Coordination gates |
+| `createTemplateMethods(client, projectId)` | `instantiate` | Entity template instantiation |
+| `createSummaryMethods(client, projectId)` | `get` | Project summary |
+| `createJournalMethods(client, projectId)` | `query` | Event journal queries |
+| `createSchemaMethods(client, projectId)` | `get`, `apply`, `history` | Schema-as-config management |
+| `createTokenMethods(client)` | `issue`, `revoke`, `list` | API token management (no `projectId`) |
+
+### GitHub Token Exchange
+
+For CI environments (GitHub Actions) where a tila API token is not available:
+
+```typescript
+import { exchangeGitHubToken, TilaClient } from "tila-sdk";
+
+const { sessionToken, expiresAt, permission } = await exchangeGitHubToken(
+  process.env.TILA_URL!,
+  "my-project",
+  process.env.GITHUB_TOKEN!,
+);
+
+const client = new TilaClient({
+  baseUrl: process.env.TILA_URL!,
+  token: sessionToken,
+});
+// sessionToken is short-lived -- expiresAt is epoch ms
+```
+
+> **Note:** `exchangeGitHubToken` is a standalone function, not a `TilaClient` method. The repository must be registered via `tila init --github` before tokens can be exchanged.
+
+## License
+
+See the repository root for license information.