@terrascale/sdk 0.0.5 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.0.7 — live shape reconnect, browser bootstrap and read replica
+
+`subscribeShape` keeps its state and retries the same position after a lost
+connection, follows the bootstrap `307` in browsers, and accepts
+`replica: { load, save }` to restore its last resumable state across restarts
+and offline periods. `indexedDbShapeReplica(key)` stores it in IndexedDB.
+Writes are never queued locally. Also publishes the query aggregates and geo
+filters below.
+
+## Unreleased — query aggregates and geo filters
+
+`query({ aggregate: { groupBy, sum, avg, min, max } })` returns typed
+`groups` (`{ key, count, sum?, avg?, min?, max? }`) with empty `items`.
+`v1Filter.withinRadius(path, { lat, lon, meters })` and
+`v1Filter.withinBox(path, { south, west, north, east })` build `within`
+filters, and `sort: [{ near: { path, lat, lon } }]` orders by meters, returned
+as each item's `distance`.
+
+## 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

package/README.md

@@ -110,15 +110,17 @@ OpenAPI and immutable release qualification remain open gates.
 | 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
-entity-ID contract. Document keys independently accept 1–256 UTF-16 code units,
-without controls or lone surrogates; natural keys, slashes and Unicode travel as
-one query parameter. A root payload `id` is ordinary data unless it equals the
+entity-ID contract. Document point operations and transaction writes require canonical
+ULIDs; the producer rejects other forms with `invalid_document_id`. SQL-backed
+collections can still return their stored primary keys in query, stream and export
+results. A root payload `id` is ordinary data unless it equals the
 key; the producer then strips that redundant member.
 Documents return
 `{ id, version, state: "value", document }`; a causal read can answer
@@ -149,6 +151,32 @@ const { items } = await docs.query({
 });
 ```
 
+Geo points are `{ lat, lon }` objects (WGS 84 degrees). `v1Filter.withinRadius`
+matches points within `meters` (haversine), `v1Filter.withinBox` points in a box
+(`west > east` crosses the antimeridian); both nest under `and`, `or` and `not`
+but shape filters reject them. A geo `near` sort orders by meters from a point,
+with the same one-page, at-most-100 rule as the vector `near`:
+
+```js
+const nearby = await places.query({
+  filter: v1Filter.withinRadius("/loc", { lat: -23.55, lon: -46.63, meters: 1000 }),
+  sort: [{ near: { path: "/loc", lat: -23.55, lon: -46.63 } }], limit: 10,
+}); // each item carries distance in meters
+```
+
+`aggregate` answers `groups` instead of items. `groupBy` takes 0-4 paths;
+`sum`, `avg`, `min` and `max` take at most 16 JSON Pointers in total and
+consider numbers only (`sum` is 0 and the others null without any). `count`
+is a decimal string. It takes no `sort`, `project`, `cursor` or `count`, and
+`limit` bounds the groups (more answer 400 `invalid_query`):
+
+```js
+const { groups } = await orders.query({
+  filter: v1Filter.gte("/created", 1761264000000),
+  aggregate: { groupBy: ["/status"], sum: ["/amount"], avg: ["/amount"] }, limit: 100,
+}); // [{ key: ["paid"], count: "250", sum: { "/amount": 12500.5 }, avg: { "/amount": 50.002 } }]
+```
+
 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.
@@ -161,6 +189,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
@@ -205,7 +264,7 @@ feed, not authorized bounded-query snapshots or the planned reactive WebSocket A
 
 ## Free shape subscriptions (protocol v1)
 
-`collection.subscribeShape({ where? }, { onUpdate?, signal? })` follows a collection's
+`collection.subscribeShape({ where? }, { onUpdate?, signal?, replica? })` follows a collection's
 sealed snapshot, log chunks, and live long-polls. Its `state` is a map from document
 id to `{ version, document }`; `upToDate` becomes true only after a fresh response
 reports `up_to_date`. Each callback sees the complete applied response or a
@@ -225,23 +284,49 @@ try {
 ```
 
 `close()` cancels a pending read. Server errors reject `done` using the existing
