@terrascale/sdk 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.0.6 — relational SQL
+
+`db.execute(sql, args)`, `db.query(sql, args)` and `db.batch(statements)` call
+TerraBase's `POST /v1/projects/{project}/databases/{database}/sql/execute`.
+Each request is one transaction. Results are typed
+`{ columns, rows, rowsAffected, lastInsertRowid }`; a refused statement throws
+`SqlError` (a `TerraBaseV1Error`) with `statement` and `sqliteCode`. The
+read-only `db.sql` route is unchanged.
+
+## Unreleased — collection TTL and vector near sort
+
+`collection.putTtl(path)`, `getTtl()` and `deleteTtl()` call
+`PUT/GET/DELETE .../collections/{collection}/ttl` and return `{ path }`
+(`null` when unset). `query({ sort: [{ near: { path, vector, metric } }] })`
+sorts by vector distance and each item carries `distance`.
+
+## Unreleased — database export
+
+`db.export({ after, signal })` streams TerraBase's
+`GET /v1/projects/{project}/databases/{database}/export` NDJSON as an async
+iterable of `{ collection, id, document }`. `after: { collection, id }` resumes
+after that document. Error answers raise the usual `TerraBaseV1Error`.
+
 ## 0.0.4
 
 Publishes current main, including `db.sql`, `db.changes`, backups, indexes and

package/README.md

@@ -108,9 +108,12 @@ OpenAPI and immutable release qualification remain open gates.
 | --- | --- |
 | Documents | `collection.get/put/create/patch/delete/list/query/pages/items` |
 | Collections and declared JSON Schema | `db.collections.create/get/list/drop`; `collection.getSchema/putSchema/deleteSchema` |
+| Collection TTL | `collection.putTtl/getTtl/deleteTtl` |
 | Databases | `client.databases.create/list/get/update/delete/branch` |
-| SQL | `db.sql/checkSql/explainSql` |
+| Relational SQL | `db.execute/query/batch` |
+| Read-only SQL (older) | `db.sql/checkSql/explainSql` |
 | Changes | `db.changes` (SSE async iterator) |
+| Export | `db.export` (NDJSON async iterator) |
 
 Project, collection catalog, and database catalog IDs are canonical uppercase
 26-character ULIDs. `generateId()`, `isValidId()` and `requireId()` retain that
@@ -136,6 +139,21 @@ does not support `lower` paths or query-body `explain`; query number comparisons
 64-bit integer/double arithmetic, even when the SDK preserves exact JSON numbers.
 `ExactDecimal` and bigint serialization require Node.js 22+ or a current browser.
 
+A `near` sort orders by vector distance, nearest first, and adds `distance` to
+each item. It is the only sort key, `metric` is `cosine` (default) or `l2`,
+`limit` is at most 100 and there is one page (no cursor):
+
+```js
+await users.putTtl("/expiresAt"); // getTtl() -> { path: "/expiresAt" }; deleteTtl() clears
+const { items } = await docs.query({
+  sort: [{ near: { path: "/embedding", vector: [0.1, 0.2], metric: "cosine" } }], limit: 10,
+});
+```
+
+A collection TTL deletes documents whose member holds a past RFC 3339 UTC time.
+An hourly home-region sweep does the delete, up to about an hour late; until
+then expired documents stay readable.
+
 `db.transaction()` builds one bounded atomic group across collections in that
 database. It supports document operations, `assert`, `assertAbsent` and
 `assertCount`; assertions examine the state before the group's writes.
@@ -144,6 +162,37 @@ or replay mutations after an uncertain result; this release does not promise
 mutation deduplication. Validation, authentication, authorization and
 precondition failures are not automatically retried.
 
