@xcitedbs/client 0.2.0 → 0.2.5

package/README.md

@@ -26,11 +26,12 @@ import { XCiteDBClient } from '@xcitedbs/client';
 const client = new XCiteDBClient({
   baseUrl: 'http://localhost:8080',
   apiKey: process.env.XCITEDB_API_KEY,
-  context: { branch: 'main', date: '03/27/2026' },
+  context: { branch: '', date: '' },
 });
 
 await client.health();
 const docs = await client.queryByIdentifier('/test1', 'FirstMatch');
+await client.put('app.settings', { theme: 'dark' });
 ```
 
 ### WebSocket

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, PolicySubjectInput, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, OwnedTenantInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -48,8 +48,8 @@ export declare class XCiteDBClient {
         api_version: string;
     }>;
     /**
-     * Platform console sign-in. The first argument is the account **email** (e.g. `admin@localhost`).
-     * Legacy `/api/v1/auth/login` has been removed.
+     * @deprecated Use {@link platformLogin} for platform operator sign-in, or {@link loginAppUser} for app end-users.
+     * This method only performs platform console login.
      */
     login(email: string, password: string): Promise<TokenPair>;
     /** Platform console sign-in (`email` + `password`). Project context is `X-Project-Id`, not the JWT. */
@@ -67,14 +67,14 @@ export declare class XCiteDBClient {
         org_name?: string;
         org_id?: string;
         attributes?: Record<string, unknown>;
-    }): Promise<unknown>;
+    }): Promise<PlatformRegisterResult>;
     platformWorkspaces(): Promise<PlatformWorkspacesResponse>;
-    listMyTenants(): Promise<OwnedTenantInfo[]>;
-    /** Alias for {@link listMyTenants} (organization/project terminology). */
-    listMyProjects(): Promise<OwnedTenantInfo[]>;
+    /** @deprecated Prefer {@link listMyProjects}. */
+    listMyTenants(): Promise<ProjectInfo[]>;
+    /** Lists projects the platform user can access (from workspaces). */
+    listMyProjects(): Promise<ProjectInfo[]>;
     /**
-     * Switch active tenant/project for API calls. Platform console: updates `X-Project-Id` only (no token exchange).
-     * Legacy `/api/v1/auth/switch-tenant` has been removed; non-platform callers should set context instead.
+     * @deprecated Use {@link switchProject}. Platform console: updates `X-Project-Id` only (no token exchange).
      */
     switchTenant(tenantId: string): Promise<void>;
     /** Alias for {@link switchTenant}. */
@@ -165,8 +165,33 @@ export declare class XCiteDBClient {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';
     }): Promise<MergeResult>;
-    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeDocumentJson`. */
+    /**
+     * Create `branchName` from {@link options.fromBranch} (or current context branch), run `fn` scoped to that branch,
+     * create a commit, then merge back into the parent branch unless {@link options.autoMerge} is `false`.
+     * Restores previous {@link DatabaseContext} afterward.
+     */
+    withBranch<T>(branchName: string, fn: (client: XCiteDBClient) => Promise<T>, options?: {
+        message?: string;
+        /** When true (default), merge `branchName` into the parent branch after commit. */
+        autoMerge?: boolean;
+        /** Branch to fork from (default: current `context.branch`, or `""`). */
+        fromBranch?: string;
+        author?: string;
+    }): Promise<{
+        result: T;
+        commit?: CommitRecord;
+        merge?: MergeResult;
+    }>;
+    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
     writeXML(xml: string, _options?: WriteDocumentOptions): Promise<void>;
+    /**
+     * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
+     * For storing JSON data by key, use `writeJsonDocument`.
+     */
+    writeXmlDocument(xml: string, options?: WriteDocumentOptions): Promise<void>;
+    /**
+     * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
+     */
     writeDocumentJson(xml: string, options?: WriteDocumentOptions): Promise<void>;
     queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
     queryDocuments(query: XCiteQuery, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
@@ -187,22 +212,30 @@ export declare class XCiteDBClient {
     }): Promise<boolean>;
     appendMeta(identifier: string, value: unknown, path?: string): Promise<boolean>;
     appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean): Promise<boolean>;
-    queryMeta(identifier: string, path?: string): Promise<unknown>;
-    queryMetaByQuery(query: XCiteQuery, path?: string): Promise<unknown>;
+    queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
+    queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
     clearMeta(query: XCiteQuery): Promise<boolean>;
     acquireLock(identifier: string, expires?: number): Promise<LockInfo>;
     releaseLock(identifier: string, lockId: string): Promise<boolean>;
     findLocks(identifier: string): Promise<LockInfo[]>;
