@terrascale/sdk 0.0.6 → 0.0.7

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

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/filter.d.ts

@@ -10,6 +10,14 @@ export function isJsonPointer(pointer: unknown): pointer is string;
  * @returns {V1Path}
  */
 export function requirePath(path: V1Path): V1Path;
+/** @param {V1Filter | null | undefined} filter @returns {number} */
+export function searchCount(filter: V1Filter | null | undefined): number;
+/**
+ * @param {unknown} lat
+ * @param {unknown} lon
+ * @returns {void}
+ */
+export function requireGeoPoint(lat: unknown, lon: unknown): void;
 /**
  * Validates a filter against the query-v1 grammar (operators, arity, paths,
  * scalar operands, depth 8 and 256 nodes), so a malformed filter fails locally
@@ -100,6 +108,13 @@ export const v1Filter: Readonly<{
      * @returns {V1Filter}
      */
     prefix: (path: V1Path, prefix: string) => V1Filter;
+    /**
+     * Full-text search on a document member.
+     * @param {V1Path} path
+     * @param {string} terms
+     * @returns {V1Filter}
+     */
+    search: (path: V1Path, terms: string) => V1Filter;
     /**
      * The value is an array containing the scalar.
      * @param {V1Path} path
@@ -107,6 +122,20 @@ export const v1Filter: Readonly<{
      * @returns {V1Filter}
      */
     contains: (path: V1Path, value: V1Scalar) => V1Filter;
+    /**
+     * 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: string, circle: V1GeoCircle) => V1Filter;
+    /**
+     * 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: string, box: V1GeoBox) => V1Filter;
 }>;
 /**
  * A filter or sort path: an RFC 6901 JSON Pointer or "$id".
@@ -144,5 +173,26 @@ export type V1Filter = {
     readonly prefix: readonly [V1Path, string];
 } | {
     readonly contains: readonly [V1Path, V1Scalar];
+} | {
+    readonly within: readonly [string, V1GeoCircle | V1GeoBox];
+} | {
+    readonly search: readonly [V1Path, string];
+};
+/**
+ * Points within `meters` (more than 0, at most 20000000) of a WGS 84 point, by haversine distance.
+ */
+export type V1GeoCircle = {
+    readonly lat: number;
+    readonly lon: number;
+    readonly meters: number;
+};
+/**
+ * Points in a latitude/longitude box; `west > east` crosses the antimeridian.
+ */
+export type V1GeoBox = {
+    readonly south: number;
+    readonly west: number;
+    readonly north: number;
+    readonly east: number;
 };
 import { ExactDecimal } from "./json.js";

package/types/v1/ids.d.ts

@@ -10,8 +10,10 @@ export function requireName(kind: "database" | "collection", name: unknown): str
  * @returns {import("../ids.js").EntityId}
  */
 export function requireProject(project: unknown): import("../ids.js").EntityId;
-/** 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: unknown): string;
+/** SQL-backed collections can return non-ULID primary keys. @param {unknown} id @returns {string} */
+export function requireStoredId(id: unknown): string;
 /**
  * @param {unknown} version
  * @returns {string}

package/types/v1/indexes.d.ts

@@ -27,10 +27,12 @@ export type V1IndexList = ReturnType<typeof indexes>;
 export type V1AutoIndexPolicy = ReturnType<typeof policy>;
 export type V1IndexRecommendations = ReturnType<typeof recommendations>;
 export type V1AppliedIndexRecommendation = ReturnType<typeof applied>;
+export type V1IndexKind = "btree" | "text";
 export type V1CreateIndexRequest = {
     readonly collection: string;
     readonly fields: readonly string[];
     readonly name?: string | null;
+    readonly kind?: V1IndexKind;
 };
 import type { V1RequestOptions } from "./terrabase-v1.js";
 import type { V1Transport } from "./transport.js";
@@ -41,6 +43,7 @@ declare const index: import("./management-decode.js").Decoder<Readonly<{
     collection: string;
     fields: readonly string[];
     state: string;
+    kind: string | undefined;
 }>>;
 declare const indexes: import("./management-decode.js").Decoder<Readonly<{
     items: readonly Readonly<{
@@ -48,6 +51,7 @@ declare const indexes: import("./management-decode.js").Decoder<Readonly<{
         collection: string;
         fields: readonly string[];
         state: string;
+        kind: string | undefined;
     }>[];
 }>>;
 declare const policy: import("./management-decode.js").Decoder<Readonly<{
@@ -70,6 +74,7 @@ declare const applied: import("./management-decode.js").Decoder<Readonly<{
         collection: string;
         fields: readonly string[];
         state: string;
+        kind: string | undefined;
     }>;
 }>>;
 export {};

package/types/v1/shape-replica.d.ts

@@ -0,0 +1,8 @@
+/** @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: string): V1ShapeReplicaStore;
+import type { V1ShapeReplicaStore } from "./shape-subscription.js";

package/types/v1/shape-subscription.d.ts

@@ -25,6 +25,21 @@ export type V1ShapeSubscribeOptions = {
      * Runs after validated responses and freshness changes; throwing rejects `done` unless already closed or aborted.
      */
     onUpdate?: ((subscription: V1ShapeSubscription) => void) | undefined;
