@xcitedbs/client 0.2.20 → 0.2.21

package/dist/client.d.ts

@@ -410,6 +410,36 @@ export declare class XCiteDBClient {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';
     }): Promise<MergeResult>;
+    /** List app-user draft workspaces visible to the caller (`GET /api/v1/user-workspaces`). */
+    listUserWorkspaces(): Promise<{
+        user_workspaces: Record<string, unknown>[];
+    }>;
+    /** Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON). */
+    createUserWorkspace(name: string, options?: {
+        sourceBranch?: string;
+        sourceDate?: string;
+    }): Promise<Record<string, unknown>>;
+    getUserWorkspace(id: string): Promise<{
+        user_workspace: Record<string, unknown>;
+    }>;
+    deleteUserWorkspace(id: string): Promise<void>;
+    addUserWorkspaceGrant(id: string, body: {
+        user_id?: string;
+        group?: string;
+        mode: string;
+    }): Promise<{
+        user_workspace: Record<string, unknown>;
+    }>;
+    removeUserWorkspaceGrant(id: string, body: {
+        user_id?: string;
+        group?: string;
+    }): Promise<{
+        user_workspace: Record<string, unknown>;
+    }>;
+    publishUserWorkspace(id: string, options?: {
+        message?: string;
+        autoResolve?: string;
+    }): Promise<Record<string, unknown>>;
     /**
      * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.

package/dist/client.js

@@ -1246,6 +1246,37 @@ class XCiteDBClient {
     async mergeBranch(targetBranch, sourceBranch, options) {
         return this.publishWorkspace(targetBranch, sourceBranch, options);
     }
+    /** List app-user draft workspaces visible to the caller (`GET /api/v1/user-workspaces`). */
+    async listUserWorkspaces() {
+        return this.request('GET', '/api/v1/user-workspaces');
+    }
+    /** Create a user workspace (`POST /api/v1/user-workspaces`). Returns the workspace record (top-level JSON). */
+    async createUserWorkspace(name, options) {
+        const body = { name };
+        if (options?.sourceBranch)
+            body.source_branch = options.sourceBranch;
+        if (options?.sourceDate)
+            body.source_date = options.sourceDate;
+        return this.request('POST', '/api/v1/user-workspaces', body);
+    }
+    async getUserWorkspace(id) {
+        return this.request('GET', `/api/v1/user-workspaces/${encodeURIComponent(id)}`);
+    }
+    async deleteUserWorkspace(id) {
+        await this.request('DELETE', `/api/v1/user-workspaces/${encodeURIComponent(id)}`);
+    }
+    async addUserWorkspaceGrant(id, body) {
+        return this.request('POST', `/api/v1/user-workspaces/${encodeURIComponent(id)}/grants`, body);
+    }
+    async removeUserWorkspaceGrant(id, body) {
+        return this.request('DELETE', `/api/v1/user-workspaces/${encodeURIComponent(id)}/grants`, body);
+    }
+    async publishUserWorkspace(id, options) {
+        const body = { auto_resolve: options?.autoResolve ?? 'none' };
+        if (options?.message)
+            body.message = options.message;
+        return this.request('POST', `/api/v1/user-workspaces/${encodeURIComponent(id)}/publish`, body);
+    }
     /**
      * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.

package/llms-full.txt

@@ -35,10 +35,11 @@ Before reading the full reference, note these critical differences from typical
 - **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.
+- **App-user user workspaces (`_uw/<owner>/<slug>`):** **`GET/POST /api/v1/user-workspaces`**, grants, publish — see repository **`web/src/docs/content/user-workspaces.md`**.
 - **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`**.
+Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/api/v1/user-workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
 
 ## Common Pitfalls
 

package/llms.txt

@@ -10,7 +10,7 @@ These are the most common sources of confusion for developers and AI assistants:
 
 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.
+3. **Shredding vs sharding (do not confuse them).** **Shredding** breaks **XML and JSON** hierarchically into small **fragments** (elements, attributes, objects, fields, array slots, and similar structural pieces) so each fragment can live under its **own LMDB key/value**. That is **not** “sharding” in the usual distributed-database sense. **Sharding** in XCiteDB means **per-tenant** isolation (each **project** is its own shard of data); **finer-grain sharding** is planned separately. Sharding and shredding are unrelated axes. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type; JSON documents are a parallel store keyed by identifier string. Both are fully versioned.
 
 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).
 
@@ -32,11 +32,13 @@ These are the most common sources of confusion for developers and AI assistants:
 
 - **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.
 
+- **App-user draft workspaces (`_uw/<owner>/<slug>`):** REST **`/api/v1/user-workspaces`**; SDK: `listUserWorkspaces`, `createUserWorkspace`, `getUserWorkspace`, `deleteUserWorkspace`, `addUserWorkspaceGrant`, `removeUserWorkspaceGrant`, `publishUserWorkspace`.
+
 - **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`**.
+Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/api/v1/user-workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
 
 ## Glossary: Project id, display name, and groups
 
@@ -154,7 +156,7 @@ When you build a backend that calls XCiteDB on behalf of users:
 
 - **JSON documents merge by default.** `POST /api/v1/json-documents` merges the posted `data` into the existing document (object fields combined per XCiteDB meta merge rules). Send **`overwrite: true`** to clear all stored JSON under that document root first, then write only the new payload. SDKs accept the same flag (e.g. `writeJsonDocument(id, data, { overwrite: true })` in JavaScript).
 - **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path` (arrays are replaced in range; excess old indices cleared); **`append`** appends array elements after existing ones at `path`. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta`** or **`addMeta(..., { mode: 'append' })`**; Python/C++: **`append_meta`** or **`add_meta`** with **`mode`** / **`overwrite`** (see SDK sections below).
-- **Prefer dictionary-style objects.** Shredded JSON metadata is keyed by field names. **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
+- **Prefer dictionary-style objects.** **Shredded** JSON metadata is stored in **fragment-level** keys (e.g. per field name). **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
 
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
@@ -297,6 +299,7 @@ interface XCiteDBClientOptions {
 - `listWorkspaces()` — List workspaces
 - `publishWorkspace(target, source, options?)` — Publish workspace changes to a target timeline
 - `deleteWorkspace(name)` — Delete workspace
+- `listUserWorkspaces()` / `createUserWorkspace(name, options?)` / `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)` / `publishUserWorkspace(id, options?)` — App-user **`_uw/…`** workspaces
 - `createCheckpoint(message, author?)` — Named snapshot of current state
 - `listCheckpoints(options?)` — List checkpoints
 - `revertToCheckpoint(checkpointId)` — Revert workspace to a prior checkpoint
@@ -417,6 +420,7 @@ auto ids = client.query_documents(q);
 ## Architecture Notes
 
 - **Multi-tenant**: Each project is an isolated tenant with its own data, users, keys, and policies.
+- **Sharding vs shredding**: **Sharding** partitions the **tenant plane** (today, one isolated dataset per project; finer-grain sharding is on the roadmap). **Shredding** splits **individual documents** into **fragments** with their own keys—see convention 3.
 - **LMDB engine**: Data is memory-mapped; reads are microsecond-class on warm data.
 - **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",