@terrascale/sdk 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.0.10 — production contract fixes
+
+The named hosted-auth token operation accepts explicit project API-key grants
+without a resource parameter. Public health probes accept omitted private build
+metadata. Hosted-auth operations return authentication denials without replaying
+requests with a changed credential. README qualification commands follow the
+binary-free HTTP test policy and document the existing TypeScript model tooling.
+
+## 0.0.9 — declared JSON Schema models
+
+Node tooling at `@terrascale/sdk/codegen` generates document, create and
+merge-patch body types from `collection.getSchema()` or a schema file. Install
+the exact tooling peer `json-schema-to-typescript@16.0.0`; the `terrascale-models`
+command is separate from browser/runtime entrypoints. Unsupported constructs
+produce JSON Pointer diagnostics. Runtime validation remains authoritative.
+
 ## 0.0.7 — live shape reconnect, browser bootstrap and read replica
 
 `subscribeShape` keeps its state and retries the same position after a lost

package/README.md

@@ -1,7 +1,7 @@
 # @terrascale/sdk
 
 The JavaScript/JSDoc SDK for the project-scoped C#/.NET TerraBase server
-(`TerraScale/terrascale`). Current source compatibility is pinned at
+(`TerraScale/terrascale`). The historical source compatibility audit records
 `e30ffdc287530551b161b0130220be53d3c0475e`; see the
 [compatibility audit](docs/api-compatibility-20261013.md) for exact evidence and open gates.
 The package targets Node.js 22 and 24 and current Chrome, Firefox, Safari, and Edge.
@@ -100,8 +100,8 @@ to TS-507; this release requires an explicit URL or caller-supplied resolver.
 
 Current handler source implements project-scoped database names and point
 addresses as `/documents/by-key?id=…`. The complete method/path/scope inventory
-is in [sdk-v1-route-manifest.json](sdk-v1-route-manifest.json), with 25 current
-source-backed routes and one retained historical shape route. Current generated
+is in [sdk-v1-route-manifest.json](sdk-v1-route-manifest.json), including the
+current public inventory and a retained historical shape route. Current generated
 OpenAPI and immutable release qualification remain open gates.
 
 | Surface | Public methods |
