@terrascale/sdk 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.0.4
+
+Publishes current main, including `db.sql`, `db.changes`, backups, indexes and
+`allRegions` placement, plus every Unreleased entry below. Releases are now
+tag-driven: pushing a `v0.0.N` tag that matches `package.json` runs
+`.github/workflows/publish.yml`, which re-runs the checks and publishes to npm
+with provenance.
+
+## Unreleased — ts-auth platform token contract
+
+`createTsAuthClient` sends every call to `apiBaseUrl`. The Atlas auth discovery
+lookup, regional `<region>.auth.terrascale.tech` routing and the
+`useReverseProxy` option are removed: ts-auth has one global issuer per tenant
+(`https://auth.terrascale.tech/terrascale` for the platform). Contract tests
+pin the issuer, the `https://api.terrascale.tech` audience, the four TerraBase
+scopes and distinct 401/403 handling.
+
 ## Unreleased — TS-754
 
 Entity IDs are plain uppercase Crockford ULIDs. `generateId()` uses the maintained

package/README.md

@@ -1,22 +1,35 @@
 # @terrascale/sdk
 
 The JavaScript/JSDoc SDK for the project-scoped C#/.NET TerraBase server
-(`terrabase`, `origin/main`). Version 0.0.1 replaces the retired Rust client.
+(`TerraScale/terrascale`). Current source compatibility is pinned at
+`e30ffdc287530551b161b0130220be53d3c0475e`; see the
+[compatibility audit](docs/api-compatibility-20261013.md) for exact evidence and open gates.
 The package targets Node.js 22 and 24 and current Chrome, Firefox, Safari, and Edge.
 Plain ES modules ship as written; `nice -n 19 npm run build` generates the
 TypeScript declarations in `types/`.
