@terrascale/sdk 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## Unreleased — TS-754
+
+Entity IDs are plain uppercase Crockford ULIDs. `generateId()` uses the maintained
+`ulid` library with monotonic generation; `isValidId()` and `requireId()` validate
+the canonical 26-character, 128-bit form. UUIDs, prefixes, lowercase and legacy
+keys fail validation. Project IDs, document requests/responses, snapshot keys,
+hosted identity DTOs and explicit development storage use this contract.
+
+The document key is the entity ID; document JSON and patches cannot duplicate it
+in a top-level `id` field. The deterministic UUIDv5 `documentIdFor` helper is
+removed. Store natural keys in indexed fields. Local Better Auth generates ULIDs
+and stores the ID only in the record key, reconstructing its adapter view on read.
+
+This is a greenfield cutover: there is no migration, ID rewrite, compatibility
+shim or legacy fallback. Service owners wipe their verified affected stores and
+recreate bootstrap state; this stateless SDK has no production data to delete.
+Release qualification requires the matching immutable C# ULID producer release.
+
+## Unreleased — TS-592
+
+The project-scoped data client accepts a ts-auth access JWT as `token`, while
+retaining legacy C# `tb_` keys for the existing producer release. Header injection
+and malformed credentials fail before I/O. TS-589 keeps data paths unchanged;
+Management and Admin remain closed and make no retired route calls.
+JWT producer qualification awaits the server implementation of `docs/api.md`.
+
+## 0.0.2 — TS-650
+
+TerraBase version tokens are opaque: `tbv1-<32 hex>` and the coming `tbv2-…`
+format are both accepted (any 1-256 visible ASCII characters without quotes, so
+they stay safe in `If-Match`). Responses with new members no longer throw:
+`durability` passes through any label, and documents pass through any `state`,
+including a causal read's `"conflict"` with its `siblings` (the LWW winner stays
+in `document`). Conditional writes and error handling are unchanged.
+
 ## 0.0.1 — TS-498
 
 The package moves from the unscoped `terrascale` npm name, which the owner has

package/README.md

@@ -11,17 +11,17 @@ npm install @terrascale/sdk
 ```
 
 ```js
-import { createTerraBaseV1Client, documentIdFor, v1Filter } from "@terrascale/sdk";
+import { createTerraBaseV1Client, generateId, v1Filter } from "@terrascale/sdk";
 
 const client = createTerraBaseV1Client({
   project: process.env.TERRABASE_PROJECT,
-  token: process.env.TERRABASE_API_KEY,
+  token: process.env.TERRABASE_ACCESS_TOKEN,
   baseUrl: process.env.TERRABASE_BASE_URL,
 });
 const db = client.database("app");
 const todos = db.collection("todos");
 
-const id = await documentIdFor("todos", "first-task");
+const id = generateId();
 await todos.put(id, { title: "Use TerraBase", done: false }, { ifNoneMatchAny: true });
 const doc = await todos.get(id);
 await todos.patch(id, { merge: { done: true } }, { ifMatch: doc.version });
