@xcitedbs/client 0.2.9 → 0.2.11

package/llms-full.txt

@@ -8,13 +8,13 @@
 
 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.
+1. **The default workspace is the empty string `""`, not `"main"`.** When no `X-Workspace` header is sent (or `context.workspace` / `context.branch` is omitted/empty), the server operates on the root timeline. `X-Branch` is a supported alias of `X-Workspace`. A workspace named `"main"` may exist as user-created metadata, 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.
+4. **Context (workspace + date) travels as HTTP headers** (`X-Workspace` preferred, `X-Branch` alias, `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.
 
@@ -28,6 +28,16 @@ Before reading the full reference, note these critical differences from typical
 
 10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
 
+## Choosing the Right Versioning Approach
+
+- **Write at a specific date:** Set `X-Date` / `context.date` and write — every dated write is a **temporal revision**; no workspace or checkpoint required.
+- **Read as-of a date:** Set `X-Date` and read; the engine returns the revision at or before that instant.
+- **Isolated editing (draft → publish):** Create a **workspace**, edit, then **publish** to the target timeline; optional **checkpoints** for named snapshots.
+- **Audit trail:** Checkpoints carry messages and affected identifiers; **bookmarks** name a checkpoint.
+- **Undo a batch:** **Revert** to a prior checkpoint on that workspace.
+
+Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
+
 ## Common Pitfalls
 
 1. **`baseUrl` must be origin-only (no `/api` or `/api/v1` path).** The SDK prepends `/api/v1/…` to every request. If `baseUrl` is `https://host/api/v1`, requests hit `/api/v1/api/v1/…` which typically returns **405 Not Allowed** from the reverse proxy. Use only the scheme + host + optional port: `https://host` or `http://localhost:8080`.
@@ -65,25 +75,25 @@ Before reading the full reference, note these critical differences from typical
 ### 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.
+**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, indexed by path, and fully queryable through the same Unquery analytics engine — with **temporal revisions**, **workspaces**, and **checkpoints** when you need collaborative workflow.
 
 ### 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.
+XciteDB bridges this gap. It provides **temporal versioning plus optional workspaces and checkpoints** 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.
+- **Collaborative Content Management:** Systems requiring isolated workspaces, publish workflows, 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.
+- **First-Class XML & JSON:** Both formats are shredded, indexed by path, versioned, 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.
+- **Document-centric versioning:** Temporal revisions (`X-Date`), workspaces, checkpoints, bookmarks, compare, publish, revert, and apply — plus time-travel reads.
 - **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.
@@ -106,10 +116,10 @@ XciteDB shines in domains requiring strict auditability, collaborative authoring
 - **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**).
+### 2.3 Document versioning model
+- **Temporal revisions & workspaces:** Every write with `X-Date` records under that revision instant. **Workspaces** isolate draft edits from the root timeline.
+- **Checkpoints, publish, apply, revert:** Optional named snapshots (**checkpoints**); **publish** merges a workspace into a target; **apply** brings another checkpoint’s changes; **revert** rolls the workspace back to a checkpoint.
+- **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
@@ -142,7 +152,8 @@ Welcome to the **XciteDB HTTP API**. This reference describes REST endpoints und
 |--------|------|-------------|
 | `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-Workspace` | Optional | Active workspace name for document and versioning operations (preferred) |
