@terrascale/sdk 0.0.5 → 0.0.7

package/src/v1/change-webhooks.js

@@ -0,0 +1,78 @@
+import { requireId } from "../ids.js";
+import { requireName } from "./ids.js";
+import { object, string } from "./decode.js";
+import { list, nullable, numeric, record, text } from "./management-decode.js";
+import { members, mutationOptions, pageQuery } from "./management-validation.js";
+import { stringifyExactJson } from "./json.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const webhook = record({ id: requireId, url: text, createdAt: text, status: text });
+const webhooks = list(webhook);
+const deliveries = list(record({ id: requireId, createdAt: text, status: text, attempts: numeric,
+  lastAttemptAt: nullable(text), nextAttemptAt: nullable(text), httpStatus: nullable(numeric), errorCode: nullable(text) }));
+/** @typedef {ReturnType<typeof webhook>} V1ChangeWebhook */
+/** @typedef {V1ChangeWebhook & { readonly secret: string }} V1CreatedChangeWebhook */
+/** @typedef {ReturnType<typeof deliveries>[number]} V1ChangeWebhookDelivery */
+/** @typedef {{ readonly after?: string; readonly limit?: number }} V1ChangeWebhookListRequest */
+
+/** @param {V1ChangeWebhookListRequest} request */
+function query(request) {
+  if (request.after !== undefined) requireId(request.after, "after");
+  return pageQuery(request);
+}
+
+/** Collection change webhook registration and sanitized delivery history. Requests are never replayed. */
+export class V1ChangeWebhooks {
+  /** @type {V1Transport} */
+  #transport;
+  /** @type {{database: string; collection: string}} */
+  #params;
+  /** @param {V1Transport} transport @param {string} database @param {string} collection */
+  constructor(transport, database, collection) {
+    this.#transport = transport;
+    this.#params = { database: requireName("database", database), collection: requireName("collection", collection) };
+    Object.freeze(this);
+  }
+  /**
+   * Registers from the current feed head. Requires documents:read and documents:write.
+   * Store secret immediately; it is non-enumerable to keep it out of JSON and ordinary diagnostics.
+   * @param {{ readonly url: string }} request @param {V1RequestOptions} [options] @returns {Promise<V1CreatedChangeWebhook>}
+   */
+  async create(request, options = {}) {
+    members(request, ["url"]);
+    if (typeof request.url !== "string" || request.url.length > 2048) throw new TypeError("Webhook URL must be an HTTPS URL of at most 2048 characters.");
+    let url;
+    try { url = new URL(request.url); } catch { throw new TypeError("Webhook URL must be absolute HTTPS."); }
+    if (url.protocol !== "https:" || url.port !== "" || url.username !== "" || url.password !== "" || url.hash !== "")
+      throw new TypeError("Webhook URL must be HTTPS on port 443, without credentials or a fragment.");
+    mutationOptions(options);
+    const raw = object((await this.#transport.call("createChangeWebhook", this.#params, {
+      body: stringifyExactJson(request, "change webhook"), signal: options.signal,
+    })).value, "created webhook");
+    const secret = string(raw.secret, "webhook secret");
+    return Object.freeze(Object.defineProperty({ ...webhook(raw), secret }, "secret", { enumerable: false }));
+  }
+  /**
+   * Requires documents:read. Ascending IDs; continue with the final ID until an empty array. No secrets.
+   * @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhook[]>}
+   */
+  async list(request = {}, options = {}) {
+    return webhooks((await this.#transport.call("listChangeWebhooks", this.#params, { query: query(request), signal: options.signal })).value);
+  }
+  /**
+   * Requires documents:read and documents:write. An in-flight delivery may still complete. Unknown ID returns 404.
+   * @param {string} id @param {V1RequestOptions} [options] @returns {Promise<void>}
+   */
+  async delete(id, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("deleteChangeWebhook", { ...this.#params, webhook: requireId(id) }, { signal: options.signal });
+  }
+  /**
+   * Requires documents:read. Latest 100 retained records; paginate with the final ID until an empty array.
+   * @param {string} id @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhookDelivery[]>}
+   */
+  async deliveries(id, request = {}, options = {}) {
+    return deliveries((await this.#transport.call("listChangeWebhookDeliveries", { ...this.#params, webhook: requireId(id) },
+      { query: query(request), signal: options.signal })).value);
+  }
+}

package/src/v1/changes.js

@@ -1,6 +1,6 @@
 import { documentObject, malformed, object, u64 } from "./decode.js";
 import { parseV1Error } from "./errors.js";
-import { requireDocumentId, requireName } from "./ids.js";
+import { requireStoredId, requireName } from "./ids.js";
 import { parseExactJson } from "./json.js";
 import { BodyTransportError } from "./transport.js";
 /** @import { JsonObject } from "./json.js" */
@@ -156,7 +156,7 @@ function decodeEvent(event, headers) {
   if (raw.op !== "upsert" && raw.op !== "delete") malformed("changes operation");
   if (typeof raw.origin !== "string" || !/^[0-9a-f]{16}$/u.test(raw.origin)) malformed("changes origin");
   return Object.freeze({ type: "change", cursor, collection: requireName("collection", raw.collection),
-    id: requireDocumentId(raw.id), op: raw.op, version: u64(raw.version, "changes version"), origin: raw.origin,
+    id: requireStoredId(raw.id), op: raw.op, version: u64(raw.version, "changes version"), origin: raw.origin,
     document: raw.document === null ? null : documentObject(raw.document),
   });
 }

package/src/v1/decode.js

@@ -1,5 +1,5 @@
 // Typed decoding of TerraBase v1 response bodies.
-import { parseU64, requireDocumentId, requireVersion } from "./ids.js";
+import { parseU64, requireDocumentId, requireStoredId, requireVersion } from "./ids.js";
 import { isJsonObject } from "./json.js";
 /** @import { JsonObject, JsonValue } from "./json.js" */
 
@@ -13,7 +13,8 @@ import { isJsonObject } from "./json.js";
  * @property {"value" | "conflict" | (string & {})} state
  * @property {JsonObject} document
  * @property {readonly JsonValue[]} [siblings] Live versions and tombstones on a causal conflict.
- * @property {number} [distance] Distance to the query vector; present only on `near` query results.
+ * @property {number} [distance] Distance to the query vector, or meters to a geo `near` point; present only on `near` query results.
+ * @property {number} [score] Full-text relevance score on results sorted by `$score`.
  */
 
 /**
@@ -100,7 +101,7 @@ export function durability(value) {
  */
 export function decodeDocument(value) {
   const raw = object(value, "document");
-  const id = requireDocumentId(raw.id);
+  const id = requireStoredId(raw.id);
   const version = requireVersion(raw.version);
   const state = string(raw.state, "document state");
   const document = documentObject(raw.document);

package/src/v1/errors.js

@@ -76,6 +76,7 @@ export const V1ErrorCode = Object.freeze({
   mustRefetch: "must_refetch", preconditionFailed: "precondition_failed", payloadTooLarge: "payload_too_large",
   unsupportedMediaType: "unsupported_media_type", uriTooLong: "uri_too_long", shapeBusy: "shape_busy",
   internalError: "internal_error", capacity: "capacity", notModified: "not_modified",
+  sqlError: "sql_error", sqlConflict: "sql_conflict", sqlTooLarge: "sql_too_large",
 });
 
 /** `412 precondition_failed`: an If-Match, If-None-Match, assert or assert_count failed. */
@@ -114,11 +115,36 @@ export class V1NotFoundError extends TerraBaseV1Error {
   }
 }
 
+/**
+ * A refused relational SQL statement: `sql_error` (400), `forbidden_scope` (403, writes and DDL need
+ * documents:write), `sql_conflict` (409) or `sql_too_large` (413). The whole request rolled back.
+ */
+export class SqlError extends TerraBaseV1Error {
+  /** @type {number} Zero-based index of the failing statement. */
+  statement;
+  /** @type {string | undefined} The SQLite error code, such as `SQLITE_CONSTRAINT_PRIMARYKEY`. */
+  sqliteCode;
+
+  /** @param {TerraBaseV1ErrorInit & { statement: number; sqliteCode?: string | undefined }} init */
+  constructor(init) {
+    super(init);
+    this.name = "SqlError";
+    this.statement = init.statement;
+    this.sqliteCode = init.sqliteCode;
+  }
+}
+
 /**
  * @param {TerraBaseV1ErrorInit} init
  * @returns {TerraBaseV1Error}
  */
 function typedError(init) {
+  // Only the SQL execute route reports a statement index.
+  const statement = init.details?.statement;
+  if (typeof statement === "number" && Number.isInteger(statement) && statement >= 0) {
+    const sqliteCode = init.details?.sqlite_code;
+    return new SqlError({ ...init, statement, sqliteCode: typeof sqliteCode === "string" ? sqliteCode : undefined });
+  }
   switch (init.code) {
     case "precondition_failed": return new V1PreconditionFailedError(init);
     case "invalid_key": return new V1InvalidKeyError(init);

package/src/v1/export.js

@@ -1,5 +1,5 @@
 import { documentObject, malformed, object } from "./decode.js";
-import { requireDocumentId, requireName } from "./ids.js";
+import { requireStoredId, requireName } from "./ids.js";
 import { parseExactJson } from "./json.js";
 import { BodyTransportError } from "./transport.js";
 /** @import { JsonObject } from "./json.js" */
@@ -22,7 +22,7 @@ function decodeLine(line) {
   try { value = parseExactJson(line); }
   catch { malformed("export line JSON"); }
   const raw = object(value, "export line");
-  return Object.freeze({ collection: requireName("collection", raw.collection), id: requireDocumentId(raw.id), document: documentObject(raw.document) });
+  return Object.freeze({ collection: requireName("collection", raw.collection), id: requireStoredId(raw.id), document: documentObject(raw.document) });
 }
 
 /**
@@ -39,7 +39,7 @@ export async function* exportDocuments(transport, database, options = {}) {
   if (after !== undefined) {
     if (typeof after !== "object" || after === null) throw new TypeError("export after is { collection, id }.");
     query.set("after_collection", requireName("collection", after.collection));
-    query.set("after_id", requireDocumentId(after.id));
+    query.set("after_id", requireStoredId(after.id));
   }
   const response = await transport.openStream("exportDatabase", { database }, { query, signal });
   const body = /** @type {ReadableStream<Uint8Array>} */ (response.body);

package/src/v1/filter.js

@@ -24,7 +24,17 @@ import { ExactDecimal } from "./json.js";
  *   | { readonly nin: readonly [V1Path, readonly V1Scalar[]] }
  *   | { readonly exists: V1Path }
  *   | { readonly prefix: readonly [V1Path, string] }
- *   | { readonly contains: readonly [V1Path, V1Scalar] }} V1Filter
+ *   | { readonly contains: readonly [V1Path, V1Scalar] }
+ *   | { readonly within: readonly [string, V1GeoCircle | V1GeoBox] }
+ *   | { readonly search: readonly [V1Path, string] }} V1Filter
+ */
+/**
+ * Points within `meters` (more than 0, at most 20000000) of a WGS 84 point, by haversine distance.
+ * @typedef {{ readonly lat: number; readonly lon: number; readonly meters: number }} V1GeoCircle
+ */
+/**
+ * Points in a latitude/longitude box; `west > east` crosses the antimeridian.
+ * @typedef {{ readonly south: number; readonly west: number; readonly north: number; readonly east: number }} V1GeoBox
  */
 
 /**
@@ -54,6 +64,28 @@ export function requirePath(path) {
   throw new TypeError('A TerraBase path is an RFC 6901 JSON Pointer of 1-16 segments, "$id".');
 }
 
+/** @param {V1Path} path @returns {V1Path} */
+function requireSearchPath(path) {
+  if (isJsonPointer(path)) return path;
+  throw new TypeError("search requires a JSON Pointer of 1-16 segments, excluding $id.");
+}
+
+/** @param {unknown} terms @returns {string} */
+function requireSearchTerms(terms) {
+  if (typeof terms !== "string" || terms.length === 0 || terms.includes("\0") || /[\uD800-\uDFFF]/u.test(terms) || new TextEncoder().encode(terms).byteLength > 4096)
+    throw new TypeError("search takes nonempty string terms of at most 4096 UTF-8 bytes without NUL.");
+  return terms;
+}
+
+/** @param {V1Filter | null | undefined} filter @returns {number} */
+export function searchCount(filter) {
+  if (!filter) return 0;
+  if ("search" in filter) return 1;
+  if ("and" in filter) return filter.and.reduce((count, child) => count + searchCount(child), 0);
+  if ("or" in filter) return filter.or.reduce((count, child) => count + searchCount(child), 0);
+  return "not" in filter ? searchCount(filter.not) : 0;
+}
+
 /**
  * @param {V1Scalar} value
  * @returns {V1Scalar}
@@ -92,6 +124,46 @@ function scalars(op, values) {
   return Object.freeze(values.map(requireScalar));
 }
 
+/**
+ * @param {unknown} lat
+ * @param {unknown} lon
+ * @returns {void}
+ */
+export function requireGeoPoint(lat, lon) {
+  if (typeof lat !== "number" || typeof lon !== "number" || !(lat >= -90 && lat <= 90 && lon >= -180 && lon <= 180))
+    throw new TypeError("lat is -90 to 90 and lon is -180 to 180.");
+}
+
+/**
+ * @param {unknown} area
+ * @returns {V1GeoCircle | V1GeoBox}
+ */
+function geoArea(area) {
+  if (typeof area !== "object" || area === null || Array.isArray(area)) throw new TypeError("within takes a circle or box object.");
+  const keys = Object.keys(area).sort().join();
+  const a = /** @type {Record<string, unknown>} */ (area);
+  if (keys === "east,north,south,west") {
+    requireGeoPoint(a.south, a.west);
+    requireGeoPoint(a.north, a.east);
+    if (/** @type {number} */ (a.south) > /** @type {number} */ (a.north)) throw new TypeError("A within box has south <= north.");
+    return Object.freeze({ south: /** @type {number} */ (a.south), west: /** @type {number} */ (a.west), north: /** @type {number} */ (a.north), east: /** @type {number} */ (a.east) });
+  }
+  if (keys !== "lat,lon,meters" || typeof a.meters !== "number" || !(a.meters > 0 && a.meters <= 20_000_000))
+    throw new TypeError("within takes {lat, lon, meters (0 to 20000000)} or {south, west, north, east}.");
+  requireGeoPoint(a.lat, a.lon);
+  return Object.freeze({ lat: /** @type {number} */ (a.lat), lon: /** @type {number} */ (a.lon), meters: a.meters });
+}
+
+/**
+ * @param {V1Path} path
+ * @param {unknown} area
+ * @returns {V1Filter}
+ */
+function within(path, area) {
+  if (requirePath(path) === "$id") throw new TypeError("within takes a JSON Pointer.");
+  return Object.freeze({ within: Object.freeze(/** @type {const} */ ([path, geoArea(area)])) });
+}
+
 const binaryOperators = new Set(["eq", "ne", "lt", "lte", "gt", "gte", "contains"]);
 
 /**
@@ -119,7 +191,15 @@ export function requireFilter(filter) {
       for (const child of args) visit(child, depth + 1);
     } else if (op === "not") visit(args, depth + 1);
     else if (op === "exists") requirePath(/** @type {V1Path} */ (args));
-    else if (binaryOperators.has(op) || op === "prefix" || op === "in" || op === "nin") {
+    else if (op === "within") {
+      if (!Array.isArray(args) || args.length !== 2) throw new TypeError("within takes [path, area].");
+      within(args[0], args[1]);
+    }
+    else if (op === "search") {
+      if (!Array.isArray(args) || args.length !== 2) throw new TypeError("search takes [path, terms].");
+      requireSearchPath(args[0]);
+      requireSearchTerms(args[1]);
+    } else if (binaryOperators.has(op) || op === "prefix" || op === "in" || op === "nin") {
       if (!Array.isArray(args) || args.length !== 2) throw new TypeError(`${op} takes [path, value].`);
       requirePath(args[0]);
       if (op === "in" || op === "nin") scalars(op, args[1]);
@@ -220,6 +300,13 @@ export const v1Filter = Object.freeze({
     if (typeof prefix !== "string") throw new TypeError("prefix takes a string.");
     return Object.freeze({ prefix: Object.freeze(/** @type {const} */ ([requirePath(path), prefix])) });
   },
+  /**
+   * Full-text search on a document member.
+   * @param {V1Path} path
+   * @param {string} terms
+   * @returns {V1Filter}
+   */
+  search: (path, terms) => Object.freeze({ search: Object.freeze(/** @type {const} */ ([requireSearchPath(path), requireSearchTerms(terms)])) }),
   /**
    * The value is an array containing the scalar.
    * @param {V1Path} path
@@ -227,4 +314,18 @@ export const v1Filter = Object.freeze({
    * @returns {V1Filter}
    */
   contains: (path, value) => Object.freeze({ contains: Object.freeze(/** @type {const} */ ([requirePath(path), requireScalar(value)])) }),
+  /**
+   * The `{lat, lon}` object at `path` lies within `meters` of the center (haversine, WGS 84 mean radius).
+   * @param {string} path JSON Pointer of a `{lat, lon}` point.
+   * @param {V1GeoCircle} circle `meters` is more than 0, at most 20000000.
+   * @returns {V1Filter}
+   */
+  withinRadius: (path, circle) => within(path, { lat: circle?.lat, lon: circle?.lon, meters: circle?.meters }),
+  /**
+   * The `{lat, lon}` object at `path` lies in the box; `west > east` crosses the antimeridian.
+   * @param {string} path JSON Pointer of a `{lat, lon}` point.
+   * @param {V1GeoBox} box
+   * @returns {V1Filter}
+   */
+  withinBox: (path, box) => within(path, { south: box?.south, west: box?.west, north: box?.north, east: box?.east }),
 });

package/src/v1/ids.js

@@ -27,11 +27,16 @@ export function requireProject(project) {
   return requireId(project);
 }
 
-/** A caller-supplied key is not a generated entity ID. @param {unknown} id @returns {string} */
+/** Every document id is a canonical ULID. @param {unknown} id @returns {string} */
 export function requireDocumentId(id) {
+  return requireId(id, "TerraBase document ID");
+}
+
+/** SQL-backed collections can return non-ULID primary keys. @param {unknown} id @returns {string} */
+export function requireStoredId(id) {
   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.");
+    throw new TypeError("TerraBase stored IDs must be 1-256 characters of valid UTF-8 without control characters.");
   return id;
 }
 

package/src/v1/indexes.js

@@ -1,10 +1,10 @@
 import { requireName } from "./ids.js";
-import { flag, list, numeric, record, text } from "./management-decode.js";
+import { flag, list, numeric, optional, 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 index = record({ name: text, collection: text, fields: list(text), state: text, kind: optional(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 })) });
@@ -14,7 +14,8 @@ const applied = record({ status: text, index });
 /** @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 */
+/** @typedef {"btree" | "text"} V1IndexKind */
+/** @typedef {{ readonly collection: string; readonly fields: readonly string[]; readonly name?: string | null; readonly kind?: V1IndexKind }} 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.");
@@ -31,7 +32,8 @@ export class V1Indexes {
   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"]);
+    members(request, ["collection", "fields", "name", "kind"]);
+    if (request.kind !== undefined && request.kind !== "btree" && request.kind !== "text") throw new TypeError("kind must be btree or text.");
     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)))

package/src/v1/management-routes.js

@@ -1,10 +1,17 @@
-/** @typedef {"getShapeManifest" | "exportDatabase" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "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 */
+/** @typedef {"getShapeManifest" | "exportDatabase" | "executeSql" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "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" | "createChangeWebhook" | "listChangeWebhooks" | "deleteChangeWebhook" | "listChangeWebhookDeliveries"} ManagementOperation */
+const webhooks = "/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks";
 const saved = "/v1/projects/{project}/saved-queries";
 const ttl = "/v1/projects/{project}/databases/{database}/collections/{collection}/ttl";
 /** @type {readonly import("./routes.js").V1Route[]} */
 export const managementV1Routes = Object.freeze([
+  route("createChangeWebhook", "POST", webhooks, 201),
+  route("listChangeWebhooks", "GET", webhooks),
+  route("deleteChangeWebhook", "DELETE", `${webhooks}/{webhook}`, 204),
+  route("listChangeWebhookDeliveries", "GET", `${webhooks}/{webhook}/deliveries`),
   route("getShapeManifest", "GET", "/v1/projects/{project}/databases/{database}/collections/{collection}/shape/manifest"),
   route("exportDatabase", "GET", "/v1/projects/{project}/databases/{database}/export"),
+  // Reads need documents:read; writes and DDL also need documents:write, checked per statement.
+  route("executeSql", "POST", "/v1/projects/{project}/databases/{database}/sql/execute"),
   route("putCollectionTtl", "PUT", ttl),
   route("getCollectionTtl", "GET", ttl),
   route("deleteCollectionTtl", "DELETE", ttl),
@@ -61,12 +68,13 @@ export const managementV1Routes = Object.freeze([
 /** @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 webhook = pathTemplate.startsWith(webhooks);
   const noBody = ["createBackup", "applyIndexRecommendation", "cancelImport", "resumeImport"].includes(operation);
   return Object.freeze({ operation, method, pathTemplate,
-    permission: operation === "getShapeManifest" || operation === "exportDatabase" || operation === "getCollectionTtl" ? "documents:read" : pathTemplate === ttl ? "documents:write" : 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"] : []),
+    permission: webhook ? write ? "documents:write" : "documents:read" : operation === "getShapeManifest" || operation === "exportDatabase" || operation === "executeSql" || operation === "getCollectionTtl" ? "documents:read" : pathTemplate === ttl ? "documents:write" : pathTemplate.startsWith("/v1/platform/") ? "platform-admin" : !pathTemplate.startsWith("/v1/") ? "anonymous" : write ? "databases:write" : "databases:read",
+    additionalPermissions: Object.freeze(webhook && write ? ["documents:read"] : ["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 ? "" : operation === "exportDatabase" ? "application/x-ndjson" : "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([]),
+    idempotencyKey: "none", replaySafe: !write, contract: webhook ? "docs/terrabase/change-webhooks.md" : "docs/terrabase/api.md", contractText: Object.freeze([]),
   });
 }

package/src/v1/shape-reader.js

@@ -5,6 +5,7 @@ import { decodeShapePage, encodeShapeRequest, requireShapeHandle, requireShapeOf
 import { decryptShapeObject } from "./shape-crypto.js";
 import { parseExactJson } from "./json.js";
 import { TerraBaseV1Error } from "./errors.js";
+import { OpaqueRedirectError } from "./transport.js";
 /** @import { V1Transport } from "./transport.js" */
 /** @import { V1ShapeRequest, V1ShapePage } from "./shapes.js" */
 /** @typedef {{handle: string; offset: string; epoch: string; keyId: string}} V1SealedShapePosition */
@@ -125,11 +126,9 @@ export async function readShapePage(transport, params, request, signal, ifNoneMa
       query.delete("cursor");
     }
   }
-  let response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal });
-  if (response.status === 307) {
-    if (query.get("offset") !== "-1") malformed("unexpected shape redirect");
-    const location = response.headers.get("location");
-    if (location === null) malformed("shape redirect Location");
+  const bootstrap = query.get("offset") === "-1";
+  /** @param {string} location */
+  const redirectTarget = location => {
     const target = new URL(location, source);
     if (target.origin !== source.origin || target.pathname !== source.pathname || target.username !== "" || target.password !== "" || target.hash !== "") malformed("shape redirect target");
     for (const key of target.searchParams.keys()) {
@@ -144,6 +143,21 @@ export async function readShapePage(transport, params, request, signal, ifNoneMa
     delete headers["TB-Shape-Resume"];
     query.set("handle", handle);
     query.set("offset", offset);
+  };
+  let response;
+  try { response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal }); }
+  catch (error) {
+    if (!(error instanceof OpaqueRedirectError) || !bootstrap) throw error;
+    // Browsers hide a manual 307; follow it natively, then hold the final URL to the Location rules.
+    response = await shapeCall(transport, params, "readFreeShape", { query: new URLSearchParams(query), headers: { ...headers }, signal, redirect: "follow" });
+    if (response.redirectedTo === undefined || response.status !== 200) malformed("shape bootstrap requires redirect");
+    redirectTarget(response.redirectedTo);
+  }
+  if (response.status === 307) {
+    if (!bootstrap) malformed("unexpected shape redirect");
+    const location = response.headers.get("location");
+    if (location === null) malformed("shape redirect Location");
+    redirectTarget(location);
     response = await shapeCall(transport, params, "readFreeShape", { query, headers, signal });
     if (response.status !== 200) malformed("repeated shape redirect");
   } else if (query.get("offset") === "-1") malformed("shape bootstrap requires redirect");

package/src/v1/shape-replica.js

@@ -0,0 +1,46 @@
+// Browser storage for a shape subscription's read replica. Durable writes never queue here.
+/** @import { V1ShapeReplicaStore } from "./shape-subscription.js" */
+
+/**
+ * A V1ShapeReplicaStore kept in browser IndexedDB, one record per key.
+ * @param {string} key Names one subject's shape, e.g. `${userId}/notes/open`; clear it on sign-out.
+ * @returns {V1ShapeReplicaStore}
+ */
+export function indexedDbShapeReplica(key) {
+  if (typeof key !== "string" || key === "") throw new TypeError("An IndexedDB replica key is a non-empty string.");
+  /** @type {Promise<IDBDatabase> | undefined} */
+  let opened;
+  /** @returns {Promise<IDBDatabase>} */
+  const open = () => opened ??= new Promise((resolve, reject) => {
+    const request = indexedDB.open("terrascale-shape-replicas", 1);
+    request.onupgradeneeded = () => { request.result.createObjectStore("replicas"); };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => { opened = undefined; reject(request.error); };
+  });
+  /**
+   * @template T
+   * @param {IDBTransactionMode} mode
+   * @param {(store: IDBObjectStore) => IDBRequest<T>} operation
+   * @returns {Promise<T>}
+   */
+  const run = async (mode, operation) => {
+    const database = await open();
+    return new Promise((resolve, reject) => {
+      const transaction = database.transaction("replicas", mode);
+      const request = operation(transaction.objectStore("replicas"));
+      transaction.oncomplete = () => resolve(request.result);
+      transaction.onerror = transaction.onabort = () => reject(transaction.error ?? request.error);
+    });
+  };
+  return Object.freeze({
+    load: async () => {
+      const value = await run("readonly", store => store.get(key));
+      return typeof value === "string" ? value : undefined;
+    },
+    /** @param {string | undefined} text */
+    save: async text => {
+      if (text === undefined) await run("readwrite", store => store.delete(key));
+      else await run("readwrite", store => store.put(text, key));
+    },
+  });
+}