+Relational SQL runs statements on tables created with `CREATE TABLE` (rows
+are documents). `execute` runs one statement, `query` returns its rows as
+objects keyed by column name, and `batch` sends 1 to 256 statements as one
+transaction: all commit or none do. `BEGIN`, `COMMIT` and `ROLLBACK` are
+refused. Arguments are positional (`?`) or named (`:name`, `@name`, `$name`,
+passed without the prefix). Each is `null`, a number, an int64 `bigint`, a
+boolean (stored as 1 or 0) or a string. Reads need `documents:read`; writes and
+DDL also need `documents:write`.
+
+```js
+await db.batch([
+  "CREATE TABLE people (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
+  { sql: "INSERT INTO people (id, name) VALUES (?, ?)", args: [1, "Ada"] },
+  { sql: "INSERT INTO people (id, name) VALUES (:id, :name)", named: { id: 2, name: "Grace" } },
+]);
+const people = await db.query("SELECT id, name FROM people WHERE id > ?", [0]);
+const { columns, rows, rowsAffected, lastInsertRowid } = await db.execute("DELETE FROM people WHERE id = :id", { id: 2 });
+```
+
+A refused statement throws `SqlError`, a `TerraBaseV1Error` that adds
+`statement` (zero-based index) and `sqliteCode` (such as
+`SQLITE_CONSTRAINT_PRIMARYKEY`). Its `code` is `sql_error` (400),
+`forbidden_scope` (403), `sql_conflict` (409) or `sql_too_large` (413).
+Authentication, quota and availability errors keep their usual error classes.
+
+TerraBase sends integers as JSON numbers. A plain JavaScript number cannot hold
+an integer above 2^53 exactly, so the SDK decodes such a value (a row value or
+`lastInsertRowid`) as an `ExactDecimal` that keeps every digit. Convert it with
+`BigInt(String(value))`. Pass large integer arguments as `bigint`.
+
+The older `db.sql` route below is read-only.
 SQL is the producer's bounded read-only subset: `{ matched, truncated, rows }`,
 with row `{ id, value }` and no pagination cursor. `checkSql` returns `ok: false`
 for invalid SQL; `explainSql` returns an HTTP error for invalid SQL. All three
@@ -169,6 +218,18 @@ errors, denials, expired history (410) and overload (429) propagate. The SDK
 never silently resets to `now` or broadens the view. Iterator `return()` also
 interrupts an already pending read.
 
+`db.export()` streams every live document as `{ collection, id, document }`,
+in collection then id order, from one read snapshot (`documents:read`). Lines
+are parsed as they arrive. A stream that ends inside a line throws; resume with
+the last whole document received, which reads a new snapshot:
+
+```js
+let last;
+for await (const row of db.export({ after: last, signal: controller.signal })) {
+  last = { collection: row.collection, id: row.id };
+}
+```
+
 The exported collection `shape()` remains compatible with the historical
 `6cb9745…` release. Its route is absent from the audited current server source;
 do not use it as current producer evidence. SSE changes are a separate database

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",

package/sdk-public-v1-route-manifest.json

