@terrascale/sdk 0.0.6 → 0.0.8

package/src/local/router.js

@@ -1,4 +1,4 @@
-import { generateId } from "../ids.js";
+import { generateId, isValidId } from "../ids.js";
 import {
   createHash,
   createHmac,
@@ -171,7 +171,7 @@ export class TerraScaleLocalRouter {
         );
         if (match === null) return problemResponse(404, "unknown_route");
         const collection = requireDatabaseId(match[1]);
-        const document = requireDatabaseId(match[2]);
+        const document = documentId(match[2]);
         return await this.#store.exclusive(() => {
           this.#binding(collection);
           return jsonResponse(this.#point(collection, document));
@@ -752,6 +752,15 @@ function transactionKey(raw) {
   const id = object(raw.transaction_id);
   return `${text(id.expires_at_unix_ms)}:${text(id.nonce)}`;
 }
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function documentId(value) {
+  if (!isValidId(value)) throw new NativeLocalError(400, "invalid_document_id");
+  return value;
+}
+
 /**
  * @param {unknown} value
  * @returns {readonly DatabaseField[]}
@@ -815,7 +824,7 @@ function decodeCommit(raw) {
         collection: requireDatabaseId(write.collection),
         schema_generation: decimal(write.schema_generation),
         schema_digest: text(write.schema_digest),
-        document: requireDatabaseId(write.document),
+        document: documentId(write.document),
         condition: /** @type {DatabaseCondition} */ (parsedCondition),
         observed: write.observed.map((rawObserved) => {
           const observed = object(rawObserved);

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/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/file-storage-routes.js

@@ -0,0 +1,17 @@
+/** @typedef {"createFileBucket" | "listFileBuckets" | "setFileBucketRules" | "deleteFileBucket" | "createFileUpload" | "completeFileUpload" | "listBucketFiles" | "createFileDownload" | "deleteBucketFile"} FileStorageOperation */
+const buckets = "/v1/projects/{project}/buckets";
+const bucket = `${buckets}/{bucket}`;
+const files = `${bucket}/files`;
+const file = `${files}/{file}`;
+/** @type {readonly import("./routes.js").V1Route[]} */
+export const fileStorageRoutes = Object.freeze(/** @type {import("./routes.js").V1Route[]} */ ([
+  { operation: "createFileBucket", method: "POST", pathTemplate: buckets, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
+  { operation: "listFileBuckets", method: "GET", pathTemplate: buckets, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "setFileBucketRules", method: "PUT", pathTemplate: `${bucket}/rules`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [200] },
+  { operation: "deleteFileBucket", method: "DELETE", pathTemplate: bucket, permission: "documents:write", requestMediaTypes: [], successStatuses: [204] },
+  { operation: "createFileUpload", method: "POST", pathTemplate: `${files}/upload`, permission: "documents:write", requestMediaTypes: ["application/json"], successStatuses: [201] },
+  { operation: "completeFileUpload", method: "POST", pathTemplate: `${file}/complete`, permission: "documents:write", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "listBucketFiles", method: "GET", pathTemplate: files, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "createFileDownload", method: "POST", pathTemplate: `${file}/download`, permission: "documents:read", requestMediaTypes: [], successStatuses: [200] },
+  { operation: "deleteBucketFile", method: "DELETE", pathTemplate: file, permission: "documents:write", requestMediaTypes: [], successStatuses: [204] },
+].map(route => Object.freeze({ ...route, responseMediaType: route.successStatuses.includes(204) ? "" : "application/json", idempotencyKey: "none", replaySafe: route.method === "GET", contract: "docs/file-buckets.md", contractText: [] }))));

package/src/v1/file-storage.js

@@ -0,0 +1,163 @@
+import { array, boolean, malformed, object, string } from "./decode.js";
+import { requireId } from "../ids.js";
+import { assertJsonObject, stringifyExactJson } from "./json.js";
+import { requireServiceUrl } from "./transport.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { FetchLike } from "../config.js" */
+/** @import { JsonObject, JsonValue } from "./json.js" */
+/** @typedef {{ owner: boolean, public: boolean, roles: readonly string[] }} FileAccessPolicy */
+/** @typedef {{ owner: string | null, read: FileAccessPolicy, write: FileAccessPolicy }} FileAccessRules */
+/** @typedef {{ id: string, name: string, region: string, rules: FileAccessRules }} FileBucketInfo */
+/** @typedef {{ id: string, name: string, contentType: string, size: number, sha256: string, metadata: JsonObject, status: string, uploadExpiresAt: string }} StoredFile */
+/** @typedef {{ id: string, url: string, expiresAt: string, headers: Readonly<Record<string, string>> }} SignedFileUrl */
+/** @typedef {{ name: string, contentType: string, size: number, sha256: string, metadata: JsonObject }} FileUploadRequest */
+/** @typedef {{ signal?: AbortSignal | undefined }} FileRequestOptions */
+/** @typedef {{ after?: string | undefined, signal?: AbortSignal | undefined }} FileListOptions */
+/** @typedef {{ metadata: JsonObject, contentType?: string | undefined, signal?: AbortSignal | undefined }} FileUploadOptions */
+const maxFileBytes = 100 * 1024 * 1024;
+
+/** @param {JsonValue | undefined} value @returns {FileAccessPolicy} */
+function policy(value) {
+  const v = object(value, "file access policy");
+  return { owner: boolean(v.owner, "owner grant"), public: boolean(v.public, "public grant"), roles: array(v.roles, "roles").map(v => string(v, "role")) };
+}
+/** @param {JsonValue | undefined} value @returns {FileAccessRules} */
+function rules(value) {
+  const v = object(value, "file access rules");
+  return { owner: v.owner === null ? null : string(v.owner, "owner pointer"), read: policy(v.read), write: policy(v.write) };
+}
+/** @param {JsonValue | undefined} value @returns {FileBucketInfo} */
+function bucketInfo(value) {
+  const v = object(value, "file bucket");
+  return { id: requireId(v.id), name: string(v.name, "bucket name"), region: string(v.region, "bucket region"), rules: rules(v.rules) };
+}
+/** @param {JsonValue | undefined} value @returns {StoredFile} */
+function storedFile(value) {
+  const v = object(value, "file");
+  if (typeof v.size !== "number" || !Number.isSafeInteger(v.size) || v.size < 1 || v.size > maxFileBytes) malformed("file size");
+  return { id: requireId(v.id), name: string(v.name, "file name"), contentType: string(v.contentType, "content type"), size: v.size,
+    sha256: string(v.sha256, "checksum"), metadata: object(v.metadata, "file metadata"), status: string(v.status, "file status"), uploadExpiresAt: string(v.uploadExpiresAt, "upload expiry") };
+}
+/** @param {JsonValue | undefined} value @returns {SignedFileUrl} */
+function signed(value) {
+  const v = object(value, "signed file URL");
+  const url = string(v.url, "signed URL");
+  requireServiceUrl(url, "Signed file URL");
+  /** @type {Record<string, string>} */
+  const headers = {};
+  for (const [key, val] of Object.entries(object(v.headers, "signed headers"))) {
+    // Object-store capabilities must never carry the project's authorization or cookies.
+    if (!["content-type", "content-length", "x-amz-checksum-sha256"].includes(key.toLowerCase())) malformed("signed upload header");
+    headers[key] = string(val, "signed header value");
+  }
+  return { id: requireId(v.id), url, expiresAt: string(v.expiresAt, "signed URL expiry"), headers };
+}
+/** @param {FileListOptions} options @returns {URLSearchParams} */
+function pageQuery(options) {
+  const query = new URLSearchParams();
+  if (options.after !== undefined) query.set("after", requireId(options.after));
+  return query;
+}
+
+/** Project file buckets, authenticated by the same token as documents. */
+export class V1FileStorage {
+  /** @type {V1Transport} */ #transport;
+  /** @type {FetchLike} */ #fetch;
+  /** @param {V1Transport} transport @param {FetchLike} fetcher */
+  constructor(transport, fetcher) { this.#transport = transport; this.#fetch = fetcher; Object.freeze(this); }
+  /** @param {string} name @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+  async createBucket(name, accessRules, options = {}) {
+    return bucketInfo((await this.#transport.call("createFileBucket", {}, { body: stringifyExactJson({ name, rules: accessRules }, "file bucket"), contentType: "application/json", signal: options.signal })).value);
+  }
+  /** @param {FileListOptions} [options] @returns {Promise<{items: FileBucketInfo[], next: string | null}>} */
+  async listBuckets(options = {}) {
+    const v = object((await this.#transport.call("listFileBuckets", {}, { query: pageQuery(options), signal: options.signal })).value, "bucket page");
+    return { items: array(v.items, "bucket items").map(bucketInfo), next: v.next === null ? null : requireId(v.next) };
+  }
+  /** @param {string} id @returns {V1FileBucket} */
+  bucket(id) { return new V1FileBucket(this.#transport, this.#fetch, requireId(id)); }
+}
+
+/** Immutable files in one project bucket. */
+export class V1FileBucket {
+  /** @type {V1Transport} */ #transport;
+  /** @type {FetchLike} */ #fetch;
+  /** @type {string} */ #bucket;
+  /** @param {V1Transport} transport @param {FetchLike} fetcher @param {string} bucket */
+  constructor(transport, fetcher, bucket) { this.#transport = transport; this.#fetch = fetcher; this.#bucket = requireId(bucket); Object.freeze(this); }
+  /** @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+  async setRules(accessRules, options = {}) {
+    return bucketInfo((await this.#transport.call("setFileBucketRules", { bucket: this.#bucket }, { body: stringifyExactJson({ rules: accessRules }, "file bucket rules"), contentType: "application/json", signal: options.signal })).value);
+  }
+  /** @param {FileRequestOptions} [options] @returns {Promise<void>} */
+  async delete(options = {}) { await this.#transport.call("deleteFileBucket", { bucket: this.#bucket }, { signal: options.signal }); }
+  /** @param {FileUploadRequest} request @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+  async createUpload(request, options = {}) {
+    assertJsonObject(request.metadata, "file metadata");
+    if (!Number.isSafeInteger(request.size) || request.size < 1 || request.size > maxFileBytes) throw new TypeError("Files must contain 1–104857600 bytes.");
+    return signed((await this.#transport.call("createFileUpload", { bucket: this.#bucket }, { body: stringifyExactJson(request, "file upload"), contentType: "application/json", signal: options.signal })).value);
+  }
+  /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<StoredFile>} */
+  async completeUpload(id, options = {}) {
+    return storedFile((await this.#transport.call("completeFileUpload", { bucket: this.#bucket, file: requireId(id) }, { signal: options.signal })).value);
+  }
+  /** @param {FileListOptions} [options] @returns {Promise<{items: StoredFile[], next: string | null}>} */
+  async list(options = {}) {
+    const v = object((await this.#transport.call("listBucketFiles", { bucket: this.#bucket }, { query: pageQuery(options), signal: options.signal })).value, "file page");
+    return { items: array(v.items, "file items").map(storedFile), next: v.next === null ? null : requireId(v.next) };
+  }
+  /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+  async downloadUrl(id, options = {}) {
+    return signed((await this.#transport.call("createFileDownload", { bucket: this.#bucket, file: requireId(id) }, { signal: options.signal })).value);
+  }
+  /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<void>} */
+  async deleteFile(id, options = {}) { await this.#transport.call("deleteBucketFile", { bucket: this.#bucket, file: requireId(id) }, { signal: options.signal }); }
+  /** Hashes a private byte snapshot, uploads it without project credentials, and verifies completion. No retries.
+   * @param {string} name @param {Uint8Array | Blob} input @param {FileUploadOptions} options @returns {Promise<StoredFile>} */
+  async upload(name, input, options) {
+    const size = input instanceof Blob ? input.size : input.byteLength;
+    if (size < 1 || size > maxFileBytes) throw new TypeError("Files must contain 1–104857600 bytes.");
+    const bytes = input instanceof Blob ? new Uint8Array(await input.arrayBuffer()) : new Uint8Array(input);
+    options.signal?.throwIfAborted();
+    const hash = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes));
+    const sha256 = btoa(String.fromCharCode(...hash));
+    const capability = await this.createUpload({ name, contentType: options.contentType ?? "application/octet-stream", size, sha256, metadata: options.metadata }, options);
+    const headers = new Headers(capability.headers);
+    // Fetch computes Content-Length from the body; browsers prohibit setting it explicitly.
+    headers.delete("Content-Length");
+    /** @type {RequestInit & { duplex?: "half" }} */
+    const init = { method: "PUT", headers, body: bytes, credentials: "omit", redirect: "error", signal: options.signal ?? null };
+    if (typeof process !== "undefined" && process.release?.name === "node") {
+      // A one-shot stream prevents Node fetch from replaying the signed PUT on HTTP 421.
+      headers.set("Content-Length", String(size));
+      init.body = new ReadableStream({ start(controller) { controller.enqueue(bytes); controller.close(); } });
+      init.duplex = "half";
+    }
+    const response = await this.#fetch(capability.url, init);
+    void response.body?.cancel().catch(() => {});
+    if (!response.ok) throw new Error(`Object upload failed (${response.status}).`);
+    return this.completeUpload(capability.id, options);
+  }
+  /** Fetches file bytes without sending the project token to the object store.
+   * @param {string} id @param {FileRequestOptions} [options] @returns {Promise<Blob>} */
+  async download(id, options = {}) {
+    const capability = await this.downloadUrl(id, options);
+    const response = await this.#fetch(capability.url, { method: "GET", credentials: "omit", redirect: "error", signal: options.signal ?? null });
+    if (!response.ok) throw new Error(`Object download failed (${response.status}).`);
+    if (response.body === null) throw new Error("Object download returned no body.");
+    const reader = response.body.getReader();
+    /** @type {Uint8Array<ArrayBuffer>[]} */ const chunks = [];
+    let length = 0;
+    try {
+      for (;;) {
+        options.signal?.throwIfAborted();
+        const part = await reader.read();
+        if (part.done) break;
+        length += part.value.byteLength;
+        if (length > maxFileBytes) throw new Error("Object download exceeds the file size limit.");
+        chunks.push(new Uint8Array(part.value));
+      }
+    } finally { await reader.cancel().catch(() => {}); reader.releaseLock(); }
+    return new Blob(chunks, { type: "application/octet-stream" });
+  }
+}

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/routes.js

@@ -1,6 +1,7 @@
+import { fileStorageRoutes } from "./file-storage-routes.js";
 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 {import("./file-storage-routes.js").FileStorageOperation | 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
@@ -61,7 +62,7 @@ export const v1Routes = Object.freeze(/** @type {V1Route[]} */ ([
 })));
 /** @param {V1Operation} operation @returns {V1Route} */
 export function v1Route(operation) {
-  const route = [...v1Routes, ...shapeV1Routes, ...managementV1Routes].find(candidate => candidate.operation === operation);
+  const route = [...v1Routes, ...shapeV1Routes, ...managementV1Routes, ...fileStorageRoutes].find(candidate => candidate.operation === operation);
   if (route === undefined) throw new TypeError(`Unknown v1 operation ${operation}.`);
   return route;
 }

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));
+    },
+  });
+}