@terrascale/sdk 0.0.5 → 0.0.7

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-execute.js

@@ -0,0 +1,132 @@
+import { array, malformed, object, string } from "./decode.js";
+import { requireName } from "./ids.js";
+import { ExactDecimal, stringifyExactJson } from "./json.js";
+/**
+ * @import { JsonValue } from "./json.js"
+ * @import { V1RequestOptions } from "./terrabase-v1.js"
+ * @import { V1Transport } from "./transport.js"
+ */
+
+/**
+ * An argument: null, a finite number, an int64 `bigint` or ExactDecimal, a boolean (stored as 1 or 0) or a string.
+ * @typedef {null | boolean | number | bigint | ExactDecimal | string} V1SqlArgument
+ */
+/** @typedef {readonly V1SqlArgument[] | Readonly<Record<string, V1SqlArgument>>} V1SqlArguments Positional array, or named values keyed without their `:`, `@` or `$` prefix. */
+/**
+ * @typedef {object} V1SqlStatement
+ * @property {string} sql
+ * @property {readonly V1SqlArgument[] | undefined} [args] Positional arguments.
+ * @property {Readonly<Record<string, V1SqlArgument>> | undefined} [named] Named arguments, keys without their prefix.
+ */
+/**
+ * A result value. Integers beyond 2^53 decode as ExactDecimal, keeping every digit; `BigInt(String(value))` converts one.
+ * @typedef {null | number | ExactDecimal | string} V1SqlValue
+ */
+/** @typedef {{ readonly name: string; readonly decltype: string | null }} V1SqlColumn A column; `decltype` is null for an expression. */
+/**
+ * @typedef {object} V1SqlExecuteResult
+ * @property {readonly V1SqlColumn[]} columns
+ * @property {readonly (readonly V1SqlValue[])[]} rows One value per column.
+ * @property {number} rowsAffected
+ * @property {number | ExactDecimal | null} lastInsertRowid
+ */
+
+const maximumStatements = 256;
+const maximumSqlLength = 16_384;
+
+/** @param {unknown} value @param {string} where */
+function requireArgument(value, where) {
+  if (value === null || typeof value === "boolean" || typeof value === "string" || value instanceof ExactDecimal) return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value === "bigint" && BigInt.asIntN(64, value) === value) return;
+  throw new TypeError(`SQL ${where} is null, a finite number, an int64 bigint, a boolean or a string.`);
+}
+
+/** @param {unknown} statement @param {number} index */
+function encodeStatement(statement, index) {
+  if (typeof statement !== "string" && (typeof statement !== "object" || statement === null || Array.isArray(statement)))
+    throw new TypeError(`SQL statement ${index} is a string or { sql, args, named }.`);
+  const { sql, args, named, ...extra } = /** @type {V1SqlStatement} */ (typeof statement === "string" ? { sql: statement } : statement);
+  for (const member of Object.keys(extra)) throw new TypeError(`Unknown SQL statement member ${member}.`);
+  if (typeof sql !== "string" || sql.length === 0 || sql.length > maximumSqlLength)
+    throw new TypeError(`SQL statement ${index} is a non-empty string of at most ${maximumSqlLength} UTF-16 code units.`);
+  /** @type {{ sql: string; args?: V1SqlArgument[]; named?: Record<string, V1SqlArgument> }} */
+  const encoded = { sql };
+  if (args !== undefined) {
+    if (!Array.isArray(args)) throw new TypeError(`SQL statement ${index} args is an array.`);
+    args.forEach((arg, position) => requireArgument(arg, `argument ${position}`));
+    encoded.args = [...args];
+  }
+  if (named !== undefined) {
+    if (named === null || typeof named !== "object" || Array.isArray(named)) throw new TypeError(`SQL statement ${index} named is an object.`);
+    for (const [name, value] of Object.entries(named)) {
+      if (/^[:@$]/u.test(name)) throw new TypeError(`SQL named argument ${name} is keyed without its prefix.`);
+      requireArgument(value, `named argument ${name}`);
+    }
+    encoded.named = { ...named };
+  }
+  return encoded;
+}
+
+/** @param {string} sql @param {V1SqlArguments | undefined} args @returns {V1SqlStatement} */
+export function sqlStatement(sql, args) {
+  if (args === undefined) return { sql };
+  return Array.isArray(args) ? { sql, args } : { sql, named: /** @type {Readonly<Record<string, V1SqlArgument>>} */ (args) };
+}
+
+/** @param {JsonValue | undefined} value @returns {V1SqlValue} */
+function decodeValue(value) {
+  if (value === null || typeof value === "number" || typeof value === "string" || value instanceof ExactDecimal) return value;
+  return malformed("SQL value");
+}
+
+/** @param {JsonValue | undefined} value @returns {V1SqlExecuteResult} */
+function decodeResult(value) {
+  const raw = object(value, "SQL statement result");
+  const columns = array(raw.columns, "SQL columns").map(entry => {
+    const column = object(entry, "SQL column");
+    const decltype = column.decltype === null || column.decltype === undefined ? null : string(column.decltype, "SQL column decltype");
+    return Object.freeze({ name: string(column.name, "SQL column name"), decltype });
+  });
+  const rows = array(raw.rows, "SQL rows").map(entry => {
+    const row = array(entry, "SQL row").map(decodeValue);
+    if (row.length !== columns.length) malformed("SQL row width");
+    return Object.freeze(row);
+  });
+  const affected = raw.rows_affected;
+  if (typeof affected !== "number" || !Number.isSafeInteger(affected) || affected < 0) malformed("SQL rows_affected");
+  const rowid = raw.last_insert_rowid ?? null;
+  if (rowid !== null && !(rowid instanceof ExactDecimal) && !(typeof rowid === "number" && Number.isInteger(rowid))) malformed("SQL last_insert_rowid");
+  return Object.freeze({ columns: Object.freeze(columns), rows: Object.freeze(rows), rowsAffected: affected, lastInsertRowid: rowid });
+}
+
+/**
+ * Runs 1 to 256 statements as one transaction: all commit or none do. BEGIN, COMMIT and ROLLBACK are refused.
+ * A refused statement throws SqlError with its index.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {readonly (string | V1SqlStatement)[]} statements
+ * @param {V1RequestOptions} [options]
+ * @returns {Promise<readonly V1SqlExecuteResult[]>}
+ */
+export async function executeSql(transport, database, statements, options = {}) {
+  if (!Array.isArray(statements) || statements.length === 0 || statements.length > maximumStatements)
+    throw new TypeError(`SQL batches hold 1 to ${maximumStatements} statements.`);
+  if (options === null || typeof options !== "object" || Array.isArray(options)) throw new TypeError("SQL request options must be an object.");
+  for (const member of Object.keys(options)) if (member !== "signal") throw new TypeError(`Unknown SQL request option ${member}.`);
+  const body = stringifyExactJson({ statements: statements.map(encodeStatement) }, "SQL statements");
+  const response = await transport.call("executeSql", { database: requireName("database", database) }, { body, signal: options.signal });
+  const results = array(object(response.value, "SQL execute response").results, "SQL results").map(decodeResult);
+  if (results.length !== statements.length) malformed("SQL result count");
+  return Object.freeze(results);
+}
+
+/**
+ * Rows as objects keyed by column name; a later duplicate column name wins.
+ * @template [T=Record<string, V1SqlValue>]
+ * @param {V1SqlExecuteResult} result
+ * @returns {T[]}
+ */
+export function sqlRowObjects(result) {
+  return result.rows.map(row => /** @type {T} */ (Object.fromEntries(result.columns.map((column, index) => [column.name, row[index] ?? null]))));
+}

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