@@ -45,6 +45,10 @@
     {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/shape","operation":"getShape","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200,307],"responseMediaType":"application/json","source":"src/TerraBase/Features/Shapes/GetShapeEndpoint.cs","request":"none"},
     {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/shape/keys","operation":"getShapeKey","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Shapes/GetShapeKeyEndpoint.cs","request":"none"},
     {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/shape/manifest","operation":"getShapeManifest","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Shapes/GetShapeManifestEndpoint.cs","request":"none"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/ttl","operation":"deleteCollectionTtl","scopes":["documents:write"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/DeleteCollectionTtlEndpoint.cs","request":"none","producerChange":"TerraScale/terrascale#416"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/ttl","operation":"getCollectionTtl","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/GetCollectionTtlEndpoint.cs","request":"none","producerChange":"TerraScale/terrascale#416"},
+    {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/ttl","operation":"putCollectionTtl","scopes":["documents:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/PutCollectionTtlEndpoint.cs","request":"CollectionTtlBody","producerChange":"TerraScale/terrascale#416"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/export","operation":"exportDatabase","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/x-ndjson","source":"src/TerraBase/Features/Documents/ExportDatabaseEndpoint.cs","request":"none","producerChange":"TerraScale/terrascale#412"},
     {"method":"GET","path":"/v1/projects/{project}/databases/{database}/import","operation":"getImport","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Import/GetImportEndpoint.cs","request":"none"},
     {"method":"PATCH","path":"/v1/projects/{project}/databases/{database}/import","operation":"updateImport","scopes":["databases:write","documents:write"],"requestMediaTypes":["application/json"],"statuses":[202],"responseMediaType":"application/json","source":"src/TerraBase/Features/Import/UpdateImportEndpoint.cs","request":"UpdateImportRequest"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/import","operation":"createImport","scopes":["databases:write","documents:write"],"requestMediaTypes":["application/json"],"statuses":[200,201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Import/CreateImportEndpoint.cs","request":"CreateImportRequest"},
@@ -67,6 +71,7 @@
     {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/schema/{collection}","operation":"declareCollectionSchema","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Schema/PutCollectionSchemaEndpoint.cs","request":"UniqueSchemaRequest"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql","operation":"runSql","scopes":["databases:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/RunSqlEndpoint.cs","request":"SqlRequest"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql/check","operation":"checkSql","scopes":["databases:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/CheckSqlEndpoint.cs","request":"SqlRequest"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql/execute","operation":"executeSql","scopes":["documents:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Sql/SqlExecuteEndpoint.cs","request":"SqlExecuteRequest","producerChange":"TerraScale/terrascale#420"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/sql/explain","operation":"explainSql","scopes":["databases:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/ExplainSqlEndpoint.cs","request":"SqlRequest"},
     {"method":"POST","path":"/v1/projects/{project}/databases/{database}/transactions","operation":"runTransaction","scopes":["documents:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/TransactionEndpoint.cs","request":"TransactionRequest"},
     {"method":"GET","path":"/v1/projects/{project}/databases/{database}/usage","operation":"getDatabaseUsage","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetDatabaseUsageEndpoint.cs","request":"none"},
@@ -76,6 +81,10 @@
     {"method":"DELETE","path":"/v1/projects/{project}/saved-queries/{query}","operation":"deleteSavedQuery","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[204],"responseMediaType":"","source":"src/TerraBase/Features/Management/Queries/DeleteSavedQueryEndpoint.cs","request":"none"},
     {"method":"GET","path":"/v1/projects/{project}/saved-queries/{query}","operation":"getSavedQuery","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/GetSavedQueryEndpoint.cs","request":"none"},
     {"method":"PUT","path":"/v1/projects/{project}/saved-queries/{query}","operation":"updateSavedQuery","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/UpdateSavedQueryEndpoint.cs","request":"SavedQueryRequest"},
-    {"method":"GET","path":"/v1/projects/{project}/usage","operation":"getProjectUsage","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetProjectUsageEndpoint.cs","request":"none"}
+    {"method":"GET","path":"/v1/projects/{project}/usage","operation":"getProjectUsage","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetProjectUsageEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks","operation":"createChangeWebhook","scopes":["documents:read","documents:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","contract":"contracts/change-webhooks.md","request":"CreateWebhookRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks","operation":"listChangeWebhooks","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","contract":"contracts/change-webhooks.md","request":"none"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks/{webhook}","operation":"deleteChangeWebhook","scopes":["documents:read","documents:write"],"requestMediaTypes":[],"statuses":[204],"responseMediaType":"","contract":"contracts/change-webhooks.md","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks/{webhook}/deliveries","operation":"listChangeWebhookDeliveries","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","contract":"contracts/change-webhooks.md","request":"none"}
   ]
 }

package/src/index.js

@@ -15,6 +15,7 @@ export {
   V1InvalidKeyError,
   V1ForbiddenScopeError,
   V1NotFoundError,
+  SqlError,
   V1ErrorCode,
   isTerraBaseV1Error,
 } from "./v1/errors.js";
@@ -28,6 +29,7 @@ export { generateId, isValidId, requireId } from "./ids.js";
 export { ExactDecimal } from "./v1/json.js";
 
 /** @typedef {import("./v1/transport.js").TerraBaseV1ClientConfig} TerraBaseV1ClientConfig */
+/** @typedef {import("./v1/transport.js").V1TokenProvider} V1TokenProvider */
 /** @typedef {import("./v1/terrabase-v1.js").V1RequestOptions} V1RequestOptions */
 /** @typedef {import("./v1/terrabase-v1.js").V1ReadOptions} V1ReadOptions */
 /** @typedef {import("./v1/terrabase-v1.js").V1WriteOptions} V1WriteOptions */
@@ -36,6 +38,7 @@ export { ExactDecimal } from "./v1/json.js";
 /** @typedef {import("./v1/terrabase-v1.js").V1PatchOp} V1PatchOp */
 /** @typedef {import("./v1/terrabase-v1.js").V1Patch} V1Patch */
 /** @typedef {import("./v1/terrabase-v1.js").V1SortKey} V1SortKey */
+/** @typedef {import("./v1/terrabase-v1.js").V1NearSortKey} V1NearSortKey */
 /** @typedef {import("./v1/terrabase-v1.js").V1Query} V1Query */
 /** @typedef {import("./v1/terrabase-v1.js").V1Count} V1Count */
 /** @typedef {import("./v1/terrabase-v1.js").V1QueryPage} V1QueryPage */
@@ -74,9 +77,17 @@ export { V1SavedQueries } from "./v1/saved-queries.js";
 /** @typedef {import("./v1/sql.js").V1SqlResult} V1SqlResult */
 /** @typedef {import("./v1/sql.js").V1SqlIndexSuggestion} V1SqlIndexSuggestion */
 /** @typedef {import("./v1/sql.js").V1SqlCheck} V1SqlCheck */
+/** @typedef {import("./v1/sql-execute.js").V1SqlArgument} V1SqlArgument */
+/** @typedef {import("./v1/sql-execute.js").V1SqlArguments} V1SqlArguments */
+/** @typedef {import("./v1/sql-execute.js").V1SqlStatement} V1SqlStatement */
+/** @typedef {import("./v1/sql-execute.js").V1SqlValue} V1SqlValue */
+/** @typedef {import("./v1/sql-execute.js").V1SqlColumn} V1SqlColumn */
+/** @typedef {import("./v1/sql-execute.js").V1SqlExecuteResult} V1SqlExecuteResult */
 /** @typedef {import("./v1/changes.js").V1ChangeStreamRequest} V1ChangeStreamRequest */
 /** @typedef {import("./v1/changes.js").V1DatabaseChange} V1DatabaseChange */
 /** @typedef {import("./v1/changes.js").V1DatabaseChangeCursor} V1DatabaseChangeCursor */
+/** @typedef {import("./v1/export.js").V1ExportOptions} V1ExportOptions */
+/** @typedef {import("./v1/export.js").V1ExportedDocument} V1ExportedDocument */
 /** @typedef {import("./v1/catalog.js").V1ManagedDatabase} V1ManagedDatabase */
 /** @typedef {import("./v1/catalog.js").V1DatabaseCreateRequest} V1DatabaseCreateRequest */
 /** @typedef {import("./v1/catalog.js").V1DatabaseUpdateRequest} V1DatabaseUpdateRequest */
@@ -84,6 +95,7 @@ export { V1SavedQueries } from "./v1/saved-queries.js";
 /** @typedef {import("./v1/catalog.js").V1DatabaseListRequest} V1DatabaseListRequest */
 /** @typedef {import("./v1/catalog.js").V1DatabasePage} V1DatabasePage */
 /** @typedef {import("./v1/catalog.js").V1CollectionSchema} V1CollectionSchema */
+/** @typedef {import("./v1/catalog.js").V1CollectionTtl} V1CollectionTtl */
 
 export { V1DatabaseSchemaClient } from "./v1/database-schema.js";
 /** @typedef {import("./v1/database-schema.js").V1InferredSchema} V1InferredSchema */
@@ -109,6 +121,11 @@ export { V1ProjectUsageClient, V1DatabaseUsageClient } from "./v1/usage.js";
 /** @typedef {import("./v1/usage.js").V1AnalyticsRequest} V1AnalyticsRequest */
 
 export { V1Backups, V1BackupDestinationClient } from "./v1/backups.js";
+export { V1ChangeWebhooks } from "./v1/change-webhooks.js";
+/** @typedef {import("./v1/change-webhooks.js").V1ChangeWebhook} V1ChangeWebhook */
+/** @typedef {import("./v1/change-webhooks.js").V1CreatedChangeWebhook} V1CreatedChangeWebhook */
+/** @typedef {import("./v1/change-webhooks.js").V1ChangeWebhookDelivery} V1ChangeWebhookDelivery */
+/** @typedef {import("./v1/change-webhooks.js").V1ChangeWebhookListRequest} V1ChangeWebhookListRequest */
 /** @typedef {import("./v1/backups.js").V1Backup} V1Backup */
 /** @typedef {import("./v1/backups.js").V1BackupPage} V1BackupPage */
 /** @typedef {import("./v1/backups.js").V1BackupPolicy} V1BackupPolicy */

package/src/v1/catalog.js

@@ -1,6 +1,7 @@
 import { requireId } from "../ids.js";
 import { array, malformed, object, string } from "./decode.js";
 import { requireName } from "./ids.js";
+import { isJsonPointer } from "./filter.js";
 import { isJsonObject, stringifyExactJson } from "./json.js";
 /**
  * @import { JsonInputObject, JsonObject, JsonValue } from "./json.js"
@@ -26,6 +27,7 @@ import { isJsonObject, stringifyExactJson } from "./json.js";
 /** @typedef {{ readonly after?: string | undefined; readonly limit?: number | undefined }} V1DatabaseListRequest */
 /** @typedef {{ readonly items: readonly V1ManagedDatabase[]; readonly next: string | null }} V1DatabasePage */
 /** @typedef {{ readonly schema: JsonObject | boolean | null; readonly dialect?: string | null | undefined }} V1CollectionSchema */
+/** The expiry member, or null when documents never expire. @typedef {{ readonly path: string | null }} V1CollectionTtl */
 
 /** @param {unknown} value @param {readonly string[]} allowed @returns {void} */
 function members(value, allowed) {
@@ -208,3 +210,31 @@ export async function deleteCollectionSchema(transport, params, options = {}) {
   mutationOptions(options);
   return collectionSchema((await transport.call("deleteCollectionSchema", params, { signal: options.signal })).value);
 }
+
+/** @param {JsonValue | undefined} value @returns {V1CollectionTtl} */
+function collectionTtl(value) {
+  const path = object(value, "collection TTL").path;
+  if (path !== null && typeof path !== "string") malformed("TTL path");
+  return Object.freeze({ path });
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export async function getCollectionTtl(transport, params, options = {}) {
+  return collectionTtl((await transport.call("getCollectionTtl", params, { signal: options.signal })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {string} path @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export async function putCollectionTtl(transport, params, path, options = {}) {
+  mutationOptions(options);
+  if (!isJsonPointer(path))
+    throw new TypeError("A TTL path is a JSON Pointer of 1 to 16 object members.");
+  return collectionTtl((await transport.call("putCollectionTtl", params, {
+    body: stringifyExactJson({ path }, "collection TTL"), signal: options.signal,
+  })).value);
+}
+
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @param {V1RequestOptions} [options] @returns {Promise<V1CollectionTtl>} */
+export async function deleteCollectionTtl(transport, params, options = {}) {
+  mutationOptions(options);
+  return collectionTtl((await transport.call("deleteCollectionTtl", params, { signal: options.signal })).value);
+}

package/src/v1/change-webhooks.js

@@ -0,0 +1,78 @@
+import { requireId } from "../ids.js";
+import { requireName } from "./ids.js";
+import { object, string } from "./decode.js";
+import { list, nullable, numeric, record, text } from "./management-decode.js";
+import { members, mutationOptions, pageQuery } from "./management-validation.js";
+import { stringifyExactJson } from "./json.js";
+/** @import { V1Transport } from "./transport.js" */
+/** @import { V1RequestOptions } from "./terrabase-v1.js" */
+const webhook = record({ id: requireId, url: text, createdAt: text, status: text });
+const webhooks = list(webhook);
+const deliveries = list(record({ id: requireId, createdAt: text, status: text, attempts: numeric,
+  lastAttemptAt: nullable(text), nextAttemptAt: nullable(text), httpStatus: nullable(numeric), errorCode: nullable(text) }));
+/** @typedef {ReturnType<typeof webhook>} V1ChangeWebhook */
+/** @typedef {V1ChangeWebhook & { readonly secret: string }} V1CreatedChangeWebhook */
+/** @typedef {ReturnType<typeof deliveries>[number]} V1ChangeWebhookDelivery */
+/** @typedef {{ readonly after?: string; readonly limit?: number }} V1ChangeWebhookListRequest */
+
+/** @param {V1ChangeWebhookListRequest} request */
+function query(request) {
+  if (request.after !== undefined) requireId(request.after, "after");
+  return pageQuery(request);
+}
+
+/** Collection change webhook registration and sanitized delivery history. Requests are never replayed. */
+export class V1ChangeWebhooks {
+  /** @type {V1Transport} */
+  #transport;
+  /** @type {{database: string; collection: string}} */
+  #params;
+  /** @param {V1Transport} transport @param {string} database @param {string} collection */
+  constructor(transport, database, collection) {
+    this.#transport = transport;
+    this.#params = { database: requireName("database", database), collection: requireName("collection", collection) };
+    Object.freeze(this);
+  }
+  /**
+   * 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>}
+   */
+  async create(request, options = {}) {
+    members(request, ["url"]);
+    if (typeof request.url !== "string" || request.url.length > 2048) throw new TypeError("Webhook URL must be an HTTPS URL of at most 2048 characters.");
+    let url;
+    try { url = new URL(request.url); } catch { throw new TypeError("Webhook URL must be absolute HTTPS."); }
+    if (url.protocol !== "https:" || url.port !== "" || url.username !== "" || url.password !== "" || url.hash !== "")
+      throw new TypeError("Webhook URL must be HTTPS on port 443, without credentials or a fragment.");
+    mutationOptions(options);
+    const raw = object((await this.#transport.call("createChangeWebhook", this.#params, {
+      body: stringifyExactJson(request, "change webhook"), signal: options.signal,
+    })).value, "created webhook");
+    const secret = string(raw.secret, "webhook secret");
+    return Object.freeze(Object.defineProperty({ ...webhook(raw), secret }, "secret", { enumerable: false }));
+  }
+  /**
+   * 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[]>}
+   */
+  async list(request = {}, options = {}) {
+    return webhooks((await this.#transport.call("listChangeWebhooks", this.#params, { query: query(request), signal: options.signal })).value);
+  }
+  /**
+   * 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>}
+   */
+  async delete(id, options = {}) {
+    mutationOptions(options);
+    await this.#transport.call("deleteChangeWebhook", { ...this.#params, webhook: requireId(id) }, { signal: options.signal });
+  }
+  /**
+   * 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[]>}
+   */
+  async deliveries(id, request = {}, options = {}) {
+    return deliveries((await this.#transport.call("listChangeWebhookDeliveries", { ...this.#params, webhook: requireId(id) },
+      { query: query(request), signal: options.signal })).value);
+  }
+}

package/src/v1/decode.js

@@ -13,6 +13,7 @@ import { isJsonObject } from "./json.js";
  * @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.
  */
 
 /**

package/src/v1/errors.js

@@ -76,6 +76,7 @@ export const V1ErrorCode = Object.freeze({
   mustRefetch: "must_refetch", preconditionFailed: "precondition_failed", payloadTooLarge: "payload_too_large",
   unsupportedMediaType: "unsupported_media_type", uriTooLong: "uri_too_long", shapeBusy: "shape_busy",
   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. */
@@ -114,11 +115,36 @@ 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 {
+  /** @type {number} Zero-based index of the failing statement. */
+  statement;
+  /** @type {string | undefined} The SQLite error code, such as `SQLITE_CONSTRAINT_PRIMARYKEY`. */
+  sqliteCode;
+
+  /** @param {TerraBaseV1ErrorInit & { statement: number; sqliteCode?: string | undefined }} init */
+  constructor(init) {
+    super(init);
+    this.name = "SqlError";
+    this.statement = init.statement;
+    this.sqliteCode = init.sqliteCode;
+  }
+}
+
 /**
  * @param {TerraBaseV1ErrorInit} init
  * @returns {TerraBaseV1Error}
  */
 function typedError(init) {
+  // Only the SQL execute route reports a statement index.
+  const statement = init.details?.statement;
+  if (typeof statement === "number" && Number.isInteger(statement) && statement >= 0) {
+    const sqliteCode = init.details?.sqlite_code;
+    return new SqlError({ ...init, statement, sqliteCode: typeof sqliteCode === "string" ? sqliteCode : undefined });
+  }
   switch (init.code) {
     case "precondition_failed": return new V1PreconditionFailedError(init);
     case "invalid_key": return new V1InvalidKeyError(init);

package/src/v1/export.js

@@ -0,0 +1,68 @@
+import { documentObject, malformed, object } from "./decode.js";
+import { requireDocumentId, requireName } from "./ids.js";
+import { parseExactJson } from "./json.js";
+import { BodyTransportError } from "./transport.js";
+/** @import { JsonObject } from "./json.js" */
+/** @import { V1Transport } from "./transport.js" */
+
+/** @typedef {{ readonly collection: string; readonly id: string; readonly document: JsonObject }} V1ExportedDocument */
+/**
+ * @typedef {object} V1ExportOptions
+ * @property {{ readonly collection: string; readonly id: string } | undefined} [after] Resume after this document; the resumed part reads a new snapshot.
+ * @property {AbortSignal | undefined} [signal]
+ */
+
+// A 1 MiB document may require six characters per character when JSON escapes it.
+const maximumLineLength = 8 * 1024 * 1024;
+
+/** @param {string} line @returns {V1ExportedDocument} */
+function decodeLine(line) {
+  /** @type {import("./json.js").JsonValue} */
+  let value;
+  try { value = parseExactJson(line); }
+  catch { malformed("export line JSON"); }
+  const raw = object(value, "export line");
+  return Object.freeze({ collection: requireName("collection", raw.collection), id: requireDocumentId(raw.id), document: documentObject(raw.document) });
+}
+
+/**
+ * Streams every live document of a database as NDJSON, in collection then id order, from one read snapshot.
+ * A stream that ends inside a line is incomplete and throws; resume with `after` set to the last document received.
+ * @param {V1Transport} transport
+ * @param {string} database
+ * @param {V1ExportOptions} [options]
+ * @returns {AsyncGenerator<V1ExportedDocument, void, undefined>}
+ */
+export async function* exportDocuments(transport, database, options = {}) {
+  const { after, signal } = options;
+  const query = new URLSearchParams();
+  if (after !== undefined) {
+    if (typeof after !== "object" || after === null) throw new TypeError("export after is { collection, id }.");
+    query.set("after_collection", requireName("collection", after.collection));
+    query.set("after_id", requireDocumentId(after.id));
+  }
+  const response = await transport.openStream("exportDatabase", { database }, { query, signal });
+  const body = /** @type {ReadableStream<Uint8Array>} */ (response.body);
+  const decoder = /** @type {ReadableWritablePair<string, Uint8Array>} */ (new TextDecoderStream("utf-8", { fatal: true, ignoreBOM: true }));
+  const reader = body.pipeThrough(decoder).getReader();
+  let pending = "";
+  try {
+    while (true) {
+      /** @type {ReadableStreamReadResult<string>} */
+      let part;
+      try { part = await reader.read(); }
+      catch (error) { signal?.throwIfAborted(); throw new BodyTransportError(error); }
+      if (part.done) break;
+      // Split only the new text so a long line arriving in many chunks is scanned once.
+      const lines = part.value.split("\n");
+      lines[0] = pending + lines[0];
+      pending = /** @type {string} */ (lines.pop());
+      if (pending.length > maximumLineLength) malformed("export line exceeding 8 MiB");
+      for (const line of lines) yield decodeLine(line);
+    }
+    if (pending !== "") malformed("incomplete export line");
+  } finally {
+    await reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}

package/src/v1/management-routes.js

@@ -1,8 +1,20 @@
-/** @typedef {"getShapeManifest" | "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"} ManagementOperation */
+/** @typedef {"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"} ManagementOperation */
+const webhooks = "/v1/projects/{project}/databases/{database}/collections/{collection}/webhooks";
 const saved = "/v1/projects/{project}/saved-queries";
+const ttl = "/v1/projects/{project}/databases/{database}/collections/{collection}/ttl";
 /** @type {readonly import("./routes.js").V1Route[]} */
 export const managementV1Routes = Object.freeze([
+  route("createChangeWebhook", "POST", webhooks, 201),
+  route("listChangeWebhooks", "GET", webhooks),
+  route("deleteChangeWebhook", "DELETE", `${webhooks}/{webhook}`, 204),
+  route("listChangeWebhookDeliveries", "GET", `${webhooks}/{webhook}/deliveries`),
   route("getShapeManifest", "GET", "/v1/projects/{project}/databases/{database}/collections/{collection}/shape/manifest"),
+  route("exportDatabase", "GET", "/v1/projects/{project}/databases/{database}/export"),
+  // Reads need documents:read; writes and DDL also need documents:write, checked per statement.
+  route("executeSql", "POST", "/v1/projects/{project}/databases/{database}/sql/execute"),
+  route("putCollectionTtl", "PUT", ttl),
+  route("getCollectionTtl", "GET", ttl),
+  route("deleteCollectionTtl", "DELETE", ttl),
   route("healthz", "GET", "/healthz"),
   route("readyz", "GET", "/readyz"),
   route("backupz", "GET", "/backupz"),
@@ -56,12 +68,13 @@ export const managementV1Routes = Object.freeze([
 /** @param {ManagementOperation} operation @param {import("./routes.js").V1Route["method"]} method @param {string} pathTemplate @param {number} [status] @returns {import("./routes.js").V1Route} */
 function route(operation, method, pathTemplate, status = 200) {
   const write = method !== "GET" && operation !== "planPointInTime";
+  const webhook = pathTemplate.startsWith(webhooks);
   const noBody = ["createBackup", "applyIndexRecommendation", "cancelImport", "resumeImport"].includes(operation);
   return Object.freeze({ operation, method, pathTemplate,
-    permission: operation === "getShapeManifest" ? "documents:read" : pathTemplate.startsWith("/v1/platform/") ? "platform-admin" : !pathTemplate.startsWith("/v1/") ? "anonymous" : write ? "databases:write" : "databases:read",
-    additionalPermissions: Object.freeze(["createImport", "uploadImportSource", "updateImport", "startImport", "resumeImport"].includes(operation) ? ["documents:write"] : []),
+    permission: webhook ? write ? "documents:write" : "documents:read" : operation === "getShapeManifest" || operation === "exportDatabase" || operation === "executeSql" || operation === "getCollectionTtl" ? "documents:read" : pathTemplate === ttl ? "documents:write" : pathTemplate.startsWith("/v1/platform/") ? "platform-admin" : !pathTemplate.startsWith("/v1/") ? "anonymous" : write ? "databases:write" : "databases:read",
+    additionalPermissions: Object.freeze(webhook && write ? ["documents:read"] : ["createImport", "uploadImportSource", "updateImport", "startImport", "resumeImport"].includes(operation) ? ["documents:write"] : []),
     requestMediaTypes: Object.freeze(noBody ? [] : operation === "uploadImportSource" ? ["application/octet-stream"] : method === "POST" || method === "PUT" || method === "PATCH" ? ["application/json"] : []),
-    responseMediaType: status === 204 ? "" : "application/json", successStatuses: Object.freeze(operation === "readyz" || operation === "backupz" ? [200, 503] : operation === "applyIndexRecommendation" || operation === "createImport" ? [200, 201] : [status]),
-    idempotencyKey: "none", replaySafe: !write, contract: "docs/terrabase/api.md", contractText: Object.freeze([]),
+    responseMediaType: status === 204 ? "" : operation === "exportDatabase" ? "application/x-ndjson" : "application/json", successStatuses: Object.freeze(operation === "readyz" || operation === "backupz" ? [200, 503] : operation === "applyIndexRecommendation" || operation === "createImport" ? [200, 201] : [status]),
+    idempotencyKey: "none", replaySafe: !write, contract: webhook ? "docs/terrabase/change-webhooks.md" : "docs/terrabase/api.md", contractText: Object.freeze([]),
   });
 }

package/src/v1/shape-reader.js

@@ -9,7 +9,7 @@ import { TerraBaseV1Error } from "./errors.js";
 /** @import { V1ShapeRequest, V1ShapePage } from "./shapes.js" */
 /** @typedef {{handle: string; offset: string; epoch: string; keyId: string}} V1SealedShapePosition */
 /** @typedef {{ latestEpoch: bigint; keys: Map<string, { epoch: bigint; key: Uint8Array }> }} ShapeKeys */
-/** @type {WeakMap<V1Transport, Map<string, ShapeKeys>>} Keys stay scoped to a credential, database and collection. */
+/** @type {WeakMap<V1Transport, Map<string, ShapeKeys>>} Only immutable credentials retain keys across decrypts. */
 const shapeKeys = new WeakMap();
 /** @param {Readonly<Record<string, string>>} params */
 const keyScope = params => JSON.stringify([params.database, params.collection]);
@@ -26,8 +26,10 @@ async function shapeCall(transport, params, operation, options) {
     throw error;
   }
 }
-/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @returns {ShapeKeys} */
+/** @param {V1Transport} transport @param {Readonly<Record<string, string>>} params @returns {ShapeKeys | undefined} */
 function currentKeys(transport, params) {
+  // Callback tokens can change users; authorize every decrypt without retaining their keys.
+  if (transport.hasTokenProvider) return undefined;
   let scopes = shapeKeys.get(transport);
   if (scopes === undefined) { scopes = new Map(); shapeKeys.set(transport, scopes); }
   const scope = keyScope(params);
@@ -152,7 +154,7 @@ export async function readShapePage(transport, params, request, signal, ifNoneMa
   return page;
 }
 /**
- * Reuse process-memory keys for this handle/epoch/KID; fetch misses without HTTP cache reuse.
+ * Reuse keys only for static credentials; callback tokens authorize every decrypt with no-store.
  * @param {V1Transport} transport @param {Readonly<Record<string,string>>} params
  * @param {Uint8Array} bytes @param {V1SealedShapePosition} position @param {AbortSignal | undefined} signal
  * @returns {Promise<V1ShapePage>}
@@ -167,7 +169,7 @@ export async function decryptSealedShapePage(transport, params, bytes, position,
   signal?.throwIfAborted();
   const cache = currentKeys(transport, params);
   const cacheId = JSON.stringify([handle, epoch, keyId]);
-  let raw = cache.keys.get(cacheId)?.key;
+  let raw = cache?.keys.get(cacheId)?.key;
   if (raw === undefined) {
     const query = new URLSearchParams({ handle, epoch, key_id: keyId });
     const response = await shapeCall(transport, params, "getShapeKey", { query, cache: "no-store", signal });
@@ -179,7 +181,7 @@ export async function decryptSealedShapePage(transport, params, bytes, position,
     if (btoa(String.fromCharCode(...raw)).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/u, "") !== encoded) malformed("shape epoch key encoding");
     const servedEpoch = BigInt(epoch);
     const active = currentKeys(transport, params);
-    if (active === cache && servedEpoch >= cache.latestEpoch) {
+    if (cache !== undefined && active === cache && servedEpoch >= cache.latestEpoch) {
       cache.latestEpoch = servedEpoch;
       for (const [id, entry] of cache.keys) if (entry.epoch < servedEpoch) cache.keys.delete(id);
       cache.keys.set(cacheId, { epoch: servedEpoch, key: raw });