@terrascale/sdk 0.0.2 → 0.0.4

package/src/v1/sql.js

@@ -0,0 +1,98 @@
+import { array, boolean, malformed, object, string } from "./decode.js";
+import { requireDocumentId, requireName } from "./ids.js";
+/**
+ * @import { JsonObject, JsonValue } from "./json.js"
+ * @import { V1RequestOptions } from "./terrabase-v1.js"
+ * @import { V1Transport } from "./transport.js"
+ */
+
+/** @typedef {{ readonly id: string; readonly value: JsonObject }} V1SqlRow */
+/**
+ * SQL returns one bounded result, without a pagination cursor.
+ * @typedef {{ readonly matched: number; readonly truncated: boolean; readonly rows: readonly V1SqlRow[] }} V1SqlResult
+ */
+/** @typedef {{ readonly field: string; readonly reason: string }} V1SqlIndexSuggestion */
+/**
+ * @typedef {{
+ *   readonly ok: boolean;
+ *   readonly error: string | null;
+ *   readonly collection: string | null;
+ *   readonly hasLimit: boolean;
+ *   readonly plan: readonly string[];
+ *   readonly indexes: readonly string[];
+ *   readonly suggestions: readonly V1SqlIndexSuggestion[];
+ * }} V1SqlCheck
+ */
+
+/** @param {string} sql @param {V1RequestOptions} options @returns {string} */
+function requestBody(sql, options) {
+  if (typeof sql !== "string" || sql.length > 16_384)
+    throw new TypeError("SQL must be a string of at most 16384 UTF-16 code units.");
+  if (options === null || typeof options !== "object" || Array.isArray(options))
+    throw new TypeError("SQL request options must be an object.");
+  for (const member of Object.keys(options))
+    if (member !== "signal") throw new TypeError(`Unknown SQL request option ${member}.`);
+  // SQL syntax, including empty statements, stays producer-owned: check returns ok:false.
+  return JSON.stringify({ sql });
+}
+
+/** @param {JsonValue | undefined} value @returns {V1SqlResult} */
+function decodeResult(value) {
+  const raw = object(value, "SQL result");
+  const rows = array(raw.rows, "SQL rows").map(entry => {
+    const row = object(entry, "SQL row");
+    return Object.freeze({ id: requireDocumentId(row.id), value: object(row.value, "SQL row value") });
+  });
+  const matched = raw.matched;
+  if (typeof matched !== "number" || !Number.isInteger(matched) || matched < 0 || matched > 1000 || matched !== rows.length)
+    malformed("SQL matched count");
+  if (new Set(rows.map(row => row.id)).size !== rows.length) malformed("SQL row identities");
+  return Object.freeze({ matched, truncated: boolean(raw.truncated, "SQL truncation flag"), rows: Object.freeze(rows) });
+}
+
+/** @param {JsonValue | undefined} value @param {"checkSql" | "explainSql"} operation @returns {V1SqlCheck} */
+function decodeCheck(value, operation) {
+  const raw = object(value, "SQL check");
+  const ok = boolean(raw.ok, "SQL check flag");
+  const error = raw.error === null ? null : string(raw.error, "SQL check error");
+  const collection = raw.collection === null ? null : requireName("collection", raw.collection);
+  const hasLimit = boolean(raw.hasLimit, "SQL limit flag");
+  const plan = array(raw.plan, "SQL plan").map(step => string(step, "SQL plan step"));
+  const indexes = array(raw.indexes, "SQL indexes").map(index => string(index, "SQL index"));
+  const suggestions = array(raw.suggestions, "SQL index suggestions").map(entry => {
+    const suggestion = object(entry, "SQL index suggestion");
+    return Object.freeze({ field: string(suggestion.field, "SQL index field"), reason: string(suggestion.reason, "SQL index reason") });
+  });
+  if (ok ? error !== null || collection === null : error === null || error === "" || collection !== null || hasLimit || plan.length > 0 || indexes.length > 0 || suggestions.length > 0)
+    malformed("SQL check outcome");
+  if (operation === "explainSql" && !ok) malformed("SQL explain outcome");
+  return Object.freeze({ ok, error, collection, hasLimit, plan: Object.freeze(plan), indexes: Object.freeze(indexes), suggestions: Object.freeze(suggestions) });
+}
+
+/**
+ * Runs the producer's read-only SQL subset; it never converts a legacy SQL builder.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {string} sql
+ * @param {V1RequestOptions} [options]
+ * @returns {Promise<V1SqlResult>}
+ */
+export async function runSql(transport, database, sql, options = {}) {
+  const body = requestBody(sql, options);
+  return decodeResult((await transport.call("runSql", { database: requireName("database", database) }, { body, signal: options.signal })).value);
+}
+
+/**
+ * Check reports invalid SQL in a successful body; explain reports a producer HTTP error.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {string} sql
+ * @param {V1RequestOptions} [options]
+ * @param {"checkSql" | "explainSql"} [operation]
+ * @returns {Promise<V1SqlCheck>}
+ */
+export async function checkSql(transport, database, sql, options = {}, operation = "checkSql") {
+  if (operation !== "checkSql" && operation !== "explainSql") throw new TypeError("SQL checks use checkSql or explainSql.");
+  const body = requestBody(sql, options);
+  return decodeCheck((await transport.call(operation, { database: requireName("database", database) }, { body, signal: options.signal })).value, operation);
+}