+| `X-Branch` | Optional | Deprecated alias of `X-Workspace` |
 | `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). |
 
@@ -241,8 +252,8 @@ describe('XciteDB integration', () => {
     expect(xml).toContain('<title>Hello</title>');
   });
 
-  it('creates a branch, commits, and merges', async () => {
-    await client.withBranch('feature-test', async (c) => {
+  it('creates a workspace, checkpoints, and publishes', async () => {
+    await client.withWorkspace('feature-test', async (c) => {
       await c.writeJsonDocument('test.feature', { active: true });
     }, { message: 'Add feature flag', autoMerge: true });
     const doc = await client.readJsonDocument<{ active: boolean }>('test.feature');
@@ -283,8 +294,8 @@ async def test_xml_document(db):
     assert "<title>Hello</title>" in result
 
 @pytest.mark.asyncio
-async def test_branch_and_merge(db):
-    async with db.with_branch("feature-test", message="Add flag", auto_merge=True):
+async def test_workspace_and_publish(db):
+    async with db.with_workspace("feature-test", message="Add flag", auto_merge=True):
         await db.put("test.feature", {"active": True})
     doc = await db.get("test.feature")
     assert doc["active"] is True
@@ -680,100 +691,107 @@ Dry-run: **`POST /api/v1/security/check`** with `subject`, `identifier`, `action
 
 ---
 
-# Branches
+# Workspaces (branches)
 
-**Base path:** `/api/v1/branches`
+**Preferred base path:** `/api/v1/workspaces`  
+**Deprecated alias:** `/api/v1/branches` (same handlers)
 
-**IMPORTANT: The default branch is the empty string `""`.** When no branch is specified, the server uses the root timeline.
+**IMPORTANT: The default workspace is the empty string `""`.** When no workspace is specified, the server uses the root timeline.
 
-## List branches
+## List workspaces
 
-**`GET /api/v1/branches`** — Returns `{ branches: [{ name, from_branch, from_date, from_date_key, tip_commit }] }`.
+**`GET /api/v1/workspaces`** — Returns `{ workspaces: [...], branches: [...] }` where each item includes `name`, `from_branch`, `from_date`, `tip_checkpoint` (and `tip_commit` mirror).
 
-## Create branch
+## Create workspace
 
-**`POST /api/v1/branches`** — `{ "name": "feature-x", "from_branch": "", "from_date": "" }`
+**`POST /api/v1/workspaces`** — `{ "name": "feature-x", "from_branch": "", "from_date": "" }`
 
-## Get branch
+## Get workspace
 
-**`GET /api/v1/branches/{name}`** — Returns `{ branch: {...} }`.
+**`GET /api/v1/workspaces/{name}`** — Returns `{ workspace: {...}, branch: {...} }`.
 
-## Delete branch
+## Delete workspace
 
-**`DELETE /api/v1/branches/{name}`**
+**`DELETE /api/v1/workspaces/{name}`**
 
-## Merge branch
+## Publish workspace
 
-**`POST /api/v1/branches/{target}/merge`**
+**`POST /api/v1/workspaces/{target}/publish`**
 
 ```json
 {
+  "source_workspace": "feature-x",
   "source_branch": "feature-x",
-  "message": "Merge feature",
+  "message": "Publish feature",
   "auto_resolve": "none"
 }
 ```
 
 `auto_resolve`: `"none"` | `"source"` | `"target"`.
 
-Returns `{ status: "completed"|"conflicts", commit?, merged_identifiers?, conflicts? }`.
+Returns `{ status: "completed"|"conflicts", checkpoint?, commit?, merged_identifiers?, conflicts? }` (`commit` mirrors `checkpoint`).
 
-## Delete revision on branch
+## Delete revision on workspace
 
-**`DELETE /api/v1/branches/{name}/revisions/{date}`**
+**`DELETE /api/v1/workspaces/{name}/revisions/{date}`** (human-readable date in path; legacy `/branches/...` path still works)
 
 ---
 
-# Commits, tags & diff
+# Checkpoints, bookmarks & compare
 
-## Create commit
+## Create checkpoint
 
-**`POST /api/v1/commits`** — `{ "message": "...", "author": "..." }`
+**`POST /api/v1/checkpoints`** — `{ "message": "...", "author": "..." }`  
+(Deprecated: **`POST /api/v1/commits`**)
 
-Returns `{ commit: { id, branch, date_key, message, author, ... } }`.
+Returns `{ checkpoint: { id, checkpoint_id, branch, date, message, author, ... }, commit: <same> }`. Public JSON uses human-readable **`date`** (no `date_key`).
 
