@terrascale/sdk 0.0.6 → 0.0.8

package/src/v1/shape-subscription.js

@@ -3,6 +3,7 @@ import { TerraBaseV1Error } from "./errors.js";
 import { requireFilter } from "./filter.js";
 import { parseExactJson, stringifyExactJson } from "./json.js";
 import { readShapePage } from "./shape-reader.js";
+import { BodyTransportError, RequestTransportError } from "./transport.js";
 /**
  * @import { JsonObject } from "./json.js"
  * @import { V1Filter } from "./filter.js"
@@ -12,6 +13,14 @@ import { readShapePage } from "./shape-reader.js";
  * @typedef {object} V1ShapeSubscribeOptions
  * @property {AbortSignal | undefined} [signal] Closes the subscription when aborted; cancellation settles `done`.
  * @property {((subscription: V1ShapeSubscription) => void) | undefined} [onUpdate] Runs after validated responses and freshness changes; throwing rejects `done` unless already closed or aborted.
+ * @property {V1ShapeReplicaStore | undefined} [replica] Keeps the last resumable state for reads across restarts and while offline; writes still go to the server.
+ */
+/**
+ * Holds one subscription's state as exact JSON text, e.g. in IndexedDB or React Native storage. Scope one store
+ * to one signed-in subject: the replica holds that subject's authorized documents. A failing store rejects `done`.
+ * @typedef {object} V1ShapeReplicaStore
+ * @property {() => string | undefined | Promise<string | undefined>} load
+ * @property {(text: string | undefined) => void | Promise<void>} save Receives undefined after must_refetch discards state.
  */
 /** @typedef {{ readonly version: string; readonly document: JsonObject }} V1ShapeDocument */
 const retryBaseMilliseconds = 250;
