@xcitedbs/client 0.2.9 → 0.2.11

package/llms.txt

@@ -1,18 +1,18 @@
 # XciteDB
 
-> XciteDB is a versioned XML and JSON document database delivered as a Backend-as-a-Service (BaaS). It provides Git-like branching, commits, time-travel, and hierarchical document identifiers over a high-performance embedded LMDB engine, exposed through a REST + WebSocket API.
+> XciteDB is a versioned XML and JSON document database delivered as a Backend-as-a-Service (BaaS). It provides **temporal revisions** (every dated write is a revision), **workspaces** for isolated editing, **checkpoints** for optional named snapshots, time-travel reads, and hierarchical document identifiers over a high-performance embedded LMDB engine, exposed through a REST + WebSocket API.
 
 ## Important: Non-Standard Conventions
 
 These are the most common sources of confusion for developers and AI assistants:
 
-1. **The default branch is the empty string `""`, not `"main"`.** When no `X-Branch` header is sent (or `context.branch` is omitted/empty in the SDK), 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 in the SDK), 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 (like a filesystem). The server indexes this hierarchy natively.
 
 3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type, stored with structural shredding. JSON documents are a parallel store keyed by identifier string. Both are fully versioned.
 
-4. **Context (branch + date) travels as HTTP headers**, not URL path segments. Use `X-Branch` and `X-Date` headers (or the SDK `context` option) to select which branch and point-in-time you are reading/writing.
+4. **`X-Date` and temporal revision (not “only now”).** Workspace and date context travel as HTTP headers (`X-Workspace` preferred, `X-Branch` alias, `X-Date`), or the SDK `context` option — not as URL path segments. **`X-Date` is not limited to the current server time.** Pass any instant you need as **ISO 8601** (e.g. `2024-01-15T00:00:00`) or **`mm/dd/yyyy`** (optional **`:HH:MM:SS`**) — for example an **official publication or approval date**, or any historical “as of” moment. When **`X-Date` is set**, that value applies to **both** **reads** (query as-of that instant) **and** **writes** (the new revision is stored under that revision instant). When **`X-Date` is omitted** and you do **not** send **`X-Unversioned: true`**, **writes** use **flat** keys (no date suffix on that write); **reads** still resolve **as of the current time**. **`X-Unversioned: true`** requests explicit flat keys and must **not** be combined with **`X-Date`** (the server returns 400).
 
 5. **XML documents carry their identifier inside the XML** — specifically via a `db:identifier` attribute on the root element (e.g. `<chapter db:identifier="/book/ch1">...</chapter>`). When writing XML, the server extracts the identifier from the document body.
 
@@ -24,6 +24,20 @@ These are the most common sources of confusion for developers and AI assistants:
 
 9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). The test DB starts **empty** (no copy of production project config or keys).
 
+## Choosing the Right Versioning Approach
+
+- **Write at a specific date** (law effective date, publication date, approval date): Set `context.date` / `X-Date` and write. No workspaces or checkpoints needed. Every write with a date creates a **temporal revision** automatically.
+
+- **Read historical data** (“what was the document on March 1, 2024?”): Set `context.date` / `X-Date` and read. The engine returns the revision at or before that instant.
+
+- **Isolated editing** (draft/review/publish): Create a **workspace**, make changes, then **publish** to the main timeline. Optionally create **checkpoints** for named snapshots within the workspace.
+
+- **Audit trail with named snapshots:** Create checkpoints with messages. List/inspect checkpoints for history.
+
+- **Undo a batch of changes:** **Revert** to a prior checkpoint (removes all changes after that point on the workspace).
+
+Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
+
 ## Glossary: Project id, display name, and groups
 
 - **Project display name** (human-readable, e.g. `invoices`): Shown in the console. The **`X-Project-Id`** header may match either this name **or** the internal project id (server convenience). Do **not** put the display name in JWT claims or in `project:<…>:role` group strings.
@@ -54,6 +68,8 @@ These are the most common sources of confusion for developers and AI assistants:
 
 11. **Integration tests should assert token claims**, not only **`/app/auth/me`**. The profile endpoint can look fine while the JWT still carries viewer-style **`groups`**; for ABAC the token payload is authoritative. Use **`getTokenClaims()`** (JS SDK) or decode the JWT in your harness.
 
