@terrascale/sdk 0.0.3 → 0.0.5

package/src/v1/transport.js

@@ -16,19 +16,20 @@ export const maximumRequestBytes = 4 * 1024 * 1024;
 // Query budgets count stored JSON before wrappers and serializer escaping.
 const defaultMaximumResponseBytes = 64 * 1024 * 1024;
 // Validate header-safe credential syntax only; the producer validates JWT claims/signatures.
-// Retain C# keys while the published TS-589 JWT contract awaits a producer release.
+// 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 */
+/** A fresh access token for each authenticated request, including stream reconnects. @typedef {() => string | Promise<string>} V1TokenProvider */
 /**
  * Project-scoped C# Documents API client. Supply exactly one of baseUrl or endpointResolver.
  * URLs must use HTTPS or loopback HTTP. Mutations are never automatically replayed.
  * @typedef {object} TerraBaseV1ClientConfig
  * @property {string} project
- * @property {string} token A ts-auth project access JWT (or a legacy C# tb_ key); held privately.
+ * @property {string | V1TokenProvider} token An access JWT (or a legacy C# tb_ key), or a provider resolved per authenticated request; held privately. Browser callers must use end-user tokens, never project credentials.
  * @property {string | undefined} [baseUrl]
  * @property {V1EndpointResolver | undefined} [endpointResolver]
  * @property {FetchLike | undefined} [fetch]
@@ -37,11 +38,12 @@ const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-
 
 /**
  * @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.
  */
 
 /**
@@ -116,6 +118,13 @@ function canonicalBaseUrl(raw) {
   return `${url.origin}${url.pathname.replace(/\/+$/u, "")}`;
 }
 
+/** @param {unknown} token @returns {string} */
+function requireToken(token) {
+  if (typeof token !== "string" || token.trim() !== token || !tokenPattern.test(token))
+    throw new TypeError("token must be a compact access JWT or a legacy C# tb_ API key.");
+  return token;
+}
+
 /** A response body that failed in transit after its headers arrived. */
 export class BodyTransportError extends Error {
   /** @param {unknown} cause */
@@ -127,30 +136,30 @@ export class BodyTransportError extends Error {
 
 /** 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 | V1TokenProvider | 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 compact access JWT or a legacy C# tb_ API key.");
+    if ((config.project !== undefined || config.token !== undefined) && typeof config.token !== "function")
+      requireToken(config.token);
     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);
@@ -163,6 +172,35 @@ export class V1Transport {
     this.#maxResponseBytes = maxResponseBytes;
   }
 
+  /** Internal credential lifetime metadata; never exposes the bearer value. */
+  get hasTokenProvider() { return typeof this.#token === "function"; }
+
+  /** @param {AbortSignal | undefined} signal @returns {Promise<string>} */
+  async #accessToken(signal) {
+    signal?.throwIfAborted();
+    const provider = this.#token;
+    if (typeof provider !== "function") return requireToken(provider);
+    /** @type {() => void} */
+    let abort = () => {};
+    try {
+      const token = await new Promise((resolve, reject) => {
+        abort = () => reject(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        void Promise.resolve().then(() => {
+          signal?.throwIfAborted();
+          return provider();
+        }).then(resolve, () => {
+          // Provider errors may contain credentials; do not retain their message or cause.
+          reject(new Error("TerraBase token provider failed."));
+        });
+      });
+      signal?.throwIfAborted();
+      return requireToken(token);
+    } finally {
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+
   /**
    * @param {V1Operation} operation
    * @param {Readonly<Record<string, string>>} params
@@ -171,8 +209,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(
@@ -182,13 +221,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();
@@ -206,7 +245,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();
@@ -217,9 +257,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[]} */
@@ -227,13 +269,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)
@@ -252,16 +297,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));
   }
 
   /**
@@ -280,13 +326,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);
@@ -300,27 +348,63 @@ 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" | "exportDatabase"} 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();
+    const expected = v1Route(operation).responseMediaType;
+    if (mediaType !== expected || response.body === null) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new TypeError(`TerraBase ${operation} requires a ${expected} 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 ${await this.#accessToken(options.signal)}`);
+    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;
+    options.signal?.throwIfAborted();
     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/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/index.d.ts

@@ -1,8 +1,18 @@
 export { v1Filter } from "./v1/filter.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 V1TokenProvider = import("./v1/transport.js").V1TokenProvider;
 export type V1RequestOptions = import("./v1/terrabase-v1.js").V1RequestOptions;
 export type V1ReadOptions = import("./v1/terrabase-v1.js").V1ReadOptions;
 export type V1WriteOptions = import("./v1/terrabase-v1.js").V1WriteOptions;
@@ -11,6 +21,7 @@ export type V1ConditionalWriteOptions = import("./v1/terrabase-v1.js").V1Conditi
 export type V1PatchOp = import("./v1/terrabase-v1.js").V1PatchOp;
 export type V1Patch = import("./v1/terrabase-v1.js").V1Patch;
 export type V1SortKey = import("./v1/terrabase-v1.js").V1SortKey;
+export type V1NearSortKey = import("./v1/terrabase-v1.js").V1NearSortKey;
 export type V1Query = import("./v1/terrabase-v1.js").V1Query;
 export type V1Count = import("./v1/terrabase-v1.js").V1Count;
 export type V1QueryPage = import("./v1/terrabase-v1.js").V1QueryPage;
@@ -31,6 +42,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,7 +52,66 @@ 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 V1ExportOptions = import("./v1/export.js").V1ExportOptions;
+export type V1ExportedDocument = import("./v1/export.js").V1ExportedDocument;
+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 V1CollectionTtl = import("./v1/catalog.js").V1CollectionTtl;
+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/ts-auth.d.ts

@@ -38,7 +38,6 @@ export function verifyTsAuthWebhookWithTolerance(signingSecret: string, timestam
  * @typedef {Omit<TsAuthRuntimeConfig, "apiBaseUrl"> & {
  *   readonly apiBaseUrl: string; // The ts-auth deployment's public origin; there is no default.
  *   readonly instanceSlug: string; // The instance the `sk_` key belongs to; it prefixes every route.
- *   readonly useReverseProxy?: boolean; // Route public auth calls through the reverse proxy instead of regional discovery.
  * }} TsAuthClientConfig
  */
 /**
@@ -1335,7 +1334,6 @@ export type TsAuthRuntimeConfig = import("./config.js").TsAuthRuntimeConfig;
 export type TsAuthClientConfig = Omit<TsAuthRuntimeConfig, "apiBaseUrl"> & {
     readonly apiBaseUrl: string;
     readonly instanceSlug: string;
-    readonly useReverseProxy?: boolean;
 };
 export type TsAuthRequestOptions = {
     readonly signal?: AbortSignal | undefined;