@xcitedbs/client 0.2.9 → 0.2.11

package/dist/client.js

@@ -33,6 +33,7 @@ class XCiteDBClient {
         this.onSessionInvalid = options.onSessionInvalid;
         this.testSessionToken = options.testSessionToken;
         this.testRequireAuth = options.testRequireAuth === true;
+        this.userIsolation = options.userIsolation;
     }
     /**
      * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
@@ -51,6 +52,7 @@ class XCiteDBClient {
             onSessionTokensUpdated: opts.onSessionTokensUpdated,
             onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
             onSessionInvalid: opts.onSessionInvalid,
+            userIsolation: opts.userIsolation,
         });
         const data = await temp.request('POST', '/api/v1/test/sessions', undefined, undefined, { no401Retry: true });
         return new XCiteDBClient({
@@ -67,6 +69,7 @@ class XCiteDBClient {
             onSessionInvalid: opts.onSessionInvalid,
             testSessionToken: data.session_token,
             testRequireAuth: opts.testRequireAuth,
+            userIsolation: opts.userIsolation,
         });
     }
     /**
@@ -144,6 +147,154 @@ class XCiteDBClient {
             jti: typeof jti === 'string' ? jti : undefined,
         };
     }
+    cacheAppUserIdFromPair(pair) {
+        if (pair?.user?.user_id) {
+            this.cachedAppUserId = pair.user.user_id;
+        }
+    }
+    clearAppUserIdCache() {
+        this.cachedAppUserId = undefined;
+    }
+    getAppUserId() {
+        if (this.cachedAppUserId) {
+            return this.cachedAppUserId;
+        }
+        const raw = this.appUserAccessToken;
+        if (!raw) {
+            return undefined;
+        }
+        const p = XCiteDBClient.decodeJwtPayloadJson(raw);
+        if (!p) {
+            return undefined;
+        }
+        const sub = p['sub'];
+        if (typeof sub === 'string' && sub.length > 0) {
+            return sub;
+        }
+        const uid = p['user_id'];
+        if (typeof uid === 'string' && uid.length > 0) {
+            return uid;
+        }
+        return undefined;
+    }
+    normalizeIsolationNamespaceTemplate(tpl) {
+        return tpl.replace(/\$\{user\.id\}/g, '{userId}');
+    }
+    canonicalId(s) {
+        let t = s.trim().replace(/\/+/g, '/');
+        if (!t.startsWith('/')) {
+            t = `/${t}`;
+        }
+        return t;
+    }
+    /** Resolved namespace root, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
+    userIsolationNamespace() {
+        if (!this.userIsolation?.enabled) {
+            return null;
+        }
+        const uid = this.getAppUserId();
+        if (!uid) {
+            return null;
+        }
+        const rawTpl = this.normalizeIsolationNamespaceTemplate(this.userIsolation.namespace ?? '/users/{userId}');
+        const trimmed = rawTpl.replace(/\/+$/, '') || '';
+        if (!trimmed) {
+            return null;
+        }
+        return trimmed.replace(/{userId}/g, uid).replace(/{user_id}/g, uid);
+    }
+    allSharedPassthroughPrefixes() {
+        const o = this.userIsolation;
+        if (!o) {
+            return [];
+        }
+        return [...(o.shared_read_paths ?? []), ...(o.shared_write_paths ?? [])];
+    }
+    pathMatchesSharedPassthrough(path) {
+        const canon = this.canonicalId(path);
+        for (const raw of this.allSharedPassthroughPrefixes()) {
+            if (!raw) {
+                continue;
+            }
+            const p = this.canonicalId(raw);
+            if (canon === p) {
+                return true;
+            }
+            if (p.endsWith('/') && canon.startsWith(p)) {
+                return true;
+            }
+            if (!p.endsWith('/') && (canon === p || canon.startsWith(`${p}/`))) {
+                return true;
+            }
+        }
+        return false;
+    }
+    isoPrefixId(id) {
+        const ns = this.userIsolationNamespace();
+        if (!ns) {
+            return id;
+        }
+        if (id.includes('..')) {
+            throw new types_1.XCiteDBError('Invalid identifier: path traversal not allowed', 400, null);
+        }
+        const canonical = this.canonicalId(id);
+        if (canonical.startsWith(`${ns}/`) || canonical === ns) {
+            return canonical;
+        }
+        if (this.pathMatchesSharedPassthrough(canonical)) {
+            return canonical;
+        }
+        if (canonical.startsWith('/users/') && !canonical.startsWith(`${ns}/`) && canonical !== ns) {
+            return canonical;
+        }
+        const combined = `${ns}${canonical === '/' ? '/' : canonical}`;
+        const finalId = combined.replace(/\/+/g, '/');
+        if (!finalId.startsWith(ns) || (finalId.length > ns.length && finalId.charAt(ns.length) !== '/')) {
+            throw new types_1.XCiteDBError('Identifier escapes user namespace', 400, null);
+        }
+        return finalId;
+    }
+    isoUnprefixId(id) {
+        const ns = this.userIsolationNamespace();
+        if (!ns) {
+            return id;
+        }
+        const canonical = this.canonicalId(id);
+        if (this.pathMatchesSharedPassthrough(canonical)) {
+            return canonical;
+        }
+        if (canonical.startsWith(`${ns}/`)) {
+            return canonical.slice(ns.length);
+        }
+        if (canonical === ns) {
+            return '/';
+        }
+        return canonical;
+    }
+    isoPrefixQuery(q) {
+        if (!this.userIsolationNamespace()) {
+            return q;
+        }
+        const out = { ...q };
+        if (out.match) {
+            out.match = this.isoPrefixId(out.match);
+        }
+        if (out.match_start) {
+            out.match_start = this.isoPrefixId(out.match_start);
+        }
+        if (out.match_end) {
+            out.match_end = this.isoPrefixId(out.match_end);
+        }
+        return out;
+    }
+    isoApplyXmlDbIdentifier(xml) {
+        if (!this.userIsolationNamespace()) {
+            return xml;
+        }
+        return xml.replace(/(db:identifier\s*=\s*")([^"]*)(")/, (_m, p1, mid, p3) => {
+            return `${p1}${this.isoPrefixId(String(mid))}${p3}`;
+        });
+    }
     /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
     async destroyTestSession() {
         if (!this.testSessionToken) {
@@ -194,7 +345,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;
@@ -206,16 +361,19 @@ class XCiteDBClient {
         this.appUserAccessToken = access;
         if (refresh !== undefined)
             this.appUserRefreshToken = refresh;
+        this.clearAppUserIdCache();
     }
     clearAppUserTokens() {
         this.appUserAccessToken = undefined;
         this.appUserRefreshToken = undefined;
+        this.clearAppUserIdCache();
     }
     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)
@@ -261,14 +419,19 @@ class XCiteDBClient {
         }
         return h;
     }
+    requestHeaders() {
+        return {
+            ...this.authHeaders(),
+            ...this.contextHeaders(),
+            ...this.testHeaders(),
+        };
+    }
     async request(method, path, body, extraHeaders, opts) {
         const no401Retry = opts?.no401Retry === true;
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
             const headers = {
-                ...this.authHeaders(),
-                ...this.contextHeaders(),
-                ...this.testHeaders(),
+                ...this.requestHeaders(),
                 ...extraHeaders,
             };
             let init = { method, headers };
@@ -336,6 +499,7 @@ class XCiteDBClient {
         const pair = await this.request('POST', '/api/v1/app/auth/refresh', this.mergeAppTenant({ refresh_token: this.appUserRefreshToken }), undefined, { no401Retry: true });
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
+        this.cacheAppUserIdFromPair(pair);
         this.onAppUserTokensUpdated?.(pair);
         return pair;
     }
@@ -474,12 +638,14 @@ class XCiteDBClient {
         const pair = await this.request('POST', '/api/v1/app/auth/oauth/exchange', this.mergeAppTenant({ code }));
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
+        this.cacheAppUserIdFromPair(pair);
         return pair;
     }
     async loginAppUser(email, password) {
         const pair = await this.request('POST', '/api/v1/app/auth/login', this.mergeAppTenant({ email, password }));
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
+        this.cacheAppUserIdFromPair(pair);
         return pair;
     }
     async refreshAppUser() {
@@ -489,6 +655,7 @@ class XCiteDBClient {
         await this.request('POST', '/api/v1/app/auth/logout', this.mergeAppTenant({ refresh_token: this.appUserRefreshToken }));
         this.appUserAccessToken = undefined;
         this.appUserRefreshToken = undefined;
+        this.clearAppUserIdCache();
     }
     async appUserMe() {
         return this.request('GET', '/api/v1/app/auth/me');
@@ -505,6 +672,7 @@ class XCiteDBClient {
         const pair = await this.request('POST', '/api/v1/app/auth/custom-token', { token });
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
+        this.cacheAppUserIdFromPair(pair);
         return pair;
     }
     /** Change app-user password (requires valid app-user access token). */