+12. **`X-Date` / `context.date` is not “server clock only.”** Revisions are keyed by the **instant you send**, not an implicit “now” when you set the header. To record a document under a **business date** (published, approved, effective), set **`X-Date`** or **`context.date`** to that instant before writing. Omitting **`X-Date`** does **not** substitute the current time on the write path — it selects **flat** writes (see convention 4).
+
 ## API key capability matrix (typical)
 
 | Capability | API key `role` | Public key allowed? |
@@ -90,7 +106,7 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 > **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised.
 
 1. **Provision:** `POST /api/v1/test/sessions` with `Authorization: Bearer …` or `X-API-Key` (same as normal API access). Response JSON includes the session token.
-2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Branch` / `context` as needed). Data is stored under the server’s `_test/<session>/` area, not your production tenant.
+2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Workspace` / `context` as needed). Data is stored under the server’s `_test/<session>/` area, not your production tenant.
 3. **Auth behavior:** Developer auth (API key / platform JWT) is bypassed by default for frictionless tests. **App-user identity** (`X-App-User-Token` or Bearer app-user JWT) **is still recognized** in default mode, so `registerAppUser` → `loginAppUser` → `appUserMe` works inside a test session. To also exercise developer auth and ABAC policies, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
 5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or manual token + `test_session_token` / `test_require_auth` constructor args. **C++:** `XCiteDBClient::create_test_session(options)`, `destroy_test_session()`, optional `test_require_auth` in options.
@@ -107,15 +123,15 @@ import { XCiteDBClient } from '@xcitedbs/client';
 const client = new XCiteDBClient({
   baseUrl: 'http://localhost:8080',
   apiKey: 'your-api-key',
-  // branch: '' means root timeline (the default); omit or use '' for default
-  context: { branch: '', date: '' },
+  // workspace: '' means root timeline (the default); omit or use '' for default
+  context: { workspace: '', date: '' },
 });
 
 // Health check (no auth required)
 await client.health();
 
-// List all branches
-const branches = await client.listBranches();
+// List all workspaces
+const workspaces = await client.listWorkspaces();
 
 // Query documents by identifier prefix
 const docs = await client.queryDocuments({ match_start: '/manual/' });
@@ -140,18 +156,18 @@ const prefs = await client.get<Record<string, unknown>>('app.prefs');
 await client.remove('app.prefs');
 const keys = await client.list(undefined, 50, 0);
 
-// Branch helper: create branch, run work, commit, merge back (restores context)
-await client.withBranch('feature-x', async (c) => {
+// Workspace helper: create workspace, run work, checkpoint, publish back (restores context)
+await client.withWorkspace('feature-x', async (c) => {
   await c.writeJsonDocument('app.settings', { theme: 'light' });
   return 'ok';
 }, { message: 'Light theme', autoMerge: true, fromBranch: '' });
 
-// Create a branch, make changes, commit, merge
-await client.createBranch('feature-x');
-client.setContext({ branch: 'feature-x' });
+// Create a workspace, make changes, checkpoint, publish
+await client.createWorkspace('feature-x');
+client.setContext({ workspace: 'feature-x' });
 await client.writeJsonDocument('app.settings', { theme: 'light' });
-const commit = await client.createCommit('Switch to light theme');
-await client.mergeBranch('', 'feature-x'); // merge into root (default) branch
+const checkpoint = await client.createCheckpoint('Switch to light theme');
+await client.publishWorkspace('', 'feature-x'); // publish into root (default) workspace
 
 // Attach JSON metadata to a document
 await client.addMeta('/manual/v1/intro', { status: 'draft', owner: 'alice' });
@@ -180,8 +196,9 @@ interface XCiteDBClientOptions {
   accessToken?: string;         // Platform JWT (from platformLogin)
   appUserAccessToken?: string;  // End-user JWT (from loginAppUser)
   context?: {
-    branch?: string;   // Branch name; '' = default/root timeline
-    date?: string;     // Point-in-time (ISO-like or internal date key)
+    workspace?: string; // Workspace name; '' = default/root timeline (preferred)
+    branch?: string;    // @deprecated alias of workspace; sends X-Workspace
+    date?: string;     // X-Date: as-of reads + write revision; any ISO/mm-dd-yyyy instant, not only "now"
     prefix?: string;   // Optional identifier prefix filter
     project_id?: string; // Preferred: project id for app-user public auth (`tenant_id` on wire)
     tenant_id?: string; // Deprecated alias of project_id
@@ -200,7 +217,7 @@ interface XCiteDBClientOptions {
 - `loginAppUser(email, password)` — App end-user sign-in
 - `XCiteDBClient.buildProjectGroup(projectId, 'admin'|'editor'|'viewer')` — Static helper: canonical `project:<tenant_id>:<role>` string
 - `getTokenClaims()` — Decode current `appUserAccessToken` or `accessToken` payload (no signature verification); use for ABAC debugging
-- `setContext(ctx)` — Update branch/date context
+- `setContext(ctx)` — Update workspace/date context
 - `setProjectId(id)` — Switch active project (platform console)
 
 **XML Documents:**
@@ -225,19 +242,20 @@ interface XCiteDBClientOptions {
 - `queryMeta(identifier, path?)` — Read metadata
 - `clearMeta(query)` — Remove metadata
 
-**Versioning:**
-- `withBranch(name, fn, options?)` — Create branch, run callback on client, commit, merge back (optional `autoMerge: false`)
-- `createBranch(name, fromBranch?, fromDate?)` — Create branch
-- `listBranches()` — List all branches
-- `mergeBranch(target, source, options?)` — Merge branches
-- `deleteBranch(name)` — Delete branch
-- `createCommit(message, author?)` — Commit current state
-- `listCommits(options?)` — List commits
-- `rollbackToCommit(commitId)` — Rollback to prior commit
-- `cherryPick(commitId, message?)` — Cherry-pick a commit
-- `diff(from, to, includeContent?)` — Diff between revisions
-- `createTag(name, commitId, message?)` — Tag a commit
-- `listTags()` / `deleteTag(name)` — Manage tags
+**Versioning (workspaces & checkpoints):**
+- `withWorkspace(name, fn, options?)` — Create workspace, run callback, checkpoint, publish back (optional `autoMerge: false`; `fromBranch` = parent workspace)
+- `createWorkspace(name, fromBranch?, fromDate?)` — Create workspace
+- `listWorkspaces()` — List workspaces
+- `publishWorkspace(target, source, options?)` — Publish workspace changes to a target timeline
+- `deleteWorkspace(name)` — Delete workspace
+- `createCheckpoint(message, author?)` — Named snapshot of current state
+- `listCheckpoints(options?)` — List checkpoints
+- `revertToCheckpoint(checkpointId)` — Revert workspace to a prior checkpoint
+- `applyCheckpoint(checkpointId, message?)` — Apply another checkpoint’s changes here
+- `compare(from, to, includeContent?)` — Compare revisions
+- `createBookmark(name, checkpointId, message?)` — Bookmark a checkpoint
+- `listBookmarks()` / `deleteBookmark(name)` — Manage bookmarks
+- **Deprecated aliases:** `withBranch`, `createBranch`, `listBranches`, `mergeBranch`, `deleteBranch`, `createCommit`, `listCommits`, `rollbackToCommit`, `cherryPick`, `diff`, `createTag`, `listTags`, `deleteTag` (same HTTP behavior)
 
 **Locks:**
 - `acquireLock(identifier, expires?)` — Acquire cooperative lock
@@ -260,7 +278,7 @@ interface XCiteDBClientOptions {
 ### Advanced: policy expressions (ABAC)
 
 - **Actions** (use in `policy.actions`): `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
-- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id` and **`subject.user_id`** (same value for app users), `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments; indices follow non-empty `/` segments after API canonicalization, e.g. `/userdata/u1/x` → `[userdata,u1,x]`), `env.branch`. Policy **`match_start` / `match_end` / `exact`** strings are canonicalized like API identifiers (add leading `/` when omitted).
+- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id` and **`subject.user_id`** (same value for app users), `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments; indices follow non-empty `/` segments after API canonicalization, e.g. `/userdata/u1/x` → `[userdata,u1,x]`), `env.branch` (workspace name; legacy name retained in policy engine). Policy **`match_start` / `match_end` / `exact`** strings are canonicalized like API identifiers (add leading `/` when omitted).
 - **Operators:** `=`, `!=`, `>=`, `<=`, `>`, `<`, `in`, `contains`, `starts_with`, `ends_with`, `&`, `|`, `!`, `+` (string concat), postfix `!` (exists).
 - **Examples:** `resource.path[0] = subject.attr.tenant_code` — tenant isolation; `subject.attr.level >= 5` — numeric attribute gate.
 
@@ -269,7 +287,7 @@ interface XCiteDBClientOptions {
 - **Events:** `meta_changed`, `document_written`, `document_deleted`.
 - **`match`:** required non-empty **`identifiers`** (same pattern objects as policy `resources.identifiers`); optional **`match_meta_path`** (exact or `prefix*`); optional **`match_operation`:** `set` | `append` | `delete`.
 - **`action`:** **`query`** (document query), **`unquery`** (Unquery template), **`target_identifier`** (or `"$trigger_identifier"`), **`meta_path`**, **`mode`:** `set` | `append`.
-- **Unquery vars:** `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`. **Trigger `conditions.expression` context:** `trigger.{event,meta_path,operation}`, `value`, `resource`, `env.branch` (no `subject`).
+- **Unquery vars:** `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`. **Trigger `conditions.expression` context:** `trigger.{event,meta_path,operation}`, `value`, `resource`, `env.branch` (workspace; no `subject`).
 
 ### Advanced: Unquery DSL (`unquery(query, unqueryDoc)`)
 
@@ -312,7 +330,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())
         ids = await client.query_documents(XCiteQuery(match_start="/manual/"))
@@ -334,7 +352,7 @@ asyncio.run(main())
 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();
@@ -347,9 +365,9 @@ auto ids = client.query_documents(q);
 
 - **Multi-tenant**: Each project is an isolated tenant with its own data, users, keys, and policies.
 - **LMDB engine**: Data is memory-mapped; reads are microsecond-class on warm data.
-- **Versioning**: Every write is versioned. Branches isolate work. Commits snapshot state. Time-travel reads any historical state via `X-Date`.
+- **Versioning**: **Temporal revisions** are always on when using dates. **Workspaces** isolate draft work; **checkpoints** are optional named snapshots; **publish** merges a workspace into a target timeline. **`X-Date`** selects an instant for **as-of reads** and, when set, for **writes** under that revision (any calendar time you choose — e.g. publication date — not only “now”). Omit **`X-Date`** for **flat** writes on that request, or use **`X-Unversioned: true`** to state that explicitly.
 - **Two user tiers**: Platform operators manage infrastructure; App users are end-users of applications built on XciteDB.
-- **Security policies (ABAC)**: Fine-grained allow/deny rules on actions, resources, roles, and branches.
+- **Security policies (ABAC)**: Fine-grained allow/deny rules on actions, resources, roles, and workspaces (`env.branch` in expressions).
 - **WebSocket**: Real-time notifications for document changes at `/api/v1/ws`.
 
 ## Documentation
@@ -362,8 +380,8 @@ auto ids = client.query_documents(q);
 - Metadata — JSON metadata on documents
 - Search — Full-text search
 - Unquery — Declarative query DSL
-- Branches — Branch management
-- Commits & tags — Version snapshots
+- Workspaces — Isolated editing environments
+- Checkpoints & bookmarks — Named snapshots and references
 - Locks — Cooperative editing locks
 - Authentication — JWT, API keys, platform vs app users
 - Security policies — ABAC access control

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.9",
+  "version": "0.2.11",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "node --test dist/**/*.test.js 2>/dev/null || echo 'No tests'"
+    "test": "npm run build && node --test dist/**/*.test.js",
+    "test:only": "node --test dist/**/*.test.js"
   },
   "keywords": [
     "xcitedb",
@@ -34,6 +35,7 @@
   },
   "dependencies": {},
   "devDependencies": {
+    "@types/node": "^20.14.0",
     "typescript": "^5.0.0"
   },
   "files": [