+    /**
+     * Keeps the last resumable state for reads across restarts and while offline; writes still go to the server.
+     */
+    replica?: V1ShapeReplicaStore | undefined;
+};
+/**
+ * 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`.
+ */
+export type V1ShapeReplicaStore = {
+    load: () => string | undefined | Promise<string | undefined>;
+    /**
+     * Receives undefined after must_refetch discards state.
+     */
+    save: (text: string | undefined) => void | Promise<void>;
 };
 export type V1ShapeDocument = {
     readonly version: string;

package/types/v1/terrabase-v1.d.ts

@@ -438,7 +438,67 @@ export type V1NearSortKey = {
         readonly metric?: "cosine" | "l2" | undefined;
     };
 };
-export type V1SortKey = V1FieldSortKey | V1NearSortKey;
+/**
+ * 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.
+ */
+export type V1GeoNearSortKey = {
+    readonly near: {
+        readonly path: string;
+        readonly lat: number;
+        readonly lon: number;
+    };
+};
+/**
+ * Relevance order, only sort key with exactly one search predicate.
+ */
+export type V1ScoreSortKey = {
+    readonly path: "$score";
+    readonly order: "desc";
+};
+export type V1SortKey = V1FieldSortKey | V1NearSortKey | V1GeoNearSortKey | V1ScoreSortKey;
+/**
+ * Groups matches instead of returning documents. Summaries consider numbers only; at most 16 summary paths in total.
+ */
+export type V1Aggregate = {
+    /**
+     * 0-4 paths; without it every match is one group.
+     */
+    groupBy?: readonly V1Path[] | undefined;
+    /**
+     * Distinct JSON Pointers.
+     */
+    sum?: readonly string[] | undefined;
+    /**
+     * Distinct JSON Pointers.
+     */
+    avg?: readonly string[] | undefined;
+    /**
+     * Distinct JSON Pointers.
+     */
+    min?: readonly string[] | undefined;
+    /**
+     * Distinct JSON Pointers.
+     */
+    max?: readonly string[] | undefined;
+};
+/**
+ * One aggregate group. Summaries are keyed by the requested JSON Pointer; `sum` is 0 and the others null without numbers.
+ */
+export type V1Group = {
+    /**
+     * One value per `groupBy` path (missing members group as null).
+     */
+    key: readonly JsonValue[];
+    /**
+     * Matching documents in the group (decimal u64).
+     */
+    count: string;
+    sum?: Readonly<Record<string, number | null>> | undefined;
+    avg?: Readonly<Record<string, number | null>> | undefined;
+    min?: Readonly<Record<string, number | null>> | undefined;
+    max?: Readonly<Record<string, number | null>> | undefined;
+};
 /**
  * A query-v1 request. Every member is optional.
  */
@@ -464,6 +524,10 @@ export type V1Query = {
      * Count every match (first page only).
      */
     count?: boolean | undefined;
+    /**
+     * Answer `groups` instead of items; `limit` bounds the groups. No sort, project, cursor or count.
+     */
+    aggregate?: V1Aggregate | undefined;
 };
 export type V1Count = {
     readonly value: string;
@@ -476,6 +540,10 @@ export type V1QueryPage = {
     items: readonly V1Document[];
     nextCursor: string | null;
     count: V1Count | undefined;
+    /**
+     * An aggregate query's groups in key order (`items` is then empty).
+     */
+    groups: readonly V1Group[] | undefined;
 };
 export type V1Precondition = {
     readonly ifMatch: string;

package/types/v1/transport.d.ts

@@ -23,6 +23,15 @@ export class BodyTransportError extends Error {
     /** @param {unknown} cause */
     constructor(cause: unknown);
 }
+/** 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: unknown);
+}
+/** A browser hid a 307 behind an opaque redirect; only the shape bootstrap may follow it. */
+export class OpaqueRedirectError extends TypeError {
+    constructor();
+}
 /** Internal transport bound to one project credential. */
 export class V1Transport {
     /**
@@ -128,11 +137,19 @@ export type V1CallOptions = {
      * Authenticated shape epoch keys must bypass caches.
      */
     cache?: "no-store" | undefined;
+    /**
+     * Only the shape bootstrap, after a browser hides its 307 behind an opaque redirect.
+     */
+    redirect?: "follow" | undefined;
 };
 export type V1CallResult = {
     status: number;
     headers: Headers;
     value: JsonValue | undefined;
+    /**
+     * The final URL after a followed redirect.
+     */
+    redirectedTo?: string | undefined;
 };
 import type { V1Operation } from "./routes.js";
 import type { JsonValue } from "./json.js";