@terrascale/sdk 0.0.5 → 0.0.7

package/types/index.d.ts

@@ -1,12 +1,15 @@
 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";
 export { V1SavedQueries } from "./v1/saved-queries.js";
 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;
@@ -22,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;
@@ -35,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;
@@ -56,6 +65,12 @@ export type V1SqlRow = import("./v1/sql.js").V1SqlRow;
 export type V1SqlResult = import("./v1/sql.js").V1SqlResult;
 export type V1SqlIndexSuggestion = import("./v1/sql.js").V1SqlIndexSuggestion;
 export type V1SqlCheck = import("./v1/sql.js").V1SqlCheck;
+export type V1SqlArgument = import("./v1/sql-execute.js").V1SqlArgument;
+export type V1SqlArguments = import("./v1/sql-execute.js").V1SqlArguments;
+export type V1SqlStatement = import("./v1/sql-execute.js").V1SqlStatement;
+export type V1SqlValue = import("./v1/sql-execute.js").V1SqlValue;
+export type V1SqlColumn = import("./v1/sql-execute.js").V1SqlColumn;
+export type V1SqlExecuteResult = import("./v1/sql-execute.js").V1SqlExecuteResult;
 export type V1ChangeStreamRequest = import("./v1/changes.js").V1ChangeStreamRequest;
 export type V1DatabaseChange = import("./v1/changes.js").V1DatabaseChange;
 export type V1DatabaseChangeCursor = import("./v1/changes.js").V1DatabaseChangeCursor;
@@ -75,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;
@@ -86,6 +102,10 @@ export type V1Analytics = import("./v1/usage.js").V1Analytics;
 export type V1Replication = import("./v1/usage.js").V1Replication;
 export type V1UsageRequest = import("./v1/usage.js").V1UsageRequest;
 export type V1AnalyticsRequest = import("./v1/usage.js").V1AnalyticsRequest;
+export type V1ChangeWebhook = import("./v1/change-webhooks.js").V1ChangeWebhook;
+export type V1CreatedChangeWebhook = import("./v1/change-webhooks.js").V1CreatedChangeWebhook;
+export type V1ChangeWebhookDelivery = import("./v1/change-webhooks.js").V1ChangeWebhookDelivery;
+export type V1ChangeWebhookListRequest = import("./v1/change-webhooks.js").V1ChangeWebhookListRequest;
 export type V1Backup = import("./v1/backups.js").V1Backup;
 export type V1BackupPage = import("./v1/backups.js").V1BackupPage;
 export type V1BackupPolicy = import("./v1/backups.js").V1BackupPolicy;
@@ -110,7 +130,7 @@ export type V1ShapeKeyRequest = import("./v1/shape-reader.js").V1ShapeKeyRequest
 export type V1ShapeKey = import("./v1/shape-reader.js").V1ShapeKey;
 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, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
+export { TerraBaseV1Error, V1PreconditionFailedError, V1InvalidKeyError, V1ForbiddenScopeError, V1NotFoundError, SqlError, V1ErrorCode, isTerraBaseV1Error } from "./v1/errors.js";
 export { generateId, isValidId, requireId } from "./ids.js";
 export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
 export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";

package/types/v1/change-webhooks.d.ts

