@terrascale/sdk 0.0.2 → 0.0.4

package/src/v1/ids.js

@@ -1,4 +1,5 @@
-// Identifiers for the TerraBase v1 Documents API (api-v1.md).
+// Identifiers for the TerraBase v1 Documents API.
+import { requireId } from "../ids.js";
 
 const namePattern = /^[a-z][a-z0-9_-]{0,62}$/u;
 // Version tokens are opaque (tbv1-<32 hex>, tbv2-...): only RFC 9110 opaque-tag characters, safe to quote in If-Match.
@@ -6,12 +7,6 @@ const versionPattern = /^[\x21\x23-\x7e]{1,256}$/u;
 const offsetPattern = /^(?:0|[1-9]\d{0,19})$/u;
 const maximumU64 = (1n << 64n) - 1n;
 
-/** RFC 9562 NAMESPACE_URL, 6ba7b811-9dad-11d1-80b4-00c04fd430c8. */
-const namespaceUrl = Uint8Array.of(
-  0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1,
-  0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8,
-);
-
 /**
  * @param {"database" | "collection"} kind
  * @param {unknown} name
@@ -24,23 +19,19 @@ export function requireName(kind, name) {
 }
 
 /**
- * The producer resolves this opaque catalog project id (normally a UUID), not its display name.
+ * The catalog project ID is a canonical ULID; database and collection routes use names.
  * @param {unknown} project
- * @returns {string}
+ * @returns {import("../ids.js").EntityId}
  */
 export function requireProject(project) {
-  if (typeof project !== "string" || project === "" || project === "." || project === ".." || /[\p{Cc}\uD800-\uDFFF]/u.test(project))
-    throw new TypeError("project must be a non-empty catalog project ID without control characters or dot path segments.");
-  return project;
+  return requireId(project);
 }
 
-/**
- * @param {unknown} id
- * @returns {string}
- */
+/** A caller-supplied key is not a generated entity ID. @param {unknown} id @returns {string} */
 export function requireDocumentId(id) {
-  if (typeof id !== "string" || id.length < 1 || id.length > 256 || /[\p{Cc}]/u.test(id) || /[\uD800-\uDFFF]/u.test(id) || id === "." || id === "..")
-    throw new TypeError("Document IDs must be 1-256 characters without control characters or dot path segments; new IDs must be lowercase UUIDs.");
+  if (typeof id !== "string" || id.length < 1 || id.length > 256 ||
+      /[\u0000-\u001f\u007f-\u009f\ud800-\udfff]/u.test(id))
+    throw new TypeError("TerraBase document keys must be 1-256 characters of valid UTF-8 without control characters.");
   return id;
 }
 
@@ -76,44 +67,3 @@ export function requireU64(value, what) {
   if (parsed === undefined) throw new TypeError(`${what} must be a u64: a canonical decimal string or bigint.`);
   return parsed;
 }