-TerraBase error types; malformed responses and network failures also stop it.
+TerraBase error types; malformed responses also stop it. A lost connection
+(a fetch rejection or a body failing in transit) keeps state and retries the same
+position with backoff, because shape reads are replay-safe `GET`s.
 Observe `done` to detect terminal errors. A throwing `onUpdate` stops the
 subscription and rejects `done` with the callback's error; already applied state
 remains available. Calling `close()` or aborting takes precedence over a later
 callback exception and resolves `done`. Document
 upserts replace the prior value and deletes of unknown ids are harmless. Repeated
 events are applied: a sealed value can be newer than its event, including after
-failover. There are no durable local writes or offline mutation queue.
+failover. There are no durable local writes or offline mutation queue: every
+write goes to the server, and a live subscription delivers it back.
+
+Pass a token provider (`token: () => getAccessToken()`) to keep a subscription
+alive across token renewal: each long-poll asks it for the current token. A
+`401` or `403` still stops the subscription.
+
+### Read replica
+
+`replica: { load, save }` keeps the last resumable state as exact JSON text. On
+start the subscription restores those documents with `upToDate` false, calls
+`onUpdate`, and catches up from the saved handle and offset; while offline it
+keeps retrying and the restored state stays readable. A `409 must_refetch`
+clears the replica with the state. A replica saved for another database,
+collection or filter is ignored. `indexedDbShapeReplica(key)` stores it in
+browser IndexedDB; use one key per signed-in subject and shape, and clear it on
+sign-out. A failing store rejects `done`.
+
+```js
+import { indexedDbShapeReplica } from "@terrascale/sdk";
+const open = todos.subscribeShape({ where: v1Filter.eq("/done", false) }, {
+  replica: indexedDbShapeReplica(`${userId}/todos/open`),
+  onUpdate: s => render(s.state, s.upToDate),
+});
+```
 
 The client preserves state for one proven cursor-resume attempt when a different
 machine rejects its handle. It never resumes an incomplete snapshot. A failed
 resume or another `409 must_refetch` clears state and starts a fresh snapshot.
 Opaque resume tokens travel verbatim in the query, or `TB-Shape-Resume` when the
 request target would exceed the protocol limit. Only documented transient
-`shape_busy`, `unavailable`, and `shape_too_large` errors retry with backoff and
-`Retry-After` until success or cancellation; authorization, validation, and
-network errors stop the subscription. The backoff delay is capped at 30 seconds
+`shape_busy`, `unavailable`, and `shape_too_large` errors and lost connections
+retry with backoff and `Retry-After` until success or cancellation;
+authorization and validation errors stop the subscription. The backoff delay is capped at 30 seconds
 unless `Retry-After` requires longer. The maximum signed-64-bit live bucket is
 accepted as a response, as §4 allows, but cannot be sent as the next input;
 `done` rejects with a `TypeError` if that protocol limit is reached.
@@ -261,8 +346,10 @@ latest served epoch advances; historical objects fetch their keys again without
 retaining them. Any `409 must_refetch` on the shape or key route clears that
 collection's key cache. A failed tag, binding, frame, or response validation
 applies nothing. Key ids follow §12's 26 ASCII bytes without assuming a ULID.
-Native browser Fetch hides manual redirect metadata, so subscription bootstrap
-currently requires server fetch. TBS1 decryption uses WebCrypto in either runtime.
+Native browser Fetch hides a manual `307` behind an opaque redirect, so in a
+browser the bootstrap is sent again with `redirect: "follow"` and the final URL
+is held to the same same-route `Location` rules. TBS1 decryption uses WebCrypto
+in either runtime.
 
 This implements the [proposed protocol](contracts/shape-v1/shape-reads.md) at
 `993927ce7ecf8f9b889d24d4d1d21ec96eaf9416`, using `documents:read`. HTTP fakes and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "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

@@ -71,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"},
@@ -80,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/sdk-v1-route-manifest.json