@@ -0,0 +1,59 @@
+/** Collection change webhook registration and sanitized delivery history. Requests are never replayed. */
+export class V1ChangeWebhooks {
+    /** @param {V1Transport} transport @param {string} database @param {string} collection */
+    constructor(transport: V1Transport, database: string, collection: string);
+    /**
+     * Registers from the current feed head. Requires documents:read and documents:write.
+     * Store secret immediately; it is non-enumerable to keep it out of JSON and ordinary diagnostics.
+     * @param {{ readonly url: string }} request @param {V1RequestOptions} [options] @returns {Promise<V1CreatedChangeWebhook>}
+     */
+    create(request: {
+        readonly url: string;
+    }, options?: V1RequestOptions): Promise<V1CreatedChangeWebhook>;
+    /**
+     * Requires documents:read. Ascending IDs; continue with the final ID until an empty array. No secrets.
+     * @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhook[]>}
+     */
+    list(request?: V1ChangeWebhookListRequest, options?: V1RequestOptions): Promise<readonly V1ChangeWebhook[]>;
+    /**
+     * Requires documents:read and documents:write. An in-flight delivery may still complete. Unknown ID returns 404.
+     * @param {string} id @param {V1RequestOptions} [options] @returns {Promise<void>}
+     */
+    delete(id: string, options?: V1RequestOptions): Promise<void>;
+    /**
+     * Requires documents:read. Latest 100 retained records; paginate with the final ID until an empty array.
+     * @param {string} id @param {V1ChangeWebhookListRequest} [request] @param {V1RequestOptions} [options] @returns {Promise<readonly V1ChangeWebhookDelivery[]>}
+     */
+    deliveries(id: string, request?: V1ChangeWebhookListRequest, options?: V1RequestOptions): Promise<readonly V1ChangeWebhookDelivery[]>;
+    #private;
+}
+export type V1ChangeWebhook = ReturnType<typeof webhook>;
+export type V1CreatedChangeWebhook = V1ChangeWebhook & {
+    readonly secret: string;
+};
+export type V1ChangeWebhookDelivery = ReturnType<typeof deliveries>[number];
+export type V1ChangeWebhookListRequest = {
+    readonly after?: string;
+    readonly limit?: number;
+};
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import type { V1Transport } from "./transport.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+declare const webhook: import("./management-decode.js").Decoder<Readonly<{
+    id: string;
+    url: string;
+    createdAt: string;
+    status: string;
+}>>;
+declare const deliveries: import("./management-decode.js").Decoder<readonly Readonly<{
+    id: string;
+    createdAt: string;
+    status: string;
+    attempts: number | import("./json.js").ExactDecimal;
+    lastAttemptAt: string | null;
+    nextAttemptAt: string | null;
+    httpStatus: number | import("./json.js").ExactDecimal | null;
+    errorCode: string | null;
+}>[]>;
+export {};

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