@@ -32,10 +32,14 @@ for await (const page of todos.pages({ filter: v1Filter.eq("/done", true), limit
 ```
 
 Provision the project, database and collection before using their handles.
-API keys begin with `tb_` and travel as `Authorization: Bearer <key>`.
+The pinned producer still requires a C# `tb_` key as `token`. The example also
+accepts a ts-auth project access JWT for the published TS-589 target, whose
+server implementation remains pending. Credentials travel as
+`Authorization: Bearer <token>` and are held privately. The SDK validates
+header-safe syntax; authentication and authorization belong to the producer.
 Reads and queries require `documents:read`; writes and transactions require
 `documents:write`. Transaction assertions additionally require `documents:read`.
-Keep keys private and out of logs and browser bundles. `createTerraBaseClient`
+Keep service credentials private and out of logs and browser bundles. `createTerraBaseClient`
 is an alias of `createTerraBaseV1Client`; it no longer accepts tenant/shard options.
 
 ## Atlas and endpoint selection
@@ -54,7 +58,7 @@ import { createTerraBaseV1Client, staticBaseUrlResolver } from "@terrascale/sdk"
 
 const client = createTerraBaseV1Client({
   project: process.env.TERRABASE_PROJECT,
-  token: process.env.TERRABASE_API_KEY,
+  token: process.env.TERRABASE_ACCESS_TOKEN,
   endpointResolver: staticBaseUrlResolver(process.env.TERRABASE_BASE_URL),
 });
 const db = client.database("app");
@@ -67,6 +71,19 @@ to TS-507; this release requires an explicit URL or caller-supplied resolver.
 
 ## Documents, queries, transactions and shapes
 
+The published TS-589 route table (`terrabase/docs/api.md`) keeps these data
+paths unchanged. Management moves to project-scoped paths using database names;
+this SDK's Management and Admin entrypoints still make no HTTP calls.
+Database creation belongs to Management (`POST /v1/projects/{project}/databases`)
+in that target contract.
+
+The current immutable producer release implements the renamed `TerraBase`
+assembly, but still authenticates data calls with `tb_` keys and exposes the old
+Management routes. Its real-release integration harness uses those existing
+bootstrap operations. JWT server compatibility and the new Management routes
+remain unqualified until the producer publishes their implementation; accepting
+a JWT in SDK configuration does not establish server compatibility.
+
 The C# producer owns these routes:
 
 | Operation | Method and path |
@@ -77,9 +94,15 @@ The C# producer owns these routes:
 | Shape | `GET /v1/projects/{project}/databases/{db}/collections/{c}/shape` |
 
 Collection methods are `get`, `put`, `create`, `patch`, `delete`, `query`,
-`pages` and `items`. New document IDs are canonical UUIDs; `documentIdFor`
-generates a stable UUIDv5 from a natural key. Documents return
-`{ id, version, state: "value", document }`. Writes return the version and a
+`pages` and `items`. Every entity ID is a plain 26-character Crockford ULID,
+canonical uppercase, without a prefix. `generateId()` uses the maintained
+`ulid` library and increases monotonically within a millisecond. `isValidId`
+checks IDs; `requireId` throws for invalid IDs. UUIDs and legacy IDs are rejected.
+The document key is the entity ID: keep it out of the JSON payload. Natural
+keys belong in indexed document fields, not deterministic UUID IDs. Documents return
+`{ id, version, state: "value", document }`; a causal read can answer
+`state: "conflict"` with `siblings`, and unknown states pass through. Versions
+(`tbv1-…`, `tbv2-…`) are opaque tokens. Writes return the version and a
 decimal-string commit `offset`; preserve those opaque positions and use
 `ifMatch` or `ifNoneMatchAny` for conditional writes.
 
@@ -138,14 +161,13 @@ Never commit keys, cookies, environment files or real tenant data.
 
 The immutable release pin is
 [`scripts/ci/terrabase-release.json`](scripts/ci/terrabase-release.json): C#
-TerraBase 0.1.0, release `ci-0248ad3ac6fb82ac900e38005840a619e5d0beac-run-13267`,
+TerraBase 0.1.0, release `ci-6cb97456b9b52a92a61856601cc025c4f2833518-run-16729`,
 with binary SHA-256
-`8abcedaa6b8487f08ecafe4485862f1f9309154e58ac1a74eda2278b78500968`.
-This official release is currently a draft: the producer's fast checks failed
-and publication was skipped (terrabase #110). The SDK integration harness may
-consume its official asset read-only when the version, source revision, size and
-SHA-256 are verified; publication is not required. Draft status does not establish
-that the producer's source qualification passed.
+`cc2db35b18c385c6d58036c6c94e59460b0e12b0d5616da2222713efbe666700`.
+This official prerelease contains the qualified TS-754 ULID producer, the renamed
+`TerraBase` assembly and `src/TerraBase` sources. Its asset name remains `terrabase-linux-amd64`.
+The SDK integration harness consumes its official asset read-only when the
+version, source revision, size and SHA-256 are verified.
 The acquisition script verifies the official release, revision, asset size and
 digest. Private downloads require `FORGEJO_TOKEN`. Missing or mismatched official
 assets block qualification rather than selecting older bytes.
@@ -185,11 +207,18 @@ See [CHANGELOG.md](CHANGELOG.md) for the 0.0.1 migration and breaking changes.
 client, with its own origin, instance and credentials. Management,
 administration and production Better Auth capabilities remain subject to their
 explicit admission errors; they are not a shortcut into the database transport.
+Webhook dead-letter replay uses the documented `endpointId:eventId` delivery
+selector; both references must be canonical ULIDs. Entity pages reject null and
+primitive records; recovery-code pages contain strings.
 
 `@terrascale/sdk/local` (including `terrascale-local`) and `@terrascale/sdk/postgres` are
 **deprecated legacy entrypoints**. SQLite stays opt-in for development only and
 refuses CI, production, staging, qualification and deployment environments.
 It is no longer the required Dashboard backend and does not qualify the C# API.
+Local SQLite uses fresh format 2. Older stores are refused before records are
+read: stop the runtime, delete the exact configured `databasePath` and its
+`-wal`/`-shm` files, then restart. Startup recreates bootstrap state; old auth
+records and references are discarded together. There is no migration.
 The PostgreSQL listener and retired tenant/shard client are outside the default
 v1 API. Existing framework, schema and SQL entrypoints are separate legacy
 surfaces; the root entrypoint exposes the C# v1 client API.
@@ -198,4 +227,4 @@ Hosted OAuth resource requests use one exact registered HTTPS `resource`. `oidc.
 
 `oauthClients` and `oauthResources` provide the producer's snake_case policy records and named management operations. Resource PATCH requires `expected_auth_epoch`; client PATCH accepts it. JSON epochs outside JavaScript's exact integer range are rejected. Client PATCH returns a bare client view unless `rotate_secret` is true, when it returns the client and its one-time secret. Resource create/PATCH always return the resource and nullable one-time introspection secret.
 
-Use `oidc.introspectResource` with independently configured `issuer`, exact `audience`, `introspection_client_id`, and `introspection_secret`. It uses resource Basic authentication only, with each credential component form encoded before Base64. An active result requires the exact configured issuer/audience, `Bearer`, integer timestamps valid at the local clock with no default skew, and the required user/service session shape. Inactive results contain only `active: false`. Resource results expose no internal epochs, refresh family, or token-use fields. The provider checks current durable token/session/resource state; an active principal or scope does not grant project ownership or management authority. Product authorization remains at the caller's existing authorization boundary.
+Use `oidc.introspectResource` with independently configured `issuer`, exact `audience`, `introspection_client_id`, and `introspection_secret`. It uses resource Basic authentication only, with each credential component form encoded before Base64. An active result requires the exact configured issuer/audience, `Bearer`, integer timestamps valid at the local clock with no default skew, and the required user/service session shape. Inactive results contain only `active: false`. Resource results expose no internal epochs, refresh family, or token-use fields. The provider checks current durable token/session/resource state; an active principal or scope does not grant project ownership or management authority. Product authorization remains at the caller's existing authorization boundary. Behind the Atlas proxy `apiBaseUrl` `https://auth.terrascale.tech`, ts-auth's issuer is regional, `https://<region>.auth.terrascale.tech/<slug>` (for example `https://gru.auth.terrascale.tech/<slug>`); configure that issuer, not the proxy host. Resource introspection then calls the issuer's regional host directly, because Atlas could rank another region, which is another issuer; `useReverseProxy` keeps it on the proxy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",
@@ -150,5 +150,8 @@
       "last 1 Edge major version"
     ]
   },
-  "packageManager": "npm@11.18.0"
+  "packageManager": "npm@11.18.0",
+  "dependencies": {
+    "ulid": "3.0.2"
+  }
 }