@terrascale/sdk 0.0.3 → 0.0.5

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,27 @@
 // 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 { exportDocuments } from "./export.js";
+import { V1Databases, getCollectionSchema, putCollectionSchema, deleteCollectionSchema, getCollectionTtl, putCollectionTtl, deleteCollectionTtl } 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 +51,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
  */
 /**
@@ -44,12 +59,17 @@ import { V1Transport } from "./transport.js";
  * @typedef {{ readonly merge: JsonInputObject } | { readonly ops: readonly V1PatchOp[] }} V1Patch
  */
 
-/** @typedef {{ readonly path: V1Path; readonly order?: "asc" | "desc" | undefined }} V1SortKey */
+/** @typedef {{ readonly path: V1Path; readonly order?: "asc" | "desc" | undefined }} V1FieldSortKey */
+/**
+ * Vector similarity sort, nearest first. It must be the only sort key; limit is at most 100 and there is no cursor.
+ * @typedef {{ readonly near: { readonly path: V1Path; readonly vector: readonly number[]; readonly metric?: "cosine" | "l2" | undefined } }} V1NearSortKey
+ */
+/** @typedef {V1FieldSortKey | V1NearSortKey} V1SortKey */
 /**
  * A query-v1 request. Every member is optional.
  * @typedef {object} V1Query
  * @property {V1Filter | null | undefined} [filter]
- * @property {readonly V1SortKey[] | undefined} [sort] At most 4 keys; results are finally ordered by `$id`.
+ * @property {readonly V1SortKey[] | undefined} [sort] At most 4 keys, or one `near` key; results are finally ordered by `$id`.
  * @property {readonly string[] | undefined} [project] At most 64 paths.
  * @property {number | undefined} [limit] 1-1000 (server default 50).
  * @property {string | null | undefined} [cursor] A previous page's `nextCursor`.
@@ -67,7 +87,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 */
 /**
@@ -94,13 +114,14 @@ function pointer(path) {
  */
 function patchOp(op) {
   if (typeof op !== "object" || op === null || Array.isArray(op)) throw new TypeError("A patch op is an object.");
-  if (op.path === "/id" || op.path?.startsWith("/id/")) throw new TypeError("The document key is the entity ID; payloads must not contain an id field.");
-  if (op.path === "" && op.op === "set") assertNoPayloadId(op.value);
   let allowed = ["op", "path", "value"];
   switch (op.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":
@@ -109,14 +130,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.");
   }
 }
 
