@terrascale/sdk 0.0.3 → 0.0.4

package/src/v1/terrabase-v1.js

@@ -1,13 +1,26 @@
 // The TerraBase v1 client: documents, transactions, queries and shapes over
 // the project-scoped C# Documents API (decision 0004 and shape-reads.md).
 import {
-  array, boolean, decodeDocument, decodeWrite, durability, malformed, object, u64,
+  array, boolean, decodeDocument, decodeWrite, documentObject, durability, malformed, object, u64,
 } from "./decode.js";
+import { requireId } from "../ids.js";
 import { isJsonPointer, requireFilter, requirePath } from "./filter.js";
 import { requireDocumentId, requireName, requireVersion } from "./ids.js";
 import { assertJsonObject, assertJsonValue, ExactDecimal, stringifyExactJson } from "./json.js";
-import { readShape } from "./shapes.js";
+import { readShapeManifest } from "./shape-manifest.js";
+import { V1ShapeSubscription } from "./shape-subscription.js";
+import { decryptSealedShapePage, readShapePage, readShapeKey } from "./shape-reader.js";
+import { runSql, checkSql } from "./sql.js";
+import { streamChanges } from "./changes.js";
+import { V1Databases, getCollectionSchema, putCollectionSchema, deleteCollectionSchema } from "./catalog.js";
 import { V1Transport } from "./transport.js";
