@terrascale/sdk 0.0.2 → 0.0.4

package/src/v1/transport.js

@@ -15,10 +15,12 @@ import { v1Route, v1RoutePath } from "./routes.js";
 export const maximumRequestBytes = 4 * 1024 * 1024;
 // Query budgets count stored JSON before wrappers and serializer escaping.
 const defaultMaximumResponseBytes = 64 * 1024 * 1024;
-const tokenPattern = /^tb_[A-Za-z0-9_-]{43}$/u;
+// Validate header-safe credential syntax only; the producer validates JWT claims/signatures.
+// Retain C# keys; current project routes also authenticate project access JWTs.
+const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|tb_[A-Za-z0-9_-]{43})$/u;
 /**
  * Resolver input contains no credential. A successful URL is cached for this client/database.
- * @typedef {{ readonly project: string; readonly database: string; readonly signal?: AbortSignal | undefined }} V1EndpointContext
+ * @typedef {{ readonly project: string | undefined; readonly database?: string | undefined; readonly signal?: AbortSignal | undefined }} V1EndpointContext
  */
 /** @typedef {(context: V1EndpointContext) => string | Promise<string>} V1EndpointResolver */
 /**
@@ -26,7 +28,7 @@ const tokenPattern = /^tb_[A-Za-z0-9_-]{43}$/u;
  * URLs must use HTTPS or loopback HTTP. Mutations are never automatically replayed.
  * @typedef {object} TerraBaseV1ClientConfig
  * @property {string} project
- * @property {string} token A tb_ API key; held privately.
+ * @property {string} token A ts-auth project access JWT (or a legacy C# tb_ key); held privately.
  * @property {string | undefined} [baseUrl]
  * @property {V1EndpointResolver | undefined} [endpointResolver]
  * @property {FetchLike | undefined} [fetch]
@@ -35,11 +37,12 @@ const tokenPattern = /^tb_[A-Za-z0-9_-]{43}$/u;
 
 /**
  * @typedef {object} V1CallOptions
- * @property {string} [body]
+ * @property {string | Uint8Array} [body]
  * @property {string} [contentType]
  * @property {Readonly<Record<string, string>>} [headers] Contract headers only (If-Match, If-None-Match).
  * @property {URLSearchParams | undefined} [query]
  * @property {AbortSignal | undefined} [signal]
+ * @property {"no-store" | undefined} [cache] Authenticated shape epoch keys must bypass caches.
  */
 
 /**
@@ -123,32 +126,32 @@ export class BodyTransportError extends Error {
   }
 }
 
-/** Internal transport bound to one data key. */
+/** Internal transport bound to one project credential. */
 export class V1Transport {
-  /** @type {string} */
+  /** @type {string | undefined} */
   #project;
   /** @type {V1EndpointResolver} */
   #resolver;
   /** @type {Map<string, { promise: Promise<string>; timer: ReturnType<typeof setTimeout>; waiters: number }>} */
   #bases = new Map();
-  /** @type {string} */
+  /** @type {string | undefined} */
   #token;
   /** @type {FetchLike} */
   #fetch;
   /** @type {number} */
   #maxResponseBytes;
 
-  /** @param {TerraBaseV1ClientConfig} config */
+  /** @param {TerraBaseV1ClientConfig | (import("./system.js").TerraBaseSystemClientConfig & { project?: undefined; endpointResolver?: undefined })} config */
   constructor(config) {
     if (typeof config !== "object" || config === null) throw new TypeError("TerraBase v1 client config is required.");
-    this.#project = requireProject(config.project);
+    this.#project = config.project === undefined ? undefined : requireProject(config.project);
     if ((config.baseUrl === undefined) === (config.endpointResolver === undefined))
       throw new TypeError("Supply exactly one of baseUrl or endpointResolver.");
     if (config.endpointResolver !== undefined && typeof config.endpointResolver !== "function")
       throw new TypeError("endpointResolver must be a function.");
     this.#resolver = config.endpointResolver ?? staticBaseUrlResolver(/** @type {string} */ (config.baseUrl));
-    if (typeof config.token !== "string" || !tokenPattern.test(config.token))
-      throw new TypeError("token must be a tb_ API key with 43 base64url characters.");
+    if ((config.project !== undefined || config.token !== undefined) && (typeof config.token !== "string" || !tokenPattern.test(config.token)))
+      throw new TypeError("token must be a compact access JWT or a legacy C# tb_ API key.");
     if ("autoIdempotencyKey" in config || "maxRetries" in config || "resolver" in config)
       throw new TypeError("Unsupported client configuration member.");
     const fetchHandler = config.fetch ?? globalThis.fetch?.bind(globalThis);
@@ -169,8 +172,9 @@ export class V1Transport {
    */
   async url(operation, params, signal) {
     signal?.throwIfAborted();
-    const database = requireName("database", params.database);
-    let base = this.#bases.get(database);
+    const database = v1Route(operation).pathTemplate.includes("{database}") ? requireName("database", params.database) : undefined;
+    const session = database ?? "";
+    let base = this.#bases.get(session);
     if (base === undefined) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(new DOMException(
@@ -180,13 +184,13 @@ export class V1Transport {
       const promise = new Promise((resolve, reject) => {
         controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true });
         void Promise.resolve().then(() => this.#resolver(Object.freeze({
-          project: this.#project, database, signal: controller.signal,
+          project: this.#project, ...(database === undefined ? {} : { database }), signal: controller.signal,
         }))).then(canonicalBaseUrl).then(resolve, reject).finally(() => clearTimeout(timer));
       });
       base = { promise, timer, waiters: 0 };
-      this.#bases.set(database, base);
+      this.#bases.set(session, base);
       // A failed resolution is not a session; a later operation may resolve again.
-      void promise.catch(() => { if (this.#bases.get(database) === base) this.#bases.delete(database); });
+      void promise.catch(() => { if (this.#bases.get(session) === base) this.#bases.delete(session); });
     }
     base.waiters++;
     if (typeof base.timer === "object") base.timer.ref();
@@ -204,7 +208,8 @@ export class V1Transport {
         });
       });
       signal?.throwIfAborted();
-      return `${resolved}${v1RoutePath(v1Route(operation), { ...params, project: this.#project })}`;
+      if (v1Route(operation).pathTemplate.includes("{project}") && this.#project === undefined) throw new TypeError("This operation requires a project client.");
+      return `${resolved}${v1RoutePath(v1Route(operation), { ...params, ...(this.#project === undefined ? {} : { project: this.#project }) })}`;
     } finally {
       // Keep Node alive only while callers are waiting for this resolution.
       if (--base.waiters === 0 && typeof base.timer === "object") base.timer.unref();
@@ -215,9 +220,11 @@ export class V1Transport {
    * Reads a response body as UTF-8 text within the response byte bound. A
    * connection failure while reading is a BodyTransportError.
    * @param {Response} response
+   * @param {AbortSignal | undefined} [signal]
    * @returns {Promise<string>}
    */
-  async readText(response) {
+  async readText(response, signal) {
+    signal?.throwIfAborted();
     const reader = response.body?.getReader();
     if (reader === undefined) return "";
     /** @type {Uint8Array[]} */
@@ -225,13 +232,16 @@ export class V1Transport {
     let size = 0;
     try {
       while (true) {
+        signal?.throwIfAborted();
         /** @type {ReadableStreamReadResult<Uint8Array>} */
         let part;
         try {
           part = await reader.read();
         } catch (error) {
+          signal?.throwIfAborted();
           throw new BodyTransportError(error);
         }
+        signal?.throwIfAborted();
         if (part.done) break;
         size += part.value.byteLength;
         if (size > this.#maxResponseBytes)
@@ -250,16 +260,17 @@ export class V1Transport {
       bytes.set(part, offset);
       offset += part.byteLength;
     }
-    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
   }
 
   /**
    * Parses a JSON response body exactly.
    * @param {Response} response
+   * @param {AbortSignal | undefined} [signal]
    * @returns {Promise<JsonValue | undefined>}
    */
-  async readJson(response) {
-    return V1Transport.#decodeJson(response, await this.readText(response));
+  async readJson(response, signal) {
+    return V1Transport.#decodeJson(response, await this.readText(response, signal));
   }
 
   /**
@@ -278,13 +289,15 @@ export class V1Transport {
   /**
    * Converts a non-success response to a TerraBaseV1Error.
    * @param {Response} response
+   * @param {AbortSignal | undefined} [signal]
    * @returns {Promise<TerraBaseV1Error>}
    */
-  async error(response) {
+  async error(response, signal) {
     let text = "";
     try {
-      text = await this.readText(response);
+      text = await this.readText(response, signal);
     } catch {
+      signal?.throwIfAborted();
       text = "";
     }
     return parseV1Error(response.status, response.headers, text);
@@ -298,27 +311,60 @@ export class V1Transport {
    * @returns {Promise<V1CallResult>}
    */
   async call(operation, params, options = {}) {
+    const response = await this.#send(operation, params, options);
+    if (response.status === 307) {
+      await response.body?.cancel();
+      return { status: response.status, headers: response.headers, value: undefined };
+    }
+    return { status: response.status, headers: response.headers, value: await this.readJson(response, options.signal) };
+  }
+
+  /**
+   * @param {"streamDatabaseChanges"} operation
+   * @param {Readonly<Record<string, string>>} params
+   * @param {V1CallOptions} [options]
+   * @returns {Promise<Response>}
+   */
+  async openStream(operation, params, options = {}) {
+    const response = await this.#send(operation, params, options);
+    const mediaType = response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
+    if (mediaType !== "text/event-stream" || response.body === null) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new TypeError("TerraBase changes require a text/event-stream response body.");
+    }
+    return response;
+  }
+
+  /** @param {V1Operation} operation @param {Readonly<Record<string, string>>} params @param {V1CallOptions} options @returns {Promise<Response>} */
+  async #send(operation, params, options) {
     const route = v1Route(operation);
-    if (options.body !== undefined && new TextEncoder().encode(options.body).byteLength > maximumRequestBytes)
+    const bytes = typeof options.body === "string" ? new TextEncoder().encode(options.body) : options.body;
+    if (bytes !== undefined && bytes.byteLength > maximumRequestBytes)
       throw new TypeError(`TerraBase request bodies are limited to ${maximumRequestBytes} bytes.`);
     let url = await this.url(operation, params, options.signal);
     if (options.query !== undefined && options.query.size > 0) url += `?${options.query}`;
     const headers = new Headers(options.headers);
-    headers.set("authorization", `Bearer ${this.#token}`);
-    headers.set("accept", route.responseMediaType);
+    if (route.permission !== "anonymous" && this.#token !== undefined) headers.set("authorization", `Bearer ${this.#token}`);
+    if (route.responseMediaType !== "") headers.set("accept", route.responseMediaType);
     if (options.body !== undefined) headers.set("content-type", options.contentType ?? "application/json");
-    /** @type {RequestInit} */
+    /** @type {RequestInit & { duplex?: "half" }} */
     const init = { method: route.method, headers, redirect: "manual" };
-    if (options.body !== undefined) init.body = options.body;
+    if (options.cache !== undefined) init.cache = options.cache;
+    if (route.permission.endsWith(":write") && typeof process !== "undefined" && process.release?.name === "node") {
+      // Node fetch replays buffered or absent bodies on 421; use a one-shot stream, including DELETE.
+      if (operation === "uploadImportSource" && bytes !== undefined) headers.set("content-length", String(bytes.byteLength));
+      init.body = new ReadableStream({ start(controller) { if (bytes !== undefined && bytes.byteLength > 0) controller.enqueue(bytes); controller.close(); } });
+      init.duplex = "half";
+    } else if (options.body !== undefined) init.body = typeof options.body === "string" ? options.body : options.body.slice().buffer;
     if (options.signal !== undefined) init.signal = options.signal;
     const response = await this.#fetch(url, init);
+    if (options.signal?.aborted) {
+      void response.body?.cancel().catch(() => undefined);
+      options.signal.throwIfAborted();
+    }
     if (response.type === "opaqueredirect")
       throw new TypeError("Fresh shape bootstrap requires server fetch; obtain a handle and snapshot offset with collection.shape() on your server.");
-    if (!route.successStatuses.includes(response.status)) throw await this.error(response);
-    if (response.status === 307) {
-      await response.body?.cancel();
-      return { status: response.status, headers: response.headers, value: undefined };
-    }
-    return { status: response.status, headers: response.headers, value: await this.readJson(response) };
+    if (!route.successStatuses.includes(response.status)) throw await this.error(response, options.signal);
+    return response;
   }
 }

package/src/v1/usage.js

@@ -0,0 +1,101 @@
+import { requireId } from "../ids.js";
+import { requireName } from "./ids.js";
+import { dictionary, flag, list, nullable, numeric, record, text } from "./management-decode.js";
+import { members } from "./management-validation.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const period = record({ from: text, to: text, granularity: text, reads: numeric, writes: numeric });
+const series = list(record({ start: text, reads: numeric, writes: numeric }));
+const databaseUsage = record({ databaseId: requireId, storageBytes: numeric, logicalBytes: numeric, collections: numeric,
+  documents: numeric, reads: numeric, writes: numeric, period, series });
+const projectUsage = record({ projectId: requireId, databases: numeric, storageBytes: numeric, logicalBytes: numeric,
+  documents: numeric, reads: numeric, writes: numeric, period, series, items: list(databaseUsage) });
+const bandwidth = record({ bytesSent: numeric, bytesReceived: numeric });
+const directedBandwidth = list(record({ sourceRegion: text, destinationRegion: text, kind: text, bytesSent: numeric, bytesReceived: numeric }));
+const latency = record({ p50Ms: nullable(numeric), p95Ms: nullable(numeric), p99Ms: nullable(numeric) });
+const analytics = record({ projectId: requireId, range: text, from: text, to: text, bucketSeconds: numeric,
+  items: list(record({ databaseId: requireId, databaseName: text, region: text,
+    series: list(record({ start: text, requests: dictionary(numeric), operations: dictionary(numeric), errors: numeric,
+      latency, storageBytes: nullable(numeric), clientBandwidth: bandwidth, replicationBandwidth: bandwidth })) })) });
+const replication = record({ projectId: requireId, range: text, from: text, to: text, bucketSeconds: numeric,
+  items: list(record({ databaseId: requireId, databaseName: text, region: text, status: text, replicatedOps: numeric,
+    lagMs: nullable(numeric), divergence: nullable(flag), convergenceMs: nullable(numeric), lastApplied: nullable(text),
+    bandwidth: directedBandwidth, series: list(record({ start: text, replicatedOps: numeric, bandwidth: directedBandwidth })) })) });
+/** @typedef {ReturnType<typeof databaseUsage>} V1DatabaseUsage */
+/** @typedef {ReturnType<typeof projectUsage>} V1ProjectUsage */
+/** @typedef {ReturnType<typeof analytics>} V1Analytics */
+/** @typedef {ReturnType<typeof replication>} V1Replication */
+/** @typedef {{ readonly granularity?: "hour" | "day"; readonly from?: string; readonly to?: string }} V1UsageRequest */
+/** @typedef {{ readonly range?: "1h" | "24h" | "7d" | "30d"; readonly database?: string; readonly region?: string }} V1AnalyticsRequest */
+/** @param {V1UsageRequest} request */
+function usageQuery(request) {
+  members(request, ["granularity", "from", "to"]);
+  const query = new URLSearchParams();
+  if (request.granularity !== undefined) {
+    if (!["hour", "day"].includes(request.granularity)) throw new TypeError("granularity must be hour or day.");
+    query.set("granularity", request.granularity);
+  }
+  for (const name of /** @type {const} */ (["from", "to"])) {
+    const value = request[name];
+    if (value === undefined) continue;
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,7})?(?:Z|[+-]\d{2}:\d{2})$/u.test(value) || !Number.isFinite(Date.parse(value)))
+      throw new TypeError("from and to must be RFC 3339 instants.");
+    query.set(name, value);
+  }
+  return query;
+}
+/** @param {V1AnalyticsRequest} request @param {boolean} project */
+function analyticsQuery(request, project) {
+  members(request, project ? ["range", "database", "region"] : ["range", "region"]);
+  const query = new URLSearchParams();
+  if (request.range !== undefined) {
+    if (!["1h", "24h", "7d", "30d"].includes(request.range)) throw new TypeError("Invalid analytics range.");
+    query.set("range", request.range);
+  }
+  if (request.database !== undefined) query.set("database", requireId(request.database));
+  if (request.region !== undefined) {
+    if (typeof request.region !== "string" || !/^[a-z][a-z0-9-]{0,62}$/u.test(request.region)) throw new TypeError("Invalid region.");
+    query.set("region", request.region);
+  }
+  return query;
+}
+
+/** Project and database usage retain the producer's separate response envelopes. */
+export class V1ProjectUsageClient {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1UsageRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1ProjectUsage>} */
+  async usage(request = {}, options = {}) {
+    return projectUsage((await this.#transport.call("getProjectUsage", {}, { query: usageQuery(request), signal: options.signal })).value);
+  }
+  /** @param {V1AnalyticsRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Analytics>} */
+  async analytics(request = {}, options = {}) {
+    return analytics((await this.#transport.call("getProjectAnalytics", {}, { query: analyticsQuery(request, true), signal: options.signal })).value);
+  }
+  /** @param {V1AnalyticsRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Replication>} */
+  async replication(request = {}, options = {}) {
+    return replication((await this.#transport.call("getProjectReplication", {}, { query: analyticsQuery(request, true), signal: options.signal })).value);
+  }
+}
+export class V1DatabaseUsageClient {
+  /** @type {V1Transport} */
+  #transport;
+  /** @type {{database: string}} */
+  #params;
+  /** @param {V1Transport} transport @param {string} database */
+  constructor(transport, database) { this.#transport = transport; this.#params = { database: requireName("database", database) }; Object.freeze(this); }
+  /** @param {V1UsageRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1DatabaseUsage>} */
+  async usage(request = {}, options = {}) {
+    return databaseUsage((await this.#transport.call("getDatabaseUsage", this.#params, { query: usageQuery(request), signal: options.signal })).value);
+  }
+  /** @param {Omit<V1AnalyticsRequest, "database">} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Analytics>} */
+  async analytics(request = {}, options = {}) {
+    return analytics((await this.#transport.call("getDatabaseAnalytics", this.#params, { query: analyticsQuery(request, false), signal: options.signal })).value);
+  }
+  /** @param {Omit<V1AnalyticsRequest, "database">} [request] @param {V1RequestOptions} [options] @returns {Promise<V1Replication>} */
+  async replication(request = {}, options = {}) {
+    return replication((await this.#transport.call("getDatabaseReplication", this.#params, { query: analyticsQuery(request, false), signal: options.signal })).value);
+  }
+}

package/types/database-codec.d.ts

@@ -1,9 +1,3 @@
-/**
- * @param {unknown} value
- * @param {string} [name]
- * @returns {string}
- */
-export function requireDatabaseUuid(value: unknown, name?: string): string;
 /**
  * @param {unknown} value
  * @param {string} [name]
@@ -88,6 +82,7 @@ export function encodeDatabaseCommit(scope: DatabaseScope, commit: DatabaseCommi
     readonly body: string;
     readonly effect_digest: string;
 }>;
+export { requireId as requireDatabaseId } from "./ids.js";
 export type Budget = {
     nodes: number;
 };

package/types/database-types.d.ts

@@ -1,17 +1,17 @@
 /**
- * The current TerraBase document protocol uses canonical UUID entity IDs.
+ * Entity identities are canonical uppercase ULIDs, including explicit local development.
  */
-export type CanonicalUuid = string;
+export type EntityId = import("./ids.js").EntityId;
 /**
  * All 64-bit quantities stay bigint in JavaScript and decimal strings on the wire.
  */
 export type DatabaseScope = {
-    readonly tenant: CanonicalUuid;
-    readonly database: CanonicalUuid;
+    readonly tenant: EntityId;
+    readonly database: EntityId;
     readonly shard: bigint;
 };
 export type CollectionBinding = {
-    readonly collection: CanonicalUuid;
+    readonly collection: EntityId;
     readonly schema_generation: bigint;
     readonly schema_digest: string;
 };
@@ -44,12 +44,12 @@ export type DatabaseField = {
     readonly value: DatabaseValue;
 };
 export type DatabaseObserved = {
-    readonly replica: CanonicalUuid;
+    readonly replica: EntityId;
     readonly incarnation: string;
     readonly sequence: bigint;
 };
 export type DatabaseEvent = DatabaseObserved & {
-    readonly database: CanonicalUuid;
+    readonly database: EntityId;
     readonly shard: bigint;
 };
 export type DatabaseAuthority = ({
@@ -58,7 +58,7 @@ export type DatabaseAuthority = ({
     readonly mode: "single_writer";
     readonly generation: bigint;
     readonly writer: {
-        readonly replica: CanonicalUuid;
+        readonly replica: EntityId;
         readonly incarnation: string;
     };
 });
@@ -77,7 +77,7 @@ export type DatabaseWriteValue = ({
     readonly kind: "tombstone";
 });
 export type DatabaseWrite = CollectionBinding & {
-    readonly document: CanonicalUuid;
+    readonly document: EntityId;
     readonly condition: DatabaseCondition;
     readonly observed: readonly DatabaseObserved[];
     readonly value: DatabaseWriteValue;
@@ -121,7 +121,7 @@ export type DatabaseQuery = {
     readonly cursor?: string;
 };
 export type DatabaseQueryRow = {
-    readonly document: CanonicalUuid;
+    readonly document: EntityId;
     readonly point: DatabasePoint;
 };
 export type DatabaseQueryPage = {
@@ -188,7 +188,7 @@ export type DatabaseSubscriptionRequest = ({
     readonly poll_cursor: string;
 });
 export type DatabaseSubscriptionEffect = {
-    readonly document: CanonicalUuid;
+    readonly document: EntityId;
     readonly point: DatabasePoint | null;
 };
 export type DatabaseSubscriptionGroup = {

package/types/http.d.ts

@@ -1,12 +1,7 @@
 /** Private transport for the named hosted identity and OIDC operations. */
 export class TsAuthHttp {
-    /**
-     * @param {TsAuthRuntimeConfig} config
-     * @param {{ readonly authReverseProxy?: boolean }} [options]
-     */
-    constructor(config: TsAuthRuntimeConfig, options?: {
-        readonly authReverseProxy?: boolean;
-    });
+    /** @param {TsAuthRuntimeConfig} config */
+    constructor(config: TsAuthRuntimeConfig);
     /**
      * @readonly
      * @type {ResolvedTsAuthRuntimeConfig}
@@ -39,7 +34,6 @@ export type TsAuthRequest<TBody> = {
     readonly formBody?: URLSearchParams | string | undefined;
     readonly userinfoAccessToken?: string | undefined;
     readonly resourceIntrospectionBasic?: string | undefined;
-    readonly issuer?: string | undefined;
     readonly signal?: AbortSignal | undefined;
 };
 import type { ResolvedTsAuthRuntimeConfig } from "./config.js";

package/types/ids.d.ts

@@ -0,0 +1,10 @@
+/** @returns {EntityId} Monotonic within a millisecond, including clock rollback. */
+export function generateId(): EntityId;
+/** @param {unknown} value @returns {value is EntityId} */
+export function isValidId(value: unknown): value is EntityId;
+/** @param {unknown} value @param {string} [name] @returns {EntityId} */
+export function requireId(value: unknown, name?: string): EntityId;
+/**
+ * A plain 26-character, uppercase Crockford ULID.
+ */
+export type EntityId = string;

package/types/index.d.ts

@@ -1,7 +1,16 @@
 export { v1Filter } from "./v1/filter.js";
-export { documentIdFor } from "./v1/ids.js";
+export { V1ShapeSubscription } from "./v1/shape-subscription.js";
 export { ExactDecimal } from "./v1/json.js";
 export { staticBaseUrlResolver } from "./v1/transport.js";
+export { V1Databases } from "./v1/catalog.js";
+export { V1SavedQueries } from "./v1/saved-queries.js";
+export { V1DatabaseSchemaClient } from "./v1/database-schema.js";
+export { V1Indexes } from "./v1/indexes.js";
+export { V1Imports } from "./v1/imports.js";
+export type V1ShapeSubscribeOptions = import("./v1/shape-subscription.js").V1ShapeSubscribeOptions;
+export type V1ShapeDocument = import("./v1/shape-subscription.js").V1ShapeDocument;
+export type V1SealedShapePosition = import("./v1/shape-reader.js").V1SealedShapePosition;
+export type EntityId = import("./ids.js").EntityId;
 export type TerraBaseV1ClientConfig = import("./v1/transport.js").TerraBaseV1ClientConfig;
 export type V1RequestOptions = import("./v1/terrabase-v1.js").V1RequestOptions;
 export type V1ReadOptions = import("./v1/terrabase-v1.js").V1ReadOptions;
@@ -31,6 +40,9 @@ export type V1JsonInputObject = import("./v1/json.js").JsonInputObject;
 export type V1ShapeRequest = import("./v1/shapes.js").V1ShapeRequest;
 export type V1ShapeChange = import("./v1/shapes.js").V1ShapeChange;
 export type V1ShapeOp = import("./v1/shapes.js").V1ShapeOp;
+export type V1SavedQuery = import("./v1/saved-queries.js").V1SavedQuery;
+export type V1SavedQueryRequest = import("./v1/saved-queries.js").V1SavedQueryRequest;
+export type V1SavedQueryPage = import("./v1/saved-queries.js").V1SavedQueryPage;
 export type TerraBaseClientConfig = import("./v1/transport.js").TerraBaseV1ClientConfig;
 export type V1EndpointContext = import("./v1/transport.js").V1EndpointContext;
 export type V1EndpointResolver = import("./v1/transport.js").V1EndpointResolver;
@@ -38,6 +50,63 @@ export type V1CollectionInfo = import("./v1/terrabase-v1.js").V1CollectionInfo;
 export type V1CollectionPage = import("./v1/terrabase-v1.js").V1CollectionPage;
 export type V1CollectionListOptions = import("./v1/terrabase-v1.js").V1CollectionListOptions;
 export type V1ShapePage = import("./v1/shapes.js").V1ShapePage;
+export type V1SqlRow = import("./v1/sql.js").V1SqlRow;
+export type V1SqlResult = import("./v1/sql.js").V1SqlResult;
+export type V1SqlIndexSuggestion = import("./v1/sql.js").V1SqlIndexSuggestion;
+export type V1SqlCheck = import("./v1/sql.js").V1SqlCheck;
+export type V1ChangeStreamRequest = import("./v1/changes.js").V1ChangeStreamRequest;
+export type V1DatabaseChange = import("./v1/changes.js").V1DatabaseChange;
+export type V1DatabaseChangeCursor = import("./v1/changes.js").V1DatabaseChangeCursor;
+export type V1ManagedDatabase = import("./v1/catalog.js").V1ManagedDatabase;
+export type V1DatabaseCreateRequest = import("./v1/catalog.js").V1DatabaseCreateRequest;
+export type V1DatabaseUpdateRequest = import("./v1/catalog.js").V1DatabaseUpdateRequest;
+export type V1DatabaseBranchRequest = import("./v1/catalog.js").V1DatabaseBranchRequest;
+export type V1DatabaseListRequest = import("./v1/catalog.js").V1DatabaseListRequest;
+export type V1DatabasePage = import("./v1/catalog.js").V1DatabasePage;
+export type V1CollectionSchema = import("./v1/catalog.js").V1CollectionSchema;
+export type V1InferredSchema = import("./v1/database-schema.js").V1InferredSchema;
+export type V1DatabaseSchema = import("./v1/database-schema.js").V1DatabaseSchema;
+export type V1UniqueSchema = import("./v1/database-schema.js").V1UniqueSchema;
+export type V1UniqueSchemaRequest = import("./v1/database-schema.js").V1UniqueSchemaRequest;
+export type V1QueryShapes = import("./v1/database-schema.js").V1QueryShapes;
+export type V1Index = import("./v1/indexes.js").V1Index;
+export type V1IndexList = import("./v1/indexes.js").V1IndexList;
+export type V1AutoIndexPolicy = import("./v1/indexes.js").V1AutoIndexPolicy;
+export type V1IndexRecommendations = import("./v1/indexes.js").V1IndexRecommendations;
+export type V1AppliedIndexRecommendation = import("./v1/indexes.js").V1AppliedIndexRecommendation;
+export type V1CreateIndexRequest = import("./v1/indexes.js").V1CreateIndexRequest;
+export type V1DatabaseUsage = import("./v1/usage.js").V1DatabaseUsage;
+export type V1ProjectUsage = import("./v1/usage.js").V1ProjectUsage;
+export type V1Analytics = import("./v1/usage.js").V1Analytics;
+export type V1Replication = import("./v1/usage.js").V1Replication;
+export type V1UsageRequest = import("./v1/usage.js").V1UsageRequest;
+export type V1AnalyticsRequest = import("./v1/usage.js").V1AnalyticsRequest;
+export type V1Backup = import("./v1/backups.js").V1Backup;
+export type V1BackupPage = import("./v1/backups.js").V1BackupPage;
+export type V1BackupPolicy = import("./v1/backups.js").V1BackupPolicy;
+export type V1RestoreWindow = import("./v1/backups.js").V1RestoreWindow;
+export type V1PointInTimePlan = import("./v1/backups.js").V1PointInTimePlan;
+export type V1RestoredDatabase = import("./v1/backups.js").V1RestoredDatabase;
+export type V1BackupDestination = import("./v1/backups.js").V1BackupDestination;
+export type V1BackupPolicyRequest = import("./v1/backups.js").V1BackupPolicyRequest;
+export type V1PointInTimeRequest = import("./v1/backups.js").V1PointInTimeRequest;
+export type V1PointInTimeRestoreRequest = import("./v1/backups.js").V1PointInTimeRestoreRequest;
+export type V1BackupDestinationRequest = import("./v1/backups.js").V1BackupDestinationRequest;
+export type V1ImportJob = import("./v1/imports.js").V1ImportJob;
+export type V1ImportOptions = import("./v1/imports.js").V1ImportOptions;
+export type V1CreateImportRequest = import("./v1/imports.js").V1CreateImportRequest;
+export type TerraBaseSystemClientConfig = import("./v1/system.js").TerraBaseSystemClientConfig;
+export type V1ProbeStatus = import("./v1/system.js").V1ProbeStatus;
+export type V1ReplicationHealth = import("./v1/system.js").V1ReplicationHealth;
+export type V1PlatformDatabases = import("./v1/system.js").V1PlatformDatabases;
+export type V1ShapeManifest = import("./v1/shape-manifest.js").V1ShapeManifest;
+export type V1ShapeManifestRequest = import("./v1/shape-manifest.js").V1ShapeManifestRequest;
+export type V1ShapeKeyRequest = import("./v1/shape-reader.js").V1ShapeKeyRequest;
+export type V1ShapeKey = import("./v1/shape-reader.js").V1ShapeKey;
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient, createTerraBaseV1Client, TerraBaseV1Client, V1Database, V1Collection, V1Collections, V1Transaction } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
 export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
+export { generateId, isValidId, requireId } from "./ids.js";
+export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
+export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";
+export { createTerraBaseSystemClient, V1Health, V1Platform } from "./v1/system.js";

package/types/local/environment.d.ts

@@ -3,7 +3,7 @@
  * @returns {void}
  */
 export function assertLocalSqliteEnvironment(environment?: Readonly<Record<string, string | undefined>>): void;
-export const localSqlitePresenceIndicators: readonly ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "FORGEJO_ACTIONS", "GITEA_ACTIONS", "TF_BUILD", "BUILDKITE", "CIRCLECI", "JENKINS_URL", "TEAMCITY_VERSION", "VERCEL", "NETLIFY", "CF_PAGES", "RENDER", "FLY_APP_NAME", "K_SERVICE", "CLOUD_RUN_JOB", "KUBERNETES_SERVICE_HOST", "AWS_LAMBDA_FUNCTION_NAME", "AWS_EXECUTION_ENV", "ECS_CONTAINER_METADATA_URI", "ECS_CONTAINER_METADATA_URI_V4", "WEBSITE_INSTANCE_ID", "WEBSITE_SITE_NAME", "FUNCTIONS_WORKER_RUNTIME", "DYNO", "HEROKU_APP_NAME", "RAILWAY_ENVIRONMENT", "RAILWAY_SERVICE_ID", "NOMAD_ALLOC_ID", "TERRASCALE_DEPLOYMENT", "TERRASCALE_QUALIFICATION"];
+export const localSqlitePresenceIndicators: readonly ["CI", "CONTINUOUS_INTEGRATION", "GITHUB_ACTIONS", "GITLAB_CI", "FORGEJO_ACTIONS", "GITEA_ACTIONS", "TF_BUILD", "BUILDKITE", "CIRCLECI", "JENKINS_URL", "TEAMCITY_VERSION", "VERCEL", "NETLIFY", "CF_PAGES", "RENDER", "K_SERVICE", "CLOUD_RUN_JOB", "KUBERNETES_SERVICE_HOST", "AWS_LAMBDA_FUNCTION_NAME", "AWS_EXECUTION_ENV", "ECS_CONTAINER_METADATA_URI", "ECS_CONTAINER_METADATA_URI_V4", "WEBSITE_INSTANCE_ID", "WEBSITE_SITE_NAME", "FUNCTIONS_WORKER_RUNTIME", "DYNO", "HEROKU_APP_NAME", "RAILWAY_ENVIRONMENT", "RAILWAY_SERVICE_ID", "NOMAD_ALLOC_ID", "TERRASCALE_DEPLOYMENT", "TERRASCALE_QUALIFICATION"];
 /**
  * Explicit opt-in for a hosted development environment.
  *

package/types/local/store.d.ts

@@ -34,6 +34,16 @@ export class TerraScaleSqliteStore {
      * @returns {T[]}
      */
     list<T>(namespace: string, scope: string): T[];
+    /**
+     * @template T
+     * @param {string} namespace
+     * @param {string} scope
+     * @returns {readonly { readonly id: string; readonly value: T }[]}
+     */
+    listEntries<T>(namespace: string, scope: string): readonly {
+        readonly id: string;
+        readonly value: T;
+    }[];
     /**
      * @template T
      * @param {string} namespace

package/types/local/test-environment.d.ts

@@ -6,9 +6,9 @@
 export function localFixture(options?: Omit<TerraScaleSqliteRuntimeOptions, "sqlite">): Promise<{
     runtime: import("./index.js").TerraScaleSqliteRuntime;
     client: import("./legacy-client.js").TerraBaseClient;
-    collection: `${string}-${string}-${string}-${string}-${string}`;
+    collection: string;
     binding: {
-        collection: `${string}-${string}-${string}-${string}-${string}`;
+        collection: string;
         schema_generation: bigint;
         schema_digest: string;
     };

package/types/postgres.d.ts

@@ -25,8 +25,8 @@ export function postgresQuery(statement: string, parameters?: readonly unknown[]
  *   readonly port: number;
  *   readonly tlsServerName: string;
  *   readonly caCertificatePem: string;
- *   readonly database: string;
- *   readonly keyId: string;
+ *   readonly database: import("./ids.js").EntityId;
+ *   readonly keyId: import("./ids.js").EntityId;
  *   readonly password: string;
  *   readonly connectTimeoutMs?: number;
  * }} PostgresConfig
@@ -107,8 +107,8 @@ export type PostgresConfig = {
     readonly port: number;
     readonly tlsServerName: string;
     readonly caCertificatePem: string;
-    readonly database: string;
-    readonly keyId: string;
+    readonly database: import("./ids.js").EntityId;
+    readonly keyId: import("./ids.js").EntityId;
     readonly password: string;
     readonly connectTimeoutMs?: number;
 };