@@ -135,7 +172,6 @@ function normalizePatch(patch) {
   if (hasMerge) {
     const merge = /** @type {{ readonly merge: JsonInputObject }} */ (patch).merge;
     assertJsonObject(merge, "merge patch");
-    assertNoPayloadId(merge);
     return { merge };
   }
   const ops = /** @type {{ readonly ops: readonly V1PatchOp[] }} */ (patch).ops;
@@ -144,6 +180,26 @@ function normalizePatch(patch) {
   return { ops: ops.map(patchOp) };
 }
 
+/**
+ * @param {V1NearSortKey} key
+ * @param {V1Query} query
+ * @returns {Record<string, unknown>}
+ */
+function nearSort(key, query) {
+  if (Object.keys(key).length !== 1 || query.sort?.length !== 1) throw new TypeError("near is the only sort key and has no path or order beside it.");
+  if (query.cursor != null) throw new TypeError("A near query has one page and takes no cursor.");
+  if (query.limit !== undefined && query.limit > 100) throw new TypeError("A near query limit is at most 100.");
+  const near = key.near;
+  if (near === null || typeof near !== "object") throw new TypeError("near is an object.");
+  for (const member of Object.keys(near)) if (!["path", "vector", "metric"].includes(member)) throw new TypeError(`Unknown near member ${member}.`);
+  if (near.metric !== undefined && near.metric !== "cosine" && near.metric !== "l2") throw new TypeError('near metric is "cosine" or "l2".');
+  const vector = near.vector;
+  if (!Array.isArray(vector) || vector.length < 1 || vector.length > 4096) throw new TypeError("A near vector has 1-4096 numbers.");
+  if (!vector.every(value => typeof value === "number" && Math.abs(value) <= 3.4028234663852886e38)) throw new TypeError("near vector values are finite float32 numbers.");
+  if (near.metric !== "l2" && vector.every(value => value === 0)) throw new TypeError("A cosine near vector is not all zeros.");
+  return { near: { path: requirePath(near.path), vector: [...vector], ...(near.metric === undefined ? {} : { metric: near.metric }) } };
+}
+
 /**
  * @param {V1Query} query
  * @returns {string}
@@ -159,6 +215,7 @@ function encodeQuery(query) {
     if (!Array.isArray(query.sort) || query.sort.length > 4) throw new TypeError("sort has at most 4 keys.");
     body.sort = query.sort.map((key) => {
       if (key === null || typeof key !== "object") throw new TypeError("Sort keys are objects.");
+      if ("near" in key) return nearSort(key, query);
       for (const member of Object.keys(key)) if (member !== "path" && member !== "order") throw new TypeError(`Unknown sort member ${member}.`);
       if (key.order !== undefined && key.order !== "asc" && key.order !== "desc") throw new TypeError('Sort order is "asc" or "desc".');
       return { path: requirePath(key.path), ...(key.order === undefined ? {} : { order: key.order }) };
@@ -187,7 +244,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");
@@ -198,7 +255,13 @@ function decodeQueryPage(value) {
     count = Object.freeze({ value: u64(rawCount.value, "count value"), exact: boolean(rawCount.exact, "count exact flag") });
   }
   return Object.freeze({
-    items: Object.freeze(array(raw.items, "query items").map(decodeDocument)),
+    items: Object.freeze(array(raw.items, "query items").map(item => {
+      const distance = object(item, "document").distance;
+      if (distance === undefined) return decodeDocument(item);
+      const value = distance instanceof ExactDecimal ? distance.toNumber() : distance;
+      if (typeof value !== "number" || !Number.isFinite(value)) malformed("near distance");
+      return Object.freeze({ ...decodeDocument(item), distance: value });
+    })),
     nextCursor: typeof next === "string" && next !== "" ? next : null,
     count,
   });
@@ -231,18 +294,11 @@ function rejectIdempotency(options) {
 /** @param {JsonInputObject} document @returns {string} */
 function encodeDocument(document) {
   assertJsonObject(document, "document");
-  assertNoPayloadId(document);
   const body = stringifyExactJson(document, "document");
   if (new TextEncoder().encode(body).byteLength > 1024 * 1024) throw new TypeError("A document is at most 1 MiB.");
   return body;
 }
 
-/** @param {unknown} document @returns {void} */
-function assertNoPayloadId(document) {
-  if (typeof document === "object" && document !== null && Object.hasOwn(document, "id"))
-    throw new TypeError("The document key is the entity ID; payloads must not contain an id field.");
-}
-
 /** A collection handle by name. It performs no I/O until an operation runs. */
 export class V1Collection {
   /** @type {V1Transport} */
@@ -362,6 +418,38 @@ 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); }
+  /** @param {V1RequestOptions} [options] */
+  getTtl(options = {}) { return getCollectionTtl(this.#transport, this.#params, options); }
+  /**
+   * Documents whose member at `path` holds a past RFC 3339 UTC time are deleted by an hourly sweep (up to about an hour late).
+   * @param {string} path JSON Pointer such as `/expiresAt`. @param {V1RequestOptions} [options]
+   */
+  putTtl(path, options = {}) { return putCollectionTtl(this.#transport, this.#params, path, options); }
+  /** @param {V1RequestOptions} [options] */
+  deleteTtl(options = {}) { return deleteCollectionTtl(this.#transport, this.#params, options); }
+
   /**
    * Iterates over every page, following `nextCursor`. `count`
    * is sent with the first page only.
@@ -372,9 +460,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 };
@@ -388,17 +480,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);
   }
 
 }
@@ -457,7 +583,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: "*" };
@@ -597,19 +723,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 {
@@ -663,6 +791,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} */
@@ -678,6 +816,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);
   }
 
@@ -694,7 +837,33 @@ 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);
+  }
 
+  /**
+   * Streams every live document as `{ collection, id, document }`, in collection then id order, from one snapshot.
+   * @param {import("./export.js").V1ExportOptions} [options]
+   */
+  export(options = {}) {
+    return exportDocuments(this.#transport, this.name, options);
+  }
 }
 
 /**
@@ -702,12 +871,31 @@ export class V1Database {
  * 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);
   }
 
@@ -718,10 +906,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}
  */