@@ -257,9 +257,9 @@ for await (const row of db.export({ after: last, signal: controller.signal })) {
 }
 ```
 
-The exported collection `shape()` remains compatible with the historical
-`6cb9745…` release. Its route is absent from the audited current server source;
-do not use it as current producer evidence. SSE changes are a separate database
+The exported collection `shape()` reads the current free shape protocol using
+`documents:read`. A retained historical `shapes:read` route descriptor does not
+qualify that current protocol. SSE changes are a separate database
 feed, not authorized bounded-query snapshots or the planned reactive WebSocket API.
 
 ## Free shape subscriptions (protocol v1)
@@ -354,12 +354,13 @@ in either runtime.
 This implements the [proposed protocol](contracts/shape-v1/shape-reads.md) at
 `993927ce7ecf8f9b889d24d4d1d21ec96eaf9416`, using `documents:read`. HTTP fakes and the
 upstream [conformance vectors](test/fixtures/shape-vectors.json) verify client
-behavior; they do not qualify a producer deployment. Current generated OpenAPI,
-live endpoint availability, and automatic region discovery remain unqualified.
-No TerraBase binary is downloaded or run by these tests. The existing historical
-`shape()` method keeps its contract. Manifest/object delivery and 302 redirects
-are deferred to FR-22; vector `presigned-manifest` is explicitly skipped until its
-delivery contract is ready upstream.
+behavior; they do not qualify a producer deployment. Isolated production checks
+on 2026-10-26 verified shape bootstrap, continuation, manifest and epoch-key reads,
+live subscription updates, and checkpoint restore. Full current generated
+OpenAPI and semantic-corpus parity, sealed-object delivery/decryption, and
+automatic region discovery remain open qualification gates. These collection
+reads do not implement the planned bounded-query WebSocket result protocol.
+No TerraBase binary is downloaded or run by SDK tests.
 
 Failures throw `TerraBaseV1Error` with status, code, optional transaction `op`,
 parsed `body`, raw `responseText`, response `headers`, and a received
@@ -376,44 +377,22 @@ failing in this draft. See the audit for exact results and producer dependencies
 ## Ouroboros and qualification
 
 Ouroboros means TerraScale services store their data in the same production
-TerraBase that customers use. SDK boundary tests must run the real C# TerraBase
-release binary, pinned by immutable version and SHA-256, with an isolated
-allocation. A fixture, mocked transport, SQLite SDK runtime, frozen Rust
-contract archive or typed build cannot establish producer compatibility.
-
-The v1 route manifest and producer contract evidence must agree with the C#
-release under test. Keep live tests environment-gated; report missing local
-configuration as skipped, never as successful integration evidence. Required
-release qualification must supply the verified binary and real producer inputs.
-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-6cb97456b9b52a92a61856601cc025c4f2833518-run-16729`,
-with binary SHA-256
-`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.
-
-```sh
-nice -n 19 npm run provision:terrabase
-export TERRABASE_BINARY=/absolute/path/printed/by/the/provisioner
-nice -n 19 npm run test:integration
-```
-
-The integration runner rechecks the binary digest, starts an isolated TLS server,
-verifies its version and runtime OpenAPI digest, and provisions a disposable
-organization, project, database, collections and scoped keys. It supplies the
-`TB_V1_*` environment and trusted local certificate to the real-server tests and
-cleans up the process and allocation afterwards. No TLS validation is disabled.
-Direct live test configuration uses `TB_V1_URL`, `TB_V1_PROJECT`,
-`TB_V1_DATA_KEY` and optionally `TB_V1_DATABASE` (default `app`);
-`TB_V1_REQUIRED=1` makes absent integration inputs fail rather than skip.
+TerraBase that customers use. Qualification requires an authorized, isolated
+real-service allocation, independently verified producer release provenance,
+and current generated-contract and route-manifest parity. HTTP fakes, local
+SQLite, historical contract inputs and typed builds cannot establish deployed
+producer compatibility.
+
+This SDK repository does not download or launch a TerraBase binary. The
+historical [release pin](scripts/ci/terrabase-release.json) does not qualify the
+current producer or JWT authorization. Keep real HTTP tests environment-gated;
+missing live configuration is skipped, never successful integration evidence.
+
+Existing live tests consume `TB_V1_URL`, `TB_V1_PROJECT`, `TB_V1_DATA_KEY` and
+optionally `TB_V1_DATABASE` (default `app`) from an independently provisioned
+allocation. Denial checks use `TB_V1_READ_KEY` and `TB_V1_WRITE_KEY`. Supply
+credentials privately; never commit keys, cookies, environment files or real
+tenant data. Local checks below do not substitute for this live gate.
 
 Local checks run at low CPU priority:
 
@@ -429,6 +408,24 @@ nice -n 19 npm test
 without adding a linter dependency. CI runs these commands at normal priority.
 See [CHANGELOG.md](CHANGELOG.md) for the 0.0.1 migration and breaking changes.
 
+## TypeScript document models
+
+Node-only `@terrascale/sdk/codegen` generates body aliases from declared JSON
+Schema, using `generateDocumentModels(schema, "Order")` or the authorized
+`generateCollectionModels(collection, "Order", { signal })` operation.
+Install its exact tooling peer separately:
+
+```sh
+npm install --save-dev json-schema-to-typescript@16.0.0
+npx terrascale-models schema.json Order models.ts
+```
+
+The input is the schema itself, without the API response wrapper. Output has
+`OrderDocument`, `OrderCreate` and `OrderPatch`; keep codegen out of browser
+bundles. Generated aliases do not validate or automatically narrow SDK reads.
+See [TypeScript document models](https://docs.terrascale.tech/guides/schema-validation#generate-typescript-document-models)
+for the supported subset, merge-patch null semantics and strict compiler setup.
+
 ## Separate and deprecated entrypoints
 
 `@terrascale/sdk/ts-auth` retains its separate hosted identity management and OIDC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",
@@ -70,10 +70,16 @@
       "workerd": null,
       "browser": null,
       "node": "./src/postgres.js"
+    },
+    "./codegen": {
+      "types": "./types/codegen.d.ts",
+      "browser": null,
+      "node": "./src/codegen.js"
     }
   },
   "bin": {
-    "terrascale-local": "./src/local/cli.js"
+    "terrascale-local": "./src/local/cli.js",
+    "terrascale-models": "./src/codegen-cli.js"
   },
   "files": [
     "src",
@@ -109,7 +115,8 @@
     "@better-auth/core": "1.7.2",
     "react": ">=18.2.0 <20.0.0",
     "pg": "8.23.0",
-    "@tanstack/db": "0.9.2"
+    "@tanstack/db": "0.9.2",
+    "json-schema-to-typescript": "16.0.0"
   },
   "peerDependenciesMeta": {
     "@better-auth/core": {
@@ -123,6 +130,9 @@
     },
     "@tanstack/db": {
       "optional": true
+    },
+    "json-schema-to-typescript": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -140,7 +150,8 @@
     "@types/react": "19.2.14",
     "@types/react-test-renderer": "19.1.0",
     "pg": "8.23.0",
-    "@types/pg": "8.23.1"
+    "@types/pg": "8.23.1",
+    "json-schema-to-typescript": "16.0.0"
   },
   "engines": {
     "node": "22.x || 24.x",

package/src/codegen-cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { generateDocumentModels } from "./codegen.js";
+import { parseExactJson } from "./v1/json.js";
+const [source, name, output, ...extra] = process.argv.slice(2);
+if (!source || !name || !output || extra.length) {
+  process.stderr.write("Usage: terrascale-models declared-schema.json ModelName models.ts\nInput is the schema itself; use @terrascale/sdk/codegen to fetch a live declaration.\n");
+  process.exitCode = 1;
+} else {
+  try {
+    const generated = await generateDocumentModels(parseExactJson(await readFile(source, "utf8")), name);
+    await writeFile(output, generated, "utf8");
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : "Model generation failed"}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/codegen.js

@@ -0,0 +1,137 @@
+// Node-only tooling. Never imported by the browser SDK entrypoint.
+import { compile } from "json-schema-to-typescript";
+import { isJsonObject, ExactDecimal } from "./v1/json.js";
+/** @import { V1Collection } from "./v1/terrabase-v1.js" */
+/** @typedef {Record<string, unknown>} Schema */
+const dialect = "https://json-schema.org/draft/2020-12/schema";
+const supported = new Set(["$schema", "type", "properties", "required", "additionalProperties", "items", "enum", "const", "readOnly", "title", "description", "default", "examples", "format", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf", "minLength", "maxLength", "minItems", "maxItems", "uniqueItems", "minProperties", "maxProperties"]);
+/** @param {string} pointer @param {string} message @returns {never} */
+function diagnostic(pointer, message) { throw new TypeError(`Collection model ${pointer || "/"}: ${message}`); }
+/** @param {string} pointer @param {string} key */
+function at(pointer, key) { return `${pointer}/${key.replaceAll("~", "~0").replaceAll("/", "~1")}`; }
+
+/**
+ * Generate body models from a declared Draft 2020-12 schema, never inferred samples.
+ * Runtime validation remains authoritative; constraints such as ranges and lengths
+ * cannot be expressed by TypeScript. Patch is an RFC 7396 merge-patch body.
+ * @param {unknown} input
+ * @param {string} name A TypeScript identifier prefix.
+ * @returns {Promise<string>}
+ */
+export async function generateDocumentModels(input, name) {
+  if (!/^[A-Z][A-Za-z0-9]*$/u.test(name)) throw new TypeError("Model name must start with A-Z and contain only letters and digits.");
+  // Also reject cyclic objects, lossy numbers, and excessive input before compilation.
+  let values = 0;
+  /** @param {unknown} value @param {number} depth */
+  function bounded(value, depth) {
+    if (++values > 4093 || depth > 15) diagnostic("", "schema exceeds 4093 values or 15 nesting levels.");
+    if (value instanceof ExactDecimal || (typeof value === "number" && (!Number.isFinite(value) || (Number.isInteger(value) && !Number.isSafeInteger(value))))) diagnostic("", "exact numeric literals outside JavaScript's safe range are unsupported.");
+    if (Array.isArray(value) || isJsonObject(value)) for (const child of Object.values(value)) bounded(child, depth + 1);
+  }
+  bounded(input, 0);
+  if (Buffer.byteLength(JSON.stringify(input) ?? "") > 65536) diagnostic("", "schema exceeds 64 KiB.");
+  if (!isJsonObject(input) || input.type !== "object") diagnostic("/type", "document root must declare type: object.");
+  const models = [];
+  for (const mode of /** @type {const} */ (["Document", "Create", "Patch"])) {
+    const schema = convert(input, "", mode);
+    const identifier = `${name}${mode}`;
+    const output = await compile(/** @type {import("json-schema-to-typescript").JSONSchema} */ (schema), identifier, {
+      bannerComment: "", format: false, unknownAny: true, ignoreMinAndMaxItems: true,
+      $refOptions: { resolve: { file: false, http: false } },
+    });
+    // Object aliases remain assignable to the SDK's JSON object input type.
+    models.push(output.replace(`export interface ${identifier} {`, `export type ${identifier} = {`).trim());
+  }
+  return `// Generated by @terrascale/sdk/codegen (json-schema-to-typescript 16.0.0). Do not edit.\n// Bodies only; id/version are server envelope fields. Runtime validation is authoritative.\n\n${models.join("\n\n")}\n`;
+}
+
+/** @param {unknown} input @param {string} pointer @param {"Document" | "Create" | "Patch"} mode @returns {Schema | boolean} */
+function convert(input, pointer, mode) {
+  if (input === false) return false;
+  const jsonType = `import("@terrascale/sdk").${mode === "Document" ? "V1JsonValue" : "V1JsonInput"}`;
+  if (input === true) return { tsType: jsonType };
+  if (!isJsonObject(input)) diagnostic(pointer, "expected a schema object or boolean.");
+  for (const key of Object.keys(input).sort()) if (!supported.has(key)) diagnostic(at(pointer, key), `unsupported keyword ${key}; inline references or simplify the schema to the documented subset.`);
+  for (const key of ["minLength", "maxLength", "minItems", "maxItems", "minProperties", "maxProperties"]) if (input[key] !== undefined && (typeof input[key] !== "number" || !Number.isSafeInteger(input[key]) || input[key] < 0)) diagnostic(at(pointer, key), "expected a nonnegative safe integer.");
+  for (const key of ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"]) if (input[key] !== undefined && (typeof input[key] !== "number" || (key === "multipleOf" && input[key] <= 0))) diagnostic(at(pointer, key), "expected a number (positive for multipleOf).");
+  for (const key of ["title", "description", "format"]) if (input[key] !== undefined && typeof input[key] !== "string") diagnostic(at(pointer, key), "expected a string annotation.");
+  if (input.examples !== undefined && !Array.isArray(input.examples)) diagnostic(at(pointer, "examples"), "expected an array.");
+  if (input.uniqueItems !== undefined && typeof input.uniqueItems !== "boolean") diagnostic(at(pointer, "uniqueItems"), "expected a boolean.");
+  if (input.$schema !== undefined && input.$schema !== dialect) diagnostic(at(pointer, "$schema"), `only ${dialect} is supported.`);
+  const types = Array.isArray(input.type) ? input.type : [input.type];
+  const kinds = types.filter(type => type !== "null");
+  if (new Set(types).size !== types.length || kinds.length > 1 || types.length === 0 || types.some(type => !["object", "array", "string", "number", "integer", "boolean", "null"].includes(String(type)))) diagnostic(at(pointer, "type"), "declare one type, optionally unioned with null.");
+  const kind = kinds[0];
+  const nullable = types.includes("null");
+  for (const key of ["properties", "required", "additionalProperties"]) if (Object.hasOwn(input, key) && kind !== "object") diagnostic(at(pointer, key), "this keyword is supported only with an object type.");
+  if (Object.hasOwn(input, "items") && kind !== "array") diagnostic(at(pointer, "items"), "items is supported only with an array type.");
+  if (input.readOnly !== undefined && typeof input.readOnly !== "boolean") diagnostic(at(pointer, "readOnly"), "expected a boolean annotation.");
+  /** @type {Schema} */
+  const result = { type: input.type };
+  if (typeof input.description === "string") result.description = input.description;
+  for (const key of ["enum", "const"]) {
+    if (!Object.hasOwn(input, key)) continue;
+    if (kind === "object" || kind === "array") diagnostic(at(pointer, key), "container literal constraints are unsupported; use type: null for a null-only value.");
+    const literals = key === "enum" ? input[key] : [input[key]];
+    if (!Array.isArray(literals) || literals.length === 0 || literals.some(value => value !== null && !["string", "number", "boolean"].includes(typeof value))) diagnostic(at(pointer, key), "only nonempty scalar literals are supported.");
+    if (literals.some(value => !types.some(type => type === "null" ? value === null : type === "integer" ? typeof value === "number" && Number.isInteger(value) : typeof value === type))) diagnostic(at(pointer, key), "literal/type intersections are unsupported; each literal must satisfy the declared type.");
+    result[key] = input[key];
+  }
+  if (Array.isArray(input.enum) && Object.hasOwn(input, "const") && !input.enum.includes(input.const ?? null)) diagnostic(at(pointer, "const"), "const must belong to enum.");
+  if ((kind === "number" || kind === "integer") && result.enum === undefined && result.const === undefined) result.tsType = `number | import("@terrascale/sdk").ExactDecimal${mode === "Document" ? "" : " | bigint"}${nullable ? " | null" : ""}`;
+  if (kind === "array") {
+    if (input.items === undefined) diagnostic(at(pointer, "items"), "declare the array item schema (or true for arbitrary JSON).");
+    result.items = convert(input.items, at(pointer, "items"), mode === "Patch" ? "Create" : mode);
+  }
+  if (kind === "object") {
+    const properties = input.properties === undefined ? {} : input.properties;
+    if (!isJsonObject(properties)) diagnostic(at(pointer, "properties"), "expected a property map.");
+    const required = input.required === undefined ? [] : input.required;
+    if (!Array.isArray(required) || required.some(key => typeof key !== "string" || !Object.hasOwn(properties, key))) diagnostic(at(pointer, "required"), "required must list declared property names.");
+    if (new Set(required).size !== required.length) diagnostic(at(pointer, "required"), "required names must be unique.");
+    const entries = Object.keys(properties).sort().map(key => {
+      const property = properties[key];
+      const location = at(at(pointer, "properties"), key);
+      // Validate even omitted read-only fields, so unsupported constructs never hide.
+      let converted = convert(property, location, mode);
+      if (mode !== "Document" && isJsonObject(property) && property.readOnly === true) converted = false;
+      else if (mode === "Patch") {
+        // null deletes in RFC 7396, including when the stored field permits null.
+        if (!required.includes(key)) converted = { anyOf: [converted, { type: "null" }] };
+        else if (property === true) converted = { tsType: `Exclude<${jsonType}, null>` };
+        else if (isJsonObject(property)) {
+          /** @type {Schema & {type: unknown[]}} */
+          const nonnull = { ...property, type: (Array.isArray(property.type) ? property.type : [property.type]).filter(t => t !== "null") };
+          if (Array.isArray(nonnull.enum)) nonnull.enum = nonnull.enum.filter(value => value !== null);
+          converted = nonnull.type.length === 0 || nonnull.const === null || (Array.isArray(nonnull.enum) && nonnull.enum.length === 0) ? false : convert(nonnull, location, mode);
+        }
+      }
+      return [key, converted];
+    });
+    for (const key of required) if (typeof key === "string" && isJsonObject(properties[key]) && properties[key].readOnly === true) diagnostic(at(at(pointer, "properties"), key), "required readOnly fields cannot be populated by the producer; default is not server generation. Make this field writable or optional.");
+    result.properties = Object.fromEntries(entries);
+    result.required = mode === "Patch" ? [] : required.filter(key => typeof key === "string" && (mode === "Document" || !isJsonObject(properties[key]) || properties[key].readOnly !== true));
+    const additional = input.additionalProperties;
+    if (additional === undefined || additional === true) {
+      // Separate the JSON index signature so the generator cannot widen it with
+      // undefined for optional properties (which SDK JSON inputs prohibit).
+      result.additionalProperties = false;
+      result.type = "object";
+      const object = { allOf: [result, { tsType: `Record<string, ${jsonType}>` }] };
+      return nullable ? { anyOf: [object, { type: "null" }] } : object;
+    }
+    if (additional !== false && Object.keys(properties).length) diagnostic(at(pointer, "additionalProperties"), "typed additional properties with named properties cannot be represented exactly; use a pure map or a closed object.");
+    let extra = convert(additional, at(pointer, "additionalProperties"), mode);
+    if (additional !== false && mode === "Patch") extra = { anyOf: [extra, { type: "null" }] };
+    result.additionalProperties = extra;
+    if (additional === false && entries.length === 0) return { tsType: `Record<string, never>${nullable ? " | null" : ""}` };
+  }
+  return result;
+}
+
+/** Fetch the authorized declared schema using the public SDK operation. @param {V1Collection} collection @param {string} name @param {import("./v1/terrabase-v1.js").V1RequestOptions} [options] */
+export async function generateCollectionModels(collection, name, options = {}) {
+  const { schema } = await collection.getSchema(options);
+  if (schema === null) diagnostic("", "collection has no declared JSON Schema; attach one with collection.putSchema(). Inference is not a declaration.");
+  return generateDocumentModels(schema, name);
+}

package/src/http.js

@@ -75,9 +75,6 @@ export class TsAuthHttp {
           ? JSON.stringify(options.body)
           : options.formBody?.toString();
       let attempt = 0;
-      let refreshed = false;
-      /** @type {string | undefined} */
-      let refreshedToken;
       while (true) {
         signal?.throwIfAborted();
         let responseReceived = false;
@@ -87,11 +84,10 @@ export class TsAuthHttp {
           const oidc = options.routeName.startsWith("tsauth.oidc.");
           const token = oidc
             ? undefined
-            : (refreshedToken ??
-              (await withCancellation(
+            : await withCancellation(
                 resolveAccessToken(this.#accessToken),
                 signal,
-              )));
+              );
           if (token !== undefined && token.length > 0)
             headers.set(
               "authorization",
@@ -133,19 +129,31 @@ export class TsAuthHttp {
                 ? "application/json"
                 : "application/x-www-form-urlencoded",
             );
+          /** @type {RequestInit & { duplex?: "half" }} */
+          const init = {
+            method: options.method,
+            headers,
+            redirect: "manual",
+            ...(signal === undefined ? {} : { signal }),
+            ...(body === undefined ? {} : { body }),
+          };
+          if (options.method !== "GET" && typeof process !== "undefined" && process.release?.name === "node") {
+            // Native Node fetch replays buffered mutations on 421, even with SDK retries disabled.
+            // Empty DELETEs also need a one-shot body. Keep JSON/form bytes and media types unchanged.
+            const bytes = body === undefined ? undefined : new TextEncoder().encode(body);
+            init.body = new ReadableStream({ start(controller) {
+              if (bytes !== undefined && bytes.byteLength > 0) controller.enqueue(bytes);
+              controller.close();
+            } });
+            init.duplex = "half";
+          }
           const request = new Request(
             buildUrl(
               this.config.apiBaseUrl,
               options.path,
               options.query,
             ),
-            {
-              method: options.method,
-              headers,
-              redirect: "manual",
-              ...(signal === undefined ? {} : { signal }),
-              ...(body === undefined ? {} : { body }),
-            },
+            init,
           );
           signal?.throwIfAborted();
           fetchStarted = true;
@@ -206,22 +214,6 @@ export class TsAuthHttp {
               /** @type {TResponse} */ (parsed.value),
             );
           }
-          if (
-            response.status === 401 &&
-            !oidc &&
-            !refreshed &&
-            typeof this.#accessToken === "function"
-          ) {
-            const next = await withCancellation(
-              resolveAccessToken(this.#accessToken),
-              signal,
-            );
-            if (next !== undefined && next.length > 0 && next !== token) {
-              refreshed = true;
-              refreshedToken = next;
-              continue;
-            }
-          }
           if (
             options.method === "GET" &&
             attempt < this.config.maxRetryAttempts &&

package/src/index.js

@@ -1,6 +1,6 @@
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
-// Project-scoped TerraBase API; shape support is retained for the historical release.
+// Project-scoped TerraBase API, including current free collection shape reads.
 export {
   createTerraBaseV1Client,
   TerraBaseV1Client,

package/src/ts-auth.js

@@ -2086,6 +2086,13 @@ export class TsAuthInstanceClient {
  *       readonly grant_type: "client_credentials";
  *       readonly scope: string;
  *       readonly resource: string;
+ *       readonly project?: never;
+ *     }
+ *   | {
+ *       readonly grant_type: "client_credentials";
+ *       readonly project: import("./ids.js").EntityId;
+ *       readonly scope?: string | undefined;
+ *       readonly resource?: never;
  *     }
  *   | {
  *       readonly grant_type: "urn:ietf:params:oauth:grant-type:device_code";
@@ -2245,6 +2252,8 @@ export class TsAuthOidcClient {
 
   /**
    * client_secret_post only. Omitted resource retains the stored code/device/refresh binding.
+   * Platform API keys use explicit project and optional subset scope, without resource
+   * (producer PlatformGrants.ApiKeyAsync and platform-api.openapi.yaml ClientCredentialsGrant).
    * @param {string} clientId
    * @param {string} clientSecret
    * @param {TsAuthOidcTokenRequest} request
@@ -2259,7 +2268,7 @@ export class TsAuthOidcClient {
         : request.grant_type === "refresh_token"
           ? ["grant_type", "refresh_token", "scope", "resource"]
           : request.grant_type === "client_credentials"
-            ? ["grant_type", "scope", "resource"]
+            ? ["grant_type", "scope", "project" in request ? "project" : "resource"]
             : request.grant_type ===
                 "urn:ietf:params:oauth:grant-type:device_code"
               ? ["grant_type", "device_code", "resource"]
@@ -2289,13 +2298,24 @@ export class TsAuthOidcClient {
       if (request.scope !== undefined)
         form.set("scope", requireOauthScope(request.scope));
     } else if (request.grant_type === "client_credentials") {
-      form.set("resource", requireResourceAudience(request.resource));
-      form.set("scope", requireOauthScope(request.scope));
+      if ("project" in request) {
+        form.set("project", requireId(request.project, "project"));
+        if (request.scope !== undefined) form.set("scope", requireOauthScope(request.scope));
+      } else {
+        form.set("resource", requireResourceAudience(request.resource));
+        form.set("scope", requireOauthScope(request.scope));
+      }
     } else {
       form.set("device_code", requireText(request.device_code, "device_code"));
     }
+    const projectScope = request.grant_type === "client_credentials" && "project" in request ? request.scope : undefined;
+    const pending = this.#postForm(`${this.#slug}/oauth/token`, "tsauth.oidc.token", form);
     return oauthResponse(
-      this.#postForm(`${this.#slug}/oauth/token`, "tsauth.oidc.token", form),
+      // TokenBody follows RFC 6749 §5.1: omitted scope equals the explicit requested scope.
+      // Snapshot it before dispatch; never infer a default or normalize other grant contracts.
+      projectScope === undefined ? pending : pending.then(result =>
+        result.ok && oauthRecord(result.value) && !Object.hasOwn(result.value, "scope")
+          ? { ...result, value: { ...result.value, scope: projectScope } } : result),
       /** @returns {value is TsAuthOidcTokenResponse} */
       (value) => isTokenResponse(value, grantType),
     );

package/src/v1/system.js

@@ -1,12 +1,14 @@
 import { decodeDocument } from "./decode.js";
 import { requireId } from "../ids.js";
 import { requireDocumentId, requireName } from "./ids.js";
-import { flag, list, nullable, numeric, record, text } from "./management-decode.js";
+import { flag, list, nullable, numeric, optional, record, text } from "./management-decode.js";
 import { members } from "./management-validation.js";
 import { decodeCollection, decodeQueryPage } from "./terrabase-v1.js";
 import { V1Transport } from "./transport.js";
 /** @import { V1RequestOptions } from "./terrabase-v1.js" */
-const status = record({ status: text, version: text, region: text, storageFormat: text, revision: nullable(text), machine: text });
+// Public probes omit build metadata; only the internal listener emits it.
+const status = record({ status: text, version: text, region: text,
+  storageFormat: optional(nullable(text)), revision: optional(nullable(text)), machine: optional(nullable(text)) });
 const replication = record({ region: text, status: text, maxLagSeconds: nullable(numeric),
   peers: list(record({ region: text, status: text, lagSeconds: nullable(numeric) })) });
 const databases = record({ items: list(record({ name: text, id: requireId, homeRegion: text, replicaRegions: list(text), allRegions: flag })) });

package/types/codegen-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/types/codegen.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Generate body models from a declared Draft 2020-12 schema, never inferred samples.
+ * Runtime validation remains authoritative; constraints such as ranges and lengths
+ * cannot be expressed by TypeScript. Patch is an RFC 7396 merge-patch body.
+ * @param {unknown} input
+ * @param {string} name A TypeScript identifier prefix.
+ * @returns {Promise<string>}
+ */
+export function generateDocumentModels(input: unknown, name: string): Promise<string>;
+/** Fetch the authorized declared schema using the public SDK operation. @param {V1Collection} collection @param {string} name @param {import("./v1/terrabase-v1.js").V1RequestOptions} [options] */
+export function generateCollectionModels(collection: V1Collection, name: string, options?: import("./v1/terrabase-v1.js").V1RequestOptions): Promise<string>;
+export type Schema = Record<string, unknown>;
+import type { V1Collection } from "./v1/terrabase-v1.js";

package/types/ts-auth.d.ts

@@ -1103,6 +1103,13 @@ export class TsAuthInstanceClient {
  *       readonly grant_type: "client_credentials";
  *       readonly scope: string;
  *       readonly resource: string;
+ *       readonly project?: never;
+ *     }
+ *   | {
+ *       readonly grant_type: "client_credentials";
+ *       readonly project: import("./ids.js").EntityId;
+ *       readonly scope?: string | undefined;
+ *       readonly resource?: never;
  *     }
  *   | {
  *       readonly grant_type: "urn:ietf:params:oauth:grant-type:device_code";
@@ -1206,6 +1213,8 @@ export class TsAuthOidcClient {
     deviceAuthorization(clientId: string, clientSecret: string, request?: TsAuthOidcDeviceAuthorizationRequest): Promise<TerraScaleResult<TsAuthOidcDeviceAuthorizationResponse>>;
     /**
      * client_secret_post only. Omitted resource retains the stored code/device/refresh binding.
+     * Platform API keys use explicit project and optional subset scope, without resource
+     * (producer PlatformGrants.ApiKeyAsync and platform-api.openapi.yaml ClientCredentialsGrant).
      * @param {string} clientId
      * @param {string} clientSecret
      * @param {TsAuthOidcTokenRequest} request
@@ -1766,6 +1775,12 @@ export type TsAuthOidcTokenRequest = {
     readonly grant_type: "client_credentials";
     readonly scope: string;
     readonly resource: string;
+    readonly project?: never;
+} | {
+    readonly grant_type: "client_credentials";
+    readonly project: import("./ids.js").EntityId;
+    readonly scope?: string | undefined;
+    readonly resource?: never;
 } | {
     readonly grant_type: "urn:ietf:params:oauth:grant-type:device_code";
     readonly device_code: string;

package/types/v1/system.d.ts

@@ -59,9 +59,9 @@ declare const status: import("./management-decode.js").Decoder<Readonly<{
     status: string;
     version: string;
     region: string;
-    storageFormat: string;
-    revision: string | null;
-    machine: string;
+    storageFormat: string | null | undefined;
+    revision: string | null | undefined;
+    machine: string | null | undefined;
 }>>;
 declare const replication: import("./management-decode.js").Decoder<Readonly<{
     region: string;