@@ -178,7 +178,7 @@
   },
   "currentSource": {
     "producer": "TerraScale/terrascale",
-    "revision": "e30ffdc287530551b161b0130220be53d3c0475e",
+    "revision": "0d2582d1d6cc73972b49f6b6089b6f9ed0848da9",
     "sdkBaseRevision": "eac7e3fca1178d30d81eb18ff35d8629e5f454e4",
     "evidence": "Read-only source snapshot; not generated OpenAPI or runtime qualification. Imports excluded.",
     "routes": {
@@ -213,16 +213,16 @@
         "sha256": "3dbf94f195b41783efb230801831ac85cba31a428a1fb43b0d4df68cf082125e"
       },
       "src/TerraBase/Errors/ErrorResponse.cs": {
-        "sha256": "db83574aa5c2737d8cb7c905b9dbd5c553ba76c4bcf8e21eb8c269916958426d"
+        "sha256": "a304375245bed8239bd48a317c81ff02eb50a33aba4aa992c395db383bef4686"
       },
       "src/TerraBase/Features/ApiKeys/ApiKeyAuthenticationHandler.cs": {
-        "sha256": "ff55b316403eaad56ff2941b75d06ce2e561d01bb1ff0cda3fcb3eb49e17e494"
+        "sha256": "da12dea0a18f633dbb3e7a43b2f3d8b2ef5b364de4fa807f5c95f49b0fafaf68"
       },
       "src/TerraBase/Features/ApiKeys/IApiKeyStore.cs": {
         "sha256": "3abf96b87470e93fd9eaa4d72bd79dac2ded185399eaed6dd5d487e99dfda066"
       },
       "src/TerraBase/Features/Documents/ChangeCursor.cs": {
-        "sha256": "0ba18e88079fc019f81b708afcfbf949b02ef9746e2aa9420d2f52470bc3224e"
+        "sha256": "1e441a7c2f6b7af31ba6cfae40311374488737fa46557822fc230adeaa464613"
       },
       "src/TerraBase/Features/Documents/CollectionSchemaRoute.cs": {
         "sha256": "60665ffa0c29d19fd63895e391c65c1b6015c2109e75f960faf569f701ab7e50"
@@ -231,31 +231,31 @@
         "sha256": "dfc7b259119127dd6bdafc34b97194659441500c47bdf7a3171e052c1547bc83"
       },
       "src/TerraBase/Features/Documents/CreateDocumentEndpoint.cs": {
-        "sha256": "25678dbe2d651d1291be796b1e9c75f93762e1e476648629427acce027d99fc5"
+        "sha256": "54b34b25eb61f2c9ad9464bfd4eb9c90653d9900ad606d45c041c552f9942495"
       },
       "src/TerraBase/Features/Documents/DatabaseChangeModels.cs": {
         "sha256": "157ab37070ec2104f72730bf0e641fa5219946614a3dafe82530885e9a573ed7"
       },
       "src/TerraBase/Features/Documents/DatabaseChanges.cs": {
-        "sha256": "bbe8ee1e1cf3dacc2ba32967538bbbb427530edbe96fbe165bba8e52400a3406"
+        "sha256": "653e1b45684fb8778267375f73d381b4417e4e52c65907b3602377c432677b19"
       },
       "src/TerraBase/Features/Documents/DeleteCollectionSchemaEndpoint.cs": {
         "sha256": "63fca1ce65c98aeba3f9caa2b12673c8c46b49b40f18180e8c9e08f233ca6830"
       },
       "src/TerraBase/Features/Documents/DeleteDocumentEndpoint.cs": {
-        "sha256": "c8062dde557574824d5278f77c736bbe62277d4f2b659c602b6fa4d3a44f9908"
+        "sha256": "a71f61b2cae9cfaa743aff0cd80394dc3657ff85ad0f647f407d1f349a391b68"
       },
       "src/TerraBase/Features/Documents/DocumentModels.cs": {
-        "sha256": "160e0cc11b4b9a28b10261c3e1718f9d047dd5c782b3b65b288be4ea31db6581"
+        "sha256": "0e2c310ebed60fedf41713d20e64595d040dee6691cddecf0fc89ce2330bb089"
       },
       "src/TerraBase/Features/Documents/DocumentPatch.cs": {
         "sha256": "6b75821cc347e30189149bec4386e8995914f31aeedd41eaa97b135835252e5d"
       },
       "src/TerraBase/Features/Documents/DocumentRoute.cs": {
-        "sha256": "1ccdf60170c6ccffdbce3dae444fed0ebefb920658b0700f8f410b3983dc53a8"
+        "sha256": "931dd2eaef5711829b09e004beaf9b3cfdfb50e4a085a49209e50c8c848da2c2"
       },
       "src/TerraBase/Features/Documents/DropCollectionEndpoint.cs": {
-        "sha256": "e1a91ca3a740218ea7c994af994ca54301308f92414759f044650d6717f4f2d9"
+        "sha256": "08960ed491b565f8ee767c091533e092220686f56e91ad587c5770ed76606f4f"
       },
       "src/TerraBase/Features/Documents/GetCollectionEndpoint.cs": {
         "sha256": "28af27dda8c6dceadebdc00562c33ef93b8f88f8f6b30e784edfa7dea4a18907"
@@ -264,7 +264,7 @@
         "sha256": "600d89a860177dc3cf20cb90b84e47cc1542afb09041636e300a9d61f3d2a526"
       },
       "src/TerraBase/Features/Documents/GetDatabaseChangesEndpoint.cs": {
-        "sha256": "13ca12352bf33d2e687f4a7fb4d78d6f28f3048f936b14e1db8f9fd947745dd8"
+        "sha256": "22a6028fd5d961cdbd307876aef7df171e0d69f6094add382c4d36444f86b191"
       },
       "src/TerraBase/Features/Documents/GetDocumentEndpoint.cs": {
         "sha256": "f2c960cafe784acc67108de412df1134e8c89a2ceac71d1bed6c5654bd5884fa"
@@ -276,31 +276,31 @@
         "sha256": "99274324f34fcaf92da5637da834bd3963db5d41a39c66515a0cefba0259c207"
       },
       "src/TerraBase/Features/Documents/PatchDocumentEndpoint.cs": {
-        "sha256": "c14d7808bea905c49064f9fce5ba3c4b081fd8ebbc539e508c520f4680b08ae0"
+        "sha256": "68ea3acff0b49b62ab94e242046de1cfc0e1cdcef35fbb618054bce23f043903"
       },
       "src/TerraBase/Features/Documents/PutCollectionSchemaEndpoint.cs": {
         "sha256": "836d24b6a8137af9fdfce3e9c800c5c47a917802233658f83f9283a59490d3b2"
       },
       "src/TerraBase/Features/Documents/PutDocumentEndpoint.cs": {
-        "sha256": "894fc735975b86c980a27a73df898fe454f920e7eca0e5c536b5af4cdae25134"
+        "sha256": "b130e811ccca916ae07d33287fd57eaa0800421bb131e3caa1486792f2ef3ccf"
       },
       "src/TerraBase/Features/Documents/QueryDocumentsEndpoint.cs": {
-        "sha256": "9052c75d80ec46bbe113312f45b2cee4b198ae1730ffe90d3eb07f7507db2a93"
+        "sha256": "dfbdf4a34abc85116e8293f2218010560e6443a9c6e2212edfcec2969259dcd6"
       },
       "src/TerraBase/Features/Documents/TransactionEndpoint.cs": {
-        "sha256": "1e518f9c73f28b13e6e1761f4706e4157e89bf50776b6ac73ad44b6e22150c5c"
+        "sha256": "63aedf3a0dcc5367a2811c6f44b01df14599792e742245c861c1bf73d333fa8c"
       },
       "src/TerraBase/Features/Management/BranchManagedDatabaseEndpoint.cs": {
         "sha256": "16729700b6baa72fd26ebe8c8537f51e3414fd1a439a9d0bcbac211dc6266043"
       },
       "src/TerraBase/Features/Management/CreateManagedDatabaseEndpoint.cs": {
-        "sha256": "8302ef780cf65c92aa5f2a86e26fdd811c68e9446fa27f292d53ddf7207aa06a"
+        "sha256": "c845cb31cf840f7b3d7a15f1dc36326b5b27316a0a6eaad47ba6a325c1c044f4"
       },
       "src/TerraBase/Features/Management/DatabaseRegions.cs": {
-        "sha256": "b25dd27ce0864e4d2fba10c7f54595aa21b263ef6a59d20583d3b20916722e31"
+        "sha256": "16a54232cdf1e6d0d63555a43807a3104807b994a12c5018b5ade3cd051548c6"
       },
       "src/TerraBase/Features/Management/DeleteManagedDatabaseEndpoint.cs": {
-        "sha256": "1f6c26915734fb2e8eefceb613b72a08952c72aafc95a83c658e8caec36f81da"
+        "sha256": "1bd3038277ac6397724921491e45b0efc824c0ff3e3cc3fe7261a2782c28bcc5"
       },
       "src/TerraBase/Features/Management/GetManagedDatabaseEndpoint.cs": {
         "sha256": "263b6ee7698bdc95b1546e5947ff2b12368348d14b833919ff4a2684bfb34d91"
@@ -309,7 +309,7 @@
         "sha256": "ddd6d4f39bd5881b26e3247d23bc50fa6aabde16406ee89c82c28b5a52dd6f9e"
       },
       "src/TerraBase/Features/Management/ManagedDatabaseBody.cs": {
-        "sha256": "eaafeb932f4189f3f5f8246408a16adc33772c36ba11ab1cec972281d8a5a2fc"
+        "sha256": "17093b73938a331e100e28345b69f32aa0ad27775ff5739df7ec437dfc619a33"
       },
       "src/TerraBase/Features/Management/ProjectApiRoute.cs": {
         "sha256": "f78ac4888e34b0aa76158e9666efaf5de996d73e2b220018e44167ea2d7372cc"
@@ -321,19 +321,19 @@
         "sha256": "a491c12f83bae64724bf36258de26b71556822ef29f94b10995e9ba4d75d6ada"
       },
       "src/TerraBase/Features/Management/Queries/RunSqlEndpoint.cs": {
-        "sha256": "a038d67d1c3e4979cc3333d425732c8d1c256035b5528fe5e649e64df93c6279"
+        "sha256": "b662ec00f189e042558d4f12f65b41673bd5db33bcfaa991088dc6fed67bbed6"
       },
       "src/TerraBase/Features/Management/UpdateManagedDatabaseEndpoint.cs": {
-        "sha256": "08120d2aa197b7739dfcdb471dd753f08a5f597e96a62c6631b710f7e148021b"
+        "sha256": "f34b3a239b785b303e333e5aafd4e5e1670e1411b71c0a085a5c183aa47beba3"
       },
       "src/TerraBase/Features/UserAuth/ProjectToken.cs": {
         "sha256": "dc880e5a063f5148df174bea1455e0058bc4cd5b89f94d26d9f8853e62ad43dc"
       },
       "src/TerraBase/Features/UserAuth/UserAuthenticationHandler.cs": {
-        "sha256": "af40f669b8759b3683dfae8454e4b9fd9b05a5588cbf303a28644768942121c5"
+        "sha256": "12aa602d1adf4e171ba859fc05e1ad58461819157567fd075a5b67dd90347918"
       },
       "src/TerraBase/Features/UserAuth/UserAuthExtensions.cs": {
-        "sha256": "ee71fc08d5f34231bd2a11029d4cd99f0213e16100841789e54f994bfcc3c38f"
+        "sha256": "0a3bae03a89ea36f49186dc3e1481367e15c65b56016f06e5aadb798774b5079"
       },
       "src/TerraBase/Features/Documents/ETags.cs": {
         "sha256": "a486f8e5297eaf50c2b5844d646b7d4f1b04cb2bcf542865426bb7a12a44fefc"
@@ -345,7 +345,10 @@
         "sha256": "8f5f4be149663febe469a13741cadc5469cfc08de622527bedaaa8fe0e5893fd"
       },
       "src/TerraBase/Features/Management/Queries/QueryService.cs": {
-        "sha256": "df439371d7df3fd8de35bd26a7c34bc4b91009f860ed76d99f83315fd813bb64"
+        "sha256": "a0e095bd9895f2fcf9b2b838c28c3d839f7ad4a3353b3409fe44b128689aa121"
+      },
+      "src/TerraBase/Primitives/EntityIds.cs": {
+        "sha256": "51cff088e94cdf2e5f347c1b0fe53e92fbc2fb885ded83252867a6ea53e7038b"
       }
     }
   },