@@ -81,6 +90,9 @@ export class V1ShapeSubscription {
   /** @type {V1Filter | undefined} */
   #where;
   #onUpdate;
+  #replica;
+  /** @type {string} */
+  #scope;
   #external;
   #onExternalAbort = () => this.close();
   #done;
@@ -92,9 +104,11 @@ export class V1ShapeSubscription {
    */
   constructor(transport, params, shape = {}, options = {}) {
     requireMembers(shape, ["where"], "shape");
-    requireMembers(options, ["signal", "onUpdate"], "shape subscribe option");
+    requireMembers(options, ["signal", "onUpdate", "replica"], "shape subscribe option");
     const { where } = shape;
-    const { signal, onUpdate } = options;
+    const { signal, onUpdate, replica } = options;
+    if (replica !== undefined && (typeof replica?.load !== "function" || typeof replica.save !== "function"))
+      throw new TypeError("replica has load and save functions.");
     if (signal !== undefined && !(signal instanceof AbortSignal)) throw new TypeError("signal is an AbortSignal.");
     if (onUpdate !== undefined && typeof onUpdate !== "function") throw new TypeError("onUpdate is a function.");
     this.#transport = transport;
@@ -102,6 +116,9 @@ export class V1ShapeSubscription {
     // Exact copy: a structuredClone would lose the source text of large or fractional JSON numbers.
     this.#where = where === undefined ? undefined : requireFilter(parseExactJson(stringifyExactJson(requireFilter(where), "shape filter")));
     this.#onUpdate = onUpdate;
+    this.#replica = replica;
+    // A replica restores only the identical shape it was saved from.
+    this.#scope = stringifyExactJson([this.#params.database, this.#params.collection, this.#where ?? null], "shape scope");
     this.#external = signal;
     if (signal?.aborted === true) this.close();
     else signal?.addEventListener("abort", this.#onExternalAbort);
@@ -120,6 +137,7 @@ export class V1ShapeSubscription {
     const signal = this.#controller.signal;
     let retries = 0;
     try {
+      if (this.#replica !== undefined) await this.#restore(signal);
       for (;;) {
         signal.throwIfAborted();
         const request = this.#request();
@@ -127,18 +145,22 @@ export class V1ShapeSubscription {
         try {
           page = await readShapePage(this.#transport, this.#params, request, signal);
         } catch (error) {
-          if (!(error instanceof TerraBaseV1Error)) throw error;
-          if (isRetryable(error)) {
+          // Shape reads are replay-safe GETs: a lost connection keeps state and resumes at the same position.
+          const lost = error instanceof RequestTransportError || error instanceof BodyTransportError;
+          if (lost || (error instanceof TerraBaseV1Error && isRetryable(error))) {
             retries = Math.min(retries + 1, maximumBackoffAttempt);
-            await sleep(retryDelay(retries, error.retryAfter), signal);
+            await sleep(retryDelay(retries, lost ? undefined : error.retryAfter), signal);
             continue;
           }
+          if (!(error instanceof TerraBaseV1Error)) throw error;
           if (error.status !== 409 || error.code !== "must_refetch") throw error;
           this.#recover(request, error);
+          if (this.#handle === undefined) await this.#replica?.save(undefined);
           continue;
         }
         retries = 0;
         this.#commit(page);
+        await this.#persist(signal);
         this.#onUpdate?.(this);
       }
     } catch (error) {
@@ -188,6 +210,36 @@ export class V1ShapeSubscription {
     this.#resumeAttempt = false;
     this.#onUpdate?.(this);
   }
+  /** @param {AbortSignal} signal */
+  async #restore(signal) {
+    const text = await this.#replica?.load();
+    signal.throwIfAborted();
+    if (text === undefined) return;
+    /** @type {any} */
+    let saved;
+    try { saved = parseExactJson(text); } catch { saved = undefined; }
+    // Unknown or other-shape replicas are discarded, never merged.
+    if (saved?.format !== 1 || saved.scope !== this.#scope || typeof saved.handle !== "string" || typeof saved.offset !== "string" ||
+        !/^(?:0|[1-9][0-9]*)$/u.test(saved.offset) || !Array.isArray(saved.documents) ||
+        !saved.documents.every((/** @type {any} */ item) => Array.isArray(item) && typeof item[0] === "string" &&
+          typeof item[1]?.version === "string" && typeof item[1].document === "object" && item[1].document !== null)) return;
+    this.#documents = new Map(saved.documents.map((/** @type {[string, V1ShapeDocument]} */ [id, entry]) => [id, deepFreeze({ version: entry.version, document: entry.document })]));
+    this.#handle = saved.handle;
+    this.#offset = saved.offset;
+    this.#cursor = typeof saved.cursor === "string" ? saved.cursor : undefined;
+    this.#resume = typeof saved.resume === "string" ? saved.resume : undefined;
+    // Restored state is stale until the server confirms a fresh head.
+    this.#upToDate = false;
+    this.#onUpdate?.(this);
+  }
+  /** @param {AbortSignal} signal */
+  async #persist(signal) {
+    // Snapshot pages are not resumable positions; keep the previous replica until the snapshot completes.
+    if (this.#replica === undefined || this.#handle === undefined || this.#offset.startsWith("snap.")) return;
+    await this.#replica.save(stringifyExactJson({ format: 1, scope: this.#scope, handle: this.#handle, offset: this.#offset,
+      cursor: this.#cursor ?? null, resume: this.#resume ?? null, documents: [...this.#documents] }, "shape replica"));
+    signal.throwIfAborted();
+  }
   /** @param {import("./shapes.js").V1ShapePage} page */
   #commit(page) {
     // Repeats are applied, never skipped: a repeated event can carry a newer materialized value.

package/src/v1/shapes.js

@@ -1,7 +1,7 @@
 // Current C# GET collection/shape contract (docs/shape-reads.md).
 import { array, boolean, documentObject, malformed, object, string, u64 } from "./decode.js";
 import { requireFilter } from "./filter.js";
-import { parseU64, requireDocumentId, requireVersion } from "./ids.js";
+import { parseU64, requireStoredId, requireVersion } from "./ids.js";
 import { stringifyExactJson } from "./json.js";
 /**
  * @import { JsonObject, JsonValue } from "./json.js"
@@ -56,7 +56,7 @@ export function requireShapeOffset(value) {
       const bytes = Uint8Array.from(atob(encoded.replace(/-/gu, "+").replace(/_/gu, "/")), c => c.charCodeAt(0));
       const id = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
       const canonical = btoa(String.fromCharCode(...new TextEncoder().encode(id))).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "");
-      if (canonical === encoded) { requireDocumentId(id); return value; }
+      if (canonical === encoded) { requireStoredId(id); return value; }
     } catch { /* Invalid base64url or UTF-8. */ }
   }
   throw new TypeError("A shape offset is -1, a signed-64-bit decimal log position, or snap.<head>.<canonical-base64url-id>.");
@@ -108,7 +108,7 @@ export function decodeShapePage(value, headers) {
       const change = object(value, "shape change");
       return Object.freeze({ offset: u64(change.offset, "shape change offset"), ops: Object.freeze(array(change.ops, "shape operations").map(value => {
         const op = object(value, "shape operation");
-        const id = requireDocumentId(op.id);
+        const id = requireStoredId(op.id);
         if (op.op === "delete") return Object.freeze({ op: /** @type {const} */ ("delete"), id });
         if (op.op !== "upsert") malformed("shape operation kind");
         return Object.freeze({ op: /** @type {const} */ ("upsert"), id, version: requireVersion(op.version), document: documentObject(op.document) });

package/src/v1/sql.js

@@ -1,5 +1,5 @@
 import { array, boolean, malformed, object, string } from "./decode.js";
-import { requireDocumentId, requireName } from "./ids.js";
+import { requireStoredId, requireName } from "./ids.js";
 /**
  * @import { JsonObject, JsonValue } from "./json.js"
  * @import { V1RequestOptions } from "./terrabase-v1.js"
@@ -41,7 +41,7 @@ function decodeResult(value) {
   const raw = object(value, "SQL result");
   const rows = array(raw.rows, "SQL rows").map(entry => {
     const row = object(entry, "SQL row");
-    return Object.freeze({ id: requireDocumentId(row.id), value: object(row.value, "SQL row value") });
+    return Object.freeze({ id: requireStoredId(row.id), value: object(row.value, "SQL row value") });
   });
   const matched = raw.matched;
   if (typeof matched !== "number" || !Number.isInteger(matched) || matched < 0 || matched > 1000 || matched !== rows.length)

package/src/v1/terrabase-v1.js

@@ -1,10 +1,11 @@
+import { V1FileStorage } from "./file-storage.js";
 // The TerraBase v1 client: documents, transactions, queries and shapes over
 // the project-scoped C# Documents API (decision 0004 and shape-reads.md).
 import {
   array, boolean, decodeDocument, decodeWrite, documentObject, durability, malformed, object, u64,
 } from "./decode.js";
 import { requireId } from "../ids.js";
-import { isJsonPointer, requireFilter, requirePath } from "./filter.js";
+import { searchCount, isJsonPointer, requireFilter, requireGeoPoint, requirePath } from "./filter.js";
 import { requireDocumentId, requireName, requireVersion } from "./ids.js";
 import { assertJsonObject, assertJsonValue, ExactDecimal, stringifyExactJson } from "./json.js";
 import { readShapeManifest } from "./shape-manifest.js";
@@ -66,7 +67,32 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * Vector similarity sort, nearest first. It must be the only sort key; limit is at most 100 and there is no cursor.
  * @typedef {{ readonly near: { readonly path: V1Path; readonly vector: readonly number[]; readonly metric?: "cosine" | "l2" | undefined } }} V1NearSortKey
  */
-/** @typedef {V1FieldSortKey | V1NearSortKey} V1SortKey */
+/**
+ * Geo distance sort: meters from a WGS 84 point to each document's `{lat, lon}` object at `path`, nearest first,
+ * returned as `distance`. Like the vector `near`, it is the only sort key, limit is at most 100 and there is no cursor.
+ * @typedef {{ readonly near: { readonly path: string; readonly lat: number; readonly lon: number } }} V1GeoNearSortKey
+ */
+/** Relevance order, only sort key with exactly one search predicate. @typedef {{ readonly path: "$score"; readonly order: "desc" }} V1ScoreSortKey */
+/** @typedef {V1FieldSortKey | V1NearSortKey | V1GeoNearSortKey | V1ScoreSortKey} V1SortKey */
+/**
+ * Groups matches instead of returning documents. Summaries consider numbers only; at most 16 summary paths in total.
+ * @typedef {object} V1Aggregate
+ * @property {readonly V1Path[] | undefined} [groupBy] 0-4 paths; without it every match is one group.
+ * @property {readonly string[] | undefined} [sum] Distinct JSON Pointers.
+ * @property {readonly string[] | undefined} [avg] Distinct JSON Pointers.
+ * @property {readonly string[] | undefined} [min] Distinct JSON Pointers.
+ * @property {readonly string[] | undefined} [max] Distinct JSON Pointers.
+ */
+/**
+ * One aggregate group. Summaries are keyed by the requested JSON Pointer; `sum` is 0 and the others null without numbers.
+ * @typedef {object} V1Group
+ * @property {readonly JsonValue[]} key One value per `groupBy` path (missing members group as null).
+ * @property {string} count Matching documents in the group (decimal u64).
+ * @property {Readonly<Record<string, number | null>> | undefined} [sum]
+ * @property {Readonly<Record<string, number | null>> | undefined} [avg]
+ * @property {Readonly<Record<string, number | null>> | undefined} [min]
+ * @property {Readonly<Record<string, number | null>> | undefined} [max]
+ */
 /**
  * A query-v1 request. Every member is optional.
  * @typedef {object} V1Query
@@ -76,6 +102,7 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * @property {number | undefined} [limit] 1-1000 (server default 50).
  * @property {string | null | undefined} [cursor] A previous page's `nextCursor`.
  * @property {boolean | undefined} [count] Count every match (first page only).
+ * @property {V1Aggregate | undefined} [aggregate] Answer `groups` instead of items; `limit` bounds the groups. No sort, project, cursor or count.
  */
 /** @typedef {{ readonly value: string; readonly exact: boolean }} V1Count */
 /**
@@ -83,6 +110,7 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * @property {readonly V1Document[]} items Documents in query order.
  * @property {string | null} nextCursor
  * @property {V1Count | undefined} count
+ * @property {readonly V1Group[] | undefined} groups An aggregate query's groups in key order (`items` is then empty).
  */
 
 /** @typedef {{ readonly ifMatch: string } | { readonly ifNoneMatchAny: true }} V1Precondition */
@@ -99,7 +127,8 @@ import { V1ChangeWebhooks } from "./change-webhooks.js";
  * @property {readonly V1TransactionOpResult[]} results One per op, in order.
  */
 
-const queryMembers = new Set(["filter", "sort", "project", "limit", "cursor", "count"]);
+const queryMembers = new Set(["filter", "sort", "project", "limit", "cursor", "count", "aggregate"]);
+const summaries = /** @type {const} */ (["sum", "avg", "min", "max"]);
 
 /**
  * @param {string} path
@@ -183,16 +212,53 @@ function normalizePatch(patch) {
 }
 
 /**
- * @param {V1NearSortKey} key
+ * @param {V1Aggregate} aggregate
+ * @param {V1Query} query
+ * @returns {Record<string, unknown>}
+ */
+function encodeAggregate(aggregate, query) {
+  if (typeof aggregate !== "object" || aggregate === null || Array.isArray(aggregate)) throw new TypeError("aggregate is an object.");
+  if (query.sort !== undefined || query.project !== undefined || query.cursor != null || query.count !== undefined)
+    throw new TypeError("aggregate takes no sort, project, cursor or count.");
+  for (const member of Object.keys(aggregate))
+    if (member !== "groupBy" && !summaries.includes(/** @type {any} */ (member))) throw new TypeError(`Unknown aggregate member ${member}.`);
+  /** @type {Record<string, unknown>} */
+  const body = {};
+  if (aggregate.groupBy !== undefined) {
+    if (!Array.isArray(aggregate.groupBy) || aggregate.groupBy.length > 4) throw new TypeError("groupBy has at most 4 paths.");
+    body.group_by = aggregate.groupBy.map(requirePath);
+  }
+  let total = 0;
+  for (const op of summaries) {
+    const paths = aggregate[op];
+    if (paths === undefined) continue;
+    if (!Array.isArray(paths) || new Set(paths).size !== paths.length) throw new TypeError(`${op} takes distinct JSON Pointers.`);
+    total += paths.length;
+    body[op] = paths.map(pointer);
+  }
+  if (total > 16) throw new TypeError("An aggregate has at most 16 sum, avg, min and max paths.");
+  return body;
+}
+
+/**
+ * @param {V1NearSortKey | V1GeoNearSortKey} key
  * @param {V1Query} query
  * @returns {Record<string, unknown>}
  */
 function nearSort(key, query) {
   if (Object.keys(key).length !== 1 || query.sort?.length !== 1) throw new TypeError("near is the only sort key and has no path or order beside it.");
+  if (searchCount(query.filter) !== 0) throw new TypeError("near cannot combine with search.");
   if (query.cursor != null) throw new TypeError("A near query has one page and takes no cursor.");
   if (query.limit !== undefined && query.limit > 100) throw new TypeError("A near query limit is at most 100.");
   const near = key.near;
   if (near === null || typeof near !== "object") throw new TypeError("near is an object.");
+  if ("lat" in near || "lon" in near) {
+    const geo = /** @type {V1GeoNearSortKey["near"]} */ (near);
+    for (const member of Object.keys(geo)) if (!["path", "lat", "lon"].includes(member)) throw new TypeError(`A geo near takes path, lat and lon, not ${member}.`);
+    requireGeoPoint(geo.lat, geo.lon);
+    if (requirePath(geo.path) === "$id") throw new TypeError("A geo near path is a JSON Pointer.");
+    return { near: { path: geo.path, lat: geo.lat, lon: geo.lon } };
+  }
   for (const member of Object.keys(near)) if (!["path", "vector", "metric"].includes(member)) throw new TypeError(`Unknown near member ${member}.`);
   if (near.metric !== undefined && near.metric !== "cosine" && near.metric !== "l2") throw new TypeError('near metric is "cosine" or "l2".');
   const vector = near.vector;
@@ -220,6 +286,10 @@ function encodeQuery(query) {
       if ("near" in key) return nearSort(key, query);
       for (const member of Object.keys(key)) if (member !== "path" && member !== "order") throw new TypeError(`Unknown sort member ${member}.`);
       if (key.order !== undefined && key.order !== "asc" && key.order !== "desc") throw new TypeError('Sort order is "asc" or "desc".');
+      if (key.path === "$score") {
+        if (key.order !== "desc" || query.sort?.length !== 1 || searchCount(query.filter) !== 1) throw new TypeError("$score requires descending order as the only sort key and exactly one search predicate.");
+        return { path: "$score", order: "desc" };
+      }
       return { path: requirePath(key.path), ...(key.order === undefined ? {} : { order: key.order }) };
     });
   }
@@ -239,9 +309,29 @@ function encodeQuery(query) {
     if (typeof query.count !== "boolean") throw new TypeError("count is a boolean.");
     body.count = query.count;
   }
+  if (query.aggregate !== undefined) body.aggregate = encodeAggregate(query.aggregate, query);
   return stringifyExactJson(body, "query");
 }
 
+/**
+ * @param {JsonValue} value
+ * @returns {V1Group}
+ */
+function decodeGroup(value) {
+  const raw = object(value, "aggregate group");
+  /** @type {Record<string, unknown>} */
+  const group = { key: Object.freeze([...array(raw.key, "group key")]), count: u64(raw.count, "group count") };
+  for (const op of summaries) {
+    if (raw[op] === undefined) continue;
+    group[op] = Object.freeze(Object.fromEntries(Object.entries(object(raw[op], `group ${op}`)).map(([path, summary]) => {
+      const number = summary instanceof ExactDecimal ? summary.toNumber() : summary;
+      if (number !== null && (typeof number !== "number" || !Number.isFinite(number))) malformed(`group ${op}`);
+      return [path, number];
+    })));
+  }
+  return /** @type {V1Group} */ (Object.freeze(group));
+}
+
 /**
  * @param {JsonValue | undefined} value
  * @returns {V1QueryPage}
@@ -258,14 +348,19 @@ export function decodeQueryPage(value) {
   }
   return Object.freeze({
     items: Object.freeze(array(raw.items, "query items").map(item => {
-      const distance = object(item, "document").distance;
-      if (distance === undefined) return decodeDocument(item);
-      const value = distance instanceof ExactDecimal ? distance.toNumber() : distance;
-      if (typeof value !== "number" || !Number.isFinite(value)) malformed("near distance");
-      return Object.freeze({ ...decodeDocument(item), distance: value });
+      const raw = object(item, "document");
+      const document = { ...decodeDocument(item) };
+      for (const field of /** @type {const} */ (["distance", "score"])) {
+        if (raw[field] === undefined) continue;
+        const value = raw[field] instanceof ExactDecimal ? raw[field].toNumber() : raw[field];
+        if (typeof value !== "number" || !Number.isFinite(value)) malformed(field);
+        document[field] = value;
+      }
+      return Object.freeze(document);
     })),
     nextCursor: typeof next === "string" && next !== "" ? next : null,
     count,
+    groups: raw.groups === undefined ? undefined : Object.freeze(array(raw.groups, "aggregate groups").map(decodeGroup)),
   });
 }
 
@@ -909,6 +1004,8 @@ export class V1Database {
  * privately; it is never serialized, logged or forwarded to redirects.
  */
 export class TerraBaseV1Client {
+  /** @type {V1FileStorage} */
+  #storage;
   /** @type {V1Health} */
   #health;
   /** @type {V1Platform} */
@@ -928,6 +1025,7 @@ export class TerraBaseV1Client {
   constructor(config) {
     requireId(config.project);
     this.#transport = new V1Transport(config);
+    this.#storage = new V1FileStorage(this.#transport, config.fetch ?? globalThis.fetch.bind(globalThis));
     this.#databases = new V1Databases(this.#transport);
     this.#savedQueries = new V1SavedQueries(this.#transport);
     this.#metrics = new V1ProjectUsageClient(this.#transport);
@@ -947,6 +1045,8 @@ export class TerraBaseV1Client {
 
   /** @returns {V1Databases} Project-scoped database catalog. */
   get databases() { return this.#databases; }
+  /** @returns {V1FileStorage} Project file buckets. */
+  get storage() { return this.#storage; }
   /** @returns {V1SavedQueries} */
   get savedQueries() { return this.#savedQueries; }
   /** @returns {V1ProjectUsageClient} */

package/src/v1/transport.js

@@ -44,6 +44,7 @@ const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-
  * @property {URLSearchParams | undefined} [query]
  * @property {AbortSignal | undefined} [signal]
  * @property {"no-store" | undefined} [cache] Authenticated shape epoch keys must bypass caches.
+ * @property {"follow" | undefined} [redirect] Only the shape bootstrap, after a browser hides its 307 behind an opaque redirect.
  */
 
 /**
@@ -51,6 +52,7 @@ const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-
  * @property {number} status
  * @property {Headers} headers
  * @property {JsonValue | undefined} value
+ * @property {string | undefined} [redirectedTo] The final URL after a followed redirect.
  */
 
 /**
@@ -134,6 +136,23 @@ export class BodyTransportError extends Error {
   }
 }
 
+/** A request that failed in transit before any response; the native failure is the cause. */
+export class RequestTransportError extends TypeError {
+  /** @param {unknown} cause */
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : "TerraBase request failed in transit.", { cause });
+    this.name = "RequestTransportError";
+  }
+}
+
+/** A browser hid a 307 behind an opaque redirect; only the shape bootstrap may follow it. */
+export class OpaqueRedirectError extends TypeError {
+  constructor() {
+    super("Fresh shape bootstrap requires server fetch; obtain a handle and snapshot offset with collection.shape() on your server.");
+    this.name = "OpaqueRedirectError";
+  }
+}
+
 /** Internal transport bound to one project credential. */
 export class V1Transport {
   /** @type {string | undefined} */
@@ -353,7 +372,8 @@ export class V1Transport {
       await response.body?.cancel();
       return { status: response.status, headers: response.headers, value: undefined };
     }
-    return { status: response.status, headers: response.headers, value: await this.readJson(response, options.signal) };
+    return { status: response.status, headers: response.headers, value: await this.readJson(response, options.signal),
+      ...(response.redirected ? { redirectedTo: response.url } : {}) };
   }
 
   /**
@@ -387,7 +407,7 @@ export class V1Transport {
     if (route.responseMediaType !== "") headers.set("accept", route.responseMediaType);
     if (options.body !== undefined) headers.set("content-type", options.contentType ?? "application/json");
     /** @type {RequestInit & { duplex?: "half" }} */
-    const init = { method: route.method, headers, redirect: "manual" };
+    const init = { method: route.method, headers, redirect: options.redirect ?? "manual" };
     if (options.cache !== undefined) init.cache = options.cache;
     if (route.permission.endsWith(":write") && typeof process !== "undefined" && process.release?.name === "node") {
       // Node fetch replays buffered or absent bodies on 421; use a one-shot stream, including DELETE.
@@ -397,13 +417,15 @@ export class V1Transport {
     } else if (options.body !== undefined) init.body = typeof options.body === "string" ? options.body : options.body.slice().buffer;
     if (options.signal !== undefined) init.signal = options.signal;
     options.signal?.throwIfAborted();
-    const response = await this.#fetch(url, init);
+    /** @type {Response} */
+    let response;
+    try { response = await this.#fetch(url, init); }
+    catch (error) { options.signal?.throwIfAborted(); throw new RequestTransportError(error); }
     if (options.signal?.aborted) {
       void response.body?.cancel().catch(() => undefined);
       options.signal.throwIfAborted();
     }
-    if (response.type === "opaqueredirect")
-      throw new TypeError("Fresh shape bootstrap requires server fetch; obtain a handle and snapshot offset with collection.shape() on your server.");
+    if (response.type === "opaqueredirect") throw new OpaqueRedirectError();
     if (!route.successStatuses.includes(response.status)) throw await this.error(response, options.signal);
     return response;
   }

package/src/v1/usage.js

@@ -8,7 +8,7 @@ const period = record({ from: text, to: text, granularity: text, reads: numeric,
 const series = list(record({ start: text, reads: numeric, writes: numeric }));
 const databaseUsage = record({ databaseId: requireId, storageBytes: numeric, logicalBytes: numeric, collections: numeric,
   documents: numeric, reads: numeric, writes: numeric, period, series });
-const projectUsage = record({ projectId: requireId, databases: numeric, storageBytes: numeric, logicalBytes: numeric,
+const projectUsage = record({ projectId: requireId, databases: numeric, storageBytes: numeric, logicalBytes: numeric, fileBytes: numeric,
   documents: numeric, reads: numeric, writes: numeric, period, series, items: list(databaseUsage) });
 const bandwidth = record({ bytesSent: numeric, bytesReceived: numeric });
 const directedBandwidth = list(record({ sourceRegion: text, destinationRegion: text, kind: text, bytesSent: numeric, bytesReceived: numeric }));

package/types/index.d.ts

@@ -1,5 +1,6 @@
 export { v1Filter } from "./v1/filter.js";
 export { V1ShapeSubscription } from "./v1/shape-subscription.js";
+export { indexedDbShapeReplica } from "./v1/shape-replica.js";
 export { ExactDecimal } from "./v1/json.js";
 export { staticBaseUrlResolver } from "./v1/transport.js";
 export { V1Databases } from "./v1/catalog.js";
@@ -8,6 +9,7 @@ export { V1DatabaseSchemaClient } from "./v1/database-schema.js";
 export { V1Indexes } from "./v1/indexes.js";
 export { V1ChangeWebhooks } from "./v1/change-webhooks.js";
 export { V1Imports } from "./v1/imports.js";
+export type V1ShapeReplicaStore = import("./v1/shape-subscription.js").V1ShapeReplicaStore;
 export type V1ShapeSubscribeOptions = import("./v1/shape-subscription.js").V1ShapeSubscribeOptions;
 export type V1ShapeDocument = import("./v1/shape-subscription.js").V1ShapeDocument;
 export type V1SealedShapePosition = import("./v1/shape-reader.js").V1SealedShapePosition;
@@ -23,6 +25,10 @@ export type V1PatchOp = import("./v1/terrabase-v1.js").V1PatchOp;
 export type V1Patch = import("./v1/terrabase-v1.js").V1Patch;
 export type V1SortKey = import("./v1/terrabase-v1.js").V1SortKey;
 export type V1NearSortKey = import("./v1/terrabase-v1.js").V1NearSortKey;
+export type V1GeoNearSortKey = import("./v1/terrabase-v1.js").V1GeoNearSortKey;
+export type V1Aggregate = import("./v1/terrabase-v1.js").V1Aggregate;
+export type V1Group = import("./v1/terrabase-v1.js").V1Group;
+export type V1ScoreSortKey = import("./v1/terrabase-v1.js").V1ScoreSortKey;
 export type V1Query = import("./v1/terrabase-v1.js").V1Query;
 export type V1Count = import("./v1/terrabase-v1.js").V1Count;
 export type V1QueryPage = import("./v1/terrabase-v1.js").V1QueryPage;
@@ -36,6 +42,8 @@ export type V1Durability = import("./v1/decode.js").V1Durability;
 export type V1Filter = import("./v1/filter.js").V1Filter;
 export type V1Path = import("./v1/filter.js").V1Path;
 export type V1Scalar = import("./v1/filter.js").V1Scalar;
+export type V1GeoCircle = import("./v1/filter.js").V1GeoCircle;
+export type V1GeoBox = import("./v1/filter.js").V1GeoBox;
 export type V1JsonValue = import("./v1/json.js").JsonValue;
 export type V1JsonObject = import("./v1/json.js").JsonObject;
 export type V1JsonInput = import("./v1/json.js").JsonInput;
@@ -82,6 +90,7 @@ export type V1UniqueSchema = import("./v1/database-schema.js").V1UniqueSchema;
 export type V1UniqueSchemaRequest = import("./v1/database-schema.js").V1UniqueSchemaRequest;
 export type V1QueryShapes = import("./v1/database-schema.js").V1QueryShapes;
 export type V1Index = import("./v1/indexes.js").V1Index;
+export type V1IndexKind = import("./v1/indexes.js").V1IndexKind;
 export type V1IndexList = import("./v1/indexes.js").V1IndexList;
 export type V1AutoIndexPolicy = import("./v1/indexes.js").V1AutoIndexPolicy;
 export type V1IndexRecommendations = import("./v1/indexes.js").V1IndexRecommendations;
@@ -119,6 +128,14 @@ export type V1ShapeManifest = import("./v1/shape-manifest.js").V1ShapeManifest;
 export type V1ShapeManifestRequest = import("./v1/shape-manifest.js").V1ShapeManifestRequest;
 export type V1ShapeKeyRequest = import("./v1/shape-reader.js").V1ShapeKeyRequest;
 export type V1ShapeKey = import("./v1/shape-reader.js").V1ShapeKey;
+export type FileAccessPolicy = import("./v1/file-storage.js").FileAccessPolicy;
+export type FileAccessRules = import("./v1/file-storage.js").FileAccessRules;
+export type FileBucketInfo = import("./v1/file-storage.js").FileBucketInfo;
+export type StoredFile = import("./v1/file-storage.js").StoredFile;
+export type SignedFileUrl = import("./v1/file-storage.js").SignedFileUrl;
+export type FileUploadRequest = import("./v1/file-storage.js").FileUploadRequest;
+export type FileUploadOptions = import("./v1/file-storage.js").FileUploadOptions;
+export type FileListOptions = import("./v1/file-storage.js").FileListOptions;
 export { createTerraBaseV1Client as createTerraBaseClient, TerraBaseV1Client as TerraBaseClient, createTerraBaseV1Client, TerraBaseV1Client, V1Database, V1Collection, V1Collections, V1Transaction } from "./v1/terrabase-v1.js";
 export { terraScaleReleaseBlockers, TerraScaleCapabilityUnavailableError } from "./management-contracts.js";
 export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, SqlError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
@@ -126,3 +143,4 @@ export { generateId, isValidId, requireId } from "./ids.js";
 export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
 export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";
 export { createTerraBaseSystemClient, V1Health, V1Platform } from "./v1/system.js";
+export { V1FileStorage, V1FileBucket } from "./v1/file-storage.js";

package/types/v1/decode.d.ts

@@ -9,7 +9,8 @@
  * @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`.
  */
 /**
  * The result of a document write.
@@ -99,9 +100,13 @@ export type V1Document = {
      */
     siblings?: readonly JsonValue[];
     /**
-     * Distance to the query vector; present only on `near` query results.
+     * Distance to the query vector, or meters to a geo `near` point; present only on `near` query results.
      */
     distance?: number;
+    /**
+     * Full-text relevance score on results sorted by `$score`.
+     */
+    score?: number;
 };
 /**
  * The result of a document write.

package/types/v1/file-storage-routes.d.ts

@@ -0,0 +1,3 @@
+/** @type {readonly import("./routes.js").V1Route[]} */
+export const fileStorageRoutes: readonly import("./routes.js").V1Route[];
+export type FileStorageOperation = "createFileBucket" | "listFileBuckets" | "setFileBucketRules" | "deleteFileBucket" | "createFileUpload" | "completeFileUpload" | "listBucketFiles" | "createFileDownload" | "deleteBucketFile";