-## List commits
+## List checkpoints
 
-**`GET /api/v1/commits?branch=...&limit=...&offset=...`**
+**`GET /api/v1/checkpoints?branch=...&limit=...&offset=...`** (query param name unchanged; means workspace)  
+Returns `{ checkpoints: [...], commits: [...], total, branch }` (mirrors).
 
-Returns `{ commits: [...], total, branch }`.
+## Get checkpoint
 
-## Get commit
+**`GET /api/v1/checkpoints/{id}`** — Returns `{ checkpoint, commit }`.
 
-**`GET /api/v1/commits/{id}`** — Returns `{ commit: {...} }`.
+## Revert to checkpoint
 
-## Rollback to commit
+**`POST /api/v1/checkpoints/{id}/revert`** — `{ "confirm": true }`  
+(Deprecated: **`.../rollback`**)
 
-**`POST /api/v1/commits/{id}/rollback`** — `{ "confirm": true }`
+## Apply checkpoint
 
-## Cherry-pick commit
+**`POST /api/v1/checkpoints/{id}/apply`** — `{ "message": "...", "author": "..." }`  
+(Deprecated: **`.../cherry-pick`**)
 
-**`POST /api/v1/commits/{id}/cherry-pick`** — `{ "message": "...", "author": "..." }`
+## Create bookmark
 
-## Create tag
+**`POST /api/v1/bookmarks`** — `{ "name": "v1.0", "checkpoint_id": "...", "commit_id": "...", "message": "..." }`  
+(Deprecated: **`POST /api/v1/tags`**)
 
-**`POST /api/v1/tags`** — `{ "name": "v1.0", "commit_id": "...", "message": "..." }`
+## List bookmarks
 
-## List tags
+**`GET /api/v1/bookmarks?limit=...&offset=...`** — Returns `{ bookmarks: [...], tags: [...], total }` (mirrors where applicable).
 
-**`GET /api/v1/tags?limit=...&offset=...`** — Returns `{ tags: [...], total }`.
+## Get / Delete bookmark
 
-## Get / Delete tag
+**`GET /api/v1/bookmarks/{name}`** / **`DELETE /api/v1/bookmarks/{name}`** (deprecated `/tags/...`)
 
-**`GET /api/v1/tags/{name}`** / **`DELETE /api/v1/tags/{name}`**
+## Compare
 
-## Diff
-
-**`POST /api/v1/diff`**
+**`POST /api/v1/compare`**
 
 ```json
 {
-  "from": { "branch": "", "date_key": "..." },
+  "from": { "branch": "", "date": "2024-01-15T00:00:00" },
   "to": { "branch": "feature-x" },
   "include_content": true
 }
 ```
 
+(Deprecated: **`POST /api/v1/diff`**; `date_key` still accepted internally but prefer **`date`**.)
+
 Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_content?, to_content? }], total_changes }`.
 
 ---
@@ -1243,7 +1261,7 @@ import { XCiteDBClient } from '@xcitedbs/client';
 const client = new XCiteDBClient({
   baseUrl: 'http://localhost:8080',
   apiKey: 'your-api-key',
-  context: { branch: '', date: '' },
+  context: { workspace: '', date: '' },
 });
 
 // Health check
@@ -1263,12 +1281,12 @@ 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' });
+// Workspace, edit, checkpoint, publish
+await client.createWorkspace('feature-x');
+client.setContext({ workspace: 'feature-x' });
 await client.writeJsonDocument('app.settings', { theme: 'light' });
-await client.createCommit('Switch to light theme');
-await client.mergeBranch('', 'feature-x');
+await client.createCheckpoint('Switch to light theme');
+await client.publishWorkspace('', 'feature-x');
 ```
 
 ## Constructor Options
