@terrascale/sdk 0.0.3 → 0.0.5

package/src/http.js

@@ -1,9 +1,5 @@
 import { resolveAccessToken, resolveTsAuthRuntimeConfig } from "./config.js";
 import { err, ok, sanitizeDiagnostic } from "./result.js";
-import {
-  regionalIssuerOrigin,
-  TsAuthEndpointDiscovery,
-} from "./ts-auth-discovery.js";
 import { parseDatabaseJson } from "./database-codec.js";
 import { validateTsAuthIds } from "./ts-auth-ids.js";
 /** @import { ResolvedTsAuthRuntimeConfig, TsAuthRuntimeConfig, FetchLike } from "./config.js" */
@@ -22,7 +18,6 @@ import { validateTsAuthIds } from "./ts-auth-ids.js";
  *   readonly formBody?: URLSearchParams | string | undefined;
  *   readonly userinfoAccessToken?: string | undefined;
  *   readonly resourceIntrospectionBasic?: string | undefined;
- *   readonly issuer?: string | undefined; // Behind the Atlas proxy a regional issuer is called on its own host.
  *   readonly signal?: AbortSignal | undefined;
  * }} TsAuthRequest
  */
@@ -40,25 +35,14 @@ export class TsAuthHttp {
   #fetch;
   /** @readonly @type {TsAuthRuntimeConfig["accessToken"]} */
   #accessToken;
-  /** @readonly @type {TsAuthEndpointDiscovery | undefined} */
-  #discovery;
-
-  /**
-   * @param {TsAuthRuntimeConfig} config
-   * @param {{ readonly authReverseProxy?: boolean }} [options]
-   */
-  constructor(config, options) {
+  /** @param {TsAuthRuntimeConfig} config */
+  constructor(config) {
     this.config = Object.freeze(resolveTsAuthRuntimeConfig(config));
     const fetchHandler = config.fetch ?? globalThis.fetch?.bind(globalThis);
     if (fetchHandler === undefined)
       throw new TypeError("TsAuthClient requires a fetch implementation.");
     this.#fetch = fetchHandler;
     this.#accessToken = config.accessToken;
-    this.#discovery =
-      options?.authReverseProxy !== true &&
-      this.config.apiBaseUrl === "https://auth.terrascale.tech"
-        ? new TsAuthEndpointDiscovery(fetchHandler)
-        : undefined;
   }
 
   /**
@@ -90,18 +74,6 @@ export class TsAuthHttp {
         options.body !== undefined
           ? JSON.stringify(options.body)
           : options.formBody?.toString();
-      const issuerOrigin =
-        this.#discovery === undefined || options.issuer === undefined
-          ? undefined
-          : regionalIssuerOrigin(options.issuer);
-      const endpoints =
-        issuerOrigin === undefined
-          ? await withCancellation(
-              this.#discovery?.endpoints(signal) ?? Promise.resolve(undefined),
-              signal,
-            )
-          : [issuerOrigin];
-      let endpointIndex = 0;
       let attempt = 0;
       let refreshed = false;
       /** @type {string | undefined} */
@@ -163,7 +135,7 @@ export class TsAuthHttp {
             );
           const request = new Request(
             buildUrl(
-              endpoints?.[endpointIndex] ?? this.config.apiBaseUrl,
+              this.config.apiBaseUrl,
               options.path,
               options.query,
             ),
@@ -189,16 +161,6 @@ export class TsAuthHttp {
             signal.throwIfAborted();
           }
           responseReceived = true;
-          if (
-            options.method === "GET" &&
-            endpoints !== undefined &&
-            endpointIndex < endpoints.length - 1 &&
-            [502, 503, 504].includes(response.status)
-          ) {
-            void response.body?.cancel().catch(() => undefined);
-            endpointIndex += 1;
-            continue;
-          }
           if (
             response.type === "opaqueredirect" ||
             (response.status >= 300 && response.status < 400)
@@ -293,13 +255,6 @@ export class TsAuthHttp {
             !signal?.aborted &&
             options.method === "GET"
           ) {
-            if (
-              endpoints !== undefined &&
-              endpointIndex < endpoints.length - 1
-            ) {
-              endpointIndex += 1;
-              continue;
-            }
             if (attempt < this.config.maxRetryAttempts) {
               await delayForRetry(
                 retryDelay(undefined, this.config.retryDelayMs, attempt),

package/src/index.js

@@ -1,6 +1,6 @@
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
-// TerraBase v1: name-based documents, transactions, queries and shapes.
+// Project-scoped TerraBase API; shape support is retained for the historical release.
 export {
   createTerraBaseV1Client,
   TerraBaseV1Client,
@@ -19,11 +19,16 @@ export {
   isTerraBaseV1Error,
 } from "./v1/errors.js";
 export { v1Filter } from "./v1/filter.js";
+export { V1ShapeSubscription } from "./v1/shape-subscription.js";
+/** @typedef {import("./v1/shape-subscription.js").V1ShapeSubscribeOptions} V1ShapeSubscribeOptions */
+/** @typedef {import("./v1/shape-subscription.js").V1ShapeDocument} V1ShapeDocument */
+/** @typedef {import("./v1/shape-reader.js").V1SealedShapePosition} V1SealedShapePosition */
 export { generateId, isValidId, requireId } from "./ids.js";
 /** @typedef {import("./ids.js").EntityId} EntityId */
 export { ExactDecimal } from "./v1/json.js";
 
 /** @typedef {import("./v1/transport.js").TerraBaseV1ClientConfig} TerraBaseV1ClientConfig */
+/** @typedef {import("./v1/transport.js").V1TokenProvider} V1TokenProvider */
 /** @typedef {import("./v1/terrabase-v1.js").V1RequestOptions} V1RequestOptions */
 /** @typedef {import("./v1/terrabase-v1.js").V1ReadOptions} V1ReadOptions */
 /** @typedef {import("./v1/terrabase-v1.js").V1WriteOptions} V1WriteOptions */
@@ -32,6 +37,7 @@ export { ExactDecimal } from "./v1/json.js";
 /** @typedef {import("./v1/terrabase-v1.js").V1PatchOp} V1PatchOp */
 /** @typedef {import("./v1/terrabase-v1.js").V1Patch} V1Patch */
 /** @typedef {import("./v1/terrabase-v1.js").V1SortKey} V1SortKey */
+/** @typedef {import("./v1/terrabase-v1.js").V1NearSortKey} V1NearSortKey */
 /** @typedef {import("./v1/terrabase-v1.js").V1Query} V1Query */
 /** @typedef {import("./v1/terrabase-v1.js").V1Count} V1Count */
 /** @typedef {import("./v1/terrabase-v1.js").V1QueryPage} V1QueryPage */
@@ -54,6 +60,11 @@ export { ExactDecimal } from "./v1/json.js";
 /** @typedef {import("./v1/shapes.js").V1ShapeOp} V1ShapeOp */
 
 export { staticBaseUrlResolver } from "./v1/transport.js";
+export { V1Databases } from "./v1/catalog.js";
+export { V1SavedQueries } from "./v1/saved-queries.js";
+/** @typedef {import("./v1/saved-queries.js").V1SavedQuery} V1SavedQuery */
+/** @typedef {import("./v1/saved-queries.js").V1SavedQueryRequest} V1SavedQueryRequest */
+/** @typedef {import("./v1/saved-queries.js").V1SavedQueryPage} V1SavedQueryPage */
 /** @typedef {import("./v1/transport.js").TerraBaseV1ClientConfig} TerraBaseClientConfig */
 /** @typedef {import("./v1/transport.js").V1EndpointContext} V1EndpointContext */
 /** @typedef {import("./v1/transport.js").V1EndpointResolver} V1EndpointResolver */
@@ -61,3 +72,71 @@ export { staticBaseUrlResolver } from "./v1/transport.js";
 /** @typedef {import("./v1/terrabase-v1.js").V1CollectionPage} V1CollectionPage */
 /** @typedef {import("./v1/terrabase-v1.js").V1CollectionListOptions} V1CollectionListOptions */
 /** @typedef {import("./v1/shapes.js").V1ShapePage} V1ShapePage */
+/** @typedef {import("./v1/sql.js").V1SqlRow} V1SqlRow */
+/** @typedef {import("./v1/sql.js").V1SqlResult} V1SqlResult */
+/** @typedef {import("./v1/sql.js").V1SqlIndexSuggestion} V1SqlIndexSuggestion */
+/** @typedef {import("./v1/sql.js").V1SqlCheck} V1SqlCheck */
+/** @typedef {import("./v1/changes.js").V1ChangeStreamRequest} V1ChangeStreamRequest */
+/** @typedef {import("./v1/changes.js").V1DatabaseChange} V1DatabaseChange */
+/** @typedef {import("./v1/changes.js").V1DatabaseChangeCursor} V1DatabaseChangeCursor */
+/** @typedef {import("./v1/export.js").V1ExportOptions} V1ExportOptions */
+/** @typedef {import("./v1/export.js").V1ExportedDocument} V1ExportedDocument */
+/** @typedef {import("./v1/catalog.js").V1ManagedDatabase} V1ManagedDatabase */
+/** @typedef {import("./v1/catalog.js").V1DatabaseCreateRequest} V1DatabaseCreateRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabaseUpdateRequest} V1DatabaseUpdateRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabaseBranchRequest} V1DatabaseBranchRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabaseListRequest} V1DatabaseListRequest */
+/** @typedef {import("./v1/catalog.js").V1DatabasePage} V1DatabasePage */
+/** @typedef {import("./v1/catalog.js").V1CollectionSchema} V1CollectionSchema */
+/** @typedef {import("./v1/catalog.js").V1CollectionTtl} V1CollectionTtl */
+
+export { V1DatabaseSchemaClient } from "./v1/database-schema.js";
+/** @typedef {import("./v1/database-schema.js").V1InferredSchema} V1InferredSchema */
+/** @typedef {import("./v1/database-schema.js").V1DatabaseSchema} V1DatabaseSchema */
+/** @typedef {import("./v1/database-schema.js").V1UniqueSchema} V1UniqueSchema */
+/** @typedef {import("./v1/database-schema.js").V1UniqueSchemaRequest} V1UniqueSchemaRequest */
+/** @typedef {import("./v1/database-schema.js").V1QueryShapes} V1QueryShapes */
+
+export { V1Indexes } from "./v1/indexes.js";
+/** @typedef {import("./v1/indexes.js").V1Index} V1Index */
+/** @typedef {import("./v1/indexes.js").V1IndexList} V1IndexList */
+/** @typedef {import("./v1/indexes.js").V1AutoIndexPolicy} V1AutoIndexPolicy */
+/** @typedef {import("./v1/indexes.js").V1IndexRecommendations} V1IndexRecommendations */
+/** @typedef {import("./v1/indexes.js").V1AppliedIndexRecommendation} V1AppliedIndexRecommendation */
+/** @typedef {import("./v1/indexes.js").V1CreateIndexRequest} V1CreateIndexRequest */
+
+export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
+/** @typedef {import("./v1/usage.js").V1DatabaseUsage} V1DatabaseUsage */
+/** @typedef {import("./v1/usage.js").V1ProjectUsage} V1ProjectUsage */
+/** @typedef {import("./v1/usage.js").V1Analytics} V1Analytics */
+/** @typedef {import("./v1/usage.js").V1Replication} V1Replication */
+/** @typedef {import("./v1/usage.js").V1UsageRequest} V1UsageRequest */
+/** @typedef {import("./v1/usage.js").V1AnalyticsRequest} V1AnalyticsRequest */
+
+export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";
+/** @typedef {import("./v1/backups.js").V1Backup} V1Backup */
+/** @typedef {import("./v1/backups.js").V1BackupPage} V1BackupPage */
+/** @typedef {import("./v1/backups.js").V1BackupPolicy} V1BackupPolicy */
+/** @typedef {import("./v1/backups.js").V1RestoreWindow} V1RestoreWindow */
+/** @typedef {import("./v1/backups.js").V1PointInTimePlan} V1PointInTimePlan */
+/** @typedef {import("./v1/backups.js").V1RestoredDatabase} V1RestoredDatabase */
+/** @typedef {import("./v1/backups.js").V1BackupDestination} V1BackupDestination */
+/** @typedef {import("./v1/backups.js").V1BackupPolicyRequest} V1BackupPolicyRequest */
+/** @typedef {import("./v1/backups.js").V1PointInTimeRequest} V1PointInTimeRequest */
+/** @typedef {import("./v1/backups.js").V1PointInTimeRestoreRequest} V1PointInTimeRestoreRequest */
+/** @typedef {import("./v1/backups.js").V1BackupDestinationRequest} V1BackupDestinationRequest */
+
+export { V1Imports } from "./v1/imports.js";
+/** @typedef {import("./v1/imports.js").V1ImportJob} V1ImportJob */
+/** @typedef {import("./v1/imports.js").V1ImportOptions} V1ImportOptions */
+/** @typedef {import("./v1/imports.js").V1CreateImportRequest} V1CreateImportRequest */
+
+export { createTerraBaseSystemClient, V1Health, V1Platform } from "./v1/system.js";
+/** @typedef {import("./v1/system.js").TerraBaseSystemClientConfig} TerraBaseSystemClientConfig */
+/** @typedef {import("./v1/system.js").V1ProbeStatus} V1ProbeStatus */
+/** @typedef {import("./v1/system.js").V1ReplicationHealth} V1ReplicationHealth */
+/** @typedef {import("./v1/system.js").V1PlatformDatabases} V1PlatformDatabases */
+/** @typedef {import("./v1/shape-manifest.js").V1ShapeManifest} V1ShapeManifest */
+/** @typedef {import("./v1/shape-manifest.js").V1ShapeManifestRequest} V1ShapeManifestRequest */
+/** @typedef {import("./v1/shape-reader.js").V1ShapeKeyRequest} V1ShapeKeyRequest */
+/** @typedef {import("./v1/shape-reader.js").V1ShapeKey} V1ShapeKey */

package/src/local/environment.js

@@ -14,7 +14,6 @@ export const localSqlitePresenceIndicators = /** @type {const} */ ([
   "NETLIFY",
   "CF_PAGES",
   "RENDER",
-  "FLY_APP_NAME",
   "K_SERVICE",
   "CLOUD_RUN_JOB",
   "KUBERNETES_SERVICE_HOST",

package/src/ts-auth.js

@@ -15,7 +15,6 @@ import { requireDeadLetterId } from "./ts-auth-ids.js";
  * @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
  */
 
@@ -2360,7 +2359,6 @@ export class TsAuthOidcClient {
         routeName: "tsauth.oidc.resourceIntrospect",
         formBody: form,
         resourceIntrospectionBasic: basic,
-        issuer: expectedIssuer,
       }),
       /** @returns {value is TsAuthOidcResourceIntrospection} */
       (value) => {
@@ -2520,9 +2518,7 @@ export class TsAuthClient {
       );
     }
     const slug = validateInstanceSlug(config?.instanceSlug);
-    this.#http = new TsAuthHttp(config, {
-      authReverseProxy: config.useReverseProxy === true,
-    });
+    this.#http = new TsAuthHttp(config);
     requireBareOrigin(this.#http.config.apiBaseUrl);
     this.users = new TsAuthUsersClient(this.#http, slug);
     this.sessions = new TsAuthSessionsClient(this.#http, slug);

package/src/v1/backups.js

@@ -0,0 +1,111 @@
+import { requireId } from "../ids.js";
+import { requireName } from "./ids.js";
+import { flag, list, nullable, numeric, optional, record, text } from "./management-decode.js";
+import { members, mutationOptions, pageQuery } from "./management-validation.js";
+import { malformed, object } from "./decode.js";
+import { stringifyExactJson } from "./json.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const backup = record({ id: requireId, databaseId: requireId, status: text, trigger: text, sizeBytes: numeric, createdAt: text });
+const backupPage = record({ items: list(backup), next: nullable(text) });
+const policy = record({ fullBackupCron: nullable(text), retentionDays: numeric, disabled: flag, updatedAt: nullable(text) });
+const window = record({ earliest: text, latest: text });
+const plan = record({ window, pointInTime: text, snapshotAt: text, latestSegmentAt: nullable(text), segmentCount: numeric, historyCheck: text });
+const restored = record({ id: requireId, projectId: requireId, name: text, branchedFrom: nullable(requireId), createdAt: text,
+  homeRegion: optional(nullable(text)), replicaRegions: optional(nullable(list(text))), placementVersion: optional(numeric), replicas: list(text) });
+const destination = record({ endpoint: text, region: text, bucket: text, mode: text, updatedAt: text });
+/** @typedef {ReturnType<typeof backup>} V1Backup */
+/** @typedef {ReturnType<typeof backupPage>} V1BackupPage */
+/** @typedef {ReturnType<typeof policy>} V1BackupPolicy */
+/** @typedef {ReturnType<typeof window>} V1RestoreWindow */
+/** @typedef {ReturnType<typeof plan>} V1PointInTimePlan */
+/** @typedef {ReturnType<typeof restored>} V1RestoredDatabase */
+/** @typedef {ReturnType<typeof destination>} V1BackupDestination */
+/** @typedef {{ readonly fullBackupCron?: string | null; readonly retentionDays?: number | null; readonly disabled?: boolean | null }} V1BackupPolicyRequest */
+/** @typedef {{ readonly pointInTime: string; readonly destination?: "platform" | "customer" | null }} V1PointInTimeRequest */
+/** @typedef {V1PointInTimeRequest & { readonly name?: string | null }} V1PointInTimeRestoreRequest */
+/** @typedef {{ readonly endpoint: string; readonly region: string; readonly bucket: string; readonly accessKeyId: string; readonly secretKey: string; readonly mode: "both" | "customer" }} V1BackupDestinationRequest */
+/** @param {unknown} value @returns {"platform" | "customer"} */
+function source(value) {
+  if (value !== "platform" && value !== "customer") throw new TypeError("destination must be platform or customer.");
+  return value;
+}
+/** @param {V1PointInTimeRequest} request */
+function pointInTime(request) {
+  if (typeof request.pointInTime !== "string" || !Number.isFinite(Date.parse(request.pointInTime))) throw new TypeError("pointInTime must be an RFC 3339 instant.");
+  if (request.destination !== undefined && request.destination !== null) source(request.destination);
+}
+
+/** Backups and explicit point-in-time restore sources for one database. */
+export class V1Backups {
+  /** @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 {V1RequestOptions} [options] @returns {Promise<V1Backup>} */
+  async create(options = {}) {
+    mutationOptions(options);
+    return backup((await this.#transport.call("createBackup", this.#params, { signal: options.signal })).value);
+  }
+  /** @param {import("./catalog.js").V1DatabaseListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1BackupPage>} */
+  async list(request = {}, options = {}) { return backupPage((await this.#transport.call("listBackups", this.#params, { query: pageQuery(request), signal: options.signal })).value); }
+  /** @param {string} id @param {{readonly name?: string | null}} [request] @param {V1RequestOptions} [options] @returns {Promise<V1RestoredDatabase>} */
+  async restore(id, request = {}, options = {}) {
+    members(request, ["name"]);
+    if (request.name !== undefined && request.name !== null) requireName("database", request.name);
+    mutationOptions(options);
+    return restored((await this.#transport.call("restoreBackup", { ...this.#params, backup: requireId(id) }, {
+      body: stringifyExactJson(request, "restore"), signal: options.signal,
+    })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1BackupPolicy>} */
+  async getPolicy(options = {}) { return policy((await this.#transport.call("getBackupPolicy", this.#params, { signal: options.signal })).value); }
+  /** @param {V1BackupPolicyRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1BackupPolicy>} */
+  async setPolicy(request, options = {}) {
+    members(request, ["fullBackupCron", "retentionDays", "disabled"]);
+    mutationOptions(options);
+    return policy((await this.#transport.call("setBackupPolicy", this.#params, { body: stringifyExactJson(request, "backup policy"), signal: options.signal })).value);
+  }
+  /** @param {{readonly destination?: "platform" | "customer"}} [request] @param {V1RequestOptions} [options] @returns {Promise<V1RestoreWindow>} */
+  async window(request = {}, options = {}) {
+    members(request, ["destination"]);
+    const query = new URLSearchParams();
+    if (request.destination !== undefined) query.set("destination", source(request.destination));
+    return window((await this.#transport.call("getRestoreWindow", this.#params, { query, signal: options.signal })).value);
+  }
+  /** @param {V1PointInTimeRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1PointInTimePlan>} */
+  async plan(request, options = {}) {
+    members(request, ["pointInTime", "destination"]);
+    pointInTime(request);
+    return plan((await this.#transport.call("planPointInTime", this.#params, { body: stringifyExactJson(request, "restore plan"), signal: options.signal })).value);
+  }
+  /** @param {V1PointInTimeRestoreRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1RestoredDatabase>} */
+  async restorePointInTime(request, options = {}) {
+    members(request, ["pointInTime", "destination", "name"]);
+    pointInTime(request);
+    if (request.name !== undefined && request.name !== null) requireName("database", request.name);
+    mutationOptions(options);
+    return restored((await this.#transport.call("restorePointInTime", this.#params, { body: stringifyExactJson(request, "point-in-time restore"), signal: options.signal })).value);
+  }
+}
+/** Write-only destination credentials are sent only to the configured API, never retained in the client. */
+export class V1BackupDestinationClient {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1BackupDestination>} */
+  async get(options = {}) { return destination((await this.#transport.call("getBackupDestination", {}, { signal: options.signal })).value); }
+  /** @param {V1BackupDestinationRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1BackupDestination>} */
+  async set(request, options = {}) {
+    members(request, ["endpoint", "region", "bucket", "accessKeyId", "secretKey", "mode"]);
+    mutationOptions(options);
+    const raw = object((await this.#transport.call("setBackupDestination", {}, { body: stringifyExactJson(request, "backup destination"), signal: options.signal })).value, "backup destination");
+    if (raw.accessKeyId !== undefined || raw.secretKey !== undefined) malformed("write-only destination credentials");
+    return destination(raw);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<void>} */
+  async delete(options = {}) { mutationOptions(options); await this.#transport.call("deleteBackupDestination", {}, { signal: options.signal }); }
+}

package/src/v1/catalog.js

@@ -0,0 +1,240 @@
+import { requireId } from "../ids.js";
+import { array, malformed, object, string } from "./decode.js";
+import { requireName } from "./ids.js";
+import { isJsonPointer } from "./filter.js";
+import { isJsonObject, stringifyExactJson } from "./json.js";
+/**
+ * @import { JsonInputObject, JsonObject, JsonValue } from "./json.js"
+ * @import { V1Transport } from "./transport.js"
+ * @import { V1RequestOptions } from "./terrabase-v1.js"
+ */
+
+/**
+ * @typedef {object} V1ManagedDatabase
+ * @property {string} id Canonical database ULID.
+ * @property {string} projectId Canonical owning-project ULID.
+ * @property {string} name Database name used in data routes.
+ * @property {string | null} branchedFrom Source database ULID, or null.
+ * @property {string} createdAt ISO date-time returned by the producer.
+ * @property {string} region Serving region.
+ * @property {string} homeRegion Management region.
+ * @property {readonly string[]} replicaRegions Other serving regions; empty when allRegions is true.
+ * @property {boolean} allRegions True when a full copy is served in every serving region, including later ones.
+ */
+/** @typedef {{ readonly name: string; readonly homeRegion?: string | null | undefined; readonly replicaRegions?: readonly string[] | null | undefined; readonly allRegions?: boolean | undefined }} V1DatabaseCreateRequest */
+/** @typedef {{ readonly replicaRegions?: readonly string[] | undefined; readonly allRegions?: true | undefined; readonly homeRegion?: string | null | undefined }} V1DatabaseUpdateRequest */
+/** @typedef {{ readonly name: string }} V1DatabaseBranchRequest */
+/** @typedef {{ readonly after?: string | undefined; readonly limit?: number | undefined }} V1DatabaseListRequest */
+/** @typedef {{ readonly items: readonly V1ManagedDatabase[]; readonly next: string | null }} V1DatabasePage */
+/** @typedef {{ readonly schema: JsonObject | boolean | null; readonly dialect?: string | null | undefined }} V1CollectionSchema */
+/** The expiry member, or null when documents never expire. @typedef {{ readonly path: string | null }} V1CollectionTtl */
+
+/** @param {unknown} value @param {readonly string[]} allowed @returns {void} */
+function members(value, allowed) {
+  if (typeof value !== "object" || value === null || Array.isArray(value) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+    throw new TypeError("A catalog request must be a plain object.");
+  for (const key of Object.keys(value))
+    if (!allowed.includes(key)) throw new TypeError(`Unknown catalog request member ${key}.`);
+}
+
+/** @param {object} options @returns {void} */
+function mutationOptions(options) {
+  if ("idempotencyKey" in options)
+    throw new TypeError("The current producer does not support Idempotency-Key; mutations are never automatically retried.");
+}
+
+/** @param {unknown} value @returns {string} */
+function region(value) {
+  if (typeof value !== "string" || !/^[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(value))
+    throw new TypeError("A region is 1-63 lowercase letters, digits or hyphens, starts with a letter and cannot end with a hyphen.");
+  return value;
+}
+
+/** @param {unknown} value @param {string | null | undefined} home @returns {readonly string[]} */
+function replicas(value, home) {
+  if (!Array.isArray(value) || value.length > 8) throw new TypeError("replicaRegions is an array of at most 8 regions.");
+  const result = value.map(region);
+  if (new Set(result).size !== result.length) throw new TypeError("replicaRegions must not repeat a region.");
+  if (home !== undefined && home !== null && result.includes(home))
+    throw new TypeError("replicaRegions must not include homeRegion.");
+  return result;
+}
+
+/** @param {JsonValue | undefined} value @returns {V1ManagedDatabase} */
+function database(value) {
+  const raw = object(value, "managed database");
+  const createdAt = string(raw.createdAt, "database createdAt");
+  if (!/^\d{4}-\d{2}-\d{2}T/u.test(createdAt) || !Number.isFinite(Date.parse(createdAt))) malformed("database createdAt");
+  if (typeof raw.allRegions !== "boolean") malformed("database allRegions");
+  return Object.freeze({
+    id: requireId(raw.id, "Database ID"), projectId: requireId(raw.projectId, "Project ID"),
+    name: requireName("database", raw.name),
+    branchedFrom: raw.branchedFrom === null ? null : requireId(raw.branchedFrom, "Source database ID"),
+    createdAt, region: region(raw.region), homeRegion: region(raw.homeRegion),
+    replicaRegions: Object.freeze(array(raw.replicaRegions, "database replicaRegions").map(region)),
+    allRegions: raw.allRegions,
+  });
+}
+
+/** Public database catalog operations, bound to the transport's authorized project. */
+export class V1Databases {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+
+  /** @param {V1DatabaseCreateRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async create(request, options = {}) {
+    members(request, ["name", "homeRegion", "replicaRegions", "allRegions"]);
+    mutationOptions(options);
+    const name = requireName("database", request.name);
+    if (request.homeRegion !== undefined && request.homeRegion !== null) region(request.homeRegion);
+    if (request.replicaRegions !== undefined && request.replicaRegions !== null) replicas(request.replicaRegions, request.homeRegion);
+    if (request.allRegions !== undefined && typeof request.allRegions !== "boolean") throw new TypeError("allRegions must be a boolean.");
+    if (request.allRegions === true && request.replicaRegions !== undefined && request.replicaRegions !== null)
+      throw new TypeError("allRegions cannot be combined with replicaRegions.");
+    const response = await this.#transport.call("createDatabase", { database: name }, {
+      body: stringifyExactJson({ name,
+        ...(request.homeRegion === undefined ? {} : { homeRegion: request.homeRegion }),
+        ...(request.replicaRegions === undefined ? {} : { replicaRegions: request.replicaRegions }),
+        ...(request.allRegions === undefined ? {} : { allRegions: request.allRegions }),
+      }, "database create"), signal: options.signal,
+    });
+    return database(response.value);
+  }
+
+  /** @param {V1DatabaseListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1DatabasePage>} */
+  async list(request = {}, options = {}) {
+    members(request, ["after", "limit"]);
+    const query = new URLSearchParams();
+    if (request.after !== undefined) {
+      if (typeof request.after !== "string") throw new TypeError("Database after must be a string.");
+      query.set("after", request.after);
+    }
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 100) throw new TypeError("Database list limit is 1-100.");
+      query.set("limit", String(request.limit));
+    }
+    const response = await this.#transport.call("listDatabases", {}, { query, signal: options.signal });
+    const raw = object(response.value, "database page");
+    if (raw.next !== null && (typeof raw.next !== "string" || raw.next === "")) malformed("database next");
+    return Object.freeze({ items: Object.freeze(array(raw.items, "databases").map(database)), next: raw.next });
+  }
+
+  /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async get(name, options = {}) {
+    const response = await this.#transport.call("getDatabase", { database: requireName("database", name) }, { signal: options.signal });
+    return database(response.value);
+  }
+
+  /** @param {string} name @param {V1DatabaseUpdateRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async update(name, request, options = {}) {
+    members(request, ["homeRegion", "replicaRegions", "allRegions"]);
+    mutationOptions(options);
+    if (request.homeRegion !== undefined && request.homeRegion !== null) region(request.homeRegion);
+    if (request.allRegions === true) {
+      if (request.replicaRegions !== undefined) throw new TypeError("allRegions cannot be combined with replicaRegions.");
+    } else {
+      if (request.allRegions !== undefined) throw new TypeError("allRegions must be true; send replicaRegions to turn it off.");
+      replicas(request.replicaRegions, request.homeRegion);
+    }
+    const response = await this.#transport.call("updateDatabase", { database: requireName("database", name) }, {
+      body: stringifyExactJson({
+        ...(request.allRegions === true ? { allRegions: true } : { replicaRegions: request.replicaRegions }),
+        ...(request.homeRegion === undefined ? {} : { homeRegion: request.homeRegion }),
+      }, "database update"), signal: options.signal,
+    });
+    return database(response.value);
+  }
+
+  /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<void>} */
+  async delete(name, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("deleteDatabase", { database: requireName("database", name) }, { signal: options.signal });
+  }
+
+  /** @param {string} name @param {V1DatabaseBranchRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ManagedDatabase>} */
+  async branch(name, request, options = {}) {
+    members(request, ["name"]);
+    mutationOptions(options);
+    const response = await this.#transport.call("branchDatabase", { database: requireName("database", name) }, {
+      body: stringifyExactJson({ name: requireName("database", request.name) }, "database branch"), signal: options.signal,
+    });
+    return database(response.value);
+  }
+}
+
+/** @param {JsonValue | undefined} value @returns {V1CollectionSchema} */
+function collectionSchema(value) {
+  const raw = object(value, "collection schema");
+  const schema = raw.schema;
+  if (schema !== null && typeof schema !== "boolean" && !isJsonObject(schema)) malformed("declared schema");
+  const dialect = raw.dialect;
+  if (dialect !== undefined && dialect !== null && typeof dialect !== "string") malformed("schema dialect");
+  return Object.freeze({ schema, ...(dialect === undefined ? {} : { dialect }) });
+}
+
+/** @param {boolean | JsonInputObject} schema @returns {string} */
+function schemaText(schema) {
+  if (typeof schema !== "boolean" && !isJsonObject(schema)) throw new TypeError("A declared schema must be a JSON object or boolean.");
+  const body = stringifyExactJson(schema, "declared schema");
+  if (new TextEncoder().encode(body).byteLength > 64 * 1024) throw new TypeError("A declared schema is at most 64 KiB.");
+  let nodes = 0;
+  /** @param {unknown} value @param {number} depth */
+  const visit = (value, depth) => {
+    if (++nodes > 4093) throw new TypeError("A declared schema holds at most 4093 values.");
+    if (!Array.isArray(value) && !isJsonObject(value)) return;
+    if (depth >= 15) throw new TypeError("A declared schema nests at most 15 levels.");
+    for (const child of Object.values(value)) visit(child, depth + 1);
+  };
+  visit(schema, 0);
+  return body;
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionSchema>} */
+export async function getCollectionSchema(transport, params, options = {}) {
+  return collectionSchema((await transport.call("getCollectionSchema", params, { signal: options.signal })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {boolean | JsonInputObject} schema @param {V1RequestOptions} [options] @returns {Promise<V1CollectionSchema>} */
+export async function putCollectionSchema(transport, params, schema, options = {}) {
+  mutationOptions(options);
+  return collectionSchema((await transport.call("putCollectionSchema", params, {
+    body: schemaText(schema), signal: options.signal,
+  })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionSchema>} */
+export async function deleteCollectionSchema(transport, params, options = {}) {
+  mutationOptions(options);
+  return collectionSchema((await transport.call("deleteCollectionSchema", params, { signal: options.signal })).value);
+}
+
+/** @param {JsonValue | undefined} value @returns {V1CollectionTtl} */
+function collectionTtl(value) {
+  const path = object(value, "collection TTL").path;
+  if (path !== null && typeof path !== "string") malformed("TTL path");
+  return Object.freeze({ path });
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export async function getCollectionTtl(transport, params, options = {}) {
+  return collectionTtl((await transport.call("getCollectionTtl", params, { signal: options.signal })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {string} path @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export async function putCollectionTtl(transport, params, path, options = {}) {
+  mutationOptions(options);
+  if (!isJsonPointer(path))
+    throw new TypeError("A TTL path is a JSON Pointer of 1 to 16 object members.");
+  return collectionTtl((await transport.call("putCollectionTtl", params, {
+    body: stringifyExactJson({ path }, "collection TTL"), signal: options.signal,
+  })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export async function deleteCollectionTtl(transport, params, options = {}) {
+  mutationOptions(options);
+  return collectionTtl((await transport.call("deleteCollectionTtl", params, { signal: options.signal })).value);
+}