-
-/**
- * @param {Uint8Array} namespace
- * @param {string} name
- * @returns {Promise<Uint8Array>}
- */
-async function uuidV5(namespace, name) {
-  const encoded = new TextEncoder().encode(name);
-  const input = new Uint8Array(namespace.length + encoded.length);
-  input.set(namespace);
-  input.set(encoded, namespace.length);
-  const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-1", input));
-  const uuid = digest.slice(0, 16);
-  uuid[6] = ((uuid[6] ?? 0) & 0x0f) | 0x50;
-  uuid[8] = ((uuid[8] ?? 0) & 0x3f) | 0x80;
-  return uuid;
-}
-
-/**
- * @param {Uint8Array} bytes
- * @returns {string}
- */
-function formatUuid(bytes) {
-  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
-  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-
-/**
- * The deterministic document ID for a natural key in a collection:
- * `uuidv5(uuidv5(NAMESPACE_URL, "terrabase:collection:" + collection), key)`.
- * Uses WebCrypto, so it works in Node.js, browsers and workers.
- * @param {string} collection
- * @param {string} key
- * @returns {Promise<string>}
- */
-export async function documentIdFor(collection, key) {
-  requireName("collection", collection);
-  if (typeof key !== "string") throw new TypeError("The natural key must be a string.");
-  const namespace = await uuidV5(namespaceUrl, `terrabase:collection:${collection}`);
-  return formatUuid(await uuidV5(namespace, key));
-}

package/src/v1/imports.js

@@ -0,0 +1,72 @@
+import { requireId } from "../ids.js";
+import { requireName } from "./ids.js";
+import { flag, list, nullable, numeric, record, text } from "./management-decode.js";
+import { members, mutationOptions } from "./management-validation.js";
+import { stringifyExactJson } from "./json.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const importOptions = record({ missingPrimaryKey: nullable(text), exclude: nullable(list(text)) });
+const column = record({ name: text, sourceType: text, mapping: text, nullable: flag, excluded: flag });
+const constraint = record({ kind: text, name: nullable(text), columns: list(text), references: nullable(text), enforced: flag });
+const issue = record({ severity: text, code: text, column: nullable(text), row: nullable(numeric), message: text });
+const table = record({ source: text, collection: text, excluded: flag, rows: numeric, idPolicy: text, primaryKey: list(text),
+  columns: list(column), constraints: list(constraint), issues: list(issue) });
+const preview = record({ id: requireId, tables: list(table), skipped: list(record({ kind: text, name: text })), skippedTruncated: flag, blocking: numeric, warnings: numeric });
+const progress = record({ tablesDone: numeric, tablesTotal: numeric, rowsWritten: numeric, rowsTotal: numeric, currentTable: nullable(text) });
+const validation = record({ passed: flag, tables: list(record({ source: text, collection: text, sourceRows: numeric, documents: numeric,
+  sourceChecksum: text, documentChecksum: text, match: flag })) });
+const error = record({ code: text, message: text, retryable: flag, table: nullable(text), row: nullable(numeric), column: nullable(text) });
+const job = record({ id: requireId, project: requireId, database: text, region: text, state: text, cancelRequested: flag, options: importOptions,
+  source: record({ format: text, bytes: numeric, sha256: text, receivedBytes: numeric, staged: flag, retainedUntil: nullable(text) }),
+  preview: nullable(preview), confirmedPreviewId: nullable(requireId), progress: nullable(progress), validation: nullable(validation), error: nullable(error),
+  createdAt: text, updatedAt: text, startedAt: nullable(text), finishedAt: nullable(text) });
+/** @typedef {ReturnType<typeof job>} V1ImportJob */
+/** @typedef {{ readonly missingPrimaryKey?: "reject" | "generate" | null; readonly exclude?: readonly string[] | null }} V1ImportOptions */
+/** @typedef {{ readonly format: "postgres_plain" | "sqlite"; readonly sourceBytes: number; readonly sourceSha256: string; readonly options?: V1ImportOptions | null }} V1CreateImportRequest */
+
+/** One import job belongs to its destination database; preview confirmation is explicit. */
+export class V1Imports {
+  /** @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 {V1CreateImportRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async create(request, options = {}) {
+    members(request, ["format", "sourceBytes", "sourceSha256", "options"]);
+    if (!["postgres_plain", "sqlite"].includes(request.format) || !Number.isSafeInteger(request.sourceBytes) || request.sourceBytes < 1 || request.sourceBytes > 1073741824 ||
+        typeof request.sourceSha256 !== "string" || !/^[a-f0-9]{64}$/u.test(request.sourceSha256)) throw new TypeError("Invalid import format, size or SHA-256.");
+    mutationOptions(options);
+    return job((await this.#transport.call("createImport", this.#params, { body: stringifyExactJson(request, "import create"), signal: options.signal })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async get(options = {}) { return job((await this.#transport.call("getImport", this.#params, { signal: options.signal })).value); }
+  /** @param {number | bigint} offset @param {Uint8Array} bytes @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async uploadSource(offset, bytes, options = {}) {
+    if (!(typeof offset === "bigint" || typeof offset === "number" && Number.isSafeInteger(offset)) || offset < 0 || BigInt(offset) > 9223372036854775807n)
+      throw new TypeError("offset must be a non-negative signed 64-bit integer.");
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength < 1 || bytes.byteLength > 4194304) throw new TypeError("A source part must contain 1-4194304 bytes.");
+    mutationOptions(options);
+    return job((await this.#transport.call("uploadImportSource", this.#params, {
+      body: bytes.slice(), contentType: "application/octet-stream", query: new URLSearchParams({ offset: String(offset) }), signal: options.signal,
+    })).value);
+  }
+  /** @param {{readonly options?: V1ImportOptions | null}} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async update(request, options = {}) {
+    members(request, ["options"]);
+    mutationOptions(options);
+    return job((await this.#transport.call("updateImport", this.#params, { body: stringifyExactJson(request, "import update"), signal: options.signal })).value);
+  }
+  /** @param {{readonly previewId: string}} request @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async start(request, options = {}) {
+    members(request, ["previewId"]);
+    requireId(request.previewId, "Preview ID");
+    mutationOptions(options);
+    return job((await this.#transport.call("startImport", this.#params, { body: stringifyExactJson(request, "import start"), signal: options.signal })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async cancel(options = {}) { mutationOptions(options); return job((await this.#transport.call("cancelImport", this.#params, { signal: options.signal })).value); }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1ImportJob>} */
+  async resume(options = {}) { mutationOptions(options); return job((await this.#transport.call("resumeImport", this.#params, { signal: options.signal })).value); }
+}

package/src/v1/indexes.js

@@ -0,0 +1,76 @@
+import { requireName } from "./ids.js";
+import { flag, list, numeric, record, text } from "./management-decode.js";
+import { members, mutationOptions } from "./management-validation.js";
+import { stringifyExactJson } from "./json.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const index = record({ name: text, collection: text, fields: list(text), state: text });
+const indexes = record({ items: list(index) });
+const policy = record({ collection: text, enabled: flag });
+const recommendations = record({ items: list(record({ id: text, collection: text, fields: list(text), reason: text, queries: numeric })) });
+const applied = record({ status: text, index });
+/** @typedef {ReturnType<typeof index>} V1Index */
+/** @typedef {ReturnType<typeof indexes>} V1IndexList */
+/** @typedef {ReturnType<typeof policy>} V1AutoIndexPolicy */
+/** @typedef {ReturnType<typeof recommendations>} V1IndexRecommendations */
+/** @typedef {ReturnType<typeof applied>} V1AppliedIndexRecommendation */
+/** @typedef {{ readonly collection: string; readonly fields: readonly string[]; readonly name?: string | null }} V1CreateIndexRequest */
+/** @param {unknown} value @returns {string} */
+function indexName(value) {
+  if (typeof value !== "string" || !/^[a-z][a-z0-9_]{0,62}$/u.test(value)) throw new TypeError("Invalid index name.");
+  return value;
+}
+
+/** Secondary indexes, automatic policies and workload recommendations for one database. */
+export class V1Indexes {
+  /** @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 {V1CreateIndexRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1Index>} */
+  async create(request, options = {}) {
+    members(request, ["collection", "fields", "name"]);
+    requireName("collection", request.collection);
+    if (!Array.isArray(request.fields) || request.fields.length < 1 || request.fields.length > 4 ||
+        new Set(request.fields).size !== request.fields.length || request.fields.some(f => typeof f !== "string" || f === "_id" || f === "_rev" || !/^[A-Za-z_][A-Za-z0-9_]{0,63}(?:\.[A-Za-z_][A-Za-z0-9_]{0,63}){0,7}$/u.test(f)))
+      throw new TypeError("fields must be 1-4 distinct dotted paths, excluding _id and _rev.");
+    if (request.name !== undefined && request.name !== null) indexName(request.name);
+    mutationOptions(options);
+    return index((await this.#transport.call("createIndex", this.#params, { body: stringifyExactJson(request, "index"), signal: options.signal })).value);
+  }
+  /** @param {{ readonly collection?: string }} [request] @param {V1RequestOptions} [options] @returns {Promise<V1IndexList>} */
+  async list(request = {}, options = {}) {
+    members(request, ["collection"]);
+    const query = new URLSearchParams();
+    if (request.collection !== undefined) query.set("collection", requireName("collection", request.collection));
+    return indexes((await this.#transport.call("listIndexes", this.#params, { query, signal: options.signal })).value);
+  }
+  /** @param {string} name @param {V1RequestOptions} [options] @returns {Promise<void>} */
+  async drop(name, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("dropIndex", { ...this.#params, index: indexName(name) }, { signal: options.signal });
+  }
+  /** @param {string} collection @param {V1RequestOptions} [options] @returns {Promise<V1AutoIndexPolicy>} */
+  async getAutoPolicy(collection, options = {}) {
+    return policy((await this.#transport.call("getAutoIndexPolicy", { ...this.#params, collection: requireName("collection", collection) }, { signal: options.signal })).value);
+  }
+  /** @param {string} collection @param {{ readonly enabled: boolean }} request @param {V1RequestOptions} [options] @returns {Promise<V1AutoIndexPolicy>} */
+  async setAutoPolicy(collection, request, options = {}) {
+    members(request, ["enabled"]);
+    if (typeof request.enabled !== "boolean") throw new TypeError("enabled must be boolean.");
+    mutationOptions(options);
+    return policy((await this.#transport.call("setAutoIndexPolicy", { ...this.#params, collection: requireName("collection", collection) }, {
+      body: stringifyExactJson(request, "auto-index policy"), signal: options.signal,
+    })).value);
+  }
+  /** @param {V1RequestOptions} [options] @returns {Promise<V1IndexRecommendations>} */
+  async recommendations(options = {}) { return recommendations((await this.#transport.call("listIndexRecommendations", this.#params, { signal: options.signal })).value); }
+  /** @param {string} id Opaque producer recommendation identifier. @param {V1RequestOptions} [options] @returns {Promise<V1AppliedIndexRecommendation>} */
+  async applyRecommendation(id, options = {}) {
+    if (typeof id !== "string" || id === "") throw new TypeError("A recommendation identifier is required.");
+    mutationOptions(options);
+    return applied((await this.#transport.call("applyIndexRecommendation", { ...this.#params, recommendation: id }, { signal: options.signal })).value);
+  }
+}

package/src/v1/json.js

@@ -28,9 +28,10 @@ function canonicalDecimal(text) {
   let digits = `${match[2]}${fraction}`.replace(/^0+/u, "");
   let exponent = BigInt(match[4] ?? "0") - BigInt(fraction.length);
   if (digits === "") return { negative: false, digits: "", exponent: 0n };
-  const trimmed = digits.replace(/0+$/u, "");
-  exponent += BigInt(digits.length - trimmed.length);
-  digits = trimmed;
+  let end = digits.length;
+  while (digits[end - 1] === "0") end--;
+  exponent += BigInt(digits.length - end);
+  digits = digits.slice(0, end);
   return { negative: match[1] === "-", digits, exponent };
 }
 

package/src/v1/management-decode.js

@@ -0,0 +1,24 @@
+import { array, malformed, object, string, boolean } from "./decode.js";
+import { ExactDecimal } from "./json.js";
+/** @import { JsonValue } from "./json.js" */
+/** @template T @typedef {(value: JsonValue | undefined) => T} Decoder */
+export const text = /** @type {Decoder<string>} */ (value => string(value, "string"));
+export const flag = /** @type {Decoder<boolean>} */ (value => boolean(value, "boolean"));
+/** @type {Decoder<number | ExactDecimal>} */
+export const numeric = value => typeof value === "number" && Number.isFinite(value) || value instanceof ExactDecimal ? value : malformed("number");
+/** @template T @param {Decoder<T>} decode @returns {Decoder<T | null>} */
+export const nullable = decode => value => value === null ? null : decode(value);
+/** @template T @param {Decoder<T>} decode @returns {Decoder<T | undefined>} */
+export const optional = decode => value => value === undefined ? undefined : decode(value);
+/** @template T @param {Decoder<T>} decode @returns {Decoder<readonly T[]>} */
+export const list = decode => value => Object.freeze(array(value, "array").map(decode));
+/** @template T @param {{ [K in keyof T]: Decoder<T[K]> }} fields @returns {Decoder<Readonly<T>>} */
+export function record(fields) {
+  return value => {
+    const raw = object(value, "management response");
+    return Object.freeze(/** @type {T} */ (Object.fromEntries(Object.entries(fields).map(([key, decode]) =>
+      [key, /** @type {Decoder<unknown>} */ (decode)(raw[key])]))));
+  };
+}
+/** @template T @param {Decoder<T>} decode @returns {Decoder<Readonly<Record<string, T>>>} */
+export const dictionary = decode => value => Object.freeze(Object.fromEntries(Object.entries(object(value, "dictionary")).map(([key, item]) => [key, decode(item)])));

package/src/v1/management-routes.js

@@ -0,0 +1,67 @@
+/** @typedef {"getShapeManifest" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery"} ManagementOperation */
+const saved = "/v1/projects/{project}/saved-queries";
+/** @type {readonly import("./routes.js").V1Route[]} */
+export const managementV1Routes = Object.freeze([
+  route("getShapeManifest", "GET", "/v1/projects/{project}/databases/{database}/collections/{collection}/shape/manifest"),
+  route("healthz", "GET", "/healthz"),
+  route("readyz", "GET", "/readyz"),
+  route("backupz", "GET", "/backupz"),
+  route("replicationHealth", "GET", "/health/replication"),
+  route("listPlatformDatabases", "GET", "/v1/platform/databases"),
+  route("listPlatformCollections", "GET", "/v1/platform/databases/{database}/collections"),
+  route("listPlatformDocuments", "GET", "/v1/platform/databases/{database}/collections/{collection}/documents"),
+  route("getPlatformDocument", "GET", "/v1/platform/databases/{database}/collections/{collection}/documents/by-key"),
+  route("createImport", "POST", "/v1/projects/{project}/databases/{database}/import", 201),
+  route("getImport", "GET", "/v1/projects/{project}/databases/{database}/import", 200),
+  route("uploadImportSource", "PUT", "/v1/projects/{project}/databases/{database}/import/source", 200),
+  route("updateImport", "PATCH", "/v1/projects/{project}/databases/{database}/import", 202),
+  route("startImport", "POST", "/v1/projects/{project}/databases/{database}/import/start", 202),
+  route("cancelImport", "POST", "/v1/projects/{project}/databases/{database}/import/cancel", 202),
+  route("resumeImport", "POST", "/v1/projects/{project}/databases/{database}/import/resume", 202),
+  route("createBackup", "POST", "/v1/projects/{project}/databases/{database}/backups", 201),
+  route("listBackups", "GET", "/v1/projects/{project}/databases/{database}/backups", 200),
+  route("restoreBackup", "POST", "/v1/projects/{project}/databases/{database}/backups/{backup}/restore", 201),
+  route("getBackupPolicy", "GET", "/v1/projects/{project}/databases/{database}/backup-policy", 200),
+  route("setBackupPolicy", "PUT", "/v1/projects/{project}/databases/{database}/backup-policy", 200),
+  route("getRestoreWindow", "GET", "/v1/projects/{project}/databases/{database}/point-in-time", 200),
+  route("planPointInTime", "POST", "/v1/projects/{project}/databases/{database}/point-in-time/plan", 200),
+  route("restorePointInTime", "POST", "/v1/projects/{project}/databases/{database}/point-in-time/restore", 201),
+  route("getBackupDestination", "GET", "/v1/projects/{project}/backup-destination", 200),
+  route("setBackupDestination", "PUT", "/v1/projects/{project}/backup-destination", 200),
+  route("deleteBackupDestination", "DELETE", "/v1/projects/{project}/backup-destination", 204),
+  route("getProjectUsage", "GET", "/v1/projects/{project}/usage"),
+  route("getProjectAnalytics", "GET", "/v1/projects/{project}/analytics"),
+  route("getProjectReplication", "GET", "/v1/projects/{project}/replication"),
+  route("getDatabaseUsage", "GET", "/v1/projects/{project}/databases/{database}/usage"),
+  route("getDatabaseAnalytics", "GET", "/v1/projects/{project}/databases/{database}/analytics"),
+  route("getDatabaseReplication", "GET", "/v1/projects/{project}/databases/{database}/replication"),
+  route("createIndex", "POST", "/v1/projects/{project}/databases/{database}/indexes", 201),
+  route("listIndexes", "GET", "/v1/projects/{project}/databases/{database}/indexes", 200),
+  route("dropIndex", "DELETE", "/v1/projects/{project}/databases/{database}/indexes/{index}", 204),
+  route("getAutoIndexPolicy", "GET", "/v1/projects/{project}/databases/{database}/auto-index/{collection}", 200),
+  route("setAutoIndexPolicy", "PUT", "/v1/projects/{project}/databases/{database}/auto-index/{collection}", 200),
+  route("listIndexRecommendations", "GET", "/v1/projects/{project}/databases/{database}/index-recommendations", 200),
+  route("applyIndexRecommendation", "POST", "/v1/projects/{project}/databases/{database}/index-recommendations/{recommendation}/apply", 201),
+  route("getDatabaseSchema", "GET", "/v1/projects/{project}/databases/{database}/schema"),
+  route("inferCollectionSchema", "GET", "/v1/projects/{project}/databases/{database}/schema/{collection}"),
+  route("declareCollectionSchema", "PUT", "/v1/projects/{project}/databases/{database}/schema/{collection}"),
+  route("listQueryShapes", "GET", "/v1/projects/{project}/databases/{database}/query-shapes"),
+  route("createSavedQuery", "POST", saved, 201),
+  route("listSavedQueries", "GET", saved),
+  route("getSavedQuery", "GET", `${saved}/{query}`),
+  route("updateSavedQuery", "PUT", `${saved}/{query}`),
+  route("deleteSavedQuery", "DELETE", `${saved}/{query}`, 204),
+]);
+
+/** @param {ManagementOperation} operation @param {import("./routes.js").V1Route["method"]} method @param {string} pathTemplate @param {number} [status] @returns {import("./routes.js").V1Route} */
+function route(operation, method, pathTemplate, status = 200) {
+  const write = method !== "GET" && operation !== "planPointInTime";
+  const noBody = ["createBackup", "applyIndexRecommendation", "cancelImport", "resumeImport"].includes(operation);
+  return Object.freeze({ operation, method, pathTemplate,
+    permission: operation === "getShapeManifest" ? "documents:read" : pathTemplate.startsWith("/v1/platform/") ? "platform-admin" : !pathTemplate.startsWith("/v1/") ? "anonymous" : write ? "databases:write" : "databases:read",
+    additionalPermissions: Object.freeze(["createImport", "uploadImportSource", "updateImport", "startImport", "resumeImport"].includes(operation) ? ["documents:write"] : []),
+    requestMediaTypes: Object.freeze(noBody ? [] : operation === "uploadImportSource" ? ["application/octet-stream"] : method === "POST" || method === "PUT" || method === "PATCH" ? ["application/json"] : []),
+    responseMediaType: status === 204 ? "" : "application/json", successStatuses: Object.freeze(operation === "readyz" || operation === "backupz" ? [200, 503] : operation === "applyIndexRecommendation" || operation === "createImport" ? [200, 201] : [status]),
+    idempotencyKey: "none", replaySafe: !write, contract: "docs/terrabase/api.md", contractText: Object.freeze([]),
+  });
+}

package/src/v1/management-validation.js

@@ -0,0 +1,25 @@
+/** @import { V1DatabaseListRequest } from "./catalog.js" */
+/** @param {unknown} request @param {readonly string[]} allowed */
+export function members(request, allowed) {
+  if (request === null || typeof request !== "object" || Array.isArray(request) ||
+      ![Object.prototype, null].includes(Object.getPrototypeOf(request))) throw new TypeError("Expected a plain request object.");
+  for (const key of Object.keys(request)) if (!allowed.includes(key)) throw new TypeError(`Unknown request member ${key}.`);
+}
+/** @param {object} options */
+export function mutationOptions(options) {
+  if ("idempotencyKey" in options) throw new TypeError("The producer does not support Idempotency-Key; mutations are never replayed.");
+}
+/** @param {V1DatabaseListRequest} request */
+export function pageQuery(request) {
+  members(request, ["after", "limit"]);
+  const query = new URLSearchParams();
+  if (request.after !== undefined) {
+    if (typeof request.after !== "string") throw new TypeError("after must be an opaque string.");
+    query.set("after", request.after);
+  }
+  if (request.limit !== undefined) {
+    if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 100) throw new TypeError("limit must be 1-100.");
+    query.set("limit", String(request.limit));
+  }
+  return query;
+}

package/src/v1/routes.js

@@ -1,11 +1,13 @@
-// Routes owned by the C# Documents API at 0248ad3 (decision 0004 and shape-reads.md).
-/** @typedef {"getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape"} V1Operation */
+import { managementV1Routes } from "./management-routes.js";
+// Current TerraBase routes at e30ffdc; readShape is retained from release 6cb9745 only.
+/** @typedef {import("./management-routes.js").ManagementOperation | "readFreeShape" | "getShapeKey" | "getDocument" | "putDocument" | "createDocument" | "patchDocument" | "deleteDocument" | "commitTransaction" | "queryDocuments" | "createCollection" | "getCollection" | "listCollections" | "dropCollection" | "readShape" | "runSql" | "checkSql" | "explainSql" | "streamDatabaseChanges" | "listDocuments" | "getCollectionSchema" | "putCollectionSchema" | "deleteCollectionSchema" | "createDatabase" | "listDatabases" | "getDatabase" | "updateDatabase" | "deleteDatabase" | "branchDatabase"} V1Operation */
 /**
  * @typedef {object} V1Route
  * @property {V1Operation} operation
  * @property {"GET" | "PUT" | "POST" | "PATCH" | "DELETE"} method
  * @property {string} pathTemplate
- * @property {"documents:read" | "documents:write" | "shapes:read"} permission
+ * @property {"documents:read" | "documents:write" | "shapes:read" | "databases:read" | "databases:write" | "anonymous" | "platform-admin"} permission
+ * @property {readonly string[]} [additionalPermissions]
  * @property {readonly string[]} requestMediaTypes
  * @property {string} responseMediaType
  * @property {readonly number[]} successStatuses
@@ -18,13 +20,14 @@ const database = "/v1/projects/{project}/databases/{database}";
 const collections = `${database}/collections`;
 const collection = `${collections}/{collection}`;
 const documents = `${collection}/documents`;
+const databases = "/v1/projects/{project}/databases";
 /** @type {readonly V1Route[]} */
 export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
-  { operation: "getDocument", method: "GET", pathTemplate: `${documents}/{id}`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
-  { operation: "putDocument", method: "PUT", pathTemplate: `${documents}/{id}`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200, 201] },
+  { operation: "getDocument", method: "GET", pathTemplate: `${documents}/by-key`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "putDocument", method: "PUT", pathTemplate: `${documents}/by-key`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200, 201] },
   { operation: "createDocument", method: "POST", pathTemplate: documents, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
-  { operation: "patchDocument", method: "PATCH", pathTemplate: `${documents}/{id}`, permission: "documents:write", requestMediaTypes: ["application/merge-patch+json", "application/vnd.terrabase.ops+json"], successStatuses: [200] },
-  { operation: "deleteDocument", method: "DELETE", pathTemplate: `${documents}/{id}`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "patchDocument", method: "PATCH", pathTemplate: `${documents}/by-key`, permission: "documents:write", requestMediaTypes: ["application/merge-patch+json", "application/vnd.terrabase.ops+json"], successStatuses: [200] },
+  { operation: "deleteDocument", method: "DELETE", pathTemplate: `${documents}/by-key`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
   { operation: "commitTransaction", method: "POST", pathTemplate: `${database}/transactions`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
   { operation: "queryDocuments", method: "POST", pathTemplate: `${collection}/query`, permission: "documents:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
   { operation: "createCollection", method: "POST", pathTemplate: collections, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
@@ -32,10 +35,25 @@ export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
   { operation: "listCollections", method: "GET", pathTemplate: collections, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
   { operation: "dropCollection", method: "DELETE", pathTemplate: collection, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
   { operation: "readShape", method: "GET", pathTemplate: `${collection}/shape`, permission: "shapes:read", requestMediaTypes: [], successStatuses: [200, 307] },
+  { operation: "runSql", method: "POST", pathTemplate: `${database}/sql`, permission: "databases:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "checkSql", method: "POST", pathTemplate: `${database}/sql/check`, permission: "databases:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "explainSql", method: "POST", pathTemplate: `${database}/sql/explain`, permission: "databases:read", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "streamDatabaseChanges", method: "GET", pathTemplate: `${database}/changes`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "listDocuments", method: "GET", pathTemplate: documents, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "getCollectionSchema", method: "GET", pathTemplate: `${collection}/schema`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "putCollectionSchema", method: "PUT", pathTemplate: `${collection}/schema`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "deleteCollectionSchema", method: "DELETE", pathTemplate: `${collection}/schema`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "createDatabase", method: "POST", pathTemplate: databases, permission: "databases:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
+  { operation: "listDatabases", method: "GET", pathTemplate: databases, permission: "databases:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "getDatabase", method: "GET", pathTemplate: database, permission: "databases:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "updateDatabase", method: "PATCH", pathTemplate: database, permission: "databases:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "deleteDatabase", method: "DELETE", pathTemplate: database, permission: "databases:write", requestMediaTypes: [], successStatuses: [204] },
+  { operation: "branchDatabase", method: "POST", pathTemplate: `${database}/branches`, permission: "databases:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
 ].map(route => ({
-  ...route, responseMediaType: "application/json", idempotencyKey: "none",
-  replaySafe: route.permission !== "documents:write",
-  contract: route.operation === "readShape" ? "docs/shape-reads.md" : "docs/decisions/0004-document-api-v1.md",
+  ...route, responseMediaType: route.operation === "deleteDatabase" ? "" : route.operation === "streamDatabaseChanges" ? "text/event-stream" : "application/json", idempotencyKey: "none",
+  replaySafe: !route.permission.endsWith(":write"),
+  contract: route.operation === "readShape" ? "docs/shape-reads.md" :
+    ["runSql", "checkSql", "explainSql", "streamDatabaseChanges"].includes(route.operation) ? "docs/terrabase/api.md" : "docs/decisions/0004-document-api-v1.md",
   contractText: [],
 }))).map(route => Object.freeze({
   ...route, requestMediaTypes: Object.freeze(route.requestMediaTypes),
@@ -43,7 +61,7 @@ export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
 })));
 /** @param {V1Operation} operation @returns {V1Route} */
 export function v1Route(operation) {
-  const route = v1Routes.find(candidate => candidate.operation === operation);
+  const route = [...v1Routes, ...shapeV1Routes, ...managementV1Routes].find(candidate => candidate.operation === operation);
   if (route === undefined) throw new TypeError(`Unknown v1 operation ${operation}.`);
   return route;
 }
@@ -55,3 +73,10 @@ export function v1RoutePath(route, params) {
     return encodeURIComponent(value);
   });
 }
+
+// Proposed free-read protocol, separately inventoried from historical/runtime route evidence.
+/** @type {readonly V1Route[]} */
+export const shapeV1Routes = Object.freeze([
+  Object.freeze({ operation: /** @type {const} */ ("readFreeShape"), method: /** @type {const} */ ("GET"), pathTemplate: `${collection}/shape`, permission: /** @type {const} */ ("documents:read"), requestMediaTypes: Object.freeze([]), responseMediaType: "application/json", successStatuses: Object.freeze([200, 307]), idempotencyKey: /** @type {const} */ ("none"), replaySafe: true, contract: "docs/terrabase/shape-reads.md", contractText: Object.freeze([]) }),
+  Object.freeze({ operation: /** @type {const} */ ("getShapeKey"), method: /** @type {const} */ ("GET"), pathTemplate: `${collection}/shape/keys`, permission: /** @type {const} */ ("documents:read"), requestMediaTypes: Object.freeze([]), responseMediaType: "application/json", successStatuses: Object.freeze([200]), idempotencyKey: /** @type {const} */ ("none"), replaySafe: true, contract: "docs/terrabase/shape-reads.md", contractText: Object.freeze([]) }),
+]);

package/src/v1/saved-queries.js

@@ -0,0 +1,58 @@
+import { requireId } from "../ids.js";
+import { array, malformed, object, string } from "./decode.js";
+import { stringifyExactJson } from "./json.js";
+import { members, mutationOptions, pageQuery } from "./management-validation.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+/** @typedef {{ readonly id: string; readonly name: string; readonly sql: string; readonly createdAt: string; readonly updatedAt: string | null }} V1SavedQuery */
+/** @typedef {{ readonly name: string; readonly sql: string }} V1SavedQueryRequest */
+/** @typedef {{ readonly items: readonly V1SavedQuery[]; readonly next: string | null }} V1SavedQueryPage */
+
+/** @param {import("./json.js").JsonValue | undefined} value @returns {V1SavedQuery} */
+function savedQuery(value) {
+  const raw = object(value, "saved query");
+  return Object.freeze({ id: requireId(raw.id), name: string(raw.name, "saved query name"), sql: string(raw.sql, "saved SQL"),
+    createdAt: string(raw.createdAt, "saved query createdAt"), updatedAt: raw.updatedAt === null ? null : string(raw.updatedAt, "saved query updatedAt") });
+}
+/** @param {V1SavedQueryRequest} request */
+function body(request) {
+  members(request, ["name", "sql"]);
+  if (typeof request.name !== "string" || request.name.trim().length < 1 || request.name.trim().length > 128 ||
+      /[\p{Cc}]/u.test(request.name) || !/[\p{L}\p{N}]/u.test(request.name)) throw new TypeError("name must contain a letter or digit and be 1-128 characters without controls.");
+  if (typeof request.sql !== "string" || request.sql.trim() === "" || request.sql.length > 16_384)
+    throw new TypeError("sql must be a non-empty statement of at most 16384 UTF-16 code units.");
+  return stringifyExactJson({ name: request.name, sql: request.sql }, "saved query");
+}
+
+/** Saved queries belong to the authorized project, independently of database handles. */
+export class V1SavedQueries {
+  /** @type {V1Transport} */
+  #transport;
+  /** @param {V1Transport} transport */
+  constructor(transport) { this.#transport = transport; Object.freeze(this); }
+  /** @param {V1SavedQueryRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+  async create(request, options = {}) {
+    mutationOptions(options);
+    return savedQuery((await this.#transport.call("createSavedQuery", {}, { body: body(request), signal: options.signal })).value);
+  }
+  /** @param {import("./catalog.js").V1DatabaseListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<V1SavedQueryPage>} */
+  async list(request = {}, options = {}) {
+    const raw = object((await this.#transport.call("listSavedQueries", {}, { query: pageQuery(request), signal: options.signal })).value, "saved query page");
+    if (raw.next !== null && (typeof raw.next !== "string" || raw.next === "")) malformed("saved query next");
+    return Object.freeze({ items: Object.freeze(array(raw.items, "saved queries").map(savedQuery)), next: raw.next });
+  }
+  /** @param {string} id @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+  async get(id, options = {}) {
+    return savedQuery((await this.#transport.call("getSavedQuery", { query: requireId(id) }, { signal: options.signal })).value);
+  }
+  /** @param {string} id @param {V1SavedQueryRequest} request @param {V1RequestOptions} [options] @returns {Promise<V1SavedQuery>} */
+  async update(id, request, options = {}) {
+    mutationOptions(options);
+    return savedQuery((await this.#transport.call("updateSavedQuery", { query: requireId(id) }, { body: body(request), signal: options.signal })).value);
+  }
+  /** @param {string} id @param {V1RequestOptions} [options] @returns {Promise<void>} */
+  async delete(id, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("deleteSavedQuery", { query: requireId(id) }, { signal: options.signal });
+  }
+}