@@ -1289,7 +1307,8 @@ interface XCiteDBClientOptions {
 }
 
 interface DatabaseContext {
-  branch?: string;   // '' = default (root timeline)
+  workspace?: string; // '' = default (root timeline); preferred
+  branch?: string;    // @deprecated alias of workspace
   date?: string;     // Point-in-time
   prefix?: string;   // Identifier prefix filter
   unversioned?: boolean; // Sends X-Unversioned: true (flat writes; do not combine with date)
@@ -1357,30 +1376,34 @@ interface DatabaseContext {
 - `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`
+### Workspaces & checkpoints
+- `withWorkspace(name, fn, options?)` → `{ result, checkpoint?, publish? }` — workspace, callback, checkpoint, publish back
+- `createWorkspace(name, fromBranch?, fromDate?)` → `void`
+- `listWorkspaces()` → `WorkspaceInfo[]`
+- `getWorkspace(name)` → `WorkspaceInfo`
+- `deleteWorkspace(name)` → `void`
+- `deleteRevision(branch, date)` → `void` (workspace name + human date)
+- `publishWorkspace(targetWorkspace, sourceWorkspace, options?)` → `PublishResult`
+- **Deprecated:** `withBranch`, `createBranch`, `listBranches`, `getBranch`, `deleteBranch`, `mergeBranch` (same HTTP behavior)
+
+### Checkpoints
+- `createCheckpoint(message, author?)` → `CheckpointRecord`
+- `listCheckpoints(options?)` → `{ checkpoints, total, branch }` (wire JSON may also include `commits` mirror)
+- `getCheckpoint(checkpointId)` → `CheckpointRecord`
+- `revertToCheckpoint(checkpointId)` → `{ rolled_back_checkpoints, rolled_back_commits?, current_tip }`
+- `applyCheckpoint(checkpointId, message?, author?)` → `CheckpointRecord`
+- **Deprecated:** `createCommit`, `listCommits`, `getCommit`, `rollbackToCommit`, `cherryPick`
+
+### Bookmarks
+- `createBookmark(name, checkpointId, message?, author?)` → `BookmarkRecord`
+- `listBookmarks(options?)` → `{ bookmarks, tags, total, limit?, offset? }`
+- `getBookmark(name)` → `BookmarkRecord`
+- `deleteBookmark(name)` → `void`
+- **Deprecated:** `createTag`, `listTags`, `getTag`, `deleteTag`
+
+### Compare
+- `compare(from: CompareRef, to: CompareRef, includeContent?)` → `CompareResult`
+- **Deprecated:** `diff(from: DiffRef, …)` — alias of `compare`
 
 ### Locks
 - `acquireLock(identifier, expires?)` → `LockInfo`
@@ -1513,7 +1536,7 @@ async def main():
     async with XCiteDBClient(
         "http://localhost:8080",
         api_key="your-key",
-        context=DatabaseContext(branch="", date=""),
+        context=DatabaseContext(workspace="", date=""),
     ) as client:
         print(await client.health())
         print(await client.query_documents(XCiteQuery(match_start="/manual/")))
@@ -1523,13 +1546,13 @@ async def main():
         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):
+        async with client.with_workspace("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).
+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_workspace` (async context manager; `with_branch` deprecated alias).
 
 ---
 
@@ -1541,7 +1564,7 @@ Async client: `write_xml_document` / `write_document_json` (deprecated), `write_
 xcitedb::XCiteDBClientOptions opt;
 opt.base_url = "http://127.0.0.1:8080";
 opt.api_key = "your-key";
-opt.context.branch = "";  // root timeline
+opt.context.workspace = "";  // root timeline (`branch` is deprecated alias)
 
 xcitedb::XCiteDBClient client(opt);
 auto health = client.health();
@@ -1553,4 +1576,4 @@ 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).
+Includes optional `xcitevcs` CLI for command-line operations (legacy branch/commit vocabulary on the wire, documents, search, import/export).