@terrascale/sdk 0.0.6 → 0.0.8

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

@@ -0,0 +1,98 @@
+/** Project file buckets, authenticated by the same token as documents. */
+export class V1FileStorage {
+    /** @param {V1Transport} transport @param {FetchLike} fetcher */
+    constructor(transport: V1Transport, fetcher: FetchLike);
+    /** @param {string} name @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+    createBucket(name: string, accessRules: FileAccessRules, options?: FileRequestOptions): Promise<FileBucketInfo>;
+    /** @param {FileListOptions} [options] @returns {Promise<{items: FileBucketInfo[], next: string | null}>} */
+    listBuckets(options?: FileListOptions): Promise<{
+        items: FileBucketInfo[];
+        next: string | null;
+    }>;
+    /** @param {string} id @returns {V1FileBucket} */
+    bucket(id: string): V1FileBucket;
+    #private;
+}
+/** Immutable files in one project bucket. */
+export class V1FileBucket {
+    /** @param {V1Transport} transport @param {FetchLike} fetcher @param {string} bucket */
+    constructor(transport: V1Transport, fetcher: FetchLike, bucket: string);
+    /** @param {FileAccessRules} accessRules @param {FileRequestOptions} [options] @returns {Promise<FileBucketInfo>} */
+    setRules(accessRules: FileAccessRules, options?: FileRequestOptions): Promise<FileBucketInfo>;
+    /** @param {FileRequestOptions} [options] @returns {Promise<void>} */
+    delete(options?: FileRequestOptions): Promise<void>;
+    /** @param {FileUploadRequest} request @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+    createUpload(request: FileUploadRequest, options?: FileRequestOptions): Promise<SignedFileUrl>;
+    /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<StoredFile>} */
+    completeUpload(id: string, options?: FileRequestOptions): Promise<StoredFile>;
+    /** @param {FileListOptions} [options] @returns {Promise<{items: StoredFile[], next: string | null}>} */
+    list(options?: FileListOptions): Promise<{
+        items: StoredFile[];
+        next: string | null;
+    }>;
+    /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<SignedFileUrl>} */
+    downloadUrl(id: string, options?: FileRequestOptions): Promise<SignedFileUrl>;
+    /** @param {string} id @param {FileRequestOptions} [options] @returns {Promise<void>} */
+    deleteFile(id: string, options?: FileRequestOptions): Promise<void>;
+    /** 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>} */
+    upload(name: string, input: Uint8Array | Blob, options: FileUploadOptions): Promise<StoredFile>;
+    /** Fetches file bytes without sending the project token to the object store.
+     * @param {string} id @param {FileRequestOptions} [options] @returns {Promise<Blob>} */
+    download(id: string, options?: FileRequestOptions): Promise<Blob>;
+    #private;
+}
+export type FileAccessPolicy = {
+    owner: boolean;
+    public: boolean;
+    roles: readonly string[];
+};
+export type FileAccessRules = {
+    owner: string | null;
+    read: FileAccessPolicy;
+    write: FileAccessPolicy;
+};
+export type FileBucketInfo = {
+    id: string;
+    name: string;
+    region: string;
+    rules: FileAccessRules;
+};
+export type StoredFile = {
+    id: string;
+    name: string;
+    contentType: string;
+    size: number;
+    sha256: string;
+    metadata: JsonObject;
+    status: string;
+    uploadExpiresAt: string;
+};
+export type SignedFileUrl = {
+    id: string;
+    url: string;
+    expiresAt: string;
+    headers: Readonly<Record<string, string>>;
+};
+export type FileUploadRequest = {
+    name: string;
+    contentType: string;
+    size: number;
+    sha256: string;
+    metadata: JsonObject;
+};
+export type FileRequestOptions = {
+    signal?: AbortSignal | undefined;
+};
+export type FileListOptions = {
+    after?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+export type FileUploadOptions = {
+    metadata: JsonObject;
+    contentType?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+import type { V1Transport } from "./transport.js";
+import type { FetchLike } from "../config.js";
+import type { JsonObject } from "./json.js";

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

@@ -6,7 +6,7 @@ export function v1RoutePath(route: V1Route, params: Readonly<Record<string, stri
 export const v1Routes: readonly V1Route[];
 /** @type {readonly V1Route[]} */
 export const shapeV1Routes: readonly V1Route[];
-export type V1Operation = 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";
+export type V1Operation = 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";
 export type V1Route = {
     operation: V1Operation;
     method: "GET" | "PUT" | "POST" | "PATCH" | "DELETE";

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

@@ -341,6 +341,8 @@ export class TerraBaseV1Client {
     database(name: string): V1Database;
     /** @returns {V1Databases} Project-scoped database catalog. */
     get databases(): V1Databases;
+    /** @returns {V1FileStorage} Project file buckets. */
+    get storage(): V1FileStorage;
     /** @returns {V1SavedQueries} */
     get savedQueries(): V1SavedQueries;
     /** @returns {V1ProjectUsageClient} */
@@ -438,7 +440,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 +526,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 +542,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;
@@ -524,6 +594,7 @@ import { V1DatabaseUsageClient } from "./usage.js";
 import { V1Indexes } from "./indexes.js";
 import { V1DatabaseSchemaClient } from "./database-schema.js";
 import { V1Databases } from "./catalog.js";
+import { V1FileStorage } from "./file-storage.js";
 import { V1SavedQueries } from "./saved-queries.js";
 import { V1ProjectUsageClient } from "./usage.js";
 import { V1BackupDestinationClient } from "./backups.js";

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

package/types/v1/usage.d.ts

@@ -63,6 +63,7 @@ declare const projectUsage: import("./management-decode.js").Decoder<Readonly<{
     databases: number | import("./json.js").ExactDecimal;
     storageBytes: number | import("./json.js").ExactDecimal;
     logicalBytes: number | import("./json.js").ExactDecimal;
+    fileBytes: number | import("./json.js").ExactDecimal;
     documents: number | import("./json.js").ExactDecimal;
     reads: number | import("./json.js").ExactDecimal;
     writes: number | import("./json.js").ExactDecimal;