+The latest published standard is [ECMAScript 2026](https://ecma-international.org/publications-and-standards/standards/ecma-262/).
+The compiler uses [`ESNext`](https://www.typescriptlang.org/tsconfig/target.html),
+its latest supported ECMAScript target. Source stays
+in `.js` files; JSDoc supplies types through `allowJs` and `checkJs`. JSDoc typing
+is a [tooling feature](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html),
+independent of the ECMAScript edition. Published runtime
+support remains Node.js 22/24 and the browser targets listed above.
 
 ```sh
 npm install @terrascale/sdk
 ```
 
+The following shows the current API with a trusted `discoveredOrigin` supplied
+by your authorized integration. Built-in Atlas integration remains pending; see
+[endpoint selection](#atlas-and-endpoint-selection).
+
 ```js
 import { createTerraBaseV1Client, generateId, v1Filter } from "@terrascale/sdk";
 
 const client = createTerraBaseV1Client({
   project: process.env.TERRABASE_PROJECT,
   token: process.env.TERRABASE_ACCESS_TOKEN,
-  baseUrl: process.env.TERRABASE_BASE_URL,
+  baseUrl: discoveredOrigin,
 });
 const db = client.database("app");
 const todos = db.collection("todos");
@@ -32,9 +45,11 @@ for await (const page of todos.pages({ filter: v1Filter.eq("/done", true), limit
 ```
 
 Provision the project, database and collection before using their handles.
-The pinned producer still requires a C# `tb_` key as `token`. The example also
-accepts a ts-auth project access JWT for the published TS-589 target, whose
-server implementation remains pending. Credentials travel as
+Current project routes authenticate ts-auth project access JWTs. Legacy C# `tb_`
+keys remain accepted for their narrower data scopes; they cannot grant
+`databases:read` or `databases:write`. The historical immutable release harness
+still uses `tb_` keys and does not qualify the current JWT implementation.
+Credentials travel as
 `Authorization: Bearer <token>` and are held privately. The SDK validates
 header-safe syntax; authentication and authorization belong to the producer.
 Reads and queries require `documents:read`; writes and transactions require
@@ -44,13 +59,25 @@ is an alias of `createTerraBaseV1Client`; it no longer accepts tenant/shard opti
 
 ## Atlas and endpoint selection
 
-Supply exactly one of `baseUrl` or `endpointResolver`. A resolver receives
-`{ project, database }` and returns the service URL, synchronously or asynchronously.
-The URL is resolved once per database session and reused by its operations.
+The [zero-configuration operating contract](AGENTS.md#zero-configuration-user-decision-2026-10-09-do-not-revert)
+requires first-party services to discover every eligible serving region and
+receive production credentials automatically, without regional activation or
+manual endpoint/secret wiring. Customer project/database scope and authorized
+access tokens remain required. This release has not implemented automatic Atlas
+integration (TS-507); the endpoint examples show the current API boundary and
+are not a first-party production setup recipe. No new resolver API is implied.
+
+The current implementation requires exactly one of `baseUrl` or
+`endpointResolver`. In these examples, `discoveredOrigin` is a trusted HTTPS
+origin supplied by an authorized integration, not an SDK-created value.
+A resolver receives
+`{ project, database?, signal }` and returns the service URL, synchronously or asynchronously.
+Project catalog operations omit `database`; each project/catalog or database session
+resolves once and reuses its URL.
 Shared resolution expires after 30 seconds and supplies a cancellation signal
 to the resolver; a later operation can retry an expired or failed resolution.
 Cancelling one operation leaves other callers' shared resolution running.
-HTTPS is required except for loopback HTTP in local development; no regional
+HTTPS is required except for loopback HTTP in isolated tests; no regional
 host is hardcoded and no implicit production endpoint is selected.
 
 ```js
@@ -59,57 +86,53 @@ import { createTerraBaseV1Client, staticBaseUrlResolver } from "@terrascale/sdk"
 const client = createTerraBaseV1Client({
   project: process.env.TERRABASE_PROJECT,
   token: process.env.TERRABASE_ACCESS_TOKEN,
-  endpointResolver: staticBaseUrlResolver(process.env.TERRABASE_BASE_URL),
+  endpointResolver: staticBaseUrlResolver(discoveredOrigin),
 });
 const db = client.database("app");
 ```
 
-Atlas (`ts-atlas`, a TypeScript Cloudflare Worker) discovers the closest eligible
+Atlas discovers the closest eligible
 region and the location of a project/database. The resolver seam allows that
 choice to stay pinned for the session. Atlas discovery integration is deferred
 to TS-507; this release requires an explicit URL or caller-supplied resolver.
 
-## Documents, queries, transactions and shapes
-
-The published TS-589 route table (`terrabase/docs/api.md`) keeps these data
-paths unchanged. Management moves to project-scoped paths using database names;
-this SDK's Management and Admin entrypoints still make no HTTP calls.
-Database creation belongs to Management (`POST /v1/projects/{project}/databases`)
-in that target contract.
-
-The current immutable producer release implements the renamed `TerraBase`
-assembly, but still authenticates data calls with `tb_` keys and exposes the old
-Management routes. Its real-release integration harness uses those existing
-bootstrap operations. JWT server compatibility and the new Management routes
-remain unqualified until the producer publishes their implementation; accepting
-a JWT in SDK configuration does not establish server compatibility.
+## Documents, SQL, change streams and catalog
 
-The C# producer owns these routes:
+Current handler source implements project-scoped database names and point
+addresses as `/documents/by-key?id=…`. The complete method/path/scope inventory
+is in [sdk-v1-route-manifest.json](sdk-v1-route-manifest.json), with 25 current
+source-backed routes and one retained historical shape route. Current generated
+OpenAPI and immutable release qualification remain open gates.
 
-| Operation | Method and path |
+| Surface | Public methods |
 | --- | --- |
-| Documents | `GET/PUT/PATCH/DELETE /v1/projects/{project}/databases/{db}/collections/{c}/documents/{id}`; `POST …/documents` |
-| Query | `POST /v1/projects/{project}/databases/{db}/collections/{c}/query` |
-| Transaction | `POST /v1/projects/{project}/databases/{db}/transactions` |
-| Shape | `GET /v1/projects/{project}/databases/{db}/collections/{c}/shape` |
-
-Collection methods are `get`, `put`, `create`, `patch`, `delete`, `query`,
-`pages` and `items`. Every entity ID is a plain 26-character Crockford ULID,
-canonical uppercase, without a prefix. `generateId()` uses the maintained
-`ulid` library and increases monotonically within a millisecond. `isValidId`
-checks IDs; `requireId` throws for invalid IDs. UUIDs and legacy IDs are rejected.
-The document key is the entity ID: keep it out of the JSON payload. Natural
-keys belong in indexed document fields, not deterministic UUID IDs. Documents return
+| 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` |
+| Databases | `client.databases.create/list/get/update/delete/branch` |
+| SQL | `db.sql/checkSql/explainSql` |
+| Changes | `db.changes` (SSE 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
+key; the producer then strips that redundant member.
+Documents return
 `{ id, version, state: "value", document }`; a causal read can answer
 `state: "conflict"` with `siblings`, and unknown states pass through. Versions
 (`tbv1-…`, `tbv2-…`) are opaque tokens. Writes return the version and a
-decimal-string commit `offset`; preserve those opaque positions and use
+decimal-string commit `offset`; PATCH also returns the stored `document`.
+Ops PATCH supports top-level `inc`, `add` and `remove` alongside `set`, `unset`
+and `append`. `inc` requires a nonzero signed Int64 integer; set elements are
+JSON scalars of at most 1 KiB under the producer serializer.
+Preserve those opaque positions and use
 `ifMatch` or `ifNoneMatchAny` for conditional writes.
 
 Queries support typed filters, sorting, projection and bounded cursor pages.
 `query` returns one page; `pages` and `items` follow `nextCursor`.
 `count.exact: false` means the count is a lower bound. The current C# producer
-does not support `lower` paths or `explain`; query number comparisons use its
+does not support `lower` paths or query-body `explain`; query number comparisons use its
 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.
 
@@ -121,29 +144,118 @@ or replay mutations after an uncertain result; this release does not promise
 mutation deduplication. Validation, authentication, authorization and
 precondition failures are not automatically retried.
 
-Shapes require `shapes:read` and use the collection's GET route with a `where`
-filter, handle, offset and live cursor. Snapshot bootstrap and checkpoint resume
-provide correctness; `must_refetch` requires discarding local state and starting
-a fresh snapshot. The C# producer has no shape gatekeeper, SSE route, edge shape
-token or projection support. Origin responses require private cache revalidation. Fresh shape bootstrap is
-server-only in this release: browsers hide the initial 307 redirect metadata.
-Browser callers need a handle and snapshot offset obtained on their server.
+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
+require `databases:read`, granted by a project access JWT.
+
+```js
+const result = await db.sql("SELECT * FROM todos LIMIT 10");
+const controller = new AbortController();
+for await (const event of db.changes({ cursor: "now", collections: ["todos"] }, {
+  signal: controller.signal,
+})) {
+  console.log(event);
+  // Stop with controller.abort(), or break to close this iterator.
+}
+```
+
+SSE emits `cursor` and `change` events. Cursors are opaque and must retain the
+same collection filter. `lastEventId` takes precedence over `cursor`; normal
+valid EOF reconnects with the latest issued cursor. Delivery is at least once;
+deduplicate by origin, version, collection and id. `document` is its current
+serving value, including null. Network failures, malformed streams, terminal
+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.
+
+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
+feed, not authorized bounded-query snapshots or the planned reactive WebSocket API.
 
-The same public SDK supplies this metadata on the server. Pass the position to
-the browser and repeat that immutable snapshot page with the identical filter
-and collection:
+## Free shape subscriptions (protocol v1)
+
+`collection.subscribeShape({ where? }, { onUpdate?, signal? })` 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
+freshness change; freshness is cleared while a changed-lineage resume is pending.
 
 ```js
-// Server: use the public client with the caller's shapes:read key.
-const snapshot = await serverCollection.shape({ where });
-const position = { handle: snapshot.handle, offset: snapshot.offset };
-// Browser: resume using position supplied by your application server.
-const page = await browserCollection.shape({ where, ...position });
+const shape = todos.subscribeShape({ where: v1Filter.eq("/done", false) }, {
+  onUpdate(subscription) {
+    console.log(subscription.state, subscription.upToDate);
+  },
+});
+try {
+  await shape.done; // Runs until close(), cancellation, or a terminal error.
+} finally {
+  shape.close();
+}
 ```
 
-Failures throw `TerraBaseV1Error` with the HTTP status and producer error code;
-transaction failures may also identify the failing `op`. Request cancellation
-uses `AbortSignal`.
+`close()` cancels a pending read. Server errors reject `done` using the existing
+TerraBase error types; malformed responses and network failures also stop it.
+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.
+
+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
+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.
+
+Origin JSON with a leading UTF-8 BOM is rejected by the v1 transport, including
+historical routes; shape v1 §6 requires bytes without a BOM.
+Subscriptions use unconditional reads; they do not send `If-None-Match` or use
+the optional `304` cached-body path.
+
+`collection.decryptShapeObject(bytes, { handle, offset, epoch, keyId }, { signal? })`
+fetches the matching epoch key with `cache: "no-store"`, derives the per-object key
+with WebCrypto HKDF, and verifies every AES-256-GCM TBS1 frame before returning a
+page. Keys are cached only in process memory by `(handle, epoch, keyId)`, scoped
+to the credential, database and collection. A key fetch bypasses HTTP caches;
+keys are never persisted. Past epochs are evicted on access as time or the
+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.
+
+This implements the [proposed protocol](contracts/shape-v1/shape-reads.md) at
+`993927ce7ecf8f9b889d24d4d1d21ec96eaf9416`, using `documents:read`. HTTP fakes and the
+upstream [conformance vectors](test/fixtures/shape-vectors.json) verify client
+behavior; they do not qualify a producer deployment. Current generated OpenAPI,
+live endpoint availability, and automatic region discovery remain unqualified.
+No TerraBase binary is downloaded or run by these tests. The existing historical
+`shape()` method keeps its contract. Manifest/object delivery and 302 redirects
+are deferred to FR-22; vector `presigned-manifest` is explicitly skipped until its
+delivery contract is ready upstream.
+
+Failures throw `TerraBaseV1Error` with status, code, optional transaction `op`,
+parsed `body`, raw `responseText`, response `headers`, and a received
+`X-Request-ID` as `requestId`. The actual producer uses `application/json`
+`{error:{code,message,op,details}}`, not RFC 9457. The SDK preserves RFC 9457
+bodies when received but does not invent producer support or request IDs.
+Cancellation preserves the supplied `AbortSignal` reason.
+
+**Browser gate remains red:** Chrome and Edge native fetch resend a buffered
+mutation once after HTTP 421. Node uses one-shot request streams to prevent that
+replay. Browser Fetch has no retry-control option; its one-wire assertions remain
+failing in this draft. See the audit for exact results and producer dependencies.
 
 ## Ouroboros and qualification
 
@@ -212,13 +324,11 @@ selector; both references must be canonical ULIDs. Entity pages reject null and
 primitive records; recovery-code pages contain strings.
 
 `@terrascale/sdk/local` (including `terrascale-local`) and `@terrascale/sdk/postgres` are
-**deprecated legacy entrypoints**. SQLite stays opt-in for development only and
-refuses CI, production, staging, qualification and deployment environments.
-It is no longer the required Dashboard backend and does not qualify the C# API.
-Local SQLite uses fresh format 2. Older stores are refused before records are
-read: stop the runtime, delete the exact configured `databasePath` and its
-`-wal`/`-shm` files, then restart. Startup recreates bootstrap state; old auth
-records and references are discarded together. There is no migration.
+**deprecated legacy entrypoints**. The operating contract confines fake/local
+stores to test code and test binaries. Their current exported runtime paths
+remain inventoried for removal; this docs change does not remove them.
+Do not use them for application onboarding, production, staging or producer
+qualification. A local adapter test does not qualify the real C# API.
 The PostgreSQL listener and retired tenant/shard client are outside the default
 v1 API. Existing framework, schema and SQL entrypoints are separate legacy
 surfaces; the root entrypoint exposes the C# v1 client API.
@@ -227,4 +337,4 @@ Hosted OAuth resource requests use one exact registered HTTPS `resource`. `oidc.
 
 `oauthClients` and `oauthResources` provide the producer's snake_case policy records and named management operations. Resource PATCH requires `expected_auth_epoch`; client PATCH accepts it. JSON epochs outside JavaScript's exact integer range are rejected. Client PATCH returns a bare client view unless `rotate_secret` is true, when it returns the client and its one-time secret. Resource create/PATCH always return the resource and nullable one-time introspection secret.
 
-Use `oidc.introspectResource` with independently configured `issuer`, exact `audience`, `introspection_client_id`, and `introspection_secret`. It uses resource Basic authentication only, with each credential component form encoded before Base64. An active result requires the exact configured issuer/audience, `Bearer`, integer timestamps valid at the local clock with no default skew, and the required user/service session shape. Inactive results contain only `active: false`. Resource results expose no internal epochs, refresh family, or token-use fields. The provider checks current durable token/session/resource state; an active principal or scope does not grant project ownership or management authority. Product authorization remains at the caller's existing authorization boundary. Behind the Atlas proxy `apiBaseUrl` `https://auth.terrascale.tech`, ts-auth's issuer is regional, `https://<region>.auth.terrascale.tech/<slug>` (for example `https://gru.auth.terrascale.tech/<slug>`); configure that issuer, not the proxy host. Resource introspection then calls the issuer's regional host directly, because Atlas could rank another region, which is another issuer; `useReverseProxy` keeps it on the proxy.
+Use `oidc.introspectResource` with independently configured `issuer`, exact `audience`, `introspection_client_id`, and `introspection_secret`. It uses resource Basic authentication only, with each credential component form encoded before Base64. An active result requires the exact configured issuer/audience, `Bearer`, integer timestamps valid at the local clock with no default skew, and the required user/service session shape. Inactive results contain only `active: false`. Resource results expose no internal epochs, refresh family, or token-use fields. The provider checks current durable token/session/resource state; an active principal or scope does not grant project ownership or management authority. Product authorization remains at the caller's existing authorization boundary. ts-auth has one global issuer per tenant, `{apiBaseUrl}/{slug}` (the platform issuer is `https://auth.terrascale.tech/terrascale`, with no regional host and no trailing slash); every call goes to `apiBaseUrl`. Platform tokens for TerraBase use audience `https://api.terrascale.tech` and only the scopes `databases:read`, `databases:write`, `documents:read` and `documents:write`, sent as one space-separated `scope` string.

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@terrascale/sdk",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "JavaScript SDK, typed with JSDoc, for project-scoped C# TerraBase v1 and hosted TerraScale identity.",
   "type": "module",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TerraScale/ts-js.git"
+  },
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -78,6 +82,7 @@
     "types",
     "!types/integration",
     "sdk-v1-route-manifest.json",
+    "sdk-public-v1-route-manifest.json",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -94,8 +99,6 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "npm run typecheck",
     "test": "vitest run",
-    "provision:terrabase": "node scripts/ci/provision-terrabase.mjs",
-    "test:integration": "node scripts/ci/run-terrabase-integration.mjs",
     "test:browser": "playwright test",
     "qualify:auth-authority": "node scripts/qualify-auth-authority.js",
     "check:frameworks": "vitest run src/database-view.test.js src/react/core.test.js src/svelte/index.test.js src/tanstack/index.test.js",
@@ -130,7 +133,7 @@
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
     "@tanstack/db": "0.9.2",
-    "svelte": "5.55.1",
+    "svelte": "5.57.2",
     "react": "19.2.8",
     "react-test-renderer": "19.2.8",
     "@types/react": "19.2.14",
@@ -153,5 +156,8 @@
   "packageManager": "npm@11.18.0",
   "dependencies": {
     "ulid": "3.0.2"
+  },
+  "overrides": {
+    "vite": "8.2.4"
   }
 }

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

@@ -0,0 +1,81 @@
+{
+  "producerRevision": "e7fa366ddb289f5612c93d316b316fb92c568151",
+  "routes": [
+    {"method":"GET","path":"/backupz","operation":"backupz","scopes":["anonymous"],"requestMediaTypes":[],"statuses":[200,503],"responseMediaType":"application/json","source":"src/TerraBase/Features/Backup/BackupHealthEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/health/replication","operation":"replicationHealth","scopes":["anonymous"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Health/ReplicationHealthEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/healthz","operation":"healthz","scopes":["anonymous"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Health/HealthzEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/readyz","operation":"readyz","scopes":["anonymous"],"requestMediaTypes":[],"statuses":[200,503],"responseMediaType":"application/json","source":"src/TerraBase/Features/Health/ReadyzEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/platform/databases","operation":"listPlatformDatabases","scopes":["platform-admin"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Platform/ListPlatformDatabasesEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/platform/databases/{database}/collections","operation":"listPlatformCollections","scopes":["platform-admin"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Platform/ListPlatformCollectionsEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/platform/databases/{database}/collections/{collection}/documents","operation":"listPlatformDocuments","scopes":["platform-admin"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Platform/ListPlatformDocumentsEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/platform/databases/{database}/collections/{collection}/documents/by-key","operation":"getPlatformDocument","scopes":["platform-admin"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Platform/GetPlatformDocumentEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/analytics","operation":"getProjectAnalytics","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetProjectAnalyticsEndpoint.cs","request":"none"},
+    {"method":"DELETE","path":"/v1/projects/{project}/backup-destination","operation":"deleteBackupDestination","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[204],"responseMediaType":"","source":"src/TerraBase/Features/Management/Backups/DeleteBackupDestinationEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/backup-destination","operation":"getBackupDestination","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/GetBackupDestinationEndpoint.cs","request":"none"},
+    {"method":"PUT","path":"/v1/projects/{project}/backup-destination","operation":"setBackupDestination","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/SetBackupDestinationEndpoint.cs","request":"ProjectBackupDestinationRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases","operation":"listDatabases","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/ListManagedDatabasesEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases","operation":"createDatabase","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/CreateManagedDatabaseEndpoint.cs","request":"DatabaseRegionsRequest"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}","operation":"deleteDatabase","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[204],"responseMediaType":"","source":"src/TerraBase/Features/Management/DeleteManagedDatabaseEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}","operation":"getDatabase","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/GetManagedDatabaseEndpoint.cs","request":"none"},
+    {"method":"PATCH","path":"/v1/projects/{project}/databases/{database}","operation":"updateDatabase","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/UpdateManagedDatabaseEndpoint.cs","request":"DatabaseRegionsRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/analytics","operation":"getDatabaseAnalytics","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetDatabaseAnalyticsEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/auto-index/{collection}","operation":"getAutoIndexPolicy","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Indexes/GetAutoIndexPolicyEndpoint.cs","request":"none"},
+    {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/auto-index/{collection}","operation":"setAutoIndexPolicy","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Indexes/SetAutoIndexPolicyEndpoint.cs","request":"AutoIndexPolicyRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/backup-policy","operation":"getBackupPolicy","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/GetBackupPolicyEndpoint.cs","request":"none"},
+    {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/backup-policy","operation":"setBackupPolicy","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/SetBackupPolicyEndpoint.cs","request":"BackupPolicyRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/backups","operation":"listBackups","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/ListBackupsEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/backups","operation":"createBackup","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/CreateBackupEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/backups/{backup}/restore","operation":"restoreBackup","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/RestoreBackupEndpoint.cs","request":"NameRequest"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/branches","operation":"branchDatabase","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/BranchManagedDatabaseEndpoint.cs","request":"NameRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/changes","operation":"streamDatabaseChanges","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"text/event-stream","source":"src/TerraBase/Features/Documents/GetDatabaseChangesEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections","operation":"listCollections","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/ListCollectionsEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/collections","operation":"createCollection","scopes":["documents:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/CreateCollectionEndpoint.cs","request":"CreateCollectionRequest"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}/collections/{collection}","operation":"dropCollection","scopes":["documents:write"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/DropCollectionEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}","operation":"getCollection","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/GetCollectionEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/documents","operation":"listDocuments","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/ListDocumentsEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/documents","operation":"createDocument","scopes":["documents:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/CreateDocumentEndpoint.cs","request":"JsonElement"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/documents/by-key","operation":"deleteDocument","scopes":["documents:write"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/DeleteDocumentEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/documents/by-key","operation":"getDocument","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/GetDocumentEndpoint.cs","request":"none"},
+    {"method":"PATCH","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/documents/by-key","operation":"patchDocument","scopes":["documents:write"],"requestMediaTypes":["application/merge-patch+json","application/vnd.terrabase.ops+json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/PatchDocumentEndpoint.cs","request":"JsonElement / PatchOpsRequest"},
+    {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/documents/by-key","operation":"putDocument","scopes":["documents:write"],"requestMediaTypes":["application/json"],"statuses":[200,201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/PutDocumentEndpoint.cs","request":"JsonElement"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/query","operation":"queryDocuments","scopes":["documents:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/QueryDocumentsEndpoint.cs","request":"QueryRequest"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/schema","operation":"deleteDeclaredCollectionSchema","scopes":["documents:write"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/DeleteCollectionSchemaEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/schema","operation":"getDeclaredCollectionSchema","scopes":["documents:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/GetCollectionSchemaEndpoint.cs","request":"none"},
+    {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/collections/{collection}/schema","operation":"putDeclaredCollectionSchema","scopes":["documents:write"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Documents/PutCollectionSchemaEndpoint.cs","request":"JsonElement"},
+    {"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":"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"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/import/cancel","operation":"cancelImport","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[202],"responseMediaType":"application/json","source":"src/TerraBase/Features/Import/CancelImportEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/import/resume","operation":"resumeImport","scopes":["databases:write","documents:write"],"requestMediaTypes":[],"statuses":[202],"responseMediaType":"application/json","source":"src/TerraBase/Features/Import/ResumeImportEndpoint.cs","request":"none"},
+    {"method":"PUT","path":"/v1/projects/{project}/databases/{database}/import/source","operation":"uploadImportSource","scopes":["databases:write","documents:write"],"requestMediaTypes":["application/octet-stream"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Import/UploadImportSourceEndpoint.cs","request":"byte[]"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/import/start","operation":"startImport","scopes":["databases:write","documents:write"],"requestMediaTypes":["application/json"],"statuses":[202],"responseMediaType":"application/json","source":"src/TerraBase/Features/Import/StartImportEndpoint.cs","request":"StartImportRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/index-recommendations","operation":"listIndexRecommendations","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Indexes/ListIndexRecommendationsEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/index-recommendations/{recommendation}/apply","operation":"applyIndexRecommendation","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[200,201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Indexes/ApplyIndexRecommendationEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/indexes","operation":"listIndexes","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Indexes/ListIndexesEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/indexes","operation":"createIndex","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Indexes/CreateIndexEndpoint.cs","request":"CreateIndexRequest"},
+    {"method":"DELETE","path":"/v1/projects/{project}/databases/{database}/indexes/{index}","operation":"dropIndex","scopes":["databases:write"],"requestMediaTypes":[],"statuses":[204],"responseMediaType":"","source":"src/TerraBase/Features/Management/Indexes/DropIndexEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/point-in-time","operation":"getRestoreWindow","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/GetRestoreWindowEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/point-in-time/plan","operation":"planPointInTime","scopes":["databases:read"],"requestMediaTypes":["application/json"],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/PlanPointInTimeEndpoint.cs","request":"PointInTimePlanRequest"},
+    {"method":"POST","path":"/v1/projects/{project}/databases/{database}/point-in-time/restore","operation":"restorePointInTime","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Backups/RestorePointInTimeEndpoint.cs","request":"PointInTimeRestoreRequest"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/query-shapes","operation":"listQueryShapes","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/ListQueryShapesEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/replication","operation":"getDatabaseReplication","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetDatabaseReplicationEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/schema","operation":"getDatabaseSchema","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Schema/ListCollectionsEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/databases/{database}/schema/{collection}","operation":"getCollectionSchema","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Schema/GetCollectionSchemaEndpoint.cs","request":"none"},
+    {"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/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"},
+    {"method":"GET","path":"/v1/projects/{project}/replication","operation":"getProjectReplication","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Usage/GetProjectReplicationEndpoint.cs","request":"none"},
+    {"method":"GET","path":"/v1/projects/{project}/saved-queries","operation":"listSavedQueries","scopes":["databases:read"],"requestMediaTypes":[],"statuses":[200],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/ListSavedQueriesEndpoint.cs","request":"none"},
+    {"method":"POST","path":"/v1/projects/{project}/saved-queries","operation":"createSavedQuery","scopes":["databases:write"],"requestMediaTypes":["application/json"],"statuses":[201],"responseMediaType":"application/json","source":"src/TerraBase/Features/Management/Queries/CreateSavedQueryEndpoint.cs","request":"SavedQueryRequest"},
+    {"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"}
+  ]
+}