@@ -4,13 +4,14 @@ 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";
 import { V1ShapeSubscription } from "./shape-subscription.js";
 import { decryptSealedShapePage, readShapePage, readShapeKey } from "./shape-reader.js";
 import { runSql, checkSql } from "./sql.js";
+import { executeSql, sqlRowObjects, sqlStatement } from "./sql-execute.js";
 import { streamChanges } from "./changes.js";
 import { exportDocuments } from "./export.js";
 import { V1Databases, getCollectionSchema, putCollectionSchema, deleteCollectionSchema, getCollectionTtl, putCollectionTtl, deleteCollectionTtl } from "./catalog.js";
@@ -22,6 +23,7 @@ import { V1ProjectUsageClient, V1DatabaseUsageClient } from "./usage.js";
 import { V1Indexes } from "./indexes.js";
 import { V1DatabaseSchemaClient } from "./database-schema.js";
 import { V1SavedQueries } from "./saved-queries.js";
+import { V1ChangeWebhooks } from "./change-webhooks.js";
 /**
  * @import { V1Document, V1Durability, V1WriteResult } from "./decode.js"
  * @import { V1Filter, V1Path } from "./filter.js"
@@ -64,7 +66,32 @@ import { V1SavedQueries } from "./saved-queries.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
@@ -74,6 +101,7 @@ import { V1SavedQueries } from "./saved-queries.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 */
 /**
@@ -81,6 +109,7 @@ import { V1SavedQueries } from "./saved-queries.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 */
@@ -97,7 +126,8 @@ import { V1SavedQueries } from "./saved-queries.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
@@ -181,16 +211,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;
@@ -218,6 +285,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 }) };
     });
   }
