@terrascale/sdk 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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,11 @@ 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` |
 | 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 +138,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.
@@ -169,6 +186,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.5",
   "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"},

package/src/index.js

@@ -28,6 +28,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 +37,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 */
@@ -77,6 +79,8 @@ export { V1SavedQueries } from "./v1/saved-queries.js";
 /** @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 +88,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 */

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/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/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,13 @@
-/** @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" | "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"} ManagementOperation */
 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("getShapeManifest", "GET", "/v1/projects/{project}/databases/{database}/collections/{collection}/shape/manifest"),
+  route("exportDatabase", "GET", "/v1/projects/{project}/databases/{database}/export"),
+  route("putCollectionTtl", "PUT", ttl),
+  route("getCollectionTtl", "GET", ttl),
+  route("deleteCollectionTtl", "DELETE", ttl),
   route("healthz", "GET", "/healthz"),
   route("readyz", "GET", "/readyz"),
   route("backupz", "GET", "/backupz"),
@@ -58,10 +63,10 @@ function route(operation, method, pathTemplate, status = 200) {
   const write = method !== "GET" && operation !== "planPointInTime";
   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",
+    permission: operation === "getShapeManifest" || operation === "exportDatabase" || 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(["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]),
+    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: "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 });

package/src/v1/terrabase-v1.js

@@ -12,7 +12,8 @@ import { V1ShapeSubscription } from "./shape-subscription.js";
 import { decryptSealedShapePage, readShapePage, readShapeKey } from "./shape-reader.js";
 import { runSql, checkSql } from "./sql.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";
@@ -58,12 +59,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 +180,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 +215,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 +255,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,
   });
@@ -407,6 +440,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`
@@ -814,6 +856,14 @@ export class V1Database {
   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

@@ -12,6 +12,7 @@ export type V1ShapeDocument = import("./v1/shape-subscription.js").V1ShapeDocume
 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 +21,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;
@@ -57,6 +59,8 @@ export type V1SqlCheck = import("./v1/sql.js").V1SqlCheck;
 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 +68,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;

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

@@ -0,0 +1,26 @@
+/**
+ * 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 function exportDocuments(transport: V1Transport, database: string, options?: V1ExportOptions): AsyncGenerator<V1ExportedDocument, void, undefined>;
+export type V1ExportedDocument = {
+    readonly collection: string;
+    readonly id: string;
+    readonly document: JsonObject;
+};
+export type V1ExportOptions = {
+    /**
+     * Resume after this document; the resumed part reads a new snapshot.
+     */
+    after?: {
+        readonly collection: string;
+        readonly id: string;
+    } | undefined;
+    signal?: AbortSignal | undefined;
+};
+import type { V1Transport } from "./transport.js";
+import type { JsonObject } from "./json.js";

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

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

@@ -9,7 +9,7 @@ export function decodeFreeShapePage(value: import("./json.js").JsonValue | undef
  */
 export function readShapePage(transport: V1Transport, params: Readonly<Record<string, string>>, request: V1ShapeRequest, signal: AbortSignal | undefined, ifNoneMatch?: string | undefined): Promise<V1ShapePage>;
 /**
- * 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>}

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

@@ -82,6 +82,15 @@ export class V1Collection {
     putSchema(schema: import("./json.js").JsonInputObject | boolean, options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionSchema>;
     /** @param {V1RequestOptions} [options] */
     deleteSchema(options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionSchema>;
+    /** @param {V1RequestOptions} [options] */
+    getTtl(options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionTtl>;
+    /**
+     * 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: string, options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionTtl>;
+    /** @param {V1RequestOptions} [options] */
+    deleteTtl(options?: V1RequestOptions): Promise<import("./catalog.js").V1CollectionTtl>;
     /**
      * Iterates over every page, following `nextCursor`. `count`
      * is sent with the first page only.
@@ -286,6 +295,11 @@ export class V1Database {
     explainSql(statement: string, options?: V1RequestOptions): Promise<import("./sql.js").V1SqlCheck>;
     /** @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>;
+    /**
+     * Streams every live document as `{ collection, id, document }`, in collection then id order, from one snapshot.
+     * @param {import("./export.js").V1ExportOptions} [options]
+     */
+    export(options?: import("./export.js").V1ExportOptions): AsyncGenerator<import("./export.js").V1ExportedDocument, void, undefined>;
     #private;
 }
 /**
@@ -385,17 +399,28 @@ export type V1Patch = {
 } | {
     readonly ops: readonly V1PatchOp[];
 };
-export type V1SortKey = {
+export type V1FieldSortKey = {
     readonly path: V1Path;
     readonly order?: "asc" | "desc" | undefined;
 };
+/**
+ * Vector similarity sort, nearest first. It must be the only sort key; limit is at most 100 and there is no cursor.
+ */
+export type V1NearSortKey = {
+    readonly near: {
+        readonly path: V1Path;
+        readonly vector: readonly number[];
+        readonly metric?: "cosine" | "l2" | undefined;
+    };
+};
+export type V1SortKey = V1FieldSortKey | V1NearSortKey;
 /**
  * A query-v1 request. Every member is optional.
  */
 export type V1Query = {
     filter?: V1Filter | null | undefined;
     /**
-     * At most 4 keys; results are finally ordered by `$id`.
+     * At most 4 keys, or one `near` key; results are finally ordered by `$id`.
      */
     sort?: readonly V1SortKey[] | undefined;
     /**

package/types/v1/transport.d.ts

@@ -36,6 +36,8 @@ export class V1Transport {
         project?: undefined;
         endpointResolver?: undefined;
     }));
+    /** Internal credential lifetime metadata; never exposes the bearer value. */
+    get hasTokenProvider(): boolean;
     /**
      * @param {V1Operation} operation
      * @param {Readonly<Record<string, string>>} params
@@ -74,12 +76,12 @@ export class V1Transport {
      */
     call(operation: V1Operation, params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<V1CallResult>;
     /**
-     * @param {"streamDatabaseChanges"} operation
+     * @param {"streamDatabaseChanges" | "exportDatabase"} operation
      * @param {Readonly<Record<string, string>>} params
      * @param {V1CallOptions} [options]
      * @returns {Promise<Response>}
      */
-    openStream(operation: "streamDatabaseChanges", params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<Response>;
+    openStream(operation: "streamDatabaseChanges" | "exportDatabase", params: Readonly<Record<string, string>>, options?: V1CallOptions): Promise<Response>;
     #private;
 }
 /**
@@ -91,6 +93,10 @@ export type V1EndpointContext = {
     readonly signal?: AbortSignal | undefined;
 };
 export type V1EndpointResolver = (context: V1EndpointContext) => string | Promise<string>;
+/**
+ * A fresh access token for each authenticated request, including stream reconnects.
+ */
+export type V1TokenProvider = () => string | Promise<string>;
 /**
  * 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.
@@ -98,9 +104,9 @@ export type V1EndpointResolver = (context: V1EndpointContext) => string | Promis
 export type TerraBaseV1ClientConfig = {
     project: string;
     /**
-     * A ts-auth project access JWT (or a legacy C# tb_ key); held privately.
+     * 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.
      */
-    token: string;
+    token: string | V1TokenProvider;
     baseUrl?: string | undefined;
     endpointResolver?: V1EndpointResolver | undefined;
     fetch?: FetchLike | undefined;