package/src/v1/system.js

@@ -0,0 +1,80 @@
+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 { 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 });
+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 })) });
+/** @typedef {ReturnType<typeof status> & {readonly httpStatus: number}} V1ProbeStatus */
+/** @typedef {ReturnType<typeof replication>} V1ReplicationHealth */
+/** @typedef {ReturnType<typeof databases>} V1PlatformDatabases */
+/** @typedef {{ readonly baseUrl: string; readonly token?: string; readonly fetch?: import("../config.js").FetchLike; readonly maxResponseBytes?: number }} TerraBaseSystemClientConfig */
+
+/** Public anonymous probes; 503 readiness/backup bodies remain typed probe outcomes. */
+export class V1Health {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ProbeStatus>} */
+  async liveness(options = {}) {
+    const response = await this.#transport.call("healthz", {}, { signal: options.signal });
+    return Object.freeze({ ...status(response.value), httpStatus: response.status });
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ProbeStatus>} */
+  async readiness(options = {}) {
+    const response = await this.#transport.call("readyz", {}, { signal: options.signal });
+    return Object.freeze({ ...status(response.value), httpStatus: response.status });
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ProbeStatus>} */
+  async backup(options = {}) {
+    const response = await this.#transport.call("backupz", {}, { signal: options.signal });
+    return Object.freeze({ ...status(response.value), httpStatus: response.status });
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ReplicationHealth>} */
+  async replication(options = {}) { return replication((await this.#transport.call("replicationHealth", {}, { signal: options.signal })).value); }
+}
+/** The public read-only explore API requires a user JWT carrying platform_role=admin. */
+export class V1Platform {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1PlatformDatabases>} */
+  async databases(options = {}) { return databases((await this.#transport.call("listPlatformDatabases", {}, { signal: options.signal })).value); }
+  /** @param {"ts-auth" | "ts-dashboard"} database @param {V1RequestOptions} [options] */
+  async collections(database, options = {}) {
+    const response = await this.#transport.call("listPlatformCollections", { database: requireName("database", database) }, { signal: options.signal });
+    return record({ items: list(decodeCollection), next_cursor: nullable(text) })(response.value);
+  }
+  /** @param {"ts-auth" | "ts-dashboard"} database @param {string} collection @param {{ readonly limit?: number; readonly cursor?: string }} [request] @param {V1RequestOptions} [options] */
+  async documents(database, collection, request = {}, options = {}) {
+    members(request, ["limit", "cursor"]);
+    const query = new URLSearchParams();
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 1000) throw new TypeError("limit must be 1-1000.");
+      query.set("limit", String(request.limit));
+    }
+    if (request.cursor !== undefined) {
+      if (typeof request.cursor !== "string" || request.cursor === "") throw new TypeError("cursor must be non-empty.");
+      query.set("cursor", request.cursor);
+    }
+    return decodeQueryPage((await this.#transport.call("listPlatformDocuments", { database: requireName("database", database), collection: requireName("collection", collection) }, { query, signal: options.signal })).value);
+  }
+  /** @param {"ts-auth" | "ts-dashboard"} database @param {string} collection @param {string} id @param {V1RequestOptions} [options] */
+  async document(database, collection, id, options = {}) {
+    return decodeDocument((await this.#transport.call("getPlatformDocument", { database: requireName("database", database), collection: requireName("collection", collection) }, {
+      query: new URLSearchParams({ id: requireDocumentId(id) }), signal: options.signal,
+    })).value);
+  }
+}
+/** @param {TerraBaseSystemClientConfig} config */
+export function createTerraBaseSystemClient(config) {
+  const transport = new V1Transport(config);
+  return Object.freeze({ health: new V1Health(transport), platform: new V1Platform(transport) });
+}

package/src/v1/terrabase-v1.js

@@ -1,13 +1,26 @@
 // The TerraBase v1 client: documents, transactions, queries and shapes over
 // the project-scoped C# Documents API (decision 0004 and shape-reads.md).
 import {
-  array, boolean, decodeDocument, decodeWrite, durability, malformed, object, u64,
+  array, boolean, decodeDocument, decodeWrite, documentObject, durability, malformed, object, u64,
 } from "./decode.js";
+import { requireId } from "../ids.js";
 import { isJsonPointer, requireFilter, requirePath } from "./filter.js";
 import { requireDocumentId, requireName, requireVersion } from "./ids.js";
 import { assertJsonObject, assertJsonValue, ExactDecimal, stringifyExactJson } from "./json.js";
-import { readShape } from "./shapes.js";
+import { readShapeManifest } from "./shape-manifest.js";
+import { V1ShapeSubscription } from "./shape-subscription.js";
+import { decryptSealedShapePage, readShapePage, readShapeKey } from "./shape-reader.js";
+import { runSql, checkSql } from "./sql.js";
+import { streamChanges } from "./changes.js";
+import { V1Databases, getCollectionSchema, putCollectionSchema, deleteCollectionSchema } from "./catalog.js";
 import { V1Transport } from "./transport.js";
+import { V1Health, V1Platform } from "./system.js";
+import { V1Imports } from "./imports.js";
+import { V1Backups, V1BackupDestinationClient } from "./backups.js";
+import { V1ProjectUsageClient, V1DatabaseUsageClient } from "./usage.js";
+import { V1Indexes } from "./indexes.js";
+import { V1DatabaseSchemaClient } from "./database-schema.js";
+import { V1SavedQueries } from "./saved-queries.js";
 /**
  * @import { V1Document, V1Durability, V1WriteResult } from "./decode.js"
  * @import { V1Filter, V1Path } from "./filter.js"
@@ -37,6 +50,7 @@ import { V1Transport } from "./transport.js";
  * @typedef {{ readonly op: "set"; readonly path: string; readonly value: JsonInput }
  *   | { readonly op: "unset"; readonly path: string }
  *   | { readonly op: "inc"; readonly path: string; readonly by: number | bigint | ExactDecimal }
+ *   | { readonly op: "add" | "remove"; readonly path: string; readonly value: import("./filter.js").V1Scalar }
  *   | { readonly op: "append"; readonly path: string; readonly value: JsonInput }} V1PatchOp
  */
 /**
@@ -67,7 +81,7 @@ import { V1Transport } from "./transport.js";
 /**
  * One op's result: `id` and `version` for writes, `asserted` for asserts, and
  * also `count` (decimal u64) for `assertCount`.
- * @typedef {{ readonly id: string; readonly version: string } | { readonly asserted: true; readonly count?: string }} V1TransactionOpResult
+ * @typedef {{ readonly id: string; readonly version: string; readonly document?: import("./json.js").JsonObject } | { readonly asserted: true; readonly count?: string }} V1TransactionOpResult
  */
 /** @typedef {{ readonly gte?: number | undefined; readonly lte?: number | undefined }} V1CountBounds */
 /**
@@ -99,6 +113,9 @@ function patchOp(op) {
     case "unset": allowed = ["op", "path"]; break;
     case "inc": allowed = ["op", "path", "by"]; break;
   }
+  const path = pointer(op.path);
+  if (["inc", "add", "remove"].includes(op.op) && path.split("/").length !== 2)
+    throw new TypeError("inc, add and remove require a top-level field.");
   for (const key of Object.keys(op)) if (!allowed.includes(key)) throw new TypeError(`Unknown patch op member ${key}.`);
   switch (op.op) {
     case "set":
@@ -107,14 +124,30 @@ function patchOp(op) {
       return { op: op.op, path: pointer(op.path), value: op.value };
     case "unset":
       return { op: "unset", path: pointer(op.path) };
+    case "add":
+    case "remove": {
+      const value = op.value;
+      if (value !== null && typeof value !== "boolean" && typeof value !== "string" &&
+          typeof value !== "number" && typeof value !== "bigint" && !(value instanceof ExactDecimal))
+        throw new TypeError("add and remove require a JSON scalar of at most 1 KiB.");
+      assertJsonValue(value, "set element");
+      if (new TextEncoder().encode(stringifyExactJson(value, "set element")).byteLength > 1024)
+        throw new TypeError("add and remove require a JSON scalar of at most 1 KiB.");
+      return { op: op.op, path, value };
+    }
     case "inc": {
       const by = op.by;
-      if (!(typeof by === "bigint" || by instanceof ExactDecimal || (typeof by === "number" && Number.isFinite(by))))
-        throw new TypeError("inc takes a finite number, bigint or ExactDecimal.");
-      return { op: "inc", path: pointer(op.path), by };
+      if (!(typeof by === "bigint" || by instanceof ExactDecimal || (typeof by === "number" && Number.isSafeInteger(by))))
+        throw new TypeError("inc requires a non-zero signed 64-bit integer.");
+      const text = String(by);
+      if (!/^-?(?:0|[1-9]\d*)$/u.test(text)) throw new TypeError("inc requires an integer JSON literal.");
+      const integer = BigInt(text);
+      if (integer === 0n || integer < -(1n << 63n) || integer >= (1n << 63n))
+        throw new TypeError("inc requires a non-zero signed 64-bit integer.");
+      return { op: "inc", path, by };
     }
     default:
-      throw new TypeError("Patch ops are set, unset, inc or append.");
+      throw new TypeError("Patch ops are set, unset, inc, append, add or remove.");
   }
 }
 
@@ -184,7 +217,7 @@ function encodeQuery(query) {
  * @param {JsonValue | undefined} value
  * @returns {V1QueryPage}
  */
-function decodeQueryPage(value) {
+export function decodeQueryPage(value) {
   const raw = object(value, "query response");
   const next = raw.next_cursor;
   if (next !== null && (typeof next !== "string" || next === "")) malformed("next_cursor");
@@ -258,11 +291,12 @@ export class V1Collection {
   }
 
   /**
+   * The by-key route takes the raw document ID in the query, not the path.
    * @param {string} id
-   * @returns {Readonly<Record<string, string>>}
+   * @returns {URLSearchParams}
    */
-  #document(id) {
-    return { ...this.#params, id: requireDocumentId(id) };
+  #documentKey(id) {
+    return new URLSearchParams({ id: requireDocumentId(id) });
   }
 
   /**
@@ -276,7 +310,7 @@ export class V1Collection {
     /** @type {Record<string, string>} */
     const headers = {};
     if (options.ifNoneMatch !== undefined) headers["if-none-match"] = `"${requireVersion(options.ifNoneMatch)}"`;
-    const response = await this.#transport.call("getDocument", this.#document(id), { headers, signal: options.signal });
+    const response = await this.#transport.call("getDocument", this.#params, { query: this.#documentKey(id), headers, signal: options.signal });
     return decodeDocument(response.value);
   }
 
@@ -288,15 +322,14 @@ export class V1Collection {
    * @returns {Promise<V1WriteResult>}
    */
   async put(id, document, options = {}) {
-    const params = this.#document(id);
     const headers = preconditionHeaders(options, true);
-    return decodeWrite(await this.#transport.call("putDocument", params, {
-      body: encodeDocument(document), headers, signal: options.signal,
+    return decodeWrite(await this.#transport.call("putDocument", this.#params, {
+      query: this.#documentKey(id), body: encodeDocument(document), headers, signal: options.signal,
     }));
   }
 
   /**
-   * Creates a document under a server-generated UUIDv7.
+   * Creates a document under a server-generated ULID.
    * @param {JsonInputObject} document
    * @param {V1CreateOptions} [options]
    * @returns {Promise<V1WriteResult>}
@@ -315,14 +348,13 @@ export class V1Collection {
    * @returns {Promise<V1WriteResult>}
    */
   async patch(id, patch, options = {}) {
-    const params = this.#document(id);
     const headers = preconditionHeaders(options, false);
     const normalized = normalizePatch(patch);
     const [contentType, body] = "merge" in normalized
       ? ["application/merge-patch+json", stringifyExactJson(normalized.merge, "merge patch")]
       : ["application/vnd.terrabase.ops+json", stringifyExactJson({ ops: normalized.ops }, "patch ops")];
-    return decodeWrite(await this.#transport.call("patchDocument", params, {
-      body, contentType, headers,
+    return decodeWrite(await this.#transport.call("patchDocument", this.#params, {
+      query: this.#documentKey(id), body, contentType, headers,
       signal: options.signal,
     }));
   }
@@ -334,10 +366,9 @@ export class V1Collection {
    * @returns {Promise<V1WriteResult>}
    */
   async delete(id, options = {}) {
-    const params = this.#document(id);
     const headers = preconditionHeaders(options, false);
-    return decodeWrite(await this.#transport.call("deleteDocument", params, {
-      headers, signal: options.signal,
+    return decodeWrite(await this.#transport.call("deleteDocument", this.#params, {
+      query: this.#documentKey(id), headers, signal: options.signal,
     }));
   }
 
@@ -354,6 +385,29 @@ export class V1Collection {
     return decodeQueryPage(response.value);
   }
 
+  /** @param {{ readonly limit?: number | undefined; readonly cursor?: string | undefined }} [request] @param {V1RequestOptions} [options] @returns {Promise<V1QueryPage>} */
+  async list(request = {}, options = {}) {
+    for (const key of Object.keys(request)) if (key !== "limit" && key !== "cursor") throw new TypeError(`Unknown document list member ${key}.`);
+    const query = new URLSearchParams();
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 1000) throw new TypeError("Document list limit is 1-1000.");
+      query.set("limit", String(request.limit));
+    }
+    if (request.cursor !== undefined) {
+      if (typeof request.cursor !== "string" || request.cursor === "") throw new TypeError("Document cursor is a non-empty string.");
+      query.set("cursor", request.cursor);
+    }
+    const response = await this.#transport.call("listDocuments", this.#params, { query, signal: options.signal });
+    return decodeQueryPage(response.value);
+  }
+
+  /** @param {V1RequestOptions} [options] */
+  getSchema(options = {}) { return getCollectionSchema(this.#transport, this.#params, options); }
+  /** @param {import("./json.js").JsonInputObject | boolean} schema @param {V1RequestOptions} [options] */
+  putSchema(schema, options = {}) { return putCollectionSchema(this.#transport, this.#params, schema, options); }
+  /** @param {V1RequestOptions} [options] */
+  deleteSchema(options = {}) { return deleteCollectionSchema(this.#transport, this.#params, options); }
+
   /**
    * Iterates over every page, following `nextCursor`. `count`
    * is sent with the first page only.
@@ -364,9 +418,13 @@ export class V1Collection {
   async *pages(query = {}, options = {}) {
     /** @type {V1Query} */
     let current = query;
+    const cursors = new Set(query.cursor == null ? [] : [query.cursor]);
     while (true) {
       const page = await this.query(current, options);
+      if (page.nextCursor !== null && cursors.has(page.nextCursor)) malformed("repeated pagination cursor");
+      if (page.nextCursor !== null) cursors.add(page.nextCursor);
       yield page;
+      options.signal?.throwIfAborted();
       if (page.nextCursor === null) return;
       const { count: _count, ...rest } = current;
       current = { ...rest, cursor: page.nextCursor };
@@ -380,17 +438,51 @@ export class V1Collection {
    * @returns {AsyncGenerator<V1Document, void, undefined>}
    */
   async *items(query = {}, options = {}) {
-    for await (const page of this.pages(query, options)) yield* page.items;
+    for await (const page of this.pages(query, options)) {
+      for (const item of page.items) {
+        options.signal?.throwIfAborted();
+        yield item;
+      }
+    }
   }
   /**
    * Reads one C# shape snapshot page or change-log chunk. Bootstrap defaults to offset -1.
    * Echo handle, nextOffset and cursor on the following read; discard state on must_refetch.
+   * ifNoneMatch sends a complete entity-tag list or *; 304 throws not_modified with cache headers.
    * @param {V1ShapeRequest} [request]
-   * @param {V1RequestOptions} [options]
+   * @param {V1RequestOptions & {readonly ifNoneMatch?: string}} [options]
    * @returns {Promise<V1ShapePage>}
    */
   shape(request = {}, options = {}) {
-    return readShape(this.#transport, this.#params, request, options.signal);
+    return readShapePage(this.#transport, this.#params, request, options.signal, options.ifNoneMatch);
+  }
+
+  /**
+   * Subscribe to the free-read v1 protocol. Stop with close() or the request signal.
+   * @param {{where?: V1Filter | undefined}} [request]
+   * @param {import("./shape-subscription.js").V1ShapeSubscribeOptions} [options]
+   * @returns {V1ShapeSubscription}
+   */
+  subscribeShape(request = {}, options = {}) {
+    return new V1ShapeSubscription(this.#transport, this.#params, request, options);
+  }
+
+  /** @param {import("./shape-manifest.js").V1ShapeManifestRequest} request @param {V1RequestOptions} [options] */
+  shapeManifest(request, options = {}) { return readShapeManifest(this.#transport, this.#params, request, options.signal); }
+  /** @param {import("./shape-reader.js").V1ShapeKeyRequest} request @param {V1RequestOptions} [options] */
+  shapeKey(request, options = {}) { return readShapeKey(this.#transport, this.#params, request, options.signal); }
+
+
+  /**
+   * Verify a complete TBS1 object using its authenticated epoch key. Applies no state.
+   * Object delivery through manifests is pending the producer's FR-22 contract.
+   * @param {Uint8Array} bytes
+   * @param {import("./shape-reader.js").V1SealedShapePosition} position
+   * @param {V1RequestOptions} [options]
+   * @returns {Promise<V1ShapePage>}
+   */
+  decryptShapeObject(bytes, position, options = {}) {
+    return decryptSealedShapePage(this.#transport, this.#params, bytes, position, options.signal);
   }
 
 }
@@ -449,7 +541,7 @@ export class V1Transaction {
   static #precondition(precondition, allowNoneMatch) {
     if (precondition === undefined) return {};
     if ("ifMatch" in precondition && !("ifNoneMatchAny" in precondition))
-      return { if_match: precondition.ifMatch === "*" ? "*" : requireVersion(precondition.ifMatch) };
+      return { if_match: precondition.ifMatch === "*" ? "*" : `"${requireVersion(precondition.ifMatch)}"` };
     if ("ifNoneMatchAny" in precondition && precondition.ifNoneMatchAny === true && !("ifMatch" in precondition)) {
       if (!allowNoneMatch) throw new TypeError("This op does not take ifNoneMatchAny.");
       return { if_none_match: "*" };
@@ -459,7 +551,7 @@ export class V1Transaction {
 
   /**
    * Adds a create (a put requiring absence). Omit `id` to have the server
-   * generate a UUIDv7, returned in the op's result.
+   * generate a ULID, returned in the op's result.
    * @param {string} collection
    * @param {JsonInputObject} document
    * @param {string} [id]
@@ -589,19 +681,21 @@ export class V1Transaction {
           return Object.freeze(result.count === undefined
             ? { asserted: /** @type {const} */ (true) }
             : { asserted: /** @type {const} */ (true), count: u64(result.count, "assert_count count") });
-        return Object.freeze({ id: requireDocumentId(result.id), version: requireVersion(result.version) });
+        return Object.freeze({ id: requireDocumentId(result.id), version: requireVersion(result.version),
+          ...(result.document === undefined ? {} : { document: documentObject(result.document) }),
+        });
       })),
     });
   }
 }
 
-/** @typedef {{ readonly name: string; readonly createdAt: string }} V1CollectionInfo */
+/** @typedef {{ readonly id: import("../ids.js").EntityId; readonly name: string; readonly createdAt: string }} V1CollectionInfo */
 /** @typedef {{ readonly items: readonly V1CollectionInfo[]; readonly nextCursor: string | null }} V1CollectionPage */
 /** @typedef {{ readonly limit?: number | undefined; readonly cursor?: string | undefined }} V1CollectionListOptions */
 /** @param {JsonValue | undefined} value @returns {V1CollectionInfo} */
-function decodeCollection(value) {
+export function decodeCollection(value) {
   const raw = object(value, "collection");
-  return Object.freeze({ name: requireName("collection", raw.name), createdAt: u64(raw.created_at, "collection created_at") });
+  return Object.freeze({ id: requireId(raw.id), name: requireName("collection", raw.name), createdAt: u64(raw.created_at, "collection created_at") });
 }
 /** Collection management on the public client listener. */
 export class V1Collections {
@@ -655,6 +749,16 @@ export class V1Collections {
 
 /** A database handle by name. It performs no I/O until an operation runs. */
 export class V1Database {
+  /** @type {V1Imports} */
+  imports;
+  /** @type {V1Backups} */
+  backups;
+  /** @type {V1DatabaseUsageClient} */
+  metrics;
+  /** @type {V1Indexes} */
+  indexes;
+  /** @type {V1DatabaseSchemaClient} */
+  schema;
   /** @type {V1Collections} */
   collections;
   /** @type {V1Transport} */
@@ -670,6 +774,11 @@ export class V1Database {
     this.#transport = transport;
     this.name = requireName("database", name);
     this.collections = new V1Collections(transport, this.name);
+    this.schema = new V1DatabaseSchemaClient(transport, this.name);
+    this.indexes = new V1Indexes(transport, this.name);
+    this.metrics = new V1DatabaseUsageClient(transport, this.name);
+    this.backups = new V1Backups(transport, this.name);
+    this.imports = new V1Imports(transport, this.name);
     Object.freeze(this);
   }
 
@@ -686,20 +795,57 @@ export class V1Database {
     return new V1Transaction(this.#transport, this.name);
   }
 
+  /** @param {string} statement @param {V1RequestOptions} [options] */
+  sql(statement, options = {}) {
+    return runSql(this.#transport, this.name, statement, options);
+  }
+
+  /** @param {string} statement @param {V1RequestOptions} [options] */
+  checkSql(statement, options = {}) {
+    return checkSql(this.#transport, this.name, statement, options);
+  }
+
+  /** @param {string} statement @param {V1RequestOptions} [options] */
+  explainSql(statement, options = {}) {
+    return checkSql(this.#transport, this.name, statement, options, "explainSql");
+  }
 
+  /** @param {import("./changes.js").V1ChangeStreamRequest} [request] @param {V1RequestOptions} [options] */
+  changes(request = {}, options = {}) {
+    return streamChanges(this.#transport, this.name, request, options.signal);
+  }
 }
 
 /**
- * A TerraBase v1 data-plane client for one project and `tb_` API key. The key is held
+ * A TerraBase v1 data-plane client for one project and access token. The token is held
  * privately; it is never serialized, logged or forwarded to redirects.
  */
 export class TerraBaseV1Client {
+  /** @type {V1Health} */
+  #health;
+  /** @type {V1Platform} */
+  #platform;
+  /** @type {V1BackupDestinationClient} */
+  #backupDestination;
+  /** @type {V1ProjectUsageClient} */
+  #metrics;
+  /** @type {V1SavedQueries} */
+  #savedQueries;
+  /** @type {V1Databases} */
+  #databases;
   /** @type {V1Transport} */
   #transport;
 
   /** @param {TerraBaseV1ClientConfig} config */
   constructor(config) {
+    requireId(config.project);
     this.#transport = new V1Transport(config);
+    this.#databases = new V1Databases(this.#transport);
+    this.#savedQueries = new V1SavedQueries(this.#transport);
+    this.#metrics = new V1ProjectUsageClient(this.#transport);
+    this.#backupDestination = new V1BackupDestinationClient(this.#transport);
+    this.#health = new V1Health(this.#transport);
+    this.#platform = new V1Platform(this.#transport);
     Object.freeze(this);
   }
 
@@ -710,10 +856,23 @@ export class TerraBaseV1Client {
   database(name) {
     return new V1Database(this.#transport, name);
   }
+
+  /** @returns {V1Databases} Project-scoped database catalog. */
+  get databases() { return this.#databases; }
+  /** @returns {V1SavedQueries} */
+  get savedQueries() { return this.#savedQueries; }
+  /** @returns {V1ProjectUsageClient} */
+  get metrics() { return this.#metrics; }
+  /** @returns {V1BackupDestinationClient} */
+  get backupDestination() { return this.#backupDestination; }
+  /** @returns {V1Health} */
+  get health() { return this.#health; }
+  /** @returns {V1Platform} */
+  get platform() { return this.#platform; }
 }
 
 /**
- * Creates a TerraBase v1 client for documents, transactions, queries and shapes.
+ * Creates a project-scoped TerraBase client for documents, SQL, changes and catalog operations.
  * @param {TerraBaseV1ClientConfig} config
  * @returns {TerraBaseV1Client}
  */