@terrascale/sdk 0.0.4 → 0.0.6

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/terrabase-v1.js

@@ -11,8 +11,10 @@ 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 { V1Databases, getCollectionSchema, putCollectionSchema, deleteCollectionSchema } from "./catalog.js";
+import { exportDocuments } from "./export.js";
+import { V1Databases, getCollectionSchema, putCollectionSchema, deleteCollectionSchema, getCollectionTtl, putCollectionTtl, deleteCollectionTtl } from "./catalog.js";
 import { V1Transport } from "./transport.js";
 import { V1Health, V1Platform } from "./system.js";
 import { V1Imports } from "./imports.js";
@@ -21,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"
@@ -58,12 +61,17 @@ import { V1SavedQueries } from "./saved-queries.js";
  * @typedef {{ readonly merge: JsonInputObject } | { readonly ops: readonly V1PatchOp[] }} V1Patch
  */
 
-/** @typedef {{ readonly path: V1Path; readonly order?: "asc" | "desc" | undefined }} V1SortKey */
+/** @typedef {{ readonly path: V1Path; readonly order?: "asc" | "desc" | undefined }} V1FieldSortKey */
+/**
+ * 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 */
 /**
  * A query-v1 request. Every member is optional.
  * @typedef {object} V1Query
  * @property {V1Filter | null | undefined} [filter]
- * @property {readonly V1SortKey[] | undefined} [sort] At most 4 keys; results are finally ordered by `$id`.
+ * @property {readonly V1SortKey[] | undefined} [sort] At most 4 keys, or one `near` key; results are finally ordered by `$id`.
  * @property {readonly string[] | undefined} [project] At most 64 paths.
  * @property {number | undefined} [limit] 1-1000 (server default 50).
  * @property {string | null | undefined} [cursor] A previous page's `nextCursor`.
@@ -174,6 +182,26 @@ function normalizePatch(patch) {
   return { ops: ops.map(patchOp) };
 }
 
+/**
+ * @param {V1NearSortKey} 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 (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.");
+  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;
+  if (!Array.isArray(vector) || vector.length < 1 || vector.length > 4096) throw new TypeError("A near vector has 1-4096 numbers.");
+  if (!vector.every(value => typeof value === "number" && Math.abs(value) <= 3.4028234663852886e38)) throw new TypeError("near vector values are finite float32 numbers.");
+  if (near.metric !== "l2" && vector.every(value => value === 0)) throw new TypeError("A cosine near vector is not all zeros.");
+  return { near: { path: requirePath(near.path), vector: [...vector], ...(near.metric === undefined ? {} : { metric: near.metric }) } };
+}
+
 /**
  * @param {V1Query} query
  * @returns {string}
@@ -189,6 +217,7 @@ function encodeQuery(query) {
     if (!Array.isArray(query.sort) || query.sort.length > 4) throw new TypeError("sort has at most 4 keys.");
     body.sort = query.sort.map((key) => {
       if (key === null || typeof key !== "object") throw new TypeError("Sort keys are objects.");
+      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".');
       return { path: requirePath(key.path), ...(key.order === undefined ? {} : { order: key.order }) };
@@ -228,7 +257,13 @@ export function decodeQueryPage(value) {
     count = Object.freeze({ value: u64(rawCount.value, "count value"), exact: boolean(rawCount.exact, "count exact flag") });
   }
   return Object.freeze({
-    items: Object.freeze(array(raw.items, "query items").map(decodeDocument)),
+    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 });
+    })),
     nextCursor: typeof next === "string" && next !== "" ? next : null,
     count,
   });
@@ -268,6 +303,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>>} */
@@ -286,6 +323,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);
   }
