@xcitedbs/client 0.2.0 → 0.2.6

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, CreateTestSessionOptions, XCiteDBClientOptions, XCiteQuery } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -14,7 +14,18 @@ export declare class XCiteDBClient {
     private onSessionTokensUpdated?;
     private onAppUserTokensUpdated?;
     private onSessionInvalid?;
+    private testSessionToken?;
+    private testRequireAuth?;
     constructor(options: XCiteDBClientOptions);
+    /**
+     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     */
+    static createTestSession(opts: CreateTestSessionOptions): Promise<XCiteDBClient>;
+    /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
+    destroyTestSession(): Promise<{
+        message: string;
+    }>;
     /** True if this client would send API key or Bearer credentials on a normal request. */
     private sentAuthCredentials;
     /** 401 on these paths is an expected auth flow outcome, not a dead session. */
@@ -34,6 +45,7 @@ export declare class XCiteDBClient {
     /** Include `tenant_id` for public app-auth routes when using only app-user tokens (no developer key/JWT). */
     private mergeAppTenant;
     private authHeaders;
+    private testHeaders;
     private request;
     /** Developer Bearer refresh first, then app-user refresh (no API key refresh). */
     private tryRefreshSessionAfter401;
@@ -48,8 +60,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 +79,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}. */
@@ -83,7 +95,7 @@ export declare class XCiteDBClient {
     createApiKey(name: string, expiresAt?: number, keyType?: 'secret' | 'public'): Promise<unknown>;
     changePassword(currentPassword: string, newPassword: string): Promise<void>;
     revokeApiKey(keyId: string): Promise<void>;
-    registerAppUser(email: string, password: string, displayName?: string, groups?: string[], attributes?: Record<string, unknown>): Promise<AppUser>;
+    registerAppUser(email: string, password: string, displayName?: string, attributes?: Record<string, unknown>): Promise<AppUser>;
     getOAuthProviders(): Promise<OAuthProvidersResponse>;
     /** Relative path + query for browser navigation to start OAuth (append to API base URL). */
     oauthAuthorizePath(provider: string): string;
@@ -165,8 +177,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 +224,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

@@ -31,6 +31,50 @@ class XCiteDBClient {
         this.onSessionTokensUpdated = options.onSessionTokensUpdated;
         this.onAppUserTokensUpdated = options.onAppUserTokensUpdated;
         this.onSessionInvalid = options.onSessionInvalid;
+        this.testSessionToken = options.testSessionToken;
+        this.testRequireAuth = options.testRequireAuth === true;
+    }
+    /**
+     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     */
+    static async createTestSession(opts) {
+        const temp = new XCiteDBClient({
+            baseUrl: opts.baseUrl,
+            apiKey: opts.apiKey,
+            accessToken: opts.accessToken,
+            appUserAccessToken: opts.appUserAccessToken,
+            appUserRefreshToken: opts.appUserRefreshToken,
+            context: opts.context,
+            platformConsole: opts.platformConsole,
+            projectId: opts.projectId,
+            onSessionTokensUpdated: opts.onSessionTokensUpdated,
+            onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
+            onSessionInvalid: opts.onSessionInvalid,
+        });
+        const data = await temp.request('POST', '/api/v1/test/sessions', undefined, undefined, { no401Retry: true });
+        return new XCiteDBClient({
+            baseUrl: opts.baseUrl,
+            apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
+            accessToken: opts.testRequireAuth ? opts.accessToken : undefined,
+            appUserAccessToken: opts.testRequireAuth ? opts.appUserAccessToken : undefined,
+            appUserRefreshToken: opts.testRequireAuth ? opts.appUserRefreshToken : undefined,
+            context: opts.context,
+            platformConsole: opts.platformConsole,
+            projectId: opts.projectId,
+            onSessionTokensUpdated: opts.onSessionTokensUpdated,
+            onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
+            onSessionInvalid: opts.onSessionInvalid,
+            testSessionToken: data.session_token,
+            testRequireAuth: opts.testRequireAuth,
+        });
+    }
+    /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
+    async destroyTestSession() {
+        if (!this.testSessionToken) {
+            throw new Error('destroyTestSession: client has no testSessionToken');
+        }
+        return this.request('DELETE', '/api/v1/test/sessions/current', undefined, undefined, { no401Retry: true });
     }
     /** True if this client would send API key or Bearer credentials on a normal request. */
     sentAuthCredentials() {
@@ -101,11 +145,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;
@@ -130,6 +176,16 @@ class XCiteDBClient {
         }
         return h;
     }
+    testHeaders() {
+        const h = {};
+        if (this.testSessionToken) {
+            h['X-Test-Session'] = this.testSessionToken;
+            if (this.testRequireAuth) {
+                h['X-Test-Auth'] = 'required';
+            }
+        }
+        return h;
+    }
     async request(method, path, body, extraHeaders, opts) {
         const no401Retry = opts?.no401Retry === true;
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -137,6 +193,7 @@ class XCiteDBClient {
             const headers = {
                 ...this.authHeaders(),
                 ...this.contextHeaders(),
+                ...this.testHeaders(),
                 ...extraHeaders,
             };
             let init = { method, headers };
@@ -214,8 +271,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 +314,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 +341,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) {
@@ -316,26 +375,23 @@ class XCiteDBClient {
         await this.request('DELETE', `/api/v1/project/keys/${encodeURIComponent(keyId)}`);
     }
     // --- App user auth (requires developer API key or JWT on the same tenant) ---
-    async registerAppUser(email, password, displayName, groups, attributes) {
+    async registerAppUser(email, password, displayName, attributes) {
         const body = { email, password };
         if (displayName !== undefined)
             body.display_name = displayName;
-        if (groups !== undefined)
-            body.groups = groups;
         if (attributes !== undefined)
             body.attributes = attributes;
         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 +647,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 +957,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).
@@ -882,6 +990,9 @@ class XCiteDBClient {
             ...this.authHeaders(),
             ...this.contextHeaders(),
         };
+        const tid = this.defaultContext.project_id ?? this.defaultContext.tenant_id;
+        if (tid)
+            headers['tenant_id'] = tid;
         const sub = new websocket_1.WebSocketSubscription(wsBase, headers);
         sub.onMessage(callback);
         if (onError)

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, CreateTestSessionOptions, 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;
@@ -173,6 +205,29 @@ export interface XCiteDBClientOptions {
      * Use to clear stored credentials and redirect to sign-in. Not invoked for login/register-style paths.
      */
     onSessionInvalid?: () => void;
+    /**
+     * Ephemeral BaaS test session token from `POST /api/v1/test/sessions`.
+     * Sends `X-Test-Session`; use with {@link XCiteDBClient.createTestSession}.
+     */
+    testSessionToken?: string;
+    /** When true with `testSessionToken`, sends `X-Test-Auth: required` so real credentials are validated. */
+    testRequireAuth?: boolean;
+}
+/** Options for {@link XCiteDBClient.createTestSession} (provisions via API key or Bearer). */
+export interface CreateTestSessionOptions {
+    baseUrl: string;
+    apiKey?: string;
+    accessToken?: string;
+    appUserAccessToken?: string;
+    appUserRefreshToken?: string;
+    context?: DatabaseContext;
+    platformConsole?: boolean;
+    projectId?: string;
+    /** Keep `apiKey` / `accessToken` on the client and send `X-Test-Auth: required` on each request. */
+    testRequireAuth?: boolean;
+    onSessionTokensUpdated?: (pair: TokenPair) => void;
+    onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
+    onSessionInvalid?: () => void;
 }
 /** Application user (tenant-scoped), distinct from developer users. */
 export interface AppUser {

package/dist/websocket.js

@@ -19,6 +19,11 @@ class WebSocketSubscription {
         const token = this.headerParams['Authorization']?.replace(/^Bearer\s+/i, '');
         if (token)
             u.searchParams.set('access_token', token);
+        if (!u.searchParams.has('access_token')) {
+            const appUser = this.headerParams['X-App-User-Token'];
+            if (appUser)
+                u.searchParams.set('access_token', appUser);
+        }
         const apiKey = this.headerParams['X-API-Key'];
         if (apiKey)
             u.searchParams.set('api_key', apiKey);

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,32 @@ 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.
+
+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, normal JWT/API-key checks are bypassed for those requests (synthetic admin for wet tests). Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
+
+## 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`.
+
+2. **Browser WebSocket requires correct CORS and proxy config.** Browsers add an `Origin` header to WebSocket connections — make sure your project's CORS allowed-origins includes your app's origin. Reverse proxies (nginx) must forward WebSocket `Upgrade` requests to XCiteDB's `/api/v1/ws` endpoint (the default `docker/nginx.conf` already does this). For production deployments that need fine-grained server-side filtering or short-lived auth tickets, consider proxying the WebSocket through your own backend:
+
+   ```
+   Browser ──ws──▶ Your API server ──ws──▶ XCiteDB /api/v1/ws
+            (same origin,            (server-to-server,
+             short ticket)            secret API key + user JWT)
+   ```
+
+3. **Prefer `context.project_id` over `platformConsole` for project-scoped API keys.** `platformConsole` / `projectId` is designed for platform-operator keys that select a project dynamically via the `X-Project-Id` header. For project-scoped keys (which already identify their project), set **`context.project_id`** instead — it adds `tenant_id` to app-auth JSON bodies via `mergeAppTenant()` without sending `X-Project-Id`.
+
+4. **Prefer `https://` in `baseUrl` for remote/production hosts.** XciteDB's default nginx uses a method-preserving **308** redirect (POST stays POST), but third-party proxies or older configurations may use **301** which silently downgrades POST to GET. Using `https://` directly avoids the redirect entirely.
+
+5. **`context.project_id` (or `tenant_id`) is required for app-user self-registration.** `registerAppUser()` uses `mergeAppTenant(body)` to add `tenant_id` to the JSON body only when `context.project_id` or `context.tenant_id` is set. If both are omitted, the server cannot determine which project to register the user in. Always set `project_id` in the constructor `context` when calling `registerAppUser`, `loginAppUser`, and other public app-auth methods.
+
+6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
+
 ---
 
 # Part 1: Product Overview
@@ -72,7 +98,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 +107,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 +142,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
 
@@ -157,6 +184,26 @@ Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oau
 
 ---
 
+# Ephemeral test sessions
+
+For **integration and wet tests** against a shared BaaS host without touching production data:
+
+| Step | What to do |
+|------|------------|
+| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). |
+| **Use** | Send **`X-Test-Session: <session_token>`** on document and other data API requests. The server routes to a dedicated LMDB under its data root (`_test/<id>/`), not the caller’s production tenant. **`tenant_id` / `X-Project-Id` semantics do not select production** while the test header is present—the synthetic test tenant is implied. |
+| **Auth** | **Default:** test requests **skip** normal auth (convenient for automated tests). **`X-Test-Auth: required`:** require normal Bearer or API key; identity and ABAC apply, but data still comes from the test session DB. |
+| **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. |
+| **CORS** | Browsers may need **`X-Test-Session`** and **`X-Test-Auth`** in the deployment’s allowed CORS headers (defaults include them). |
+
+**SDK usage (summary):**
+
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })` returns a client configured with `testSessionToken`; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor.
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key` (and optional `test_require_auth`); `destroy_test_session()`.
+
+---
+
 # Health, version & discovery
 
 ## Health
@@ -876,7 +923,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 +965,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 +979,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 +1000,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 +1016,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 +1065,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`
@@ -1031,7 +1084,7 @@ interface DatabaseContext {
 - `deleteTrigger(name)` → `void`
 
 ### App User Auth
-- `registerAppUser(email, password, displayName?, groups?, attributes?)` → `AppUser`
+- `registerAppUser(email, password, displayName?, attributes?)` → `AppUser` (groups assigned from server config)
 - `loginAppUser(email, password)` → `AppUserTokenPair`
 - `refreshAppUser()` → `AppUserTokenPair`
 - `logoutAppUser()` → `void`
@@ -1070,6 +1123,9 @@ interface DatabaseContext {
 
 ### WebSocket
 - `subscribe(options: SubscriptionOptions, callback, onError?)` → `WebSocketSubscription`
+- Browser WebSocket cannot send HTTP headers. The SDK maps credentials to query params:
+  `Authorization: Bearer <jwt>` → `?access_token=<jwt>`, `X-App-User-Token` → `?access_token=<jwt>` (fallback),
+  `X-API-Key` → `?api_key=<key>`. The SDK also propagates `context.project_id` as `?tenant_id=`.
 
 ## Key Types
 
@@ -1116,7 +1172,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 +1186,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 +1221,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,32 @@ 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.
+
+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 those requests **skip** normal auth; send **`X-Test-Auth: required`** to exercise real JWT/API-key auth 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).
+
+## 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`.
+
+2. **Browser WebSocket requires correct CORS and proxy config.** Browsers add an `Origin` header to WebSocket connections — make sure your project's CORS allowed-origins includes your app's origin. Reverse proxies (nginx) must forward WebSocket `Upgrade` requests to XCiteDB's `/api/v1/ws` endpoint (the default `docker/nginx.conf` already does this). For production deployments that need fine-grained server-side filtering or short-lived auth tickets, consider proxying the WebSocket through your own backend.
+
+3. **Prefer `context.project_id` over `platformConsole` for project-scoped API keys.** `platformConsole` / `projectId` is designed for platform-operator keys that select a project dynamically via the `X-Project-Id` header. For project-scoped keys (which already identify their project), set **`context.project_id`** instead — it adds `tenant_id` to app-auth JSON bodies via `mergeAppTenant()` without sending `X-Project-Id`.
+
+4. **Prefer `https://` in `baseUrl` for remote/production hosts.** XciteDB's default nginx uses a method-preserving **308** redirect (POST stays POST), but third-party proxies or older configurations may use **301** which silently downgrades POST to GET. Using `https://` directly avoids the redirect entirely.
+
+5. **`context.project_id` (or `tenant_id`) is required for app-user self-registration.** `registerAppUser()` uses `mergeAppTenant(body)` to add `tenant_id` to the JSON body only when `context.project_id` or `context.tenant_id` is set. If both are omitted, the server cannot determine which project to register the user in. Always set `project_id` in the constructor `context` when calling `registerAppUser`, `loginAppUser`, and other public app-auth methods.
+
+6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
+
+## Test mode (how to use)
+
+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.
+3. **Auth behavior:** Omit extra headers for frictionless tests. To test policies and real identities, 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.
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -49,7 +75,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 +85,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 +134,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 +153,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 +163,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 +175,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
@@ -167,11 +208,14 @@ interface XCiteDBClientOptions {
 
 **App Users (admin):**
 - `listAppUsers()` / `createAppUser()` / `deleteAppUser()` — Manage end-user accounts
-- `registerAppUser()` — Self-registration
+- `registerAppUser(email, password, displayName?, attributes?)` — Self-registration (groups assigned from server config)
 - `getAppAuthConfig()` — Auth configuration
 
 **WebSocket:**
 - `subscribe(options, callback, onError?)` — Real-time document change notifications
+- Browser WebSocket cannot send HTTP headers. The SDK maps credentials to query params:
+  `Authorization: Bearer <jwt>` → `?access_token=<jwt>`, `X-App-User-Token` → `?access_token=<jwt>` (fallback),
+  `X-API-Key` → `?api_key=<key>`. The SDK also propagates `context.project_id` as `?tenant_id=`.
 
 ### Query Flags
 
@@ -191,7 +235,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 +246,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 +283,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.6",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",