@@ -92,6 +92,9 @@ export const V1ErrorCode: Readonly<{
     internalError: "internal_error";
     capacity: "capacity";
     notModified: "not_modified";
+    sqlError: "sql_error";
+    sqlConflict: "sql_conflict";
+    sqlTooLarge: "sql_too_large";
 }>;
 /** `412 precondition_failed`: an If-Match, If-None-Match, assert or assert_count failed. */
 export class V1PreconditionFailedError extends TerraBaseV1Error {
@@ -105,6 +108,21 @@ export class V1ForbiddenScopeError extends TerraBaseV1Error {
 /** `404 not_found`: absent or deleted; `etag` carries a tombstone version. */
 export class V1NotFoundError extends TerraBaseV1Error {
 }
+/**
+ * A refused relational SQL statement: `sql_error` (400), `forbidden_scope` (403, writes and DDL need
+ * documents:write), `sql_conflict` (409) or `sql_too_large` (413). The whole request rolled back.
+ */
+export class SqlError extends TerraBaseV1Error {
+    /** @param {TerraBaseV1ErrorInit & { statement: number; sqliteCode?: string | undefined }} init */
+    constructor(init: TerraBaseV1ErrorInit & {
+        statement: number;
+        sqliteCode?: string | undefined;
+    });
+    /** @type {number} Zero-based index of the failing statement. */
+    statement: number;
+    /** @type {string | undefined} The SQLite error code, such as `SQLITE_CONSTRAINT_PRIMARYKEY`. */
+    sqliteCode: string | undefined;
+}
 export type TerraBaseV1ErrorInit = {
     status: number;
     code: string;

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

@@ -1,3 +1,3 @@
 /** @type {readonly import("./routes.js").V1Route[]} */
 export const managementV1Routes: readonly import("./routes.js").V1Route[];
-export type ManagementOperation = "getShapeManifest" | "exportDatabase" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery";
+export type ManagementOperation = "getShapeManifest" | "exportDatabase" | "executeSql" | "putCollectionTtl" | "getCollectionTtl" | "deleteCollectionTtl" | "healthz" | "readyz" | "backupz" | "replicationHealth" | "listPlatformDatabases" | "listPlatformCollections" | "listPlatformDocuments" | "getPlatformDocument" | "createImport" | "getImport" | "uploadImportSource" | "updateImport" | "startImport" | "cancelImport" | "resumeImport" | "createBackup" | "listBackups" | "restoreBackup" | "getBackupPolicy" | "setBackupPolicy" | "getRestoreWindow" | "planPointInTime" | "restorePointInTime" | "getBackupDestination" | "setBackupDestination" | "deleteBackupDestination" | "getProjectUsage" | "getProjectAnalytics" | "getProjectReplication" | "getDatabaseUsage" | "getDatabaseAnalytics" | "getDatabaseReplication" | "createIndex" | "listIndexes" | "dropIndex" | "getAutoIndexPolicy" | "setAutoIndexPolicy" | "listIndexRecommendations" | "applyIndexRecommendation" | "getDatabaseSchema" | "inferCollectionSchema" | "declareCollectionSchema" | "listQueryShapes" | "createSavedQuery" | "listSavedQueries" | "getSavedQuery" | "updateSavedQuery" | "deleteSavedQuery" | "createChangeWebhook" | "listChangeWebhooks" | "deleteChangeWebhook" | "listChangeWebhookDeliveries";

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

@@ -0,0 +1,61 @@
+/** @param {string} sql @param {V1SqlArguments | undefined} args @returns {V1SqlStatement} */
+export function sqlStatement(sql: string, args: V1SqlArguments | undefined): V1SqlStatement;
+/**
+ * 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 function executeSql(transport: V1Transport, database: string, statements: readonly (string | V1SqlStatement)[], options?: V1RequestOptions): Promise<readonly V1SqlExecuteResult[]>;
+/**
+ * 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<T = Record<string, V1SqlValue>>(result: V1SqlExecuteResult): T[];
+/**
+ * An argument: null, a finite number, an int64 `bigint` or ExactDecimal, a boolean (stored as 1 or 0) or a string.
+ */
+export type V1SqlArgument = null | boolean | number | bigint | ExactDecimal | string;
+/**
+ * Positional array, or named values keyed without their `:`, `@` or `$` prefix.
+ */
+export type V1SqlArguments = readonly V1SqlArgument[] | Readonly<Record<string, V1SqlArgument>>;
+export type V1SqlStatement = {
+    sql: string;
+    /**
+     * Positional arguments.
+     */
+    args?: readonly V1SqlArgument[] | undefined;
+    /**
+     * Named arguments, keys without their prefix.
+     */
+    named?: Readonly<Record<string, V1SqlArgument>> | undefined;
+};
+/**
+ * A result value. Integers beyond 2^53 decode as ExactDecimal, keeping every digit; `BigInt(String(value))` converts one.
+ */
+export type V1SqlValue = null | number | ExactDecimal | string;
+/**
+ * A column; `decltype` is null for an expression.
+ */
+export type V1SqlColumn = {
+    readonly name: string;
+    readonly decltype: string | null;
+};
+export type V1SqlExecuteResult = {
+    columns: readonly V1SqlColumn[];
+    /**
+     * One value per column.
+     */
+    rows: readonly (readonly V1SqlValue[])[];
+    rowsAffected: number;
+    lastInsertRowid: number | ExactDecimal | null;
+};
+import type { V1Transport } from "./transport.js";
+import type { V1RequestOptions } from "./terrabase-v1.js";
+import { ExactDecimal } from "./json.js";

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

@@ -22,6 +22,8 @@ export class V1Collection {
      * @param {string} name
      */
     constructor(transport: V1Transport, database: string, name: string);
+    /** @type {V1ChangeWebhooks} */
+    webhooks: V1ChangeWebhooks;
     /** @type {string} */
     name: string;
     /** @type {string} */
@@ -293,6 +295,29 @@ export class V1Database {
     checkSql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlCheck>;
     /** @param {string} statement @param {V1RequestOptions} [options] */
     explainSql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlCheck>;
+    /**
+     * 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>}
+     */
+    execute(sql: string, args?: import("./sql-execute.js").V1SqlArguments, options?: V1RequestOptions): Promise<import("./sql-execute.js").V1SqlExecuteResult>;
+    /**
+     * 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[]>}
+     */
+    query<T = Record<string, import("./sql-execute.js").V1SqlValue>>(sql: string, args?: import("./sql-execute.js").V1SqlArguments, options?: V1RequestOptions): Promise<T[]>;
+    /**
+     * 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: readonly (string | import("./sql-execute.js").V1SqlStatement)[], options?: V1RequestOptions): Promise<readonly import("./sql-execute.js").V1SqlExecuteResult[]>;
     /** @param {import("./changes.js").V1ChangeStreamRequest} [request] @param {V1RequestOptions} [options] */
     changes(request?: import("./changes.js").V1ChangeStreamRequest, options?: V1RequestOptions): AsyncGenerator<import("./changes.js").V1DatabaseChange | import("./changes.js").V1DatabaseChangeCursor, void, undefined>;
     /**
@@ -413,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.
  */
@@ -439,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;
@@ -451,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;
@@ -483,6 +576,7 @@ export type V1TransactionResult = {
 };
 import type { JsonValue } from "./json.js";
 import type { TerraBaseV1ClientConfig } from "./transport.js";
+import { V1ChangeWebhooks } from "./change-webhooks.js";
 import type { V1Document } from "./decode.js";
 import type { JsonInputObject } from "./json.js";
 import type { V1WriteResult } from "./decode.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";