@@ -369,7 +372,7 @@
       "operation": "putDocument",
       "producerOperationId": "putDocument",
       "sourcePath": "src/TerraBase/Features/Documents/PutDocumentEndpoint.cs",
-      "sha256": "894fc735975b86c980a27a73df898fe454f920e7eca0e5c536b5af4cdae25134",
+      "sha256": "b130e811ccca916ae07d33287fd57eaa0800421bb131e3caa1486792f2ef3ccf",
       "method": "PUT",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/collections/{collection}/documents/by-key",
       "authorizationPolicy": "ApiKeyScopes.DocumentsWrite",
@@ -387,7 +390,7 @@
       "operation": "createDocument",
       "producerOperationId": "createDocument",
       "sourcePath": "src/TerraBase/Features/Documents/CreateDocumentEndpoint.cs",
-      "sha256": "25678dbe2d651d1291be796b1e9c75f93762e1e476648629427acce027d99fc5",
+      "sha256": "54b34b25eb61f2c9ad9464bfd4eb9c90653d9900ad606d45c041c552f9942495",
       "method": "POST",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/collections/{collection}/documents",
       "authorizationPolicy": "ApiKeyScopes.DocumentsWrite",
@@ -404,7 +407,7 @@
       "operation": "patchDocument",
       "producerOperationId": "patchDocument",
       "sourcePath": "src/TerraBase/Features/Documents/PatchDocumentEndpoint.cs",
