@xcitedbs/client 0.2.10 → 0.2.12

package/README.md

@@ -34,6 +34,19 @@ const docs = await client.queryByIdentifier('/test1', 'FirstMatch');
 await client.put('app.settings', { theme: 'dark' });
 ```
 
+### Full-text search (temporal)
+
+`client.search()` accepts `TextSearchQuery` with optional **`at_date`** (point-in-time), **`date_from`** / **`date_to`** (range overlap), and **`mode`: `'fts'`** for pure keyword search. Omit temporal fields for the default “current” posting view. Hits may include **`valid_from`** / **`valid_to`** (7-character internal date keys returned by the server).
+
+```typescript
+await client.search({
+  query: 'installation guide',
+  mode: 'fts',
+  at_date: '2024-06-01',
+  limit: 20,
+});
+```
+
 ### WebSocket
 
 ```typescript
@@ -45,6 +58,15 @@ client.subscribe(
 
 With JWT in browsers, tokens are passed as `access_token` query parameter on the WebSocket URL. API keys can use `api_key` query parameter.
 
+## Test sessions (ephemeral and overlay)
+
+Call **`POST /api/v1/test/sessions`** with your normal API key or Bearer (same project context as usual). Use **`XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`** to get a client that sends **`X-Test-Session`** on requests.
+
+- **Default:** isolated empty LMDB under the server’s `_test/<uuid>/` (writes never touch production).
+- **Overlay:** pass **`overlay: true`** in **`createTestSession`** options (or **`POST`** body **`{"overlay":true}`**). The server layers a writable LMDB on top of the **current project’s on-disk data opened read-only** so you can debug against real data; changes still live only under `_test/<uuid>/`. Use project-scoped credentials or platform Bearer + **`X-Project-Id`** as when calling production APIs.
+
+Tear down with **`destroyTestSession()`** (or **`DELETE /api/v1/test/sessions/current`** with the session header). See **`llms.txt`** / **`llms-full.txt`** in this package for full behavior, limits, and auth notes.
+
 ## Build
 
 ```bash

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, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -18,10 +18,13 @@ export declare class XCiteDBClient {
     private testRequireAuth?;
     private userIsolation?;
     private cachedAppUserId?;
+    private readonly requestTimeoutMs?;
     constructor(options: XCiteDBClientOptions);
     /**
-     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * Create an ephemeral test 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).
+     * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
+     * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
     static createTestSession(opts: CreateTestSessionOptions): Promise<XCiteDBClient>;
     /**
@@ -293,12 +296,34 @@ export declare class XCiteDBClient {
      * the server (namespace + shared paths). Does not send `X-Prefix`; identifiers in requests are rewritten.
      */
     enableUserIsolation(): Promise<UserIsolationConfig>;
+    createWorkspace(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
+    /** @deprecated Use {@link createWorkspace}. */
     createBranch(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
+    deleteWorkspace(name: string): Promise<void>;
+    /** @deprecated Use {@link deleteWorkspace}. */
     deleteBranch(name: string): Promise<void>;
+    deleteWorkspaceRevision(workspace: string, date: string): Promise<void>;
+    /** @deprecated Use {@link deleteWorkspaceRevision}. */
     deleteRevision(branch: string, date: string): Promise<void>;
+    listWorkspaces(): Promise<WorkspaceInfo[]>;
+    /** @deprecated Use {@link listWorkspaces}. */
     listBranches(): Promise<BranchInfo[]>;
+    getWorkspace(name: string): Promise<WorkspaceInfo>;
+    /** @deprecated Use {@link getWorkspace}. */
     getBranch(name: string): Promise<BranchInfo>;
+    createCheckpoint(message: string, author?: string): Promise<CheckpointRecord>;
+    /** @deprecated Use {@link createCheckpoint}. */
     createCommit(message: string, author?: string): Promise<CommitRecord>;
+    listCheckpoints(options?: {
+        branch?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        checkpoints: CheckpointRecord[];
+        total: number;
+        branch: string;
+    }>;
+    /** @deprecated Use {@link listCheckpoints}. */
     listCommits(options?: {
         branch?: string;
         limit?: number;
@@ -308,13 +333,33 @@ export declare class XCiteDBClient {
         total: number;
         branch: string;
     }>;
+    getCheckpoint(checkpointId: string): Promise<CheckpointRecord>;
+    /** @deprecated Use {@link getCheckpoint}. */
     getCommit(commitId: string): Promise<CommitRecord>;
+    revertToCheckpoint(checkpointId: string, _confirm?: boolean): Promise<{
+        rolled_back_checkpoints: string[];
+        rolled_back_commits?: string[];
+        current_tip: string;
+    }>;
+    /** @deprecated Use {@link revertToCheckpoint}. */
     rollbackToCommit(commitId: string, _confirm?: boolean): Promise<{
         rolled_back_commits: string[];
         current_tip: string;
     }>;
+    applyCheckpoint(checkpointId: string, message?: string, author?: string): Promise<CheckpointRecord>;
+    /** @deprecated Use {@link applyCheckpoint}. */
     cherryPick(commitId: string, message?: string, author?: string): Promise<CommitRecord>;
+    createBookmark(name: string, checkpointId: string, message?: string, author?: string): Promise<BookmarkRecord>;
+    /** @deprecated Use {@link createBookmark}. */
     createTag(name: string, commitId: string, message?: string, author?: string): Promise<TagRecord>;
+    listBookmarks(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        bookmarks: BookmarkRecord[];
+        total: number;
+    }>;
+    /** @deprecated Use {@link listBookmarks}. */
     listTags(options?: {
         limit?: number;
         offset?: number;
@@ -322,23 +367,44 @@ export declare class XCiteDBClient {
         tags: TagRecord[];
         total: number;
     }>;
+    getBookmark(name: string): Promise<BookmarkRecord>;
+    /** @deprecated Use {@link getBookmark}. */
     getTag(name: string): Promise<TagRecord>;
+    deleteBookmark(name: string): Promise<void>;
+    /** @deprecated Use {@link deleteBookmark}. */
     deleteTag(name: string): Promise<void>;
+    compare(from: CompareRef, to: CompareRef, includeContent?: boolean): Promise<CompareResult>;
+    /** @deprecated Use {@link compare}. */
     diff(from: DiffRef, to: DiffRef, includeContent?: boolean): Promise<DiffResult>;
+    publishWorkspace(targetWorkspace: string, sourceWorkspace: string, options?: {
+        message?: string;
+        autoResolve?: 'none' | 'source' | 'target';
+    }): Promise<PublishResult>;
+    /** @deprecated Use {@link publishWorkspace}. */
     mergeBranch(targetBranch: string, sourceBranch: string, options?: {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';
     }): Promise<MergeResult>;
     /**
-     * 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.
+     * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
+     * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.
      */
+    withWorkspace<T>(workspaceName: string, fn: (client: XCiteDBClient) => Promise<T>, options?: {
+        message?: string;
+        /** When true (default), publish `workspaceName` into the parent workspace after checkpoint. */
+        autoMerge?: boolean;
+        /** Workspace to fork from (default: current `context.branch` / `context.workspace`, or `""`). */
+        fromBranch?: string;
+        author?: string;
+    }): Promise<{
+        result: T;
+        checkpoint?: CheckpointRecord;
+        publish?: PublishResult;
+    }>;
+    /** @deprecated Use {@link withWorkspace}. */
     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<{
@@ -421,6 +487,18 @@ export declare class XCiteDBClient {
     getProjectSearchSettings(): Promise<ProjectSearchSettings>;
     /** Update project search settings (`PUT /api/v1/project/settings/search`). Returns the same shape as GET. */
     updateProjectSearchSettings(patch: ProjectSearchSettingsUpdate): Promise<ProjectSearchSettings>;
+    /** Per-project `document.conf` override (`GET /api/v1/project/settings/doc-conf`). */
+    getProjectDocConf(): Promise<ProjectDocConfResponse>;
+    /** Save or clear project `document.conf` (`PUT /api/v1/project/settings/doc-conf`). */
+    updateProjectDocConf(body: {
+        doc_conf_text: string;
+    } | {
+        clear: true;
+    }): Promise<ProjectDocConfResponse>;
+    /** Remove project override; server uses platform default (`DELETE /api/v1/project/settings/doc-conf`). */
+    deleteProjectDocConf(): Promise<ProjectDocConfResponse>;
+    /** Embedded platform default `document.conf` text (`GET /api/v1/platform/default-doc-conf`). */
+    getPlatformDefaultDocConf(): Promise<PlatformDefaultDocConfResponse>;
     /** Blocking full DB scan (admin; no calls to embedding API). Prefer {@link postVectorIndexEstimateSession} for UI. */
     getVectorIndexEstimate(): Promise<VectorIndexEstimate>;
     /** Start background estimate (202); cancel prior session for this tenant. */

package/dist/client.js

@@ -18,6 +18,30 @@ function buildQuery(params) {
     const s = sp.toString();
     return s ? `?${s}` : '';
 }
+function warnIfHttpOnTlsPort(baseUrl) {
+    try {
+        const u = new URL(baseUrl);
+        if (u.protocol !== 'http:')
+            return;
+        if (u.port === '443') {
+            if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+                console.warn('[@xcitedbs/client] baseUrl uses http: on port 443; use https:// to avoid hangs or TLS errors.');
+            }
+        }
+    }
+    catch {
+        /* ignore invalid baseUrl */
+    }
+}
+/** Uses `AbortSignal.timeout` when the runtime supports it. */
+function requestTimeoutSignal(ms) {
+    if (ms === undefined || ms <= 0)
+        return undefined;
+    const ctor = AbortSignal;
+    if (typeof ctor.timeout === 'function')
+        return ctor.timeout(ms);
+    return undefined;
+}
 class XCiteDBClient {
     constructor(options) {
         this.baseUrl = options.baseUrl.replace(/\/+$/, '');
@@ -34,10 +58,14 @@ class XCiteDBClient {
         this.testSessionToken = options.testSessionToken;
         this.testRequireAuth = options.testRequireAuth === true;
         this.userIsolation = options.userIsolation;
+        this.requestTimeoutMs = options.requestTimeoutMs;
+        warnIfHttpOnTlsPort(this.baseUrl);
     }
     /**
-     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * Create an ephemeral test 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).
+     * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
+     * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
     static async createTestSession(opts) {
         const temp = new XCiteDBClient({
@@ -53,8 +81,9 @@ class XCiteDBClient {
             onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
             onSessionInvalid: opts.onSessionInvalid,
             userIsolation: opts.userIsolation,
+            requestTimeoutMs: opts.requestTimeoutMs,
         });
-        const data = await temp.request('POST', '/api/v1/test/sessions', undefined, undefined, { no401Retry: true });
+        const data = await temp.request('POST', '/api/v1/test/sessions', opts.overlay === true ? { overlay: true } : undefined, undefined, { no401Retry: true });
         return new XCiteDBClient({
             baseUrl: opts.baseUrl,
             apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
@@ -70,6 +99,7 @@ class XCiteDBClient {
             testSessionToken: data.session_token,
             testRequireAuth: opts.testRequireAuth,
             userIsolation: opts.userIsolation,
+            requestTimeoutMs: opts.requestTimeoutMs,
         });
     }
     /**
@@ -345,7 +375,11 @@ class XCiteDBClient {
         this.projectId = projectId;
     }
     setContext(ctx) {
-        this.defaultContext = { ...this.defaultContext, ...ctx };
+        const next = { ...this.defaultContext, ...ctx };
+        if (ctx.workspace !== undefined) {
+            next.branch = ctx.workspace;
+        }
+        this.defaultContext = next;
     }
     setTokens(access, refresh) {
         this.accessToken = access;
@@ -367,8 +401,9 @@ class XCiteDBClient {
     contextHeaders() {
         const h = {};
         const c = this.defaultContext;
-        if (c.branch)
-            h['X-Branch'] = c.branch;
+        const ws = c.workspace ?? c.branch;
+        if (ws)
+            h['X-Workspace'] = ws;
         if (c.date)
             h['X-Date'] = c.date;
         if (c.prefix)
@@ -439,6 +474,9 @@ class XCiteDBClient {
                     init.body = JSON.stringify(body);
                 }
             }
+            const sig = requestTimeoutSignal(this.requestTimeoutMs);
+            if (sig)
+                init.signal = sig;
             const res = await fetch(url, init);
             const text = await res.text();
             let data;
@@ -941,121 +979,202 @@ class XCiteDBClient {
         }
         return cfg;
     }
-    async createBranch(name, fromBranch, fromDate) {
+    async createWorkspace(name, fromBranch, fromDate) {
         const body = { name };
         if (fromBranch)
             body.from_branch = fromBranch;
         if (fromDate)
             body.from_date = fromDate;
-        await this.request('POST', '/api/v1/branches', body);
+        await this.request('POST', '/api/v1/workspaces', body);
     }
+    /** @deprecated Use {@link createWorkspace}. */
+    async createBranch(name, fromBranch, fromDate) {
+        return this.createWorkspace(name, fromBranch, fromDate);
+    }
+    async deleteWorkspace(name) {
+        await this.request('DELETE', `/api/v1/workspaces/${encodeURIComponent(name)}`);
+    }
+    /** @deprecated Use {@link deleteWorkspace}. */
     async deleteBranch(name) {
-        await this.request('DELETE', `/api/v1/branches/${encodeURIComponent(name)}`);
+        return this.deleteWorkspace(name);
+    }
+    async deleteWorkspaceRevision(workspace, date) {
+        await this.request('DELETE', `/api/v1/workspaces/${encodeURIComponent(workspace)}/revisions/${encodeURIComponent(date)}`);
     }
+    /** @deprecated Use {@link deleteWorkspaceRevision}. */
     async deleteRevision(branch, date) {
-        await this.request('DELETE', `/api/v1/branches/${encodeURIComponent(branch)}/revisions/${encodeURIComponent(date)}`);
+        return this.deleteWorkspaceRevision(branch, date);
     }
+    async listWorkspaces() {
+        const r = await this.request('GET', '/api/v1/workspaces');
+        return r.workspaces ?? r.branches ?? [];
+    }
+    /** @deprecated Use {@link listWorkspaces}. */
     async listBranches() {
-        const r = await this.request('GET', '/api/v1/branches');
-        return r.branches ?? [];
+        return this.listWorkspaces();
+    }
+    async getWorkspace(name) {
+        const r = await this.request('GET', `/api/v1/workspaces/${encodeURIComponent(name)}`);
+        return (r.workspace ?? r.branch);
     }
+    /** @deprecated Use {@link getWorkspace}. */
     async getBranch(name) {
-        const r = await this.request('GET', `/api/v1/branches/${encodeURIComponent(name)}`);
-        return r.branch;
+        return this.getWorkspace(name);
     }
-    async createCommit(message, author) {
+    async createCheckpoint(message, author) {
         const body = { message };
         if (author)
             body.author = author;
-        const r = await this.request('POST', '/api/v1/commits', body);
-        return r.commit;
+        const r = await this.request('POST', '/api/v1/checkpoints', body);
+        return (r.checkpoint ?? r.commit);
     }
-    async listCommits(options) {
+    /** @deprecated Use {@link createCheckpoint}. */
+    async createCommit(message, author) {
+        return this.createCheckpoint(message, author);
+    }
+    async listCheckpoints(options) {
         const q = buildQuery({
             branch: options?.branch,
             limit: options?.limit,
             offset: options?.offset,
         });
-        return this.request('GET', `/api/v1/commits${q}`);
+        const r = await this.request('GET', `/api/v1/checkpoints${q}`);
+        const list = r.checkpoints ?? r.commits ?? [];
+        return { checkpoints: list, total: r.total, branch: r.branch };
+    }
+    /** @deprecated Use {@link listCheckpoints}. */
+    async listCommits(options) {
+        const r = await this.listCheckpoints(options);
+        return { commits: r.checkpoints, total: r.total, branch: r.branch };
+    }
+    async getCheckpoint(checkpointId) {
+        const r = await this.request('GET', `/api/v1/checkpoints/${encodeURIComponent(checkpointId)}`);
+        return (r.checkpoint ?? r.commit);
     }
+    /** @deprecated Use {@link getCheckpoint}. */
     async getCommit(commitId) {
-        const r = await this.request('GET', `/api/v1/commits/${encodeURIComponent(commitId)}`);
-        return r.commit;
+        return this.getCheckpoint(commitId);
     }
-    async rollbackToCommit(commitId, _confirm) {
-        return this.request('POST', `/api/v1/commits/${encodeURIComponent(commitId)}/rollback`, {
+    async revertToCheckpoint(checkpointId, _confirm) {
+        return this.request('POST', `/api/v1/checkpoints/${encodeURIComponent(checkpointId)}/revert`, {
             confirm: true,
         });
     }
-    async cherryPick(commitId, message, author) {
+    /** @deprecated Use {@link revertToCheckpoint}. */
+    async rollbackToCommit(commitId, _confirm) {
+        const r = await this.revertToCheckpoint(commitId, _confirm);
+        return {
+            rolled_back_commits: r.rolled_back_commits ?? r.rolled_back_checkpoints,
+            current_tip: r.current_tip,
+        };
+    }
+    async applyCheckpoint(checkpointId, message, author) {
         const body = {};
         if (message)
             body.message = message;
         if (author)
             body.author = author;
-        const r = await this.request('POST', `/api/v1/commits/${encodeURIComponent(commitId)}/cherry-pick`, body);
-        return r.commit;
+        const r = await this.request('POST', `/api/v1/checkpoints/${encodeURIComponent(checkpointId)}/apply`, body);
+        return (r.checkpoint ?? r.commit);
     }
-    async createTag(name, commitId, message, author) {
-        const body = { name, commit_id: commitId };
+    /** @deprecated Use {@link applyCheckpoint}. */
+    async cherryPick(commitId, message, author) {
+        return this.applyCheckpoint(commitId, message, author);
+    }
+    async createBookmark(name, checkpointId, message, author) {
+        const body = { name, checkpoint_id: checkpointId };
         if (message)
             body.message = message;
         if (author)
             body.author = author;
-        const r = await this.request('POST', '/api/v1/tags', body);
-        return r.tag;
+        const r = await this.request('POST', '/api/v1/bookmarks', body);
+        return (r.bookmark ?? r.tag);
     }
-    async listTags(options) {
+    /** @deprecated Use {@link createBookmark}. */
+    async createTag(name, commitId, message, author) {
+        return this.createBookmark(name, commitId, message, author);
+    }
+    async listBookmarks(options) {
         const q = buildQuery({ limit: options?.limit, offset: options?.offset });
-        return this.request('GET', `/api/v1/tags${q}`);
+        const r = await this.request('GET', `/api/v1/bookmarks${q}`);
+        const list = r.bookmarks ?? r.tags ?? [];
+        return { bookmarks: list, total: r.total };
     }
+    /** @deprecated Use {@link listBookmarks}. */
+    async listTags(options) {
+        const r = await this.listBookmarks(options);
+        return { tags: r.bookmarks, total: r.total };
+    }
+    async getBookmark(name) {
+        const r = await this.request('GET', `/api/v1/bookmarks/${encodeURIComponent(name)}`);
+        return (r.bookmark ?? r.tag);
+    }
+    /** @deprecated Use {@link getBookmark}. */
     async getTag(name) {
-        const r = await this.request('GET', `/api/v1/tags/${encodeURIComponent(name)}`);
-        return r.tag;
+        return this.getBookmark(name);
+    }
+    async deleteBookmark(name) {
+        await this.request('DELETE', `/api/v1/bookmarks/${encodeURIComponent(name)}`);
     }
+    /** @deprecated Use {@link deleteBookmark}. */
     async deleteTag(name) {
-        await this.request('DELETE', `/api/v1/tags/${encodeURIComponent(name)}`);
+        return this.deleteBookmark(name);
     }
-    async diff(from, to, includeContent) {
-        return this.request('POST', '/api/v1/diff', {
+    async compare(from, to, includeContent) {
+        return this.request('POST', '/api/v1/compare', {
             from,
             to,
             include_content: includeContent ?? false,
         });
     }
-    async mergeBranch(targetBranch, sourceBranch, options) {
-        const body = { source_branch: sourceBranch };
+    /** @deprecated Use {@link compare}. */
+    async diff(from, to, includeContent) {
+        return this.compare(from, to, includeContent);
+    }
+    async publishWorkspace(targetWorkspace, sourceWorkspace, options) {
+        const body = {
+            source_workspace: sourceWorkspace,
+            source_branch: sourceWorkspace,
+        };
         if (options?.message)
             body.message = options.message;
         body.auto_resolve = options?.autoResolve ?? 'none';
-        return this.request('POST', `/api/v1/branches/${encodeURIComponent(targetBranch)}/merge`, body);
+        return this.request('POST', `/api/v1/workspaces/${encodeURIComponent(targetWorkspace)}/publish`, body);
+    }
+    /** @deprecated Use {@link publishWorkspace}. */
+    async mergeBranch(targetBranch, sourceBranch, options) {
+        return this.publishWorkspace(targetBranch, sourceBranch, options);
     }
     /**
-     * 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.
+     * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
+     * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.
      */
-    async withBranch(branchName, fn, options) {
+    async withWorkspace(workspaceName, fn, options) {
         const prev = { ...this.defaultContext };
-        const fromBranch = options?.fromBranch ?? prev.branch ?? '';
-        let commit;
-        let merge;
+        const fromWs = options?.fromBranch ?? prev.branch ?? prev.workspace ?? '';
+        let checkpoint;
+        let publish;
         try {
-            await this.createBranch(branchName, fromBranch || undefined, prev.date || undefined);
-            this.setContext({ branch: branchName });
+            await this.createWorkspace(workspaceName, fromWs || undefined, prev.date || undefined);
+            this.setContext({ workspace: workspaceName, branch: workspaceName });
             const result = await fn(this);
-            commit = await this.createCommit(options?.message ?? `Branch ${branchName}`, options?.author);
+            checkpoint = await this.createCheckpoint(options?.message ?? `Workspace ${workspaceName}`, options?.author);
             if (options?.autoMerge !== false) {
-                merge = await this.mergeBranch(fromBranch, branchName, {
+                publish = await this.publishWorkspace(fromWs, workspaceName, {
                     message: options?.message,
                 });
             }
-            return { result, commit, merge };
+            return { result, checkpoint, publish };
         }
         finally {
             this.setContext(prev);
         }
     }
+    /** @deprecated Use {@link withWorkspace}. */
+    async withBranch(branchName, fn, options) {
+        const r = await this.withWorkspace(branchName, fn, options);
+        return { result: r.result, commit: r.checkpoint, merge: r.publish };
+    }
     /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
     async writeXML(xml, _options) {
         const payload = this.isoApplyXmlDbIdentifier(xml);
@@ -1324,12 +1443,18 @@ class XCiteDBClient {
             body.offset = q.offset;
         if (q.limit !== undefined)
             body.limit = q.limit;
-        if (q.mode)
+        if (q.mode !== undefined)
             body.mode = q.mode;
         if (q.min_score !== undefined)
             body.min_score = q.min_score;
         if (q.semantic_weight !== undefined)
             body.semantic_weight = q.semantic_weight;
+        if (q.at_date !== undefined && q.at_date !== '')
+            body.at_date = q.at_date;
+        if (q.date_from !== undefined && q.date_from !== '')
+            body.date_from = q.date_from;
+        if (q.date_to !== undefined && q.date_to !== '')
+            body.date_to = q.date_to;
         const data = await this.request('POST', '/api/v1/search', body);
         const hits = [];
         if (Array.isArray(data.hits)) {
@@ -1350,6 +1475,12 @@ class XCiteDBClient {
                     if (o.source === 'fts' || o.source === 'semantic' || o.source === 'both') {
                         hit.source = o.source;
                     }
+                    if (typeof o.valid_from === 'string' && o.valid_from.length > 0) {
+                        hit.valid_from = o.valid_from;
+                    }
+                    if (typeof o.valid_to === 'string' && o.valid_to.length > 0) {
+                        hit.valid_to = o.valid_to;
+                    }
                     hits.push(hit);
                 }
             }
@@ -1374,6 +1505,22 @@ class XCiteDBClient {
     async updateProjectSearchSettings(patch) {
         return this.request('PUT', '/api/v1/project/settings/search', patch);
     }
+    /** Per-project `document.conf` override (`GET /api/v1/project/settings/doc-conf`). */
+    async getProjectDocConf() {
+        return this.request('GET', '/api/v1/project/settings/doc-conf');
+    }
+    /** Save or clear project `document.conf` (`PUT /api/v1/project/settings/doc-conf`). */
+    async updateProjectDocConf(body) {
+        return this.request('PUT', '/api/v1/project/settings/doc-conf', body);
+    }
+    /** Remove project override; server uses platform default (`DELETE /api/v1/project/settings/doc-conf`). */
+    async deleteProjectDocConf() {
+        return this.request('DELETE', '/api/v1/project/settings/doc-conf');
+    }
+    /** Embedded platform default `document.conf` text (`GET /api/v1/platform/default-doc-conf`). */
+    async getPlatformDefaultDocConf() {
+        return this.request('GET', '/api/v1/platform/default-doc-conf');
+    }
     /** Blocking full DB scan (admin; no calls to embedding API). Prefer {@link postVectorIndexEstimateSession} for UI. */
     async getVectorIndexEstimate() {
         return this.request('GET', '/api/v1/project/settings/search/vector-index-estimate', undefined);

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, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationOptions, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationOptions, WorkspaceInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';