@@ -407,6 +445,15 @@ export class V1Collection {
   putSchema(schema, options = {}) { return putCollectionSchema(this.#transport, this.#params, schema, options); }
   /** @param {V1RequestOptions} [options] */
   deleteSchema(options = {}) { return deleteCollectionSchema(this.#transport, this.#params, options); }
+  /** @param {V1RequestOptions} [options] */
+  getTtl(options = {}) { return getCollectionTtl(this.#transport, this.#params, options); }
+  /**
+   * Documents whose member at `path` holds a past RFC 3339 UTC time are deleted by an hourly sweep (up to about an hour late).
+   * @param {string} path JSON Pointer such as `/expiresAt`. @param {V1RequestOptions} [options]
+   */
+  putTtl(path, options = {}) { return putCollectionTtl(this.#transport, this.#params, path, options); }
+  /** @param {V1RequestOptions} [options] */
+  deleteTtl(options = {}) { return deleteCollectionTtl(this.#transport, this.#params, options); }
 
   /**
    * Iterates over every page, following `nextCursor`. `count`
@@ -810,10 +857,51 @@ 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);
   }
+
+  /**
+   * Streams every live document as `{ collection, id, document }`, in collection then id order, from one snapshot.
+   * @param {import("./export.js").V1ExportOptions} [options]
+   */
+  export(options = {}) {
+    return exportDocuments(this.#transport, this.name, options);
+  }
 }
 
 /**

package/src/v1/transport.js

@@ -23,12 +23,13 @@ const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-
  * @typedef {{ readonly project: string | undefined; readonly database?: string | undefined; readonly signal?: AbortSignal | undefined }} V1EndpointContext
  */
 /** @typedef {(context: V1EndpointContext) => string | Promise<string>} V1EndpointResolver */
+/** A fresh access token for each authenticated request, including stream reconnects. @typedef {() => string | Promise<string>} V1TokenProvider */
 /**
  * Project-scoped C# Documents API client. Supply exactly one of baseUrl or endpointResolver.
  * URLs must use HTTPS or loopback HTTP. Mutations are never automatically replayed.
  * @typedef {object} TerraBaseV1ClientConfig
  * @property {string} project
- * @property {string} token A ts-auth project access JWT (or a legacy C# tb_ key); held privately.
+ * @property {string | V1TokenProvider} token An access JWT (or a legacy C# tb_ key), or a provider resolved per authenticated request; held privately. Browser callers must use end-user tokens, never project credentials.
  * @property {string | undefined} [baseUrl]
  * @property {V1EndpointResolver | undefined} [endpointResolver]
  * @property {FetchLike | undefined} [fetch]
@@ -117,6 +118,13 @@ function canonicalBaseUrl(raw) {
   return `${url.origin}${url.pathname.replace(/\/+$/u, "")}`;
 }
 
+/** @param {unknown} token @returns {string} */
+function requireToken(token) {
+  if (typeof token !== "string" || token.trim() !== token || !tokenPattern.test(token))
+    throw new TypeError("token must be a compact access JWT or a legacy C# tb_ API key.");
+  return token;
+}
+
 /** A response body that failed in transit after its headers arrived. */
 export class BodyTransportError extends Error {
   /** @param {unknown} cause */
@@ -134,7 +142,7 @@ export class V1Transport {
   #resolver;
   /** @type {Map<string, { promise: Promise<string>; timer: ReturnType<typeof setTimeout>; waiters: number }>} */
   #bases = new Map();
-  /** @type {string | undefined} */
+  /** @type {string | V1TokenProvider | undefined} */
   #token;
   /** @type {FetchLike} */
   #fetch;
@@ -150,8 +158,8 @@ export class V1Transport {
     if (config.endpointResolver !== undefined && typeof config.endpointResolver !== "function")
       throw new TypeError("endpointResolver must be a function.");
     this.#resolver = config.endpointResolver ?? staticBaseUrlResolver(/** @type {string} */ (config.baseUrl));
-    if ((config.project !== undefined || config.token !== undefined) && (typeof config.token !== "string" || !tokenPattern.test(config.token)))
-      throw new TypeError("token must be a compact access JWT or a legacy C# tb_ API key.");
+    if ((config.project !== undefined || config.token !== undefined) && typeof config.token !== "function")
+      requireToken(config.token);
     if ("autoIdempotencyKey" in config || "maxRetries" in config || "resolver" in config)
       throw new TypeError("Unsupported client configuration member.");
     const fetchHandler = config.fetch ?? globalThis.fetch?.bind(globalThis);
@@ -164,6 +172,35 @@ export class V1Transport {
     this.#maxResponseBytes = maxResponseBytes;
   }
 
+  /** Internal credential lifetime metadata; never exposes the bearer value. */
+  get hasTokenProvider() { return typeof this.#token === "function"; }
+
+  /** @param {AbortSignal | undefined} signal @returns {Promise<string>} */
+  async #accessToken(signal) {
+    signal?.throwIfAborted();
+    const provider = this.#token;
+    if (typeof provider !== "function") return requireToken(provider);
+    /** @type {() => void} */
+    let abort = () => {};
+    try {
+      const token = await new Promise((resolve, reject) => {
+        abort = () => reject(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        void Promise.resolve().then(() => {
+          signal?.throwIfAborted();
+          return provider();
+        }).then(resolve, () => {
+          // Provider errors may contain credentials; do not retain their message or cause.
+          reject(new Error("TerraBase token provider failed."));
+        });
+      });
+      signal?.throwIfAborted();
+      return requireToken(token);
+    } finally {
+      signal?.removeEventListener("abort", abort);
+    }
+  }
+
   /**
    * @param {V1Operation} operation
    * @param {Readonly<Record<string, string>>} params
@@ -320,7 +357,7 @@ export class V1Transport {
   }
 
   /**
-   * @param {"streamDatabaseChanges"} operation
+   * @param {"streamDatabaseChanges" | "exportDatabase"} operation
    * @param {Readonly<Record<string, string>>} params
    * @param {V1CallOptions} [options]
    * @returns {Promise<Response>}
@@ -328,9 +365,10 @@ export class V1Transport {
   async openStream(operation, params, options = {}) {
     const response = await this.#send(operation, params, options);
     const mediaType = response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
-    if (mediaType !== "text/event-stream" || response.body === null) {
+    const expected = v1Route(operation).responseMediaType;
+    if (mediaType !== expected || response.body === null) {
       void response.body?.cancel().catch(() => undefined);
-      throw new TypeError("TerraBase changes require a text/event-stream response body.");
+      throw new TypeError(`TerraBase ${operation} requires a ${expected} response body.`);
     }
     return response;
   }
@@ -344,7 +382,8 @@ export class V1Transport {
     let url = await this.url(operation, params, options.signal);
     if (options.query !== undefined && options.query.size > 0) url += `?${options.query}`;
     const headers = new Headers(options.headers);
-    if (route.permission !== "anonymous" && this.#token !== undefined) headers.set("authorization", `Bearer ${this.#token}`);
+    if (route.permission !== "anonymous" && this.#token !== undefined)
+      headers.set("authorization", `Bearer ${await this.#accessToken(options.signal)}`);
     if (route.responseMediaType !== "") headers.set("accept", route.responseMediaType);
     if (options.body !== undefined) headers.set("content-type", options.contentType ?? "application/json");
     /** @type {RequestInit & { duplex?: "half" }} */
@@ -357,6 +396,7 @@ export class V1Transport {
       init.duplex = "half";
     } 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);
     if (options.signal?.aborted) {
       void response.body?.cancel().catch(() => undefined);

package/types/index.d.ts

@@ -6,12 +6,14 @@ 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 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;
 export type EntityId = import("./ids.js").EntityId;
 export type TerraBaseV1ClientConfig = import("./v1/transport.js").TerraBaseV1ClientConfig;
+export type V1TokenProvider = import("./v1/transport.js").V1TokenProvider;
 export type V1RequestOptions = import("./v1/terrabase-v1.js").V1RequestOptions;
 export type V1ReadOptions = import("./v1/terrabase-v1.js").V1ReadOptions;
 export type V1WriteOptions = import("./v1/terrabase-v1.js").V1WriteOptions;
@@ -20,6 +22,7 @@ export type V1ConditionalWriteOptions = import("./v1/terrabase-v1.js").V1Conditi
 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 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;
@@ -54,9 +57,17 @@ 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;
+export type V1ExportOptions = import("./v1/export.js").V1ExportOptions;
+export type V1ExportedDocument = import("./v1/export.js").V1ExportedDocument;
 export type V1ManagedDatabase = import("./v1/catalog.js").V1ManagedDatabase;
 export type V1DatabaseCreateRequest = import("./v1/catalog.js").V1DatabaseCreateRequest;
 export type V1DatabaseUpdateRequest = import("./v1/catalog.js").V1DatabaseUpdateRequest;
@@ -64,6 +75,7 @@ export type V1DatabaseBranchRequest = import("./v1/catalog.js").V1DatabaseBranch
 export type V1DatabaseListRequest = import("./v1/catalog.js").V1DatabaseListRequest;
 export type V1DatabasePage = import("./v1/catalog.js").V1DatabasePage;
 export type V1CollectionSchema = import("./v1/catalog.js").V1CollectionSchema;
+export type V1CollectionTtl = import("./v1/catalog.js").V1CollectionTtl;
 export type V1InferredSchema = import("./v1/database-schema.js").V1InferredSchema;
 export type V1DatabaseSchema = import("./v1/database-schema.js").V1DatabaseSchema;
 export type V1UniqueSchema = import("./v1/database-schema.js").V1UniqueSchema;
@@ -81,6 +93,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;
@@ -105,7 +121,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/catalog.d.ts

@@ -4,6 +4,12 @@ export function getCollectionSchema(transport: V1Transport, params: Readonly<Rec
 export function putCollectionSchema(transport: V1Transport, params: Readonly<Record<string, string>>, schema: boolean | JsonInputObject, options?: V1RequestOptions): Promise<V1CollectionSchema>;
 /** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionSchema>} */
 export function deleteCollectionSchema(transport: V1Transport, params: Readonly<Record<string, string>>, options?: V1RequestOptions): Promise<V1CollectionSchema>;
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export function getCollectionTtl(transport: V1Transport, params: Readonly<Record<string, string>>, options?: V1RequestOptions): Promise<V1CollectionTtl>;
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {string} path @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export function putCollectionTtl(transport: V1Transport, params: Readonly<Record<string, string>>, path: string, options?: V1RequestOptions): Promise<V1CollectionTtl>;
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export function deleteCollectionTtl(transport: V1Transport, params: Readonly<Record<string, string>>, options?: V1RequestOptions): Promise<V1CollectionTtl>;
 /** Public database catalog operations, bound to the transport's authorized project. */
 export class V1Databases {
     /** @param {V1Transport} transport */
@@ -86,6 +92,12 @@ export type V1CollectionSchema = {
     readonly schema: JsonObject | boolean | null;
     readonly dialect?: string | null | undefined;
 };
+/**
+ * The expiry member, or null when documents never expire.
+ */
+export type V1CollectionTtl = {
+    readonly path: string | null;
+};
 import type { V1Transport } from "./transport.js";
 import type { V1RequestOptions } from "./terrabase-v1.js";
 import type { JsonInputObject } from "./json.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,6 +9,7 @@
  * @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.
  */
 /**
  * The result of a document write.
@@ -97,6 +98,10 @@ export type V1Document = {
      * Live versions and tombstones on a causal conflict.
      */
     siblings?: readonly JsonValue[];
+    /**
+     * Distance to the query vector; present only on `near` query results.
+     */
+    distance?: 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;