-      "sha256": "c14d7808bea905c49064f9fce5ba3c4b081fd8ebbc539e508c520f4680b08ae0",
+      "sha256": "68ea3acff0b49b62ab94e242046de1cfc0e1cdcef35fbb618054bce23f043903",
       "method": "PATCH",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/collections/{collection}/documents/by-key",
       "authorizationPolicy": "ApiKeyScopes.DocumentsWrite",
@@ -422,7 +425,7 @@
       "operation": "deleteDocument",
       "producerOperationId": "deleteDocument",
       "sourcePath": "src/TerraBase/Features/Documents/DeleteDocumentEndpoint.cs",
-      "sha256": "c8062dde557574824d5278f77c736bbe62277d4f2b659c602b6fa4d3a44f9908",
+      "sha256": "a71f61b2cae9cfaa743aff0cd80394dc3657ff85ad0f647f407d1f349a391b68",
       "method": "DELETE",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/collections/{collection}/documents/by-key",
       "authorizationPolicy": "ApiKeyScopes.DocumentsWrite",
@@ -437,7 +440,7 @@
       "operation": "commitTransaction",
       "producerOperationId": "runTransaction",
       "sourcePath": "src/TerraBase/Features/Documents/TransactionEndpoint.cs",
-      "sha256": "1e518f9c73f28b13e6e1761f4706e4157e89bf50776b6ac73ad44b6e22150c5c",
+      "sha256": "63aedf3a0dcc5367a2811c6f44b01df14599792e742245c861c1bf73d333fa8c",
       "method": "POST",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/transactions",
       "authorizationPolicy": "ApiKeyScopes.DocumentsWrite",