@@ -237,9 +308,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}
@@ -256,14 +347,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)),
   });
 }
 
@@ -301,6 +397,8 @@ function encodeDocument(document) {
 
 /** A collection handle by name. It performs no I/O until an operation runs. */
 export class V1Collection {
+  /** @type {V1ChangeWebhooks} */
+  webhooks;
   /** @type {V1Transport} */
   #transport;
   /** @type {Readonly<Record<string, string>>} */
@@ -319,6 +417,7 @@ export class V1Collection {
     this.#transport = transport;
     this.database = requireName("database", database);
     this.name = requireName("collection", name);
+    this.webhooks = new V1ChangeWebhooks(transport, this.database, this.name);
     this.#params = Object.freeze({ database: this.database, collection: this.name });
     Object.freeze(this);
   }
@@ -852,6 +951,39 @@ export class V1Database {
     return checkSql(this.#transport, this.name, statement, options, "explainSql");
   }
 
+  /**
+   * Runs one relational SQL statement as its own transaction. Reads need documents:read; writes and DDL need documents:write.
+   * @param {string} sql
+   * @param {import("./sql-execute.js").V1SqlArguments} [args] Positional array, or named values keyed without their prefix.
+   * @param {V1RequestOptions} [options]
+   * @returns {Promise<import("./sql-execute.js").V1SqlExecuteResult>}
+   */
+  async execute(sql, args, options = {}) {
+    const [result] = await executeSql(this.#transport, this.name, [sqlStatement(sql, args)], options);
+    return /** @type {import("./sql-execute.js").V1SqlExecuteResult} */ (result);
+  }
+
+  /**
+   * Runs one statement and returns its rows as objects keyed by column name.
+   * @template [T=Record<string, import("./sql-execute.js").V1SqlValue>]
+   * @param {string} sql
+   * @param {import("./sql-execute.js").V1SqlArguments} [args]
+   * @param {V1RequestOptions} [options]
+   * @returns {Promise<T[]>}
+   */
+  async query(sql, args, options = {}) {
+    return sqlRowObjects(await this.execute(sql, args, options));
+  }
+
+  /**
+   * Runs 1 to 256 statements as one transaction: all commit or none do. A refused statement throws SqlError.
+   * @param {readonly (string | import("./sql-execute.js").V1SqlStatement)[]} statements
+   * @param {V1RequestOptions} [options]
+   */
+  batch(statements, options = {}) {
+    return executeSql(this.#transport, this.name, statements, options);
+  }
+
   /** @param {import("./changes.js").V1ChangeStreamRequest} [request] @param {V1RequestOptions} [options] */
   changes(request = {}, options = {}) {
     return streamChanges(this.#transport, this.name, request, options.signal);

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;
   }