@@ -721,7 +889,7 @@ class XCiteDBClient {
      * ```
      */
     async checkAccess(subject, identifier, action, metaPath, branch) {
-        const body = { subject, identifier, action };
+        const body = { subject, identifier: this.isoPrefixId(identifier), action };
         if (metaPath !== undefined)
             body.meta_path = metaPath;
         if (branch !== undefined)
@@ -747,124 +915,237 @@ class XCiteDBClient {
     async updateSecurityConfig(config) {
         await this.request('PUT', '/api/v1/security/config', config);
     }
-    async createBranch(name, fromBranch, fromDate) {
+    /** Per-tenant user data spaces (`GET /api/v1/security/user-isolation`). Requires security admin. */
+    async getUserIsolationConfig() {
+        return this.request('GET', '/api/v1/security/user-isolation');
+    }
+    /** Enable or reconfigure user isolation (`PUT /api/v1/security/user-isolation`). */
+    async setUserIsolationConfig(config) {
+        return this.request('PUT', '/api/v1/security/user-isolation', config);
+    }
+    /** Disable user isolation and remove generated policies (`DELETE /api/v1/security/user-isolation`). */
+    async disableUserIsolation() {
+        await this.request('DELETE', '/api/v1/security/user-isolation');
+    }
+    /**
+     * Loads server isolation config; when enabled, configures client-side identifier prefixing to match
+     * the server (namespace + shared paths). Does not send `X-Prefix`; identifiers in requests are rewritten.
+     */
+    async enableUserIsolation() {
+        const cfg = await this.getUserIsolationConfig();
+        if (cfg.enabled) {
+            this.userIsolation = {
+                enabled: true,
+                namespace: cfg.namespace_pattern,
+                shared_read_paths: cfg.shared_read_paths,
+                shared_write_paths: cfg.shared_write_paths,
+            };
+        }
+        else {
+            this.userIsolation = { enabled: false };
+        }
+        return cfg;
+    }
+    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) {
-        await this.request('POST', '/api/v1/documents', xml, {
+        const payload = this.isoApplyXmlDbIdentifier(xml);
+        await this.request('POST', '/api/v1/documents', payload, {
             'Content-Type': 'application/xml',
         });
     }
@@ -874,7 +1155,7 @@ class XCiteDBClient {
      */
     async writeXmlDocument(xml, options) {
         await this.request('POST', '/api/v1/documents', {
-            xml,
+            xml: this.isoApplyXmlDbIdentifier(xml),
             is_top: options?.is_top ?? true,
             compare_attributes: options?.compare_attributes ?? false,
         });
@@ -887,92 +1168,97 @@ class XCiteDBClient {
     }
     async queryByIdentifier(identifier, flags, filter, pathFilter) {
         const q = buildQuery({
-            identifier,
+            identifier: this.isoPrefixId(identifier),
             flags: flags,
             filter,
             path_filter: pathFilter,
         });
-        return this.request('GET', `/api/v1/documents/by-id${q}`);
+        const rows = await this.request('GET', `/api/v1/documents/by-id${q}`);
+        return Array.isArray(rows) ? rows.map((x) => this.isoUnprefixId(String(x))) : rows;
     }
     async queryDocuments(query, flags, filter, pathFilter) {
+        const pq = this.isoPrefixQuery(query);
         const params = {
-            match: query.match,
-            match_start: query.match_start,
-            match_end: query.match_end,
-            regex: query.regex,
+            match: pq.match,
+            match_start: pq.match_start,
+            match_end: pq.match_end,
+            regex: pq.regex,
             flags: flags,
             filter,
             path_filter: pathFilter,
         };
-        if (query.contains !== undefined) {
-            const c = Array.isArray(query.contains) ? query.contains.join(',') : query.contains;
+        if (pq.contains !== undefined) {
+            const c = Array.isArray(pq.contains) ? pq.contains.join(',') : pq.contains;
             params.contains = c;
         }
-        if (query.required_meta_paths !== undefined && query.required_meta_paths.length > 0) {
-            params.required_meta_paths = query.required_meta_paths.join(',');
+        if (pq.required_meta_paths !== undefined && pq.required_meta_paths.length > 0) {
+            params.required_meta_paths = pq.required_meta_paths.join(',');
         }
-        if (query.filter_any_meta === true) {
+        if (pq.filter_any_meta === true) {
             params.any_meta = '1';
         }
-        return this.request('GET', `/api/v1/documents${buildQuery(params)}`);
+        const rows = await this.request('GET', `/api/v1/documents${buildQuery(params)}`);
+        return Array.isArray(rows) ? rows.map((x) => this.isoUnprefixId(String(x))) : rows;
     }
     async deleteDocument(identifier) {
-        await this.request('DELETE', `/api/v1/documents/by-id${buildQuery({ identifier })}`);
+        await this.request('DELETE', `/api/v1/documents/by-id${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
     }
     async addIdentifier(identifier) {
         const r = await this.request('POST', '/api/v1/documents/identifiers', {
-            identifier,
+            identifier: this.isoPrefixId(identifier),
         });
         return r?.ok !== false;
     }
     async addAlias(original, alias) {
-        const r = await this.request('POST', '/api/v1/documents/identifiers/alias', { original, alias });
+        const r = await this.request('POST', '/api/v1/documents/identifiers/alias', { original: this.isoPrefixId(original), alias: this.isoPrefixId(alias) });
         return r?.ok !== false;
     }
     async queryChangeDate(identifier) {
-        const r = await this.request('GET', `/api/v1/documents/change-date${buildQuery({ identifier })}`);
+        const r = await this.request('GET', `/api/v1/documents/change-date${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
         return r?.change_date ?? r?.date ?? '';
     }
     async getXcitepath(identifier) {
-        const r = await this.request('GET', `/api/v1/documents/xcitepath${buildQuery({ identifier })}`);
+        const r = await this.request('GET', `/api/v1/documents/xcitepath${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
         return r?.xcitepath ?? '';
     }
     async changedIdentifiers(branch, fromDate, toDate) {
-        return this.request('GET', `/api/v1/documents/changed${buildQuery({ branch, from_date: fromDate, to_date: toDate })}`);
+        const ids = await this.request('GET', `/api/v1/documents/changed${buildQuery({ branch, from_date: fromDate, to_date: toDate })}`);
+        return Array.isArray(ids) ? ids.map((x) => this.isoUnprefixId(String(x))) : ids;
     }
     async listIdentifiers(query) {
+        const pq = this.isoPrefixQuery(query);
         const params = {
-            match: query.match,
-            match_start: query.match_start,
-            match_end: query.match_end,
-            regex: query.regex,
-            limit: query.limit,
-            offset: query.offset,
+            match: pq.match,
+            match_start: pq.match_start,
+            match_end: pq.match_end,
+            regex: pq.regex,
+            limit: pq.limit,
+            offset: pq.offset,
         };
-        if (query.contains !== undefined) {
-            params.contains = Array.isArray(query.contains)
-                ? query.contains.join(',')
-                : query.contains;
+        if (pq.contains !== undefined) {
+            params.contains = Array.isArray(pq.contains) ? pq.contains.join(',') : pq.contains;
         }
-        if (query.required_meta_paths !== undefined && query.required_meta_paths.length > 0) {
-            params.required_meta_paths = query.required_meta_paths.join(',');
+        if (pq.required_meta_paths !== undefined && pq.required_meta_paths.length > 0) {
+            params.required_meta_paths = pq.required_meta_paths.join(',');
         }
-        if (query.filter_any_meta === true) {
+        if (pq.filter_any_meta === true) {
             params.any_meta = '1';
         }
         const data = await this.request('GET', `/api/v1/documents/identifiers${buildQuery(params)}`);
+        const un = (ids) => ids.map((id) => this.isoUnprefixId(id));
         // Older servers returned a bare string[]; paginated API returns { identifiers, total, offset, limit }.
         if (Array.isArray(data)) {
+            const ids = un(data);
             return {
-                identifiers: data,
-                total: data.length,
+                identifiers: ids,
+                total: ids.length,
                 offset: 0,
-                limit: data.length,
+                limit: ids.length,
             };
         }
         if (data !== null && typeof data === 'object') {
             const o = data;
-            const ids = Array.isArray(o.identifiers) ? o.identifiers : [];
+            const ids = Array.isArray(o.identifiers) ? un(o.identifiers) : [];
             return {
                 identifiers: ids,
                 total: typeof o.total === 'number' ? o.total : ids.length,
@@ -985,7 +1271,7 @@ class XCiteDBClient {
     async listIdentifierChildren(parentPath) {
         const params = {};
         if (parentPath !== undefined && parentPath !== '') {
-            params.parent_path = parentPath;
+            params.parent_path = this.isoPrefixId(parentPath);
         }
         const data = await this.request('GET', `/api/v1/documents/identifier-children${buildQuery(params)}`);
         if (data !== null && typeof data === 'object') {
@@ -998,7 +1284,7 @@ class XCiteDBClient {
                         const r = row;
                         children.push({
                             segment: typeof r.segment === 'string' ? r.segment : '',
-                            full_path: typeof r.full_path === 'string' ? r.full_path : '',
+                            full_path: typeof r.full_path === 'string' ? this.isoUnprefixId(r.full_path) : '',
                             is_identifier: r.is_identifier === true,
                             has_children: r.has_children === true,
                         });
@@ -1006,7 +1292,7 @@ class XCiteDBClient {
                 }
             }
             return {
-                parent_path: typeof o.parent_path === 'string' ? o.parent_path : '',
+                parent_path: typeof o.parent_path === 'string' ? this.isoUnprefixId(o.parent_path) : '',
                 parent_is_identifier: o.parent_is_identifier === true,
                 hierarchy_index_available: o.hierarchy_index_available === true,
                 children,
@@ -1020,16 +1306,17 @@ class XCiteDBClient {
         };
     }
     async queryLog(query, fromDate, toDate) {
+        const pq = this.isoPrefixQuery(query);
         const params = {
-            match_start: query.match_start,
-            match: query.match,
+            match_start: pq.match_start,
+            match: pq.match,
             from_date: fromDate,
             to_date: toDate,
         };
         return this.request('GET', `/api/v1/documents/log${buildQuery(params)}`);
     }
     async addMeta(identifier, value, path = '', opts) {
-        const body = { identifier, value, path };
+        const body = { identifier: this.isoPrefixId(identifier), value, path };
         if (opts?.mode === 'append')
             body.mode = 'append';
         const r = await this.request('POST', '/api/v1/meta', body);
@@ -1037,7 +1324,7 @@ class XCiteDBClient {
     }
     async addMetaByQuery(query, value, path = '', firstMatch = false, opts) {
         const body = {
-            query,
+            query: this.isoPrefixQuery(query),
             value,
             path,
             first_match: firstMatch,
@@ -1054,27 +1341,36 @@ class XCiteDBClient {
         return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append' });
     }
     async queryMeta(identifier, path = '') {
-        return this.request('GET', `/api/v1/meta${buildQuery({ identifier, path })}`);
+        return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`);
     }
     async queryMetaByQuery(query, path = '') {
-        return this.request('POST', '/api/v1/meta/query', { query, path });
+        return this.request('POST', '/api/v1/meta/query', { query: this.isoPrefixQuery(query), path });
     }
     async clearMeta(query) {
-        const r = await this.request('DELETE', '/api/v1/meta', { query });
+        const r = await this.request('DELETE', '/api/v1/meta', {
+            query: this.isoPrefixQuery(query),
+        });
         return r?.ok !== false;
     }
     async acquireLock(identifier, expires = 0) {
-        return this.request('POST', '/api/v1/locks', { identifier, expires });
+        const lock = await this.request('POST', '/api/v1/locks', {
+            identifier: this.isoPrefixId(identifier),
+            expires,
+        });
+        return { ...lock, identifier: this.isoUnprefixId(lock.identifier) };
     }
     async releaseLock(identifier, lockId) {
         const r = await this.request('DELETE', '/api/v1/locks', {
-            identifier,
+            identifier: this.isoPrefixId(identifier),
             lock_id: lockId,
         });
         return r?.ok !== false;
     }
     async findLocks(identifier) {
-        return this.request('GET', `/api/v1/locks${buildQuery({ identifier })}`);
+        const locks = await this.request('GET', `/api/v1/locks${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
+        return Array.isArray(locks)
+            ? locks.map((L) => ({ ...L, identifier: this.isoUnprefixId(L.identifier) }))
+            : locks;
     }
     /**
      * Run Unquery (`POST /api/v1/unquery`): declarative analytics over documents matching `query`.
@@ -1102,7 +1398,7 @@ class XCiteDBClient {
      * ```
      */
     async unquery(query, unquery) {
-        return this.request('POST', '/api/v1/unquery', { query, unquery });
+        return this.request('POST', '/api/v1/unquery', { query: this.isoPrefixQuery(query), unquery });
     }
     async search(q) {
         const body = { query: q.query };
@@ -1114,6 +1410,12 @@ class XCiteDBClient {
             body.offset = q.offset;
         if (q.limit !== undefined)
             body.limit = q.limit;
+        if (q.mode)
+            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;
         const data = await this.request('POST', '/api/v1/search', body);
         const hits = [];
         if (Array.isArray(data.hits)) {
@@ -1121,7 +1423,7 @@ class XCiteDBClient {
                 if (h && typeof h === 'object') {
                     const o = h;
                     const hit = {
-                        identifier: String(o.identifier ?? ''),
+                        identifier: this.isoUnprefixId(String(o.identifier ?? '')),
                         path: String(o.path ?? ''),
                         doc_type: o.doc_type === 'json' ? 'json' : 'xml',
                         branch: String(o.branch ?? ''),
@@ -1131,6 +1433,9 @@ class XCiteDBClient {
                     if (typeof o.xcitepath === 'string' && o.xcitepath.length > 0) {
                         hit.xcitepath = o.xcitepath;
                     }
+                    if (o.source === 'fts' || o.source === 'semantic' || o.source === 'both') {
+                        hit.source = o.source;
+                    }
                     hits.push(hit);
                 }
             }
@@ -1144,24 +1449,170 @@ class XCiteDBClient {
     async reindex() {
         return this.request('POST', '/api/v1/search/reindex', {});
     }
+    async reembedVector() {
+        return this.request('POST', '/api/v1/search/reembed-vector', {});
+    }
+    /** Project search / FTS / vector / LLM configuration (`GET /api/v1/project/settings/search`). */
+    async getProjectSearchSettings() {
+        return this.request('GET', '/api/v1/project/settings/search');
+    }
+    /** Update project search settings (`PUT /api/v1/project/settings/search`). Returns the same shape as GET. */
+    async updateProjectSearchSettings(patch) {
+        return this.request('PUT', '/api/v1/project/settings/search', patch);
+    }
+    /** 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);
+    }
+    /** Start background estimate (202); cancel prior session for this tenant. */
+    async postVectorIndexEstimateSession() {
+        return this.request('POST', '/api/v1/project/settings/search/vector-index-estimate', {});
+    }
+    async getVectorIndexEstimateSession(sessionId) {
+        const q = buildQuery({ session: sessionId });
+        return this.request('GET', `/api/v1/project/settings/search/vector-index-estimate${q}`, undefined);
+    }
+    async deleteVectorIndexEstimateSession(sessionId) {
+        const q = buildQuery({ session: sessionId });
+        return this.request('DELETE', `/api/v1/project/settings/search/vector-index-estimate${q}`, undefined);
+    }
+    /**
+     * RAG over indexed documents (`POST /api/v1/rag/query` with JSON body).
+     * Requires LLM completion; embedding required when retrieval uses semantic or hybrid.
+     */
+    async ragQuery(options) {
+        const body = {
+            question: options.question,
+            stream: false,
+        };
+        if (options.branch !== undefined)
+            body.branch = options.branch;
+        if (options.max_context_docs !== undefined)
+            body.max_context_docs = options.max_context_docs;
+        if (options.doc_types?.length)
+            body.doc_types = options.doc_types;
+        if (options.search_mode !== undefined)
+            body.search_mode = options.search_mode;
+        if (options.min_score !== undefined)
+            body.min_score = options.min_score;
+        if (options.semantic_weight !== undefined)
+            body.semantic_weight = options.semantic_weight;
+        const data = await this.request('POST', '/api/v1/rag/query', body);
+        if (!data || typeof data !== 'object') {
+            throw new types_1.XCiteDBError('Invalid RAG response', 500, data);
+        }
+        const answer = typeof data.answer === 'string' ? data.answer : '';
+        const sources = 'sources' in data ? data.sources : [];
+        return { answer, sources };
+    }
+    /**
+     * Streaming RAG (`POST /api/v1/rag/query` with `stream: true`). Parses SSE `data: {...}` lines.
+     * The final event has `done: true` and may include `sources`.
+     */
+    async ragQueryStream(options, onEvent) {
+        const path = '/api/v1/rag/query';
+        const payload = JSON.stringify({
+            question: options.question,
+            stream: true,
+            ...(options.branch !== undefined ? { branch: options.branch } : {}),
+            ...(options.max_context_docs !== undefined ? { max_context_docs: options.max_context_docs } : {}),
+            ...(options.doc_types?.length ? { doc_types: options.doc_types } : {}),
+            ...(options.search_mode !== undefined ? { search_mode: options.search_mode } : {}),
+            ...(options.min_score !== undefined ? { min_score: options.min_score } : {}),
+            ...(options.semantic_weight !== undefined ? { semantic_weight: options.semantic_weight } : {}),
+        });
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const url = joinUrl(this.baseUrl, path);
+            const headers = {
+                ...this.requestHeaders(),
+                'Content-Type': 'application/json',
+            };
+            const res = await fetch(url, { method: 'POST', headers, body: payload });
+            if (res.status === 401 &&
+                attempt === 0 &&
+                (await this.tryRefreshSessionAfter401())) {
+                continue;
+            }
+            if (!res.ok) {
+                const text = await res.text();
+                let data;
+                try {
+                    data = text ? JSON.parse(text) : null;
+                }
+                catch {
+                    data = text;
+                }
+                const msg = typeof data === 'object' && data !== null && 'message' in data
+                    ? String(data.message)
+                    : res.statusText;
+                this.notifySessionInvalidIfNeeded(path, res.status);
+                throw new types_1.XCiteDBError(msg || `HTTP ${res.status}`, res.status, data);
+            }
+            const streamBody = res.body;
+            if (!streamBody) {
+                const text = await res.text();
+                throw new types_1.XCiteDBError('RAG stream: empty response body', res.status, text);
+            }
+            const reader = streamBody.getReader();
+            const decoder = new TextDecoder();
+            let buf = '';
+            try {
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (value) {
+                        buf += decoder.decode(value, { stream: !done });
+                    }
+                    let sep;
+                    while ((sep = buf.indexOf('\n\n')) >= 0) {
+                        const block = buf.slice(0, sep);
+                        buf = buf.slice(sep + 2);
+                        const lines = block.split('\n');
+                        const dataLine = lines.find((l) => l.startsWith('data:'));
+                        if (!dataLine)
+                            continue;
+                        const jsonStr = dataLine.replace(/^data:\s*/, '').trim();
+                        if (!jsonStr)
+                            continue;
+                        let ev;
+                        try {
+                            ev = JSON.parse(jsonStr);
+                        }
+                        catch {
+                            continue;
+                        }
+                        onEvent(ev);
+                    }
+                    if (done)
+                        break;
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            return;
+        }
+        throw new types_1.XCiteDBError('RAG stream failed after retry', 401, null);
+    }
     async writeJsonDocument(identifier, data) {
-        await this.request('POST', '/api/v1/json-documents', { identifier, data });
+        await this.request('POST', '/api/v1/json-documents', { identifier: this.isoPrefixId(identifier), data });
     }
     async readJsonDocument(identifier) {
-        return this.request('GET', `/api/v1/json-documents${buildQuery({ identifier })}`);
+        return this.request('GET', `/api/v1/json-documents${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
     }
     async deleteJsonDocument(identifier) {
-        await this.request('DELETE', `/api/v1/json-documents${buildQuery({ identifier })}`);
+        await this.request('DELETE', `/api/v1/json-documents${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
     }
     async listJsonDocuments(match, limit, offset) {
-        const data = await this.request('GET', `/api/v1/json-documents/list${buildQuery({ match, limit, offset })}`);
+        const m = match !== undefined && match !== '' ? this.isoPrefixId(match) : match;
+        const data = await this.request('GET', `/api/v1/json-documents/list${buildQuery({ match: m, limit, offset })}`);
+        const un = (ids) => ids.map((id) => this.isoUnprefixId(id));
         if (Array.isArray(data)) {
-            const identifiers = data;
+            const identifiers = un(data);
             return { identifiers, total: identifiers.length, offset: 0, limit: identifiers.length };
         }
         if (data !== null && typeof data === 'object') {
             const o = data;
-            const ids = Array.isArray(o.identifiers) ? o.identifiers : [];
+            const ids = Array.isArray(o.identifiers) ? un(o.identifiers) : [];
             return {
                 identifiers: ids,
                 total: typeof o.total === 'number' ? o.total : ids.length,