@@ -454,7 +457,7 @@
       "operation": "queryDocuments",
       "producerOperationId": "queryDocuments",
       "sourcePath": "src/TerraBase/Features/Documents/QueryDocumentsEndpoint.cs",
-      "sha256": "9052c75d80ec46bbe113312f45b2cee4b198ae1730ffe90d3eb07f7507db2a93",
+      "sha256": "dfbdf4a34abc85116e8293f2218010560e6443a9c6e2212edfcec2969259dcd6",
       "method": "POST",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/collections/{collection}/query",
       "authorizationPolicy": "ApiKeyScopes.DocumentsRead",
@@ -518,7 +521,7 @@
       "operation": "dropCollection",
       "producerOperationId": "dropCollection",
       "sourcePath": "src/TerraBase/Features/Documents/DropCollectionEndpoint.cs",
-      "sha256": "e1a91ca3a740218ea7c994af994ca54301308f92414759f044650d6717f4f2d9",
+      "sha256": "08960ed491b565f8ee767c091533e092220686f56e91ad587c5770ed76606f4f",
       "method": "DELETE",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/collections/{collection}",
       "authorizationPolicy": "ApiKeyScopes.DocumentsWrite",
@@ -533,7 +536,7 @@
       "operation": "runSql",
       "producerOperationId": "runSql",
       "sourcePath": "src/TerraBase/Features/Management/Queries/RunSqlEndpoint.cs",