+import { V1Health, V1Platform } from "./system.js";
+import { V1Imports } from "./imports.js";
+import { V1Backups, V1BackupDestinationClient } from "./backups.js";
+import { V1ProjectUsageClient, V1DatabaseUsageClient } from "./usage.js";
+import { V1Indexes } from "./indexes.js";
+import { V1DatabaseSchemaClient } from "./database-schema.js";
+import { V1SavedQueries } from "./saved-queries.js";
 /**
  * @import { V1Document, V1Durability, V1WriteResult } from "./decode.js"
  * @import { V1Filter, V1Path } from "./filter.js"
@@ -37,6 +50,7 @@ import { V1Transport } from "./transport.js";
  * @typedef {{ readonly op: "set"; readonly path: string; readonly value: JsonInput }
  *   | { readonly op: "unset"; readonly path: string }
  *   | { readonly op: "inc"; readonly path: string; readonly by: number | bigint | ExactDecimal }
+ *   | { readonly op: "add" | "remove"; readonly path: string; readonly value: import("./filter.js").V1Scalar }
  *   | { readonly op: "append"; readonly path: string; readonly value: JsonInput }} V1PatchOp
  */
 /**
@@ -67,7 +81,7 @@ import { V1Transport } from "./transport.js";
 /**
  * One op's result: `id` and `version` for writes, `asserted` for asserts, and
  * also `count` (decimal u64) for `assertCount`.
- * @typedef {{ readonly id: string; readonly version: string } | { readonly asserted: true; readonly count?: string }} V1TransactionOpResult
+ * @typedef {{ readonly id: string; readonly version: string; readonly document?: import("./json.js").JsonObject } | { readonly asserted: true; readonly count?: string }} V1TransactionOpResult
  */
 /** @typedef {{ readonly gte?: number | undefined; readonly lte?: number | undefined }} V1CountBounds */
 /**
@@ -94,13 +108,14 @@ function pointer(path) {
  */
 function patchOp(op) {
   if (typeof op !== "object" || op === null || Array.isArray(op)) throw new TypeError("A patch op is an object.");
-  if (op.path === "/id" || op.path?.startsWith("/id/")) throw new TypeError("The document key is the entity ID; payloads must not contain an id field.");
-  if (op.path === "" && op.op === "set") assertNoPayloadId(op.value);
   let allowed = ["op", "path", "value"];
   switch (op.op) {
     case "unset": allowed = ["op", "path"]; break;
     case "inc": allowed = ["op", "path", "by"]; break;
   }
+  const path = pointer(op.path);
+  if (["inc", "add", "remove"].includes(op.op) && path.split("/").length !== 2)
+    throw new TypeError("inc, add and remove require a top-level field.");
   for (const key of Object.keys(op)) if (!allowed.includes(key)) throw new TypeError(`Unknown patch op member ${key}.`);
   switch (op.op) {
     case "set":
@@ -109,14 +124,30 @@ function patchOp(op) {
       return { op: op.op, path: pointer(op.path), value: op.value };
     case "unset":
       return { op: "unset", path: pointer(op.path) };
+    case "add":
+    case "remove": {
+      const value = op.value;
+      if (value !== null && typeof value !== "boolean" && typeof value !== "string" &&
+          typeof value !== "number" && typeof value !== "bigint" && !(value instanceof ExactDecimal))
+        throw new TypeError("add and remove require a JSON scalar of at most 1 KiB.");
+      assertJsonValue(value, "set element");
+      if (new TextEncoder().encode(stringifyExactJson(value, "set element")).byteLength > 1024)
+        throw new TypeError("add and remove require a JSON scalar of at most 1 KiB.");
+      return { op: op.op, path, value };
+    }
     case "inc": {
       const by = op.by;
-      if (!(typeof by === "bigint" || by instanceof ExactDecimal || (typeof by === "number" && Number.isFinite(by))))
-        throw new TypeError("inc takes a finite number, bigint or ExactDecimal.");
-      return { op: "inc", path: pointer(op.path), by };
+      if (!(typeof by === "bigint" || by instanceof ExactDecimal || (typeof by === "number" && Number.isSafeInteger(by))))
+        throw new TypeError("inc requires a non-zero signed 64-bit integer.");
+      const text = String(by);
+      if (!/^-?(?:0|[1-9]\d*)$/u.test(text)) throw new TypeError("inc requires an integer JSON literal.");
+      const integer = BigInt(text);
+      if (integer === 0n || integer < -(1n << 63n) || integer >= (1n << 63n))
+        throw new TypeError("inc requires a non-zero signed 64-bit integer.");
+      return { op: "inc", path, by };
     }
     default:
-      throw new TypeError("Patch ops are set, unset, inc or append.");
+      throw new TypeError("Patch ops are set, unset, inc, append, add or remove.");
   }
 }
 
@@ -135,7 +166,6 @@ function normalizePatch(patch) {
   if (hasMerge) {
     const merge = /** @type {{ readonly merge: JsonInputObject }} */ (patch).merge;
     assertJsonObject(merge, "merge patch");
-    assertNoPayloadId(merge);
     return { merge };
   }
   const ops = /** @type {{ readonly ops: readonly V1PatchOp[] }} */ (patch).ops;
@@ -187,7 +217,7 @@ function encodeQuery(query) {
  * @param {JsonValue | undefined} value
  * @returns {V1QueryPage}
  */
-function decodeQueryPage(value) {
+export function decodeQueryPage(value) {
   const raw = object(value, "query response");
   const next = raw.next_cursor;
   if (next !== null && (typeof next !== "string" || next === "")) malformed("next_cursor");
@@ -231,18 +261,11 @@ function rejectIdempotency(options) {
 /** @param {JsonInputObject} document @returns {string} */
 function encodeDocument(document) {
   assertJsonObject(document, "document");
-  assertNoPayloadId(document);
   const body = stringifyExactJson(document, "document");
   if (new TextEncoder().encode(body).byteLength > 1024 * 1024) throw new TypeError("A document is at most 1 MiB.");
   return body;
 }
 
-/** @param {unknown} document @returns {void} */
-function assertNoPayloadId(document) {
-  if (typeof document === "object" && document !== null && Object.hasOwn(document, "id"))
-    throw new TypeError("The document key is the entity ID; payloads must not contain an id field.");
-}
-
 /** A collection handle by name. It performs no I/O until an operation runs. */
 export class V1Collection {
   /** @type {V1Transport} */
@@ -362,6 +385,29 @@ export class V1Collection {
     return decodeQueryPage(response.value);
   }
 
+  /** @param {{ readonly limit?: number | undefined; readonly cursor?: string | undefined }} [request] @param {V1RequestOptions} [options] @returns {Promise<V1QueryPage>} */
+  async list(request = {}, options = {}) {
+    for (const key of Object.keys(request)) if (key !== "limit" && key !== "cursor") throw new TypeError(`Unknown document list member ${key}.`);
+    const query = new URLSearchParams();
+    if (request.limit !== undefined) {
+      if (!Number.isInteger(request.limit) || request.limit < 1 || request.limit > 1000) throw new TypeError("Document list limit is 1-1000.");
+      query.set("limit", String(request.limit));
+    }
+    if (request.cursor !== undefined) {
+      if (typeof request.cursor !== "string" || request.cursor === "") throw new TypeError("Document cursor is a non-empty string.");
+      query.set("cursor", request.cursor);
+    }
+    const response = await this.#transport.call("listDocuments", this.#params, { query, signal: options.signal });
+    return decodeQueryPage(response.value);
+  }
+
+  /** @param {V1RequestOptions} [options] */
+  getSchema(options = {}) { return getCollectionSchema(this.#transport, this.#params, options); }
+  /** @param {import("./json.js").JsonInputObject | boolean} schema @param {V1RequestOptions} [options] */
+  putSchema(schema, options = {}) { return putCollectionSchema(this.#transport, this.#params, schema, options); }
+  /** @param {V1RequestOptions} [options] */
+  deleteSchema(options = {}) { return deleteCollectionSchema(this.#transport, this.#params, options); }
+
   /**
    * Iterates over every page, following `nextCursor`. `count`
    * is sent with the first page only.
@@ -372,9 +418,13 @@ export class V1Collection {
   async *pages(query = {}, options = {}) {
     /** @type {V1Query} */
     let current = query;
+    const cursors = new Set(query.cursor == null ? [] : [query.cursor]);
     while (true) {
       const page = await this.query(current, options);
+      if (page.nextCursor !== null && cursors.has(page.nextCursor)) malformed("repeated pagination cursor");
+      if (page.nextCursor !== null) cursors.add(page.nextCursor);
       yield page;
+      options.signal?.throwIfAborted();
       if (page.nextCursor === null) return;
       const { count: _count, ...rest } = current;
       current = { ...rest, cursor: page.nextCursor };
@@ -388,17 +438,51 @@ export class V1Collection {
    * @returns {AsyncGenerator<V1Document, void, undefined>}
    */
   async *items(query = {}, options = {}) {
-    for await (const page of this.pages(query, options)) yield* page.items;
+    for await (const page of this.pages(query, options)) {
+      for (const item of page.items) {
+        options.signal?.throwIfAborted();
+        yield item;
+      }
+    }
   }
   /**
    * Reads one C# shape snapshot page or change-log chunk. Bootstrap defaults to offset -1.
    * Echo handle, nextOffset and cursor on the following read; discard state on must_refetch.
+   * ifNoneMatch sends a complete entity-tag list or *; 304 throws not_modified with cache headers.
    * @param {V1ShapeRequest} [request]
-   * @param {V1RequestOptions} [options]
+   * @param {V1RequestOptions & {readonly ifNoneMatch?: string}} [options]
    * @returns {Promise<V1ShapePage>}
    */
   shape(request = {}, options = {}) {
-    return readShape(this.#transport, this.#params, request, options.signal);
+    return readShapePage(this.#transport, this.#params, request, options.signal, options.ifNoneMatch);
+  }
+
+  /**
+   * Subscribe to the free-read v1 protocol. Stop with close() or the request signal.
+   * @param {{where?: V1Filter | undefined}} [request]
+   * @param {import("./shape-subscription.js").V1ShapeSubscribeOptions} [options]
+   * @returns {V1ShapeSubscription}
+   */
+  subscribeShape(request = {}, options = {}) {
+    return new V1ShapeSubscription(this.#transport, this.#params, request, options);
+  }
+
+  /** @param {import("./shape-manifest.js").V1ShapeManifestRequest} request @param {V1RequestOptions} [options] */
+  shapeManifest(request, options = {}) { return readShapeManifest(this.#transport, this.#params, request, options.signal); }
+  /** @param {import("./shape-reader.js").V1ShapeKeyRequest} request @param {V1RequestOptions} [options] */
+  shapeKey(request, options = {}) { return readShapeKey(this.#transport, this.#params, request, options.signal); }
+
+
+  /**
+   * Verify a complete TBS1 object using its authenticated epoch key. Applies no state.
+   * Object delivery through manifests is pending the producer's FR-22 contract.
+   * @param {Uint8Array} bytes
+   * @param {import("./shape-reader.js").V1SealedShapePosition} position
+   * @param {V1RequestOptions} [options]
+   * @returns {Promise<V1ShapePage>}
+   */
+  decryptShapeObject(bytes, position, options = {}) {
+    return decryptSealedShapePage(this.#transport, this.#params, bytes, position, options.signal);
   }
 
 }
@@ -457,7 +541,7 @@ export class V1Transaction {
   static #precondition(precondition, allowNoneMatch) {
     if (precondition === undefined) return {};
     if ("ifMatch" in precondition && !("ifNoneMatchAny" in precondition))
-      return { if_match: precondition.ifMatch === "*" ? "*" : requireVersion(precondition.ifMatch) };
+      return { if_match: precondition.ifMatch === "*" ? "*" : `"${requireVersion(precondition.ifMatch)}"` };
     if ("ifNoneMatchAny" in precondition && precondition.ifNoneMatchAny === true && !("ifMatch" in precondition)) {
       if (!allowNoneMatch) throw new TypeError("This op does not take ifNoneMatchAny.");
       return { if_none_match: "*" };
@@ -597,19 +681,21 @@ export class V1Transaction {
           return Object.freeze(result.count === undefined
             ? { asserted: /** @type {const} */ (true) }
             : { asserted: /** @type {const} */ (true), count: u64(result.count, "assert_count count") });
-        return Object.freeze({ id: requireDocumentId(result.id), version: requireVersion(result.version) });
+        return Object.freeze({ id: requireDocumentId(result.id), version: requireVersion(result.version),
+          ...(result.document === undefined ? {} : { document: documentObject(result.document) }),
+        });
       })),
     });
   }
 }
 
-/** @typedef {{ readonly name: string; readonly createdAt: string }} V1CollectionInfo */
+/** @typedef {{ readonly id: import("../ids.js").EntityId; readonly name: string; readonly createdAt: string }} V1CollectionInfo */
 /** @typedef {{ readonly items: readonly V1CollectionInfo[]; readonly nextCursor: string | null }} V1CollectionPage */
 /** @typedef {{ readonly limit?: number | undefined; readonly cursor?: string | undefined }} V1CollectionListOptions */
 /** @param {JsonValue | undefined} value @returns {V1CollectionInfo} */
-function decodeCollection(value) {
+export function decodeCollection(value) {
   const raw = object(value, "collection");
-  return Object.freeze({ name: requireName("collection", raw.name), createdAt: u64(raw.created_at, "collection created_at") });
+  return Object.freeze({ id: requireId(raw.id), name: requireName("collection", raw.name), createdAt: u64(raw.created_at, "collection created_at") });
 }
 /** Collection management on the public client listener. */
 export class V1Collections {
@@ -663,6 +749,16 @@ export class V1Collections {
 
 /** A database handle by name. It performs no I/O until an operation runs. */
 export class V1Database {
+  /** @type {V1Imports} */
+  imports;
+  /** @type {V1Backups} */
+  backups;
+  /** @type {V1DatabaseUsageClient} */
+  metrics;
+  /** @type {V1Indexes} */
+  indexes;
+  /** @type {V1DatabaseSchemaClient} */
+  schema;
   /** @type {V1Collections} */
   collections;
   /** @type {V1Transport} */
@@ -678,6 +774,11 @@ export class V1Database {
     this.#transport = transport;
     this.name = requireName("database", name);
     this.collections = new V1Collections(transport, this.name);
+    this.schema = new V1DatabaseSchemaClient(transport, this.name);
+    this.indexes = new V1Indexes(transport, this.name);
+    this.metrics = new V1DatabaseUsageClient(transport, this.name);
+    this.backups = new V1Backups(transport, this.name);
+    this.imports = new V1Imports(transport, this.name);
     Object.freeze(this);
   }
 
@@ -694,7 +795,25 @@ export class V1Database {
     return new V1Transaction(this.#transport, this.name);
   }
 
+  /** @param {string} statement @param {V1RequestOptions} [options] */
+  sql(statement, options = {}) {
+    return runSql(this.#transport, this.name, statement, options);
+  }
+
+  /** @param {string} statement @param {V1RequestOptions} [options] */
+  checkSql(statement, options = {}) {
+    return checkSql(this.#transport, this.name, statement, options);
+  }
 
+  /** @param {string} statement @param {V1RequestOptions} [options] */
+  explainSql(statement, options = {}) {
+    return checkSql(this.#transport, this.name, statement, options, "explainSql");
+  }
+
+  /** @param {import("./changes.js").V1ChangeStreamRequest} [request] @param {V1RequestOptions} [options] */
+  changes(request = {}, options = {}) {
+    return streamChanges(this.#transport, this.name, request, options.signal);
+  }
 }
 
 /**
@@ -702,12 +821,31 @@ export class V1Database {
  * privately; it is never serialized, logged or forwarded to redirects.
  */
 export class TerraBaseV1Client {
+  /** @type {V1Health} */
+  #health;
+  /** @type {V1Platform} */
+  #platform;
+  /** @type {V1BackupDestinationClient} */
+  #backupDestination;
+  /** @type {V1ProjectUsageClient} */
+  #metrics;
+  /** @type {V1SavedQueries} */
+  #savedQueries;
+  /** @type {V1Databases} */
+  #databases;
   /** @type {V1Transport} */
   #transport;
 
   /** @param {TerraBaseV1ClientConfig} config */
   constructor(config) {
+    requireId(config.project);
     this.#transport = new V1Transport(config);
+    this.#databases = new V1Databases(this.#transport);
+    this.#savedQueries = new V1SavedQueries(this.#transport);
+    this.#metrics = new V1ProjectUsageClient(this.#transport);
+    this.#backupDestination = new V1BackupDestinationClient(this.#transport);
+    this.#health = new V1Health(this.#transport);
+    this.#platform = new V1Platform(this.#transport);
     Object.freeze(this);
   }
 
@@ -718,10 +856,23 @@ export class TerraBaseV1Client {
   database(name) {
     return new V1Database(this.#transport, name);
   }
+
+  /** @returns {V1Databases} Project-scoped database catalog. */
+  get databases() { return this.#databases; }
+  /** @returns {V1SavedQueries} */
+  get savedQueries() { return this.#savedQueries; }
+  /** @returns {V1ProjectUsageClient} */
+  get metrics() { return this.#metrics; }
+  /** @returns {V1BackupDestinationClient} */
+  get backupDestination() { return this.#backupDestination; }
+  /** @returns {V1Health} */
+  get health() { return this.#health; }
+  /** @returns {V1Platform} */
+  get platform() { return this.#platform; }
 }
 
 /**
- * Creates a TerraBase v1 client for documents, transactions, queries and shapes.
+ * Creates a project-scoped TerraBase client for documents, SQL, changes and catalog operations.
  * @param {TerraBaseV1ClientConfig} config
  * @returns {TerraBaseV1Client}
  */

package/src/v1/transport.js

@@ -16,11 +16,11 @@ export const maximumRequestBytes = 4 * 1024 * 1024;
 // Query budgets count stored JSON before wrappers and serializer escaping.
 const defaultMaximumResponseBytes = 64 * 1024 * 1024;
 // Validate header-safe credential syntax only; the producer validates JWT claims/signatures.
-// Retain C# keys while the published TS-589 JWT contract awaits a producer release.
+// Retain C# keys; current project routes also authenticate project access JWTs.
 const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+|tb_[A-Za-z0-9_-]{43})$/u;
 /**
  * Resolver input contains no credential. A successful URL is cached for this client/database.
- * @typedef {{ readonly project: string; readonly database: string; readonly signal?: AbortSignal | undefined }} V1EndpointContext
+ * @typedef {{ readonly project: string | undefined; readonly database?: string | undefined; readonly signal?: AbortSignal | undefined }} V1EndpointContext
  */
 /** @typedef {(context: V1EndpointContext) => string | Promise<string>} V1EndpointResolver */
 /**
@@ -37,11 +37,12 @@ const tokenPattern = /^(?!tbk1\.)(?:[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-
 
 /**
  * @typedef {object} V1CallOptions
- * @property {string} [body]
+ * @property {string | Uint8Array} [body]
  * @property {string} [contentType]
  * @property {Readonly<Record<string, string>>} [headers] Contract headers only (If-Match, If-None-Match).
  * @property {URLSearchParams | undefined} [query]
  * @property {AbortSignal | undefined} [signal]
+ * @property {"no-store" | undefined} [cache] Authenticated shape epoch keys must bypass caches.
  */
 
 /**
@@ -127,29 +128,29 @@ export class BodyTransportError extends Error {
 
 /** Internal transport bound to one project credential. */
 export class V1Transport {
-  /** @type {string} */
+  /** @type {string | undefined} */
   #project;
   /** @type {V1EndpointResolver} */
   #resolver;
   /** @type {Map<string, { promise: Promise<string>; timer: ReturnType<typeof setTimeout>; waiters: number }>} */
   #bases = new Map();
-  /** @type {string} */
+  /** @type {string | undefined} */
   #token;
   /** @type {FetchLike} */
   #fetch;
   /** @type {number} */
   #maxResponseBytes;
 
-  /** @param {TerraBaseV1ClientConfig} config */
+  /** @param {TerraBaseV1ClientConfig | (import("./system.js").TerraBaseSystemClientConfig & { project?: undefined; endpointResolver?: undefined })} config */
   constructor(config) {
     if (typeof config !== "object" || config === null) throw new TypeError("TerraBase v1 client config is required.");
-    this.#project = requireProject(config.project);
+    this.#project = config.project === undefined ? undefined : requireProject(config.project);
     if ((config.baseUrl === undefined) === (config.endpointResolver === undefined))
       throw new TypeError("Supply exactly one of baseUrl or endpointResolver.");
     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 (typeof config.token !== "string" || !tokenPattern.test(config.token))
+    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 ("autoIdempotencyKey" in config || "maxRetries" in config || "resolver" in config)
       throw new TypeError("Unsupported client configuration member.");
@@ -171,8 +172,9 @@ export class V1Transport {
    */
   async url(operation, params, signal) {
     signal?.throwIfAborted();
-    const database = requireName("database", params.database);
-    let base = this.#bases.get(database);
+    const database = v1Route(operation).pathTemplate.includes("{database}") ? requireName("database", params.database) : undefined;
+    const session = database ?? "";
+    let base = this.#bases.get(session);
     if (base === undefined) {
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(new DOMException(
@@ -182,13 +184,13 @@ export class V1Transport {
       const promise = new Promise((resolve, reject) => {
         controller.signal.addEventListener("abort", () => reject(controller.signal.reason), { once: true });
         void Promise.resolve().then(() => this.#resolver(Object.freeze({
-          project: this.#project, database, signal: controller.signal,
+          project: this.#project, ...(database === undefined ? {} : { database }), signal: controller.signal,
         }))).then(canonicalBaseUrl).then(resolve, reject).finally(() => clearTimeout(timer));
       });
       base = { promise, timer, waiters: 0 };
-      this.#bases.set(database, base);
+      this.#bases.set(session, base);
       // A failed resolution is not a session; a later operation may resolve again.
-      void promise.catch(() => { if (this.#bases.get(database) === base) this.#bases.delete(database); });
+      void promise.catch(() => { if (this.#bases.get(session) === base) this.#bases.delete(session); });
     }
     base.waiters++;
     if (typeof base.timer === "object") base.timer.ref();
@@ -206,7 +208,8 @@ export class V1Transport {
         });
       });
       signal?.throwIfAborted();
-      return `${resolved}${v1RoutePath(v1Route(operation), { ...params, project: this.#project })}`;
+      if (v1Route(operation).pathTemplate.includes("{project}") && this.#project === undefined) throw new TypeError("This operation requires a project client.");
+      return `${resolved}${v1RoutePath(v1Route(operation), { ...params, ...(this.#project === undefined ? {} : { project: this.#project }) })}`;
     } finally {
       // Keep Node alive only while callers are waiting for this resolution.
       if (--base.waiters === 0 && typeof base.timer === "object") base.timer.unref();
@@ -217,9 +220,11 @@ export class V1Transport {
    * Reads a response body as UTF-8 text within the response byte bound. A
    * connection failure while reading is a BodyTransportError.
    * @param {Response} response
+   * @param {AbortSignal | undefined} [signal]
    * @returns {Promise<string>}
    */
-  async readText(response) {
+  async readText(response, signal) {
+    signal?.throwIfAborted();
     const reader = response.body?.getReader();
     if (reader === undefined) return "";
     /** @type {Uint8Array[]} */
@@ -227,13 +232,16 @@ export class V1Transport {
     let size = 0;
     try {
       while (true) {
+        signal?.throwIfAborted();
         /** @type {ReadableStreamReadResult<Uint8Array>} */
         let part;
         try {
           part = await reader.read();
         } catch (error) {
+          signal?.throwIfAborted();
           throw new BodyTransportError(error);
         }
+        signal?.throwIfAborted();
         if (part.done) break;
         size += part.value.byteLength;
         if (size > this.#maxResponseBytes)
@@ -252,16 +260,17 @@ export class V1Transport {
       bytes.set(part, offset);
       offset += part.byteLength;
     }
-    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
   }
 
   /**
    * Parses a JSON response body exactly.
    * @param {Response} response
+   * @param {AbortSignal | undefined} [signal]
    * @returns {Promise<JsonValue | undefined>}
    */
-  async readJson(response) {
-    return V1Transport.#decodeJson(response, await this.readText(response));
+  async readJson(response, signal) {
+    return V1Transport.#decodeJson(response, await this.readText(response, signal));
   }
 
   /**
@@ -280,13 +289,15 @@ export class V1Transport {
   /**
    * Converts a non-success response to a TerraBaseV1Error.
    * @param {Response} response
+   * @param {AbortSignal | undefined} [signal]
    * @returns {Promise<TerraBaseV1Error>}
    */
-  async error(response) {
+  async error(response, signal) {
     let text = "";
     try {
-      text = await this.readText(response);
+      text = await this.readText(response, signal);
     } catch {
+      signal?.throwIfAborted();
       text = "";
     }
     return parseV1Error(response.status, response.headers, text);
@@ -300,27 +311,60 @@ export class V1Transport {
    * @returns {Promise<V1CallResult>}
    */
   async call(operation, params, options = {}) {
+    const response = await this.#send(operation, params, options);
+    if (response.status === 307) {
+      await response.body?.cancel();
+      return { status: response.status, headers: response.headers, value: undefined };
+    }
+    return { status: response.status, headers: response.headers, value: await this.readJson(response, options.signal) };
+  }
+
+  /**
+   * @param {"streamDatabaseChanges"} operation
+   * @param {Readonly<Record<string, string>>} params
+   * @param {V1CallOptions} [options]
+   * @returns {Promise<Response>}
+   */
+  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) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new TypeError("TerraBase changes require a text/event-stream response body.");
+    }
+    return response;
+  }
+
+  /** @param {V1Operation} operation @param {Readonly<Record<string, string>>} params @param {V1CallOptions} options @returns {Promise<Response>} */
+  async #send(operation, params, options) {
     const route = v1Route(operation);
-    if (options.body !== undefined && new TextEncoder().encode(options.body).byteLength > maximumRequestBytes)
+    const bytes = typeof options.body === "string" ? new TextEncoder().encode(options.body) : options.body;
+    if (bytes !== undefined && bytes.byteLength > maximumRequestBytes)
       throw new TypeError(`TerraBase request bodies are limited to ${maximumRequestBytes} bytes.`);
     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);
-    headers.set("authorization", `Bearer ${this.#token}`);
-    headers.set("accept", route.responseMediaType);
+    if (route.permission !== "anonymous" && this.#token !== undefined) headers.set("authorization", `Bearer ${this.#token}`);
+    if (route.responseMediaType !== "") headers.set("accept", route.responseMediaType);
     if (options.body !== undefined) headers.set("content-type", options.contentType ?? "application/json");
-    /** @type {RequestInit} */
+    /** @type {RequestInit & { duplex?: "half" }} */
     const init = { method: route.method, headers, redirect: "manual" };
-    if (options.body !== undefined) init.body = options.body;
+    if (options.cache !== undefined) init.cache = options.cache;
+    if (route.permission.endsWith(":write") && typeof process !== "undefined" && process.release?.name === "node") {
+      // Node fetch replays buffered or absent bodies on 421; use a one-shot stream, including DELETE.
+      if (operation === "uploadImportSource" && bytes !== undefined) headers.set("content-length", String(bytes.byteLength));
+      init.body = new ReadableStream({ start(controller) { if (bytes !== undefined && bytes.byteLength > 0) controller.enqueue(bytes); controller.close(); } });
+      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;
     const response = await this.#fetch(url, init);
+    if (options.signal?.aborted) {
+      void response.body?.cancel().catch(() => undefined);
+      options.signal.throwIfAborted();
+    }
     if (response.type === "opaqueredirect")
       throw new TypeError("Fresh shape bootstrap requires server fetch; obtain a handle and snapshot offset with collection.shape() on your server.");
-    if (!route.successStatuses.includes(response.status)) throw await this.error(response);
-    if (response.status === 307) {
-      await response.body?.cancel();
-      return { status: response.status, headers: response.headers, value: undefined };
-    }
-    return { status: response.status, headers: response.headers, value: await this.readJson(response) };
+    if (!route.successStatuses.includes(response.status)) throw await this.error(response, options.signal);
+    return response;
   }
 }