@xcitedbs/client 0.1.0 → 0.2.5

package/llms-full.txt

@@ -0,0 +1,1181 @@
+# XciteDB — Complete Reference for AI Assistants
+
+> This file contains the full XciteDB documentation and SDK reference, intended to be provided as context to AI assistants for accurate code generation. It covers the product overview, every HTTP API surface, the JavaScript/TypeScript SDK, the Python SDK, and the C++ SDK.
+
+---
+
+## IMPORTANT: Non-Standard Conventions
+
+Before reading the full reference, note these critical differences from typical databases:
+
+1. **The default branch is the empty string `""`, not `"main"`.** When no `X-Branch` header is sent (or `context.branch` is omitted/empty), the server operates on the root timeline. A branch named `"main"` may exist as a user-created branch, but it is not required or special.
+
+2. **Identifiers are hierarchical, path-like strings** — e.g. `/us/bills/hr1`, `/manual/v2/chapter3`. They are NOT auto-generated UUIDs. The leading `/` is part of the identifier. Parent/child relationships are derived from the path structure.
+
+3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type. JSON documents are a parallel store. Both are fully versioned.
+
+4. **Context (branch + date) travels as HTTP headers** (`X-Branch`, `X-Date`, and optionally `X-Unversioned` for explicit flat writes), not URL path segments.
+
+5. **XML documents carry their identifier inside the XML** via a `db:identifier` attribute on the root element.
+
+6. **Authentication has two tiers.** Platform operators use `/api/v1/platform/auth/*`; Application end-users use `/api/v1/app/auth/*`. API keys bypass login for server-to-server use.
+
+7. **The query model is NOT SQL.** Use REST query parameters (`match`, `match_start`, `contains`, `regex`) or the **Unquery** JSON DSL.
+
+8. **Project vs tenant id.** Prefer SDK `context.project_id` and `listMyProjects` / `switchProject`. JSON bodies often use the field name `tenant_id` for the same value.
+
+9. **OpenAPI:** See repository `docs/openapi.yaml` for a machine-readable route map.
+
+---
+
+# Part 1: Product Overview
+
+# XciteDB: Executive Summary
+
+**Audience:** Technical stakeholders (CTOs, architects, senior engineers, and product managers) evaluating XciteDB. This document provides a high-level understanding of XciteDB's purpose, target workloads, architecture, and unique differentiators.
+
+---
+
+## 1. Executive Overview
+
+### 1.1 What is XciteDB?
+XciteDB is an enterprise-grade **Backend-as-a-Service (BaaS)** built on top of a highly optimized **embedded LMDB** database engine. Powered by a high-performance C++17 HTTP/WebSocket API, XciteDB exposes a multi-tenant, secure platform for managing complex, versioned, structured documents.
+
+**Both XML and JSON are first-class citizens.** XciteDB can operate as a pure **XML document store**, a pure **JSON document database**, or any combination of the two — including the common pattern of **XML documents enriched with structured JSON metadata**. In every mode, data is deeply shredded into its structural components (elements, attributes, objects, fields, array items), versioned, branched, indexed by path, and fully queryable through the same Unquery analytics engine.
+
+### 1.2 The Problem It Solves
+Standard relational databases and generic NoSQL stores struggle with highly structured, hierarchical, and deeply versioned content. Building collaborative authoring tools, legislative drafting systems, or complex content management platforms usually requires bolting a Git-like versioning layer and document-aware parsers onto an ill-fitting database.
+
+XciteDB bridges this gap. It provides **Git-like versioning for structured XML and JSON data** out of the box, delivered as a modern, API-first cloud platform with multi-tenancy, Attribute-Based Access Control (ABAC), and S3-compatible backups.
+
+### 1.3 Target Workloads
+XciteDB shines in domains requiring strict auditability, collaborative authoring, and complex document hierarchies:
+- **Legal and Legislative Drafting:** Tracking amendments, clauses, and exact historical states of laws.
+- **Structured Technical Documentation:** Managing manuals, specifications, and compliance documents where every change must be versioned and attributable.
+- **Collaborative Content Management:** Systems requiring branching, merging, and cooperative locking to prevent editor conflicts.
+- **Application State and Configuration:** Storing deeply structured JSON configuration, feature flags, or workflow state that benefits from versioning and path-level querying.
+
+### 1.4 Unique Differentiators
+- **First-Class XML & JSON:** Both formats are shredded, indexed by path, versioned, branched, and fully queryable through the same engine.
+- **Embedded LMDB Engine:** A memory-mapped, ACID-compliant storage core purpose-built for structured document workloads.
+- **Bare-Metal Speed:** Reads hit memory-mapped pages with no network round-trip. Microsecond-class read latency on warm data.
+- **"Git for Data" Versioning:** Branches, commits, tags, diffs, and time-travel are first-class database primitives.
+- **Unquery DSL:** A purpose-built declarative query language for navigating, filtering, and aggregating data across both XML trees and JSON structures.
+- **Native Office Ingestion:** Directly convert and ingest DOCX, ODF, RTF, and PDF formats into clean, versioned XML documents.
+- **Transparent Tenant Routing:** Scale out horizontally using a coordinator/worker topology without breaking the client API contract.
+- **Optional encryption at rest (per project):** AES-256-GCM protection for document values.
+
+---
+
+## 2. Architecture at a Glance
+
+### 2.1 Logical Layers
+- **Edge:** HTTPS traffic terminates at NGINX, which proxies to the C++ API.
+- **Security & Routing:** Drogon filters enforce rate limits, validate JWT/API keys, and isolate requests to specific tenant projects.
+- **Execution:** Business logic services interact with the `xcitelib` library for ACID-compliant LMDB transactions.
+- **Response:** Data is returned as structured JSON or XML.
+
+### 2.2 Storage & Document Model
+- **LMDB Backed:** Memory-mapped key-value store organized into specialized sub-databases (`nodes`, `ids`, `meta`, `vcs_data`).
+- **XML Documents:** Stored natively via pugixml and shredded into elements, attributes, and text nodes. Addressed by hierarchical, path-like identifiers (e.g., `/manual/v1/chapter1`).
+- **JSON Documents:** Stored as standalone structured documents keyed by string. Shredded into objects, fields, and array elements.
+- **JSON Metadata on XML:** JSON metadata can be attached to any XML document or path.
+- **Hierarchical Identifiers:** Both XML and JSON documents are addressed via logical, path-like strings. The engine natively indexes parent/child relationships.
+
+### 2.3 Git-Like Document Versioning
+- **Branches & Commits:** Isolate collaborative edits into branches. Create atomic commits with descriptive messages.
+- **Merge & Cherry-Pick:** Merge branches or cherry-pick specific commits.
+- **Time Travel:** Read historical state at any point in time using the `X-Date` header. For **writes**, `X-Unversioned: true` explicitly requests flat (unversioned) storage; it conflicts with `X-Date` (**400**).
+- **Cooperative Locking:** TTL locks prevent conflicting writes (HTTP 409 on conflict).
+
+### 2.4 Unquery: Declarative Query DSL
+Clients submit structured query documents via `POST /api/v1/unquery`; the engine evaluates them against matching identifiers and returns structured JSON results. Supports hierarchical navigation, XPath queries, JSON path navigation, aggregation, and conditional branching.
+
+---
+
+# Part 2: HTTP API Reference
+
+# Getting started
+
+Welcome to the **XciteDB HTTP API**. This reference describes REST endpoints under the `/api/v1` prefix, plus a few discovery URLs.
+
+## Base URL and versioning
+
+- All documented JSON APIs use the prefix **`/api/v1`**.
+- Replace `https://your-server` with your deployment origin (scheme + host + optional port).
+
+## Content types
+
+| Usage | Header |
+|--------|--------|
+| JSON request bodies | `Content-Type: application/json` |
+| XML document bodies | `Content-Type: application/xml` or `text/xml` |
+| Multipart uploads | `multipart/form-data` (e.g. document import) |
+
+## Common request headers
+
+| Header | When | Description |
+|--------|------|-------------|
+| `Authorization` | Usually required | `Bearer <JWT>` or `Bearer <api_key>` |
+| `X-Project-Id` | Platform console / multi-project JWT | Selects the **tenant project** when the token is not already bound to one tenant |
+| `X-Branch` | Optional | Active branch name for document and versioning operations |
+| `X-Date` | Optional | Point-in-time / revision context (ISO-like string as used by your deployment) |
+| `X-Unversioned` | Optional | When `true` or `1`, **writes** use flat LMDB keys (no date revision). Must not be combined with `X-Date` (**400**). Omitting `X-Date` remains valid (implicit unversioned). |
+
+## Errors
+
+Errors are usually JSON objects with `error` or `message` and optional `code` fields.
+
+HTTP status codes: **`401`** unauthenticated, **`403`** forbidden by role or policy, **`404`** not found, **`409`** conflict, **`422`** validation, **`423`** encrypted and locked, **`429`** rate limited, **`500`** server error.
+
+## Pagination and limits
+
+List endpoints often accept **`limit`** and **`offset`** query parameters.
+
+---
+
+# Authentication
+
+XciteDB supports several credentials depending on **who** is calling: **platform operators**, **tenant administrators**, **project members** (JWT or API keys), and **end-user app accounts**.
+
+## Bearer tokens
+
+```http
+Authorization: Bearer <token>
+```
+
+## Platform vs project context
+
+| Mode | Typical token | Project selection |
+|------|----------------|-------------------|
+| **Platform** (site operator) | Platform JWT from `/api/v1/platform/auth/login` | Use **`X-Project-Id`** for tenant data APIs when JWT is system-scoped |
+| **Tenant / project member** | Tenant JWT or API key from project keys | Tenant is implied by the key or login |
+| **App user** (end user) | App JWT from `/api/v1/app/auth/login` | Scoped to the **tenant_id** / project used at login |
+
+## API keys (project)
+
+Project administrators can create **public** and **secret** API keys. Public keys are suited to read-only or limited clients; secret keys can perform privileged operations.
+
+## OAuth (app users)
+
+Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oauth/...`.
+
+---
+
+# Health, version & discovery
+
+## Health
+
+**`GET /api/v1/health`** — Returns `{"status":"ok"}`. No authentication required.
+
+## Version
+
+**`GET /api/v1/version`** — Build version and metadata. No authentication.
+
+## JWKS
+
+**`GET /.well-known/jwks.json`** — JSON Web Key Set for JWT validation.
+
+## OpenID configuration
+
+**`GET /.well-known/openid-configuration`** — OIDC discovery document.
+
+---
+
+# Documents (XML)
+
+**Base path:** `/api/v1/documents`
+
+## List / query documents
+
+**`GET /api/v1/documents`**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `limit` | integer | No | Page size (clamped by server) |
+| `offset` | integer | No | Skip rows |
+| `prefix` | string | No | Identifier prefix filter |
+| `match` | string | No | Match expression / pattern |
+| `match_start` | string | No | Identifier starts with |
+| `match_end` | string | No | Identifier ends with |
+| `contains` | string | No | Identifier contains substring |
+| `regex` | string | No | Regex filter |
+
+## Write document
+
+**`POST /api/v1/documents`**
+
+With `Content-Type: application/json`:
+```json
+{
+  "xml": "<chapter db:identifier=\"/book/ch1\">...</chapter>",
+  "is_top": true
+}
+```
+
+With `Content-Type: application/xml`: send raw XML body.
+
+The identifier is extracted from the `db:identifier` attribute in the root XML element.
+
+## Get document by identifier
+
+**`GET /api/v1/documents/by-id?identifier=/book/ch1`**
+
+Query parameters: `identifier` (required), `flags` (optional: `FirstMatch`, `IncludeChildren`, `NoChildren`, `KeepIndexNodes`), `filter`, `path_filter`.
+
+## Delete document
+
+**`DELETE /api/v1/documents/by-id?identifier=/book/ch1`**
+
+## List identifiers
+
+**`GET /api/v1/documents/identifiers`** — Returns `{ identifiers: string[], total, offset, limit }`.
+
+Same query filters as document listing (`match`, `match_start`, `contains`, `regex`, `limit`, `offset`).
+
+## Identifier children (hierarchy)
+
+**`GET /api/v1/documents/identifier-children?parent_path=/book`**
+
+Returns `{ parent_path, parent_is_identifier, children: [{ segment, full_path, is_identifier, has_children }] }`.
+
+## Add identifier
+
+**`POST /api/v1/documents/identifiers`** — `{ "identifier": "/book/ch2" }`
+
+## Add alias
+
+**`POST /api/v1/documents/identifiers/alias`** — `{ "original": "/book/ch1", "alias": "/book/intro" }`
+
+## Changed documents
+
+**`GET /api/v1/documents/changed?branch=...&from_date=...&to_date=...`**
+
+## Document change log
+
+**`GET /api/v1/documents/log?match_start=...&from_date=...&to_date=...`**
+
+## Change date query
+
+**`GET /api/v1/documents/change-date?identifier=...`**
+
+## Resolve xcitepath
+
+**`GET /api/v1/documents/xcitepath?identifier=...`**
+
+---
+
+# JSON documents
+
+**Base path:** `/api/v1/json-documents`
+
+## Write JSON document
+
+**`POST /api/v1/json-documents`**
+
+```json
+{
+  "identifier": "app.settings",
+  "data": { "theme": "dark", "maxUploadMb": 25 }
+}
+```
+
+Note: The SDK method uses `identifier` and `data` fields. Some older documentation shows `key` and `value`.
+
+## Read JSON document
+
+**`GET /api/v1/json-documents?identifier=app.settings`**
+
+## Delete JSON document
+
+**`DELETE /api/v1/json-documents?identifier=app.settings`**
+
+## List JSON documents
+
+**`GET /api/v1/json-documents/list?match=...&limit=...&offset=...`**
+
+Returns `{ identifiers: string[], total, offset, limit }`.
+
+---
+
+# Document import & export
+
+## Import document
+
+**`POST /api/v1/documents/import`** — `Content-Type: multipart/form-data`, field `file`. Supported: DOCX, ODF, RTF, PDF, Markdown, plain text.
+
+## Export document
+
+**`GET /api/v1/documents/export?id=/book/ch1&format=...`**
+
+## Export provision
+
+**`GET /api/v1/documents/export/provision`** — Migration / mirror workflows.
+
+---
+
+# Metadata
+
+Attach structured **JSON metadata** to documents or nodes.
+
+**Base path:** `/api/v1/meta`
+
+## Append / set metadata
+
+**`POST /api/v1/meta`**
+
+```json
+{
+  "identifier": "/book/ch1",
+  "value": { "status": "review", "owner": "alice" },
+  "path": ""
+}
+```
+
+Optional `"mode": "append"` to append rather than overwrite.
+
+Can also use `"query"` instead of `"identifier"` to target multiple documents by query filter.
+
+## Query metadata (GET)
+
+**`GET /api/v1/meta?identifier=/book/ch1&path=`**
+
+## Query metadata (POST body)
+
+**`POST /api/v1/meta/query`** — `{ "query": {...}, "path": "" }`
+
+## Clear metadata
+
+**`DELETE /api/v1/meta`** — `{ "query": {...} }`
+
+---
+
+# Search
+
+Full-text search (backed by Meilisearch or Elasticsearch).
+
+**Base path:** `/api/v1/search`
+
+## Search
+
+**`POST /api/v1/search`**
+
+```json
+{
+  "query": "installation guide",
+  "doc_types": ["xml", "json"],
+  "branch": "",
+  "limit": 20,
+  "offset": 0
+}
+```
+
+Response: `{ hits: [{ identifier, path, doc_type, branch, snippet, score, xcitepath? }], total, query }`.
+
+## Reindex
+
+**`POST /api/v1/search/reindex`** — Rebuilds the search index.
+
+---
+
+# Unquery
+
+**`POST /api/v1/unquery`**
+
+Executes a structured query document (JSON DSL) for advanced analytics, bulk exports, and cross-document operations.
+
+```json
+{
+  "query": { "match_start": "/manual/" },
+  "unquery": { /* Unquery DSL operations */ }
+}
+```
+
+Unquery supports: hierarchical navigation (self, parents, ancestors, children, descendants), XPath queries on XML, JSON path navigation, counts, sums, string operations, type casting, and conditional branching. Results are always structured JSON.
+
+---
+
+# Branches
+
+**Base path:** `/api/v1/branches`
+
+**IMPORTANT: The default branch is the empty string `""`.** When no branch is specified, the server uses the root timeline.
+
+## List branches
+
+**`GET /api/v1/branches`** — Returns `{ branches: [{ name, from_branch, from_date, from_date_key, tip_commit }] }`.
+
+## Create branch
+
+**`POST /api/v1/branches`** — `{ "name": "feature-x", "from_branch": "", "from_date": "" }`
+
+## Get branch
+
+**`GET /api/v1/branches/{name}`** — Returns `{ branch: {...} }`.
+
+## Delete branch
+
+**`DELETE /api/v1/branches/{name}`**
+
+## Merge branch
+
+**`POST /api/v1/branches/{target}/merge`**
+
+```json
+{
+  "source_branch": "feature-x",
+  "message": "Merge feature",
+  "auto_resolve": "none"
+}
+```
+
+`auto_resolve`: `"none"` | `"source"` | `"target"`.
+
+Returns `{ status: "completed"|"conflicts", commit?, merged_identifiers?, conflicts? }`.
+
+## Delete revision on branch
+
+**`DELETE /api/v1/branches/{name}/revisions/{date}`**
+
+---
+
+# Commits, tags & diff
+
+## Create commit
+
+**`POST /api/v1/commits`** — `{ "message": "...", "author": "..." }`
+
+Returns `{ commit: { id, branch, date_key, message, author, ... } }`.
+
+## List commits
+
+**`GET /api/v1/commits?branch=...&limit=...&offset=...`**
+
+Returns `{ commits: [...], total, branch }`.
+
+## Get commit
+
+**`GET /api/v1/commits/{id}`** — Returns `{ commit: {...} }`.
+
+## Rollback to commit
+
+**`POST /api/v1/commits/{id}/rollback`** — `{ "confirm": true }`
+
+## Cherry-pick commit
+
+**`POST /api/v1/commits/{id}/cherry-pick`** — `{ "message": "...", "author": "..." }`
+
+## Create tag
+
+**`POST /api/v1/tags`** — `{ "name": "v1.0", "commit_id": "...", "message": "..." }`
+
+## List tags
+
+**`GET /api/v1/tags?limit=...&offset=...`** — Returns `{ tags: [...], total }`.
+
+## Get / Delete tag
+
+**`GET /api/v1/tags/{name}`** / **`DELETE /api/v1/tags/{name}`**
+
+## Diff
+
+**`POST /api/v1/diff`**
+
+```json
+{
+  "from": { "branch": "", "date_key": "..." },
+  "to": { "branch": "feature-x" },
+  "include_content": true
+}
+```
+
+Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_content?, to_content? }], total_changes }`.
+
+---
+
+# Locks
+
+**Base path:** `/api/v1/locks`
+
+## Acquire lock
+
+**`POST /api/v1/locks`** — `{ "identifier": "/book/ch1", "expires": 600 }`
+
+Returns lock info. **`409`** if already locked.
+
+## Release lock
+
+**`DELETE /api/v1/locks`** — `{ "identifier": "/book/ch1", "lock_id": "..." }`
+
+## Query locks
+
+**`GET /api/v1/locks?identifier=...`** — Lists active locks.
+
+---
+
+# Project configuration
+
+**Base path:** `/api/v1/config`
+
+**`GET /api/v1/config`** — Returns `{ settings: {...} }`.
+
+**`PUT /api/v1/config`** — `{ "settings": {...} }`.
+
+---
+
+# Triggers
+
+**Base path:** `/api/v1/triggers`
+
+## Create or update trigger
+
+**`POST /api/v1/triggers`**
+
+```json
+{
+  "trigger_id": "on_status_review",
+  "trigger": {
+    "match": { "meta_key": "status", "meta_value": "review" },
+    "action": { "type": "webhook", "url": "https://hooks.example.com/xcite" }
+  }
+}
+```
+
+## List triggers
+
+**`GET /api/v1/triggers`** — Returns map of `{ trigger_id: trigger_definition }`.
+
+## Delete trigger
+
+**`DELETE /api/v1/triggers?name=on_status_review`**
+
+---
+
+# Security policies
+
+**Base path:** `/api/v1/security`
+
+## Create policy
+
+**`POST /api/v1/security/policies`**
+
+```json
+{
+  "policy_id": "deny-viewers-admin",
+  "policy": {
+    "effect": "deny",
+    "priority": 10,
+    "subjects": { "type": "app_user", "groups": ["viewers"] },
+    "resources": { "identifiers": [{ "match_start": "/admin/" }] },
+    "actions": ["document:write", "document:delete"],
+    "conditions": {}
+  }
+}
+```
+
+## List / Get / Update / Delete policies
+
+**`GET /api/v1/security/policies`** — Map of all policies.
+**`GET /api/v1/security/policies/{id}`**
+**`PUT /api/v1/security/policies/{id}`**
+**`DELETE /api/v1/security/policies/{id}`**
+
+## Check access (dry run)
+
+**`POST /api/v1/security/check`**
+
+```json
+{
+  "subject": { "type": "app_user", "groups": ["editors"] },
+  "identifier": "/admin/config",
+  "action": "document:write"
+}
+```
+
+Returns `{ effect: "allow"|"deny", matched_policy_id? }`.
+
+## Security config
+
+**`GET /api/v1/security/config`** / **`PUT /api/v1/security/config`**
+
+Fields: `default_effect`, `app_user_default_effect`, `developer_bypass`.
+
+---
+
+# App authentication
+
+End-user authentication for application accounts.
+
+**Base path:** `/api/v1/app/auth`
+
+## Register
+
+**`POST /api/v1/app/auth/register`** — `{ "tenant_id": "default", "email": "...", "password": "..." }`
+
+## Login
+
+**`POST /api/v1/app/auth/login`** — `{ "tenant_id": "default", "email": "...", "password": "..." }`
+
+Returns `{ access_token, refresh_token, expires_in, user? }`.
+
+## Refresh
+
+**`POST /api/v1/app/auth/refresh`** — `{ "refresh_token": "...", "tenant_id": "..." }`
+
+## Logout
+
+**`POST /api/v1/app/auth/logout`**
+
+## Profile
+
+**`GET /api/v1/app/auth/me`** / **`PUT /api/v1/app/auth/me`**
+
+## Password flows
+
+- `POST /api/v1/app/auth/change-password` — `{ current_password, new_password }`
+- `POST /api/v1/app/auth/forgot-password` — `{ email }`
+- `POST /api/v1/app/auth/reset-password` — `{ token, new_password, tenant_id }`
+
+## Email verification
+
+- `POST /api/v1/app/auth/verify-email` — `{ token, tenant_id }`
+- `POST /api/v1/app/auth/send-verification` — `{ user_id }`
+
+## Custom token
+
+**`POST /api/v1/app/auth/custom-token`** — Exchange or mint a custom scoped token.
+
+---
+
+# OAuth (app users)
+
+**Base path:** `/api/v1/app/auth/oauth`
+
+## List providers
+
+**`GET /api/v1/app/auth/oauth/providers?tenant_id=default`** — Returns `{ providers: [{ id, display_name }] }`.
+
+## Start authorization
+
+**`GET /api/v1/app/auth/oauth/{provider}/authorize?tenant_id=default`** — Redirects browser to IdP.
+
+## Callback
+
+**`GET /api/v1/app/auth/oauth/{provider}/callback`** — Handles IdP redirect.
+
+## Exchange code (API)
+
+**`POST /api/v1/app/auth/oauth/exchange`** — `{ "provider": "google", "code": "...", "tenant_id": "default" }`
+
+---
+
+# App users (administration)
+
+**Base path:** `/api/v1/app/users`
+
+**`GET /api/v1/app/users`** — List with pagination.
+**`POST /api/v1/app/users`** — Create user.
+**`GET /api/v1/app/users/{id}`** — Get user.
+**`DELETE /api/v1/app/users/{id}`** — Delete user.
+**`PUT /api/v1/app/users/{id}/groups`** — `{ "groups": ["editors"] }`
+**`PUT /api/v1/app/users/{id}/status`** — `{ "status": "active"|"disabled"|"pending_verification" }`
+
+---
+
+# Email configuration
+
+**Base path:** `/api/v1/app/email`
+
+**`GET /api/v1/app/email/config`** / **`PUT /api/v1/app/email/config`** — SMTP settings.
+**`GET /api/v1/app/email/templates`** / **`PUT /api/v1/app/email/templates`** — Email templates.
+**`POST /api/v1/app/email/test`** — `{ "to": "admin@example.com" }`
+
+---
+
+# Project & API keys
+
+**Base path:** `/api/v1/project`
+
+**`GET /api/v1/project`** / **`PUT /api/v1/project`** / **`DELETE /api/v1/project`** — Project CRUD.
+**`POST /api/v1/project/reset`** — Wipe document data.
+
+## Members
+
+**`GET /api/v1/project/members`** — List.
+**`POST /api/v1/project/members`** — `{ "email": "...", "role": "editor" }`
+**`PUT /api/v1/project/members/{member_id}/role`** — `{ "role": "admin" }`
+**`DELETE /api/v1/project/members/{member_id}`**
+
+## API keys
+
+**`GET /api/v1/project/keys`** — List key metadata.
+**`POST /api/v1/project/keys`** — `{ "name": "CI key", "key_type": "public"|"secret" }`. Raw secret returned **once**.
+**`DELETE /api/v1/project/keys/{key_id}`** — Revoke.
+
+---
+
+# Project CORS & rate limits
+
+**`GET /api/v1/project/settings/cors`** / **`PUT /api/v1/project/settings/cors`**
+
+```json
+{
+  "allowed_origins": ["https://app.example.com"],
+  "allowed_methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+  "allow_credentials": true
+}
+```
+
+**`GET /api/v1/project/settings/rate-limits`** / **`PUT /api/v1/project/settings/rate-limits`**
+
+```json
+{ "read_rpm": 1200, "write_rpm": 120, "auth_rpm": 30 }
+```
+
+---
+
+# Project backups
+
+**Base path:** `/api/v1/project/settings/backup`
+
+**`GET .../config`** / **`PUT .../config`** — S3 destination, schedule, retention.
+**`POST .../config/test`** — Test credentials.
+**`GET .../list`** — List backups.
+**`POST .../run`** — Run backup now.
+**`GET .../status`** — Job state.
+**`POST .../restore`** — `{ "backup_id": "2025-01-15T10-00-00Z" }`
+
+---
+
+# Mirror sync
+
+**Base path:** `/api/v1/project/mirror`
+
+**`GET .../config`** / **`PUT .../config`** — Upstream URI, sync mode, credentials.
+**`POST .../test`** — Test connectivity.
+**`GET .../status`** — Last sync time, lag, errors.
+**`POST .../sync`** — Trigger immediate sync.
+
+---
+
+# Activity log & notifications
+
+**`GET /api/v1/project/logs`** — Paginated audit events.
+**`DELETE /api/v1/project/logs`** — Truncate logs (admin).
+**`GET /api/v1/project/logs/config`** / **`PUT .../config`** — Log settings.
+**`GET /api/v1/project/notifications`** — Unread/read notifications.
+**`POST /api/v1/project/notifications/{id}/read`** — Mark one read.
+**`POST /api/v1/project/notifications/read-all`** — Mark all read.
+**`GET /api/v1/project/notifications/config`** / **`PUT .../config`** — Notification settings.
+
+---
+
+# Tenant admin API
+
+**Base path:** `/api/v1/admin`
+
+**`POST /api/v1/admin/tenants`** — `{ "tenant_id": "acme-docs", "name": "Acme Docs" }`
+**`GET /api/v1/admin/tenants`** — List tenants.
+**`GET /api/v1/admin/tenants/{id}`** / **`PUT .../{id}`** / **`DELETE .../{id}`**
+**`POST /api/v1/admin/tenants/reset`** — `{ "tenant_id": "acme-docs" }`
+**`POST /api/v1/admin/users`** — Create tenant user.
+**`GET /api/v1/admin/users`** — List users.
+**`DELETE /api/v1/admin/users/{id}`**
+**`PUT /api/v1/admin/users/{id}/role`** — `{ "role": "editor" }`
+
+---
+
+# Platform authentication
+
+**Base path:** `/api/v1/platform/auth`
+
+**`GET .../registration-config`** — Public: registration policy.
+**`POST .../login`** — `{ "email": "...", "password": "..." }`
+**`POST .../register`** — Create platform user.
+**`POST .../refresh`** — Refresh JWT.
+**`POST .../logout`** — Invalidate session.
+**`GET .../me`** / **`PUT .../me`** — Profile.
+**`POST .../change-password`** — `{ current_password, new_password }`
+**`POST .../forgot-password`** / **`POST .../reset-password`** / **`POST .../verify-email`** — Email flows.
+**`GET .../workspaces`** — List orgs/projects.
+
+---
+
+# Platform admin
+
+**Base path:** `/api/v1/platform/admin`
+
+## Users
+**`GET .../users`** / **`POST .../users`** / **`GET .../users/{id}`** / **`PUT .../users/{id}`** / **`DELETE .../users/{id}`**
+Moderation: **`POST .../users/{id}/approve|reject|suspend|activate`**
+
+## Invites
+**`GET .../invites`** / **`POST .../invites`** / **`DELETE .../invites/{code}`**
+
+## Config
+**`GET .../config`** / **`PUT .../config`**
+
+## IP access control
+**`GET .../ip-access`** / **`PUT .../ip-access`**
+
+## Rate limits
+**`GET .../rate-limits`** / **`PUT .../rate-limits`**
+
+---
+
+# Platform organizations
+
+**Base path:** `/api/v1/platform/orgs`
+
+**`GET .../`** / **`POST .../`** — `{ "name": "Acme Corp", "slug": "acme" }`
+**`GET .../{org_id}`** / **`PUT .../{org_id}`** / **`DELETE .../{org_id}`**
+**Members:** **`GET .../{org_id}/members`** / **`POST`** / **`PUT .../{member_id}`** / **`DELETE .../{member_id}`**
+**Projects:** **`GET .../{org_id}/projects`** / **`POST .../{org_id}/projects`**
+
+## Member-scoped org API (`/api/v1/orgs`)
+For logged-in users (not only platform admins):
+**`GET /api/v1/orgs`** / **`GET .../{org_id}`** / **`GET .../{org_id}/members`** / **`POST .../{org_id}/members`** / **`PUT .../{org_id}/members/{id}`** / **`DELETE .../{org_id}/members/{id}`** / **`GET .../{org_id}/projects`** / **`POST .../{org_id}/projects`**
+
+---
+
+# Platform projects
+
+**Base path:** `/api/v1/platform/projects`
+
+**`GET .../{project_id}`** / **`PUT .../{project_id}`** / **`DELETE .../{project_id}`**
+**Members:** **`GET .../{project_id}/members`** / **`POST`** / **`PUT .../{member_id}`** / **`DELETE .../{member_id}`**
+
+---
+
+# Platform backups
+
+**Base path:** `/api/v1/platform/admin/backup`
+
+**`GET .../config`** / **`PUT .../config`**
+**`POST .../config/test`** — Test destination.
+**`GET .../list`** — List backups.
+**`POST .../run`** — Start backup.
+**`GET .../status`** — Job progress.
+**`POST .../restore`** — `{ "backup_id": "platform-2025-01-20T00-00-00Z" }`
+
+---
+
+# Part 3: SDK Reference
+
+# JavaScript/TypeScript SDK (`@xcitedbs/client`)
+
+Install: `npm install @xcitedbs/client`
+
+## Quick Start
+
+```typescript
+import { XCiteDBClient } from '@xcitedbs/client';
+
+const client = new XCiteDBClient({
+  baseUrl: 'http://localhost:8080',
+  apiKey: 'your-api-key',
+  context: { branch: '', date: '' },
+});
+
+// Health check
+await client.health();
+
+// Write XML document
+await client.writeXmlDocument(
+  '<chapter db:identifier="/manual/v1/intro"><title>Introduction</title></chapter>'
+);
+
+// Read document by identifier
+const xml = await client.queryByIdentifier('/manual/v1/intro', 'FirstMatch');
+
+// Write JSON document
+await client.writeJsonDocument('app.settings', { theme: 'dark' });
+
+// Read JSON document
+const settings = await client.readJsonDocument('app.settings');
+
+// Branch, edit, commit, merge
+await client.createBranch('feature-x');
+client.setContext({ branch: 'feature-x' });
+await client.writeJsonDocument('app.settings', { theme: 'light' });
+await client.createCommit('Switch to light theme');
+await client.mergeBranch('', 'feature-x');
+```
+
+## Constructor Options
+
+```typescript
+interface XCiteDBClientOptions {
+  baseUrl: string;
+  apiKey?: string;
+  accessToken?: string;
+  appUserAccessToken?: string;
+  appUserRefreshToken?: string;
+  context?: DatabaseContext;
+  platformConsole?: boolean;
+  projectId?: string;
+  onSessionTokensUpdated?: (pair: TokenPair) => void;
+  onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
+  onSessionInvalid?: () => void;
+}
+
+interface DatabaseContext {
+  branch?: string;   // '' = default (root timeline)
+  date?: string;     // Point-in-time
+  prefix?: string;   // Identifier prefix filter
+  unversioned?: boolean; // Sends X-Unversioned: true (flat writes; do not combine with date)
+  project_id?: string; // Preferred: project id for app-user public auth (`tenant_id` on wire)
+  tenant_id?: string; // Deprecated alias of project_id
+}
+```
+
+## Complete Method List
+
+### Health & Version
+- `health()` → `{ status, timestamp? }`
+- `version()` → `{ version, server, api_version }`
+
+### Platform Auth
+- `platformLogin(email, password)` → `TokenPair`
+- `login(email, password)` → `TokenPair` — **deprecated**; use `platformLogin` (operator) or `loginAppUser` (end-user)
+- `refresh()` → `TokenPair`
+- `logout()` → `void`
+- `me()` → `UserInfo`
+- `platformRegister(body)` → `PlatformRegisterResult`
+- `platformRegistrationConfig()` → `PlatformRegistrationConfig`
+- `platformWorkspaces()` → `PlatformWorkspacesResponse`
+- `listMyProjects()` → `ProjectInfo[]` — preferred
+- `listMyTenants()` → `ProjectInfo[]` — **deprecated**; same as `listMyProjects`
+- `switchProject(projectId)` → `void` (platform console only) — preferred
+- `switchTenant(tenantId)` → `void` — **deprecated**; same as `switchProject`
+- `changePassword(current, new)` → `void`
+
+### Context & Configuration
+- `setContext(ctx: DatabaseContext)` → `void`
+- `setProjectId(projectId)` → `void`
+- `setTokens(access, refresh?)` → `void`
+- `setAppUserTokens(access, refresh?)` → `void`
+- `clearAppUserTokens()` → `void`
+
+### XML Documents
+- `writeXmlDocument(xml, options?)` → `void` — XML via JSON body (recommended). Deprecated: `writeDocumentJson`.
+- `writeXML(xml)` → `void` — Raw XML body
+- `queryByIdentifier(identifier, flags?, filter?, pathFilter?)` → `string[]`
+- `queryDocuments(query: XCiteQuery, flags?, filter?, pathFilter?)` → `string[]`
+- `deleteDocument(identifier)` → `void`
+- `listIdentifiers(query: XCiteQuery)` → `ListIdentifiersResult`
+- `listIdentifierChildren(parentPath?)` → `ListIdentifierChildrenResult`
+- `addIdentifier(identifier)` → `boolean`
+- `addAlias(original, alias)` → `boolean`
+- `queryChangeDate(identifier)` → `string`
+- `getXcitepath(identifier)` → `string`
+- `changedIdentifiers(branch, fromDate?, toDate?)` → `string[]`
+- `queryLog(query, fromDate, toDate)` → `LogEntry[]`
+
+### JSON Documents
+- `writeJsonDocument(identifier, data)` → `void`
+- `readJsonDocument<T>(identifier)` → `T` (default `unknown`)
+- `deleteJsonDocument(identifier)` → `void`
+- `listJsonDocuments(match?, limit?, offset?)` → `ListIdentifiersResult`
+- `put(identifier, data)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases
+
+### Metadata
+- `addMeta(identifier, value, path?, opts?)` → `boolean`
+- `addMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
+- `appendMeta(identifier, value, path?)` → `boolean`
+- `appendMetaByQuery(query, value, path?, firstMatch?)` → `boolean`
+- `queryMeta<T>(identifier, path?)` → `T`
+- `queryMetaByQuery<T>(query, path?)` → `T`
+- `clearMeta(query)` → `boolean`
+
+### Branches
+- `withBranch(name, fn, options?)` → `{ result, commit?, merge? }` — branch, callback, commit, merge back
+- `createBranch(name, fromBranch?, fromDate?)` → `void`
+- `listBranches()` → `BranchInfo[]`
+- `getBranch(name)` → `BranchInfo`
+- `deleteBranch(name)` → `void`
+- `deleteRevision(branch, date)` → `void`
+- `mergeBranch(targetBranch, sourceBranch, options?)` → `MergeResult`
+
+### Commits
+- `createCommit(message, author?)` → `CommitRecord`
+- `listCommits(options?)` → `{ commits, total, branch }`
+- `getCommit(commitId)` → `CommitRecord`
+- `rollbackToCommit(commitId)` → `{ rolled_back_commits, current_tip }`
+- `cherryPick(commitId, message?, author?)` → `CommitRecord`
+
+### Tags
+- `createTag(name, commitId, message?, author?)` → `TagRecord`
+- `listTags(options?)` → `{ tags, total }`
+- `getTag(name)` → `TagRecord`
+- `deleteTag(name)` → `void`
+
+### Diff
+- `diff(from: DiffRef, to: DiffRef, includeContent?)` → `DiffResult`
+
+### Locks
+- `acquireLock(identifier, expires?)` → `LockInfo`
+- `releaseLock(identifier, lockId)` → `boolean`
+- `findLocks(identifier)` → `LockInfo[]`
+
+### Search
+- `search(query: TextSearchQuery)` → `TextSearchResult`
+- `reindex()` → `{ status, message }`
+
+### Unquery
+- `unquery<T>(query: XCiteQuery, unqueryDoc)` → `T`
+
+### Security Policies
+- `createPolicy(policyId, policy: SecurityPolicy)` → `StoredPolicyResponse`
+- `listPolicies()` → `Record<string, SecurityPolicy>`
+- `getPolicy(policyId)` → `StoredPolicyResponse`
+- `updatePolicy(policyId, policy)` → `PolicyUpdateResponse`
+- `deletePolicy(policyId)` → `void`
+- `checkAccess(subject, identifier, action, metaPath?, branch?)` → `AccessCheckResult`
+- `getSecurityConfig()` → `SecurityConfig`
+- `updateSecurityConfig(config)` → `void`
+
+### Triggers
+- `upsertTrigger(triggerId, trigger)` → `StoredTriggerResponse`
+- `listTriggers()` → `Record<string, TriggerDefinition>`
+- `getTrigger(name)` → `StoredTriggerResponse`
+- `deleteTrigger(name)` → `void`
+
+### App User Auth
+- `registerAppUser(email, password, displayName?, groups?, attributes?)` → `AppUser`
+- `loginAppUser(email, password)` → `AppUserTokenPair`
+- `refreshAppUser()` → `AppUserTokenPair`
+- `logoutAppUser()` → `void`
+- `appUserMe()` → `AppUser`
+- `updateAppUserProfile(displayName?, attributes?)` → `AppUser`
+- `changeAppUserPassword(current, new)` → `void`
+- `forgotAppUserPassword(email)` → `ForgotPasswordResponse`
+- `resetAppUserPassword(token, newPassword)` → `void`
+- `sendAppUserVerification(userId)` → `SendVerificationResponse`
+- `verifyAppUserEmail(token)` → `void`
+- `exchangeCustomToken(token)` → `AppUserTokenPair`
+- `getOAuthProviders()` → `OAuthProvidersResponse`
+- `oauthAuthorizePath(provider)` → `string`
+- `exchangeOAuthCode(code)` → `AppUserTokenPair`
+- `getAppAuthConfig()` → `AppAuthConfig`
+
+### App User Management (admin)
+- `listAppUsers()` → `AppUser[]`
+- `getAppUser(userId)` → `AppUser`
+- `createAppUser(email, password, displayName?, groups?, attributes?)` → `AppUser`
+- `deleteAppUser(userId)` → `void`
+- `updateAppUserGroups(userId, groups)` → `void`
+- `updateAppUserStatus(userId, status)` → `void`
+
+### Email Config
+- `getEmailConfig()` → `AppEmailConfig`
+- `updateEmailConfig(config)` → `AppEmailConfig`
+- `getEmailTemplates()` → `AppEmailTemplates`
+- `updateEmailTemplates(templates)` → `AppEmailTemplates`
+- `sendTestEmail(to)` → `EmailTestResponse`
+
+### API Keys
+- `listApiKeys()` → `ApiKeyInfo[]`
+- `createApiKey(name, expiresAt?, keyType?)` → `unknown`
+- `revokeApiKey(keyId)` → `void`
+
+### WebSocket
+- `subscribe(options: SubscriptionOptions, callback, onError?)` → `WebSocketSubscription`
+
+## Key Types
+
+```typescript
+interface XCiteQuery {
+  match?: string;
+  match_start?: string;
+  match_end?: string;
+  contains?: string | string[];
+  regex?: string;
+  required_meta_paths?: string[];
+  filter_any_meta?: boolean;
+  limit?: number;
+  offset?: number;
+}
+
+type Flags = 'None' | 'FirstMatch' | 'IncludeChildren' | 'NoChildren' | 'KeepIndexNodes' | string;
+
+interface WriteDocumentOptions {
+  is_top?: boolean;
+  compare_attributes?: boolean;
+}
+
+interface SubscriptionOptions {
+  pattern: string;      // e.g. '/manual/*'
+  event_type?: string;  // e.g. '*'
+}
+```
+
+## Errors
+
+```typescript
+class XCiteDBError extends Error {
+  status: number;  // HTTP status code
+  body?: unknown;  // Parsed response body
+}
+```
+
+---
+
+# Python SDK (`xcitedb`)
+
+Install: `pip install xcitedb`
+
+```python
+import asyncio
+from xcitedb import (
+    XCiteDBClient,
+    XCiteQuery,
+    DatabaseContext,
+    TextSearchQuery,
+)
+
+async def main():
+    async with XCiteDBClient(
+        "http://localhost:8080",
+        api_key="your-key",
+        context=DatabaseContext(branch="", date=""),
+    ) as client:
+        print(await client.health())
+        print(await client.query_documents(XCiteQuery(match_start="/manual/")))
+        await client.write_json_document("app.settings", {"theme": "dark"})
+        print(await client.read_json_document("app.settings"))
+        print(await client.list_identifiers(XCiteQuery(match_start="/manual/")))
+        print(await client.search(TextSearchQuery(query="guide", limit=10)))
+        await client.platform_login("admin@localhost", "password")
+        # await client.login_app_user("user@example.com", "pw")  # set context.project_id / tenant_id if needed
+        async with client.with_branch("feature-x", message="WIP", auto_merge=True):
+            await client.put("app.settings", {"theme": "light"})
+
+asyncio.run(main())
+```
+
+Async client: `write_xml_document` / `write_document_json` (deprecated), `write_json_document`, `read_json_document`, `list_json_documents`, `list_identifiers`, `search`, `reindex`, `platform_login` / `login` (deprecated), `login_app_user`, `refresh_app_user`, `logout_app_user`, `register_app_user`, `put` / `get` / `remove` / `list_documents` (JSON aliases), `with_branch` (async context manager).
+
+---
+
+# C++ SDK (`xcitedb`)
+
+```cpp
+#include <xcitedb/xcitedb.hpp>
+
+xcitedb::XCiteDBClientOptions opt;
+opt.base_url = "http://127.0.0.1:8080";
+opt.api_key = "your-key";
+opt.context.branch = "";  // root timeline
+
+xcitedb::XCiteDBClient client(opt);
+auto health = client.health();
+
+xcitedb::XCiteQuery q;
+q.match_start = "/manual/";
+auto ids = client.query_documents(q);
+```
+
+Synchronous (blocking) HTTP client. Methods mirror the JavaScript SDK with C++ naming (`write_xml_document`, deprecated `write_document_json`). Errors throw `xcitedb::XCiteDBError` with `.status()` and `.body()`.
+
+Includes optional `xcitevcs` CLI for command-line operations (branches, commits, documents, search, import/export).