-      "sha256": "a038d67d1c3e4979cc3333d425732c8d1c256035b5528fe5e649e64df93c6279",
+      "sha256": "b662ec00f189e042558d4f12f65b41673bd5db33bcfaa991088dc6fed67bbed6",
       "method": "POST",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/sql",
       "authorizationPolicy": "ApiKeyScopes.DatabasesRead",
@@ -584,7 +587,7 @@
       "operation": "streamDatabaseChanges",
       "producerOperationId": "streamDatabaseChanges",
       "sourcePath": "src/TerraBase/Features/Documents/GetDatabaseChangesEndpoint.cs",
-      "sha256": "13ca12352bf33d2e687f4a7fb4d78d6f28f3048f936b14e1db8f9fd947745dd8",
+      "sha256": "22a6028fd5d961cdbd307876aef7df171e0d69f6094add382c4d36444f86b191",
       "method": "GET",
       "pathTemplate": "/v1/projects/{project}/databases/{database}/changes",
       "authorizationPolicy": "ApiKeyScopes.DocumentsRead",
@@ -661,7 +664,7 @@
       "operation": "createDatabase",
       "producerOperationId": "createDatabase",
       "sourcePath": "src/TerraBase/Features/Management/CreateManagedDatabaseEndpoint.cs",
-      "sha256": "8302ef780cf65c92aa5f2a86e26fdd811c68e9446fa27f292d53ddf7207aa06a",
+      "sha256": "c845cb31cf840f7b3d7a15f1dc36326b5b27316a0a6eaad47ba6a325c1c044f4",
       "method": "POST",
       "pathTemplate": "/v1/projects/{project}/databases",
       "authorizationPolicy": "ApiKeyScopes.DatabasesWrite",
@@ -708,7 +711,7 @@
       "operation": "updateDatabase",
       "producerOperationId": "updateDatabase",
       "sourcePath": "src/TerraBase/Features/Management/UpdateManagedDatabaseEndpoint.cs",
-      "sha256": "08120d2aa197b7739dfcdb471dd753f08a5f597e96a62c6631b710f7e148021b",
+      "sha256": "f34b3a239b785b303e333e5aafd4e5e1670e1411b71c0a085a5c183aa47beba3",
       "method": "PATCH",
       "pathTemplate": "/v1/projects/{project}/databases/{database}",
       "authorizationPolicy": "ApiKeyScopes.DatabasesWrite",
@@ -725,7 +728,7 @@
       "operation": "deleteDatabase",
       "producerOperationId": "deleteDatabase",
       "sourcePath": "src/TerraBase/Features/Management/DeleteManagedDatabaseEndpoint.cs",
-      "sha256": "1f6c26915734fb2e8eefceb613b72a08952c72aafc95a83c658e8caec36f81da",
+      "sha256": "1bd3038277ac6397724921491e45b0efc824c0ff3e3cc3fe7261a2782c28bcc5",
       "method": "DELETE",
       "pathTemplate": "/v1/projects/{project}/databases/{database}",
       "authorizationPolicy": "ApiKeyScopes.DatabasesWrite",

package/src/index.js

@@ -15,11 +15,14 @@ export {
   V1InvalidKeyError,
   V1ForbiddenScopeError,
   V1NotFoundError,
+  SqlError,
   V1ErrorCode,
   isTerraBaseV1Error,
 } from "./v1/errors.js";
 export { v1Filter } from "./v1/filter.js";
 export { V1ShapeSubscription } from "./v1/shape-subscription.js";
+export { indexedDbShapeReplica } from "./v1/shape-replica.js";
+/** @typedef {import("./v1/shape-subscription.js").V1ShapeReplicaStore} V1ShapeReplicaStore */
 /** @typedef {import("./v1/shape-subscription.js").V1ShapeSubscribeOptions} V1ShapeSubscribeOptions */
 /** @typedef {import("./v1/shape-subscription.js").V1ShapeDocument} V1ShapeDocument */
 /** @typedef {import("./v1/shape-reader.js").V1SealedShapePosition} V1SealedShapePosition */
@@ -38,6 +41,10 @@ export { ExactDecimal } from "./v1/json.js";
 /** @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").V1GeoNearSortKey} V1GeoNearSortKey */
+/** @typedef {import("./v1/terrabase-v1.js").V1Aggregate} V1Aggregate */
+/** @typedef {import("./v1/terrabase-v1.js").V1Group} V1Group */
+/** @typedef {import("./v1/terrabase-v1.js").V1ScoreSortKey} V1ScoreSortKey */
 /** @typedef {import("./v1/terrabase-v1.js").V1Query} V1Query */
 /** @typedef {import("./v1/terrabase-v1.js").V1Count} V1Count */
 /** @typedef {import("./v1/terrabase-v1.js").V1QueryPage} V1QueryPage */
@@ -51,6 +58,8 @@ export { ExactDecimal } from "./v1/json.js";
 /** @typedef {import("./v1/filter.js").V1Filter} V1Filter */
 /** @typedef {import("./v1/filter.js").V1Path} V1Path */
 /** @typedef {import("./v1/filter.js").V1Scalar} V1Scalar */
+/** @typedef {import("./v1/filter.js").V1GeoCircle} V1GeoCircle */
+/** @typedef {import("./v1/filter.js").V1GeoBox} V1GeoBox */
 /** @typedef {import("./v1/json.js").JsonValue} V1JsonValue */
 /** @typedef {import("./v1/json.js").JsonObject} V1JsonObject */
 /** @typedef {import("./v1/json.js").JsonInput} V1JsonInput */
@@ -76,6 +85,12 @@ 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 */
@@ -99,6 +114,7 @@ export { V1DatabaseSchemaClient } from "./v1/database-schema.js";
 
 export { V1Indexes } from "./v1/indexes.js";
 /** @typedef {import("./v1/indexes.js").V1Index} V1Index */
+/** @typedef {import("./v1/indexes.js").V1IndexKind} V1IndexKind */
 /** @typedef {import("./v1/indexes.js").V1IndexList} V1IndexList */
 /** @typedef {import("./v1/indexes.js").V1AutoIndexPolicy} V1AutoIndexPolicy */
 /** @typedef {import("./v1/indexes.js").V1IndexRecommendations} V1IndexRecommendations */
@@ -114,6 +130,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/local/router.js

@@ -1,4 +1,4 @@
-import { generateId } from "../ids.js";
+import { generateId, isValidId } from "../ids.js";
 import {
   createHash,
   createHmac,
@@ -171,7 +171,7 @@ export class TerraScaleLocalRouter {
         );
         if (match === null) return problemResponse(404, "unknown_route");
         const collection = requireDatabaseId(match[1]);
-        const document = requireDatabaseId(match[2]);
+        const document = documentId(match[2]);
         return await this.#store.exclusive(() => {
           this.#binding(collection);
           return jsonResponse(this.#point(collection, document));
@@ -752,6 +752,15 @@ function transactionKey(raw) {
   const id = object(raw.transaction_id);
   return `${text(id.expires_at_unix_ms)}:${text(id.nonce)}`;
 }
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function documentId(value) {
+  if (!isValidId(value)) throw new NativeLocalError(400, "invalid_document_id");
+  return value;
+}
+
 /**
  * @param {unknown} value
  * @returns {readonly DatabaseField[]}
@@ -815,7 +824,7 @@ function decodeCommit(raw) {
         collection: requireDatabaseId(write.collection),
         schema_generation: decimal(write.schema_generation),
         schema_digest: text(write.schema_digest),
-        document: requireDatabaseId(write.document),
+        document: documentId(write.document),
         condition: /** @type {DatabaseCondition} */ (parsedCondition),
         observed: write.observed.map((rawObserved) => {
           const observed = object(rawObserved);