-    unquery(query: XCiteQuery, unquery: unknown): Promise<unknown>;
+    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: unknown): Promise<T>;
     search(q: TextSearchQuery): Promise<TextSearchResult>;
     reindex(): Promise<{
         status: string;
         message: string;
     }>;
     writeJsonDocument(identifier: string, data: unknown): Promise<void>;
-    readJsonDocument(identifier: string): Promise<unknown>;
+    readJsonDocument<T = unknown>(identifier: string): Promise<T>;
     deleteJsonDocument(identifier: string): Promise<void>;
     listJsonDocuments(match?: string, limit?: number, offset?: number): Promise<ListIdentifiersResult>;
+    /** JSON document shorthand — same as {@link writeJsonDocument}. */
+    put(identifier: string, data: unknown): Promise<void>;
+    /** JSON document read — same as {@link readJsonDocument}. */
+    get<T = unknown>(identifier: string): Promise<T>;
+    /** JSON document delete — same as {@link deleteJsonDocument}. */
+    remove(identifier: string): Promise<void>;
+    /** List JSON document keys — same as {@link listJsonDocuments}. */
+    list(match?: string, limit?: number, offset?: number): Promise<ListIdentifiersResult>;
     /**
      * WebSocket `/api/v1/ws` — optional initial subscription pattern.
      * Uses `access_token` or `api_key` query params when headers are not available (browser).

package/dist/client.js

@@ -101,11 +101,13 @@ class XCiteDBClient {
             h['X-Date'] = c.date;
         if (c.prefix)
             h['X-Prefix'] = c.prefix;
+        if (c.unversioned)
+            h['X-Unversioned'] = 'true';
         return h;
     }
     /** Include `tenant_id` for public app-auth routes when using only app-user tokens (no developer key/JWT). */
     mergeAppTenant(body) {
-        const tid = this.defaultContext.tenant_id;
+        const tid = this.defaultContext.project_id ?? this.defaultContext.tenant_id;
         if (tid)
             return { ...body, tenant_id: tid };
         return body;
@@ -214,8 +216,8 @@ class XCiteDBClient {
         return this.request('GET', '/api/v1/version');
     }
     /**
-     * Platform console sign-in. The first argument is the account **email** (e.g. `admin@localhost`).
-     * Legacy `/api/v1/auth/login` has been removed.
+     * @deprecated Use {@link platformLogin} for platform operator sign-in, or {@link loginAppUser} for app end-users.
+     * This method only performs platform console login.
      */
     async login(email, password) {
         return this.platformLogin(email, password);
@@ -257,12 +259,19 @@ class XCiteDBClient {
     async platformWorkspaces() {
         return this.request('GET', '/api/v1/platform/auth/workspaces');
     }
+    /** @deprecated Prefer {@link listMyProjects}. */
     async listMyTenants() {
+        return this.listMyProjects();
+    }
+    /** Lists projects the platform user can access (from workspaces). */
+    async listMyProjects() {
         const w = await this.platformWorkspaces();
         const tenants = (w.projects ?? []).map((p) => {
             const r = p;
+            const id = r.tenant_id || r.project_id || '';
             return {
-                tenant_id: r.tenant_id || r.project_id || '',
+                project_id: id,
+                tenant_id: id,
                 org_id: r.org_id,
                 name: r.name,
                 status: r.status,
@@ -277,13 +286,8 @@ class XCiteDBClient {
         }
         return tenants;
     }
-    /** Alias for {@link listMyTenants} (organization/project terminology). */
-    async listMyProjects() {
-        return this.listMyTenants();
-    }
     /**
-     * Switch active tenant/project for API calls. Platform console: updates `X-Project-Id` only (no token exchange).
-     * Legacy `/api/v1/auth/switch-tenant` has been removed; non-platform callers should set context instead.
+     * @deprecated Use {@link switchProject}. Platform console: updates `X-Project-Id` only (no token exchange).
      */
     async switchTenant(tenantId) {
         if (this.platformConsole) {
@@ -327,15 +331,14 @@ class XCiteDBClient {
         return this.request('POST', '/api/v1/app/auth/register', this.mergeAppTenant(body));
     }
     async getOAuthProviders() {
-        const tid = this.defaultContext.tenant_id;
+        const tid = this.defaultContext.project_id ?? this.defaultContext.tenant_id;
         const q = buildQuery({ tenant_id: tid && String(tid).length > 0 ? String(tid) : 'default' });
         return this.request('GET', `/api/v1/app/auth/oauth/providers${q}`);
     }
     /** Relative path + query for browser navigation to start OAuth (append to API base URL). */
     oauthAuthorizePath(provider) {
-        const tid = this.defaultContext.tenant_id && String(this.defaultContext.tenant_id).length > 0
-            ? String(this.defaultContext.tenant_id)
-            : 'default';
+        const raw = this.defaultContext.project_id ?? this.defaultContext.tenant_id;
+        const tid = raw && String(raw).length > 0 ? String(raw) : 'default';
         return `/api/v1/app/auth/oauth/${encodeURIComponent(provider)}/authorize${buildQuery({ tenant_id: tid })}`;
     }
     /** Exchange one-time session code from OAuth browser redirect (public + tenant_id). */
@@ -591,19 +594,55 @@ class XCiteDBClient {
         body.auto_resolve = options?.autoResolve ?? 'none';
         return this.request('POST', `/api/v1/branches/${encodeURIComponent(targetBranch)}/merge`, body);
     }
-    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeDocumentJson`. */
+    /**
+     * Create `branchName` from {@link options.fromBranch} (or current context branch), run `fn` scoped to that branch,
+     * create a commit, then merge back into the parent branch unless {@link options.autoMerge} is `false`.
+     * Restores previous {@link DatabaseContext} afterward.
+     */
+    async withBranch(branchName, fn, options) {
+        const prev = { ...this.defaultContext };
+        const fromBranch = options?.fromBranch ?? prev.branch ?? '';
+        let commit;
+        let merge;
+        try {
+            await this.createBranch(branchName, fromBranch || undefined, prev.date || undefined);
+            this.setContext({ branch: branchName });
+            const result = await fn(this);
+            commit = await this.createCommit(options?.message ?? `Branch ${branchName}`, options?.author);
+            if (options?.autoMerge !== false) {
+                merge = await this.mergeBranch(fromBranch, branchName, {
+                    message: options?.message,
+                });
+            }
+            return { result, commit, merge };
+        }
+        finally {
+            this.setContext(prev);
+        }
+    }
+    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
     async writeXML(xml, _options) {
         await this.request('POST', '/api/v1/documents', xml, {
             'Content-Type': 'application/xml',
         });
     }
-    async writeDocumentJson(xml, options) {
+    /**
+     * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
+     * For storing JSON data by key, use `writeJsonDocument`.
+     */
+    async writeXmlDocument(xml, options) {
         await this.request('POST', '/api/v1/documents', {
             xml,
             is_top: options?.is_top ?? true,
             compare_attributes: options?.compare_attributes ?? false,
         });
     }
+    /**
+     * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
+     */
+    async writeDocumentJson(xml, options) {
+        return this.writeXmlDocument(xml, options);
+    }
     async queryByIdentifier(identifier, flags, filter, pathFilter) {
         const q = buildQuery({
             identifier,
@@ -865,6 +904,22 @@ class XCiteDBClient {
         }
         return { identifiers: [], total: 0, offset: 0, limit: 0 };
     }
+    /** JSON document shorthand — same as {@link writeJsonDocument}. */
+    async put(identifier, data) {
+        return this.writeJsonDocument(identifier, data);
+    }
+    /** JSON document read — same as {@link readJsonDocument}. */
+    async get(identifier) {
+        return this.readJsonDocument(identifier);
+    }
+    /** JSON document delete — same as {@link deleteJsonDocument}. */
+    async remove(identifier) {
+        return this.deleteJsonDocument(identifier);
+    }
+    /** List JSON document keys — same as {@link listJsonDocuments}. */
+    async list(match, limit, offset) {
+        return this.listJsonDocuments(match, limit, offset);
+    }
     /**
      * WebSocket `/api/v1/ws` — optional initial subscription pattern.
      * Uses `access_token` or `api_key` query params when headers are not available (browser).

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { XCiteDBClient } from './client';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, XCiteDBClientOptions, UnqueryResult, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -14,6 +14,19 @@ export interface XCiteQuery {
     /** Skip this many rows (for pagination). */
     offset?: number;
 }
+/** Root object returned by `readJsonDocument` (use generics for app-specific shapes). */
+export type JsonDocumentData = Record<string, unknown>;
+/** JSON metadata from meta APIs (structure is document-specific). */
+export type MetaValue = unknown;
+/** Result of `unquery` (shape depends on the unquery definition). */
+export type UnqueryResult = unknown;
+/** Typical `POST /api/v1/platform/auth/register` response (fields vary by registration policy). */
+export interface PlatformRegisterResult {
+    user_id?: string;
+    status?: string;
+    message?: string;
+    [key: string]: unknown;
+}
 /** Full-text search (`POST /api/v1/search`) */
 export interface TextSearchQuery {
     query: string;
@@ -77,8 +90,14 @@ export interface TokenPair {
     refresh_token: string;
     expires_in: number;
 }
-/** Projects from `GET /api/v1/platform/auth/workspaces` (mapped for compatibility). */
-export interface OwnedTenantInfo {
+/**
+ * Project row from `GET /api/v1/platform/auth/workspaces` and related APIs.
+ * The server often labels the id as `tenant_id`; both fields are set when mapped by the SDK.
+ */
+export interface ProjectInfo {
+    /** Project id (wire alias: `tenant_id` in many JSON bodies). */
+    project_id: string;
+    /** Same id as `project_id` (legacy / wire field name). */
     tenant_id: string;
     org_id?: string;
     name: string;
@@ -88,6 +107,8 @@ export interface OwnedTenantInfo {
     config?: unknown;
     owner_user_id?: string;
 }
+/** @deprecated Use {@link ProjectInfo}. */
+export type OwnedTenantInfo = ProjectInfo;
 export interface UserInfo {
     user_id: string;
     username: string;
@@ -117,7 +138,7 @@ export interface PlatformWorkspaceOrg {
 }
 export interface PlatformWorkspacesResponse {
     orgs: PlatformWorkspaceOrg[];
-    projects: OwnedTenantInfo[];
+    projects: ProjectInfo[];
 }
 /** One row from `GET /api/v1/project/keys` (secret is never returned). */
 export interface ApiKeyInfo {
@@ -127,13 +148,24 @@ export interface ApiKeyInfo {
     expires_at: number;
     /** `secret` = server-side full access; `public` = client-safe, restricted. */
     key_type?: 'secret' | 'public';
+    /** Project id this key belongs to. */
+    tenant_id?: string;
 }
 export type Flags = 'None' | 'FirstMatch' | 'IncludeChildren' | 'NoChildren' | 'KeepIndexNodes' | 'PrevIfDeleted' | string;
 export interface DatabaseContext {
     branch?: string;
     date?: string;
     prefix?: string;
-    /** Project/tenant id; sent as `tenant_id` in app-user public auth bodies when no developer token is used. */
+    /**
+     * When true, sends `X-Unversioned: true` so writes use flat LMDB keys (no date revision).
+     * Do not combine with `date`; the server returns 400 if both are set.
+     */
+    unversioned?: boolean;
+    /** Preferred: project id; sent as `tenant_id` in app-user public auth bodies when no developer token is used. */
+    project_id?: string;
+    /**
+     * @deprecated Use {@link DatabaseContext.project_id} (same JSON field name on the wire: `tenant_id`).
+     */
     tenant_id?: string;
 }
 export interface WriteDocumentOptions {
@@ -162,7 +194,7 @@ export interface XCiteDBClientOptions {
     context?: DatabaseContext;
     /** When true, sends `X-Project-Id` for console requests; developer JWTs are always platform tokens. */
     platformConsole?: boolean;
-    /** Active project id for platform console requests (`X-Project-Id` header). */
+    /** Active project id for platform console requests (`X-Project-Id` header). Alias of {@link DatabaseContext.project_id} for console mode. */
     projectId?: string;
     /** Persist developer session tokens after refresh (e.g. localStorage). */
     onSessionTokensUpdated?: (pair: TokenPair) => void;

package/llms-full.txt

@@ -14,7 +14,7 @@ Before reading the full reference, note these critical differences from typical
 
 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`), not URL path segments.
+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.
 
@@ -22,6 +22,10 @@ Before reading the full reference, note these critical differences from typical
 
 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
@@ -72,7 +76,7 @@ XciteDB shines in domains requiring strict auditability, collaborative authoring
 - **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`, `json_docs`).
+- **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.
@@ -81,7 +85,7 @@ XciteDB shines in domains requiring strict auditability, collaborative authoring
 ### 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.
+- **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
@@ -116,6 +120,7 @@ Welcome to the **XciteDB HTTP API**. This reference describes REST endpoints und
 | `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
 
@@ -876,7 +881,7 @@ const client = new XCiteDBClient({
 await client.health();
 
 // Write XML document
-await client.writeDocumentJson(
+await client.writeXmlDocument(
   '<chapter db:identifier="/manual/v1/intro"><title>Introduction</title></chapter>'
 );
 
@@ -918,7 +923,9 @@ interface DatabaseContext {
   branch?: string;   // '' = default (root timeline)
   date?: string;     // Point-in-time
   prefix?: string;   // Identifier prefix filter
-  tenant_id?: string; // For app-user auth
+  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
 }
 ```
 
@@ -930,15 +937,17 @@ interface DatabaseContext {
 
 ### Platform Auth
 - `platformLogin(email, password)` → `TokenPair`
-- `login(email, password)` → `TokenPair` (alias for platformLogin)
+- `login(email, password)` → `TokenPair` — **deprecated**; use `platformLogin` (operator) or `loginAppUser` (end-user)
 - `refresh()` → `TokenPair`
 - `logout()` → `void`
 - `me()` → `UserInfo`
-- `platformRegister(body)` → `unknown`
+- `platformRegister(body)` → `PlatformRegisterResult`
 - `platformRegistrationConfig()` → `PlatformRegistrationConfig`
 - `platformWorkspaces()` → `PlatformWorkspacesResponse`
-- `listMyTenants()` / `listMyProjects()` → `OwnedTenantInfo[]`
-- `switchTenant(tenantId)` / `switchProject(projectId)` → `void` (platform console only)
+- `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
@@ -949,7 +958,7 @@ interface DatabaseContext {
 - `clearAppUserTokens()` → `void`
 
 ### XML Documents
-- `writeDocumentJson(xml, options?)` → `void` — JSON wrapper (recommended)
+- `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[]`
@@ -965,20 +974,22 @@ interface DatabaseContext {
 
 ### JSON Documents
 - `writeJsonDocument(identifier, data)` → `void`
-- `readJsonDocument(identifier)` → `unknown`
+- `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(identifier, path?)` → `unknown`
-- `queryMetaByQuery(query, path?)` → `unknown`
+- `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`
@@ -1012,7 +1023,7 @@ interface DatabaseContext {
 - `reindex()` → `{ status, message }`
 
 ### Unquery
-- `unquery(query: XCiteQuery, unqueryDoc)` → `unknown`
+- `unquery<T>(query: XCiteQuery, unqueryDoc)` → `T`
 
 ### Security Policies
 - `createPolicy(policyId, policy: SecurityPolicy)` → `StoredPolicyResponse`
@@ -1116,7 +1127,12 @@ Install: `pip install xcitedb`
 
 ```python
 import asyncio
-from xcitedb import XCiteDBClient, XCiteQuery, DatabaseContext
+from xcitedb import (
+    XCiteDBClient,
+    XCiteQuery,
+    DatabaseContext,
+    TextSearchQuery,
+)
 
 async def main():
     async with XCiteDBClient(
@@ -1125,13 +1141,20 @@ async def main():
         context=DatabaseContext(branch="", date=""),
     ) as client:
         print(await client.health())
-        ids = await client.query_documents(XCiteQuery(match_start="/manual/"))
-        print(ids)
+        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())
 ```
 
-Methods mirror the JavaScript SDK with Python naming conventions (e.g. `query_documents`, `write_json_document`).
+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).
 
 ---
 
@@ -1153,6 +1176,6 @@ q.match_start = "/manual/";
 auto ids = client.query_documents(q);
 ```
 
-Synchronous (blocking) HTTP client. Methods mirror the JavaScript SDK with C++ naming. Errors throw `xcitedb::XCiteDBError` with `.status()` and `.body()`.
+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).

package/llms.txt

@@ -20,6 +20,8 @@ These are the most common sources of confusion for developers and AI assistants:
 
 7. **The query model is NOT SQL.** Listing/filtering documents uses query parameters on REST endpoints (`match`, `match_start`, `contains`, `regex`, `prefix`). Advanced analytics use **Unquery**, a JSON-defined declarative DSL posted to `POST /api/v1/unquery`.
 
+8. **Project vs tenant id.** In the SDK, prefer `context.project_id` (and `listMyProjects` / `switchProject`). Many JSON bodies and JWT claims still use the field name `tenant_id` for the same value — the client sends that wire name automatically.
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -49,7 +51,7 @@ const docs = await client.queryDocuments({ match_start: '/manual/' });
 const xml = await client.queryByIdentifier('/manual/v1/intro', 'FirstMatch');
 
 // Write an XML document (identifier is inside the XML body)
-await client.writeDocumentJson(
+await client.writeXmlDocument(
   '<chapter db:identifier="/manual/v1/intro"><title>Introduction</title></chapter>'
 );
 
@@ -59,6 +61,18 @@ await client.writeJsonDocument('app.settings', { theme: 'dark', locale: 'en' });
 // Read a JSON document
 const settings = await client.readJsonDocument('app.settings');
 
+// Quick JSON CRUD aliases (same as writeJsonDocument / readJsonDocument / deleteJsonDocument / listJsonDocuments)
+await client.put('app.prefs', { theme: 'dark' });
+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) => {
+  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' });
@@ -96,7 +110,8 @@ interface XCiteDBClientOptions {
     branch?: string;   // Branch name; '' = default/root timeline
     date?: string;     // Point-in-time (ISO-like or internal date key)
     prefix?: string;   // Optional identifier prefix filter
-    tenant_id?: string; // Project/tenant ID for app-user auth
+    project_id?: string; // Preferred: project id for app-user public auth (`tenant_id` on wire)
+    tenant_id?: string; // Deprecated alias of project_id
   };
   platformConsole?: boolean;    // true = use X-Project-Id header
   projectId?: string;           // Active project for platform console mode
@@ -114,7 +129,7 @@ interface XCiteDBClientOptions {
 - `setProjectId(id)` — Switch active project (platform console)
 
 **XML Documents:**
-- `writeDocumentJson(xml, options?)` — Store XML (identifier inside XML body)
+- `writeXmlDocument(xml, options?)` — Store XML via JSON body (identifier inside XML). Deprecated alias: `writeDocumentJson`.
 - `writeXML(xml)` — Store raw XML with `Content-Type: application/xml`
 - `queryByIdentifier(id, flags?, filter?)` — Get document(s) by identifier
 - `queryDocuments(query, flags?)` — List/filter documents
@@ -124,9 +139,10 @@ interface XCiteDBClientOptions {
 
 **JSON Documents:**
 - `writeJsonDocument(identifier, data)` — Store a JSON document
-- `readJsonDocument(identifier)` — Read a JSON document
+- `readJsonDocument(identifier)` — Read a JSON document (generic `readJsonDocument<T>()` supported)
 - `deleteJsonDocument(identifier)` — Delete a JSON document
 - `listJsonDocuments(match?, limit?, offset?)` — List JSON document keys
+- **Quick JSON aliases:** `put`, `get`, `remove`, `list` — same as the four methods above
 
 **Metadata (JSON on XML):**
 - `addMeta(identifier, value, path?)` — Set metadata on a document
@@ -135,6 +151,7 @@ interface XCiteDBClientOptions {
 - `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
@@ -191,7 +208,7 @@ Install: `pip install xcitedb`
 
 ```python
 import asyncio
-from xcitedb import XCiteDBClient, XCiteQuery, DatabaseContext
+from xcitedb import XCiteDBClient, XCiteQuery, DatabaseContext, TextSearchQuery
 
 async def main():
     async with XCiteDBClient(
@@ -202,6 +219,11 @@ async def main():
         print(await client.health())
         ids = await client.query_documents(XCiteQuery(match_start="/manual/"))
         print(ids)
+        await client.write_json_document("app.settings", {"theme": "dark"})
+        print(await client.read_json_document("app.settings"))
+        print(await client.search(TextSearchQuery(query="guide", limit=10)))
+        pair = await client.platform_login("admin@localhost", "password")
+        # await client.login_app_user("user@example.com", "secret", tenant_id="...")
 
 asyncio.run(main())
 ```
@@ -234,7 +256,8 @@ auto ids = client.query_documents(q);
 
 ## Documentation
 
-Full API reference is available at your XciteDB server's `/docs` path. Key sections:
+- **OpenAPI 3.1:** Repository file `docs/openapi.yaml` (machine-readable route map and shared schemas).
+- Full API reference is also available at your XciteDB server's `/docs` path. Key sections:
 - Getting started — Base URL, headers, errors, pagination
 - Documents — XML document CRUD, identifiers, hierarchy
 - JSON documents — JSON document CRUD

package/package.json

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