@xcitedbs/client 0.2.8 → 0.2.10

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,230 @@ class XCiteDBClient {
             onSessionInvalid: opts.onSessionInvalid,
             testSessionToken: data.session_token,
             testRequireAuth: opts.testRequireAuth,
+            userIsolation: opts.userIsolation,
+        });
+    }
+    /**
+     * Canonical `project:<tenant_id>:<role>` group string. The middle segment must match the app JWT `tenant_id`
+     * (internal project id), not the human-readable project name.
+     */
+    static buildProjectGroup(projectId, role) {
+        return `project:${projectId}:${role}`;
+    }
+    static decodeJwtPayloadJson(token) {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return null;
+        try {
+            let b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+            const pad = (4 - (b64.length % 4)) % 4;
+            b64 += '='.repeat(pad);
+            const g = globalThis;
+            let json = null;
+            if (g.Buffer) {
+                json = g.Buffer.from(b64, 'base64').toString('utf8');
+            }
+            else if (typeof atob === 'function') {
+                json = atob(b64);
+            }
+            if (json === null)
+                return null;
+            return JSON.parse(json);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Decode `appUserAccessToken`, or `accessToken` if no app token (platform JWT), without verifying the signature.
+     * Use for debugging ABAC (compare `tenant_id` and `groups` to `project:<…>:role` in policies).
+     */
+    getTokenClaims() {
+        const raw = this.appUserAccessToken ?? this.accessToken;
+        if (!raw)
+            return null;
+        const p = XCiteDBClient.decodeJwtPayloadJson(raw);
+        if (!p)
+            return null;
+        let groups = [];
+        const g = p['groups'];
+        if (Array.isArray(g)) {
+            groups = g.filter((x) => typeof x === 'string');
+        }
+        else if (g && typeof g === 'object' && !Array.isArray(g)) {
+            groups = Object.keys(g);
+        }
+        else if (typeof g === 'string') {
+            groups = g.split(',').map((s) => s.trim()).filter(Boolean);
+        }
+        const sub = p['sub'];
+        const tenant_id = p['tenant_id'];
+        if (typeof sub !== 'string' || typeof tenant_id !== 'string')
+            return null;
+        const email = p['email'];
+        const type = p['type'];
+        const exp = p['exp'];
+        const iat = p['iat'];
+        const iss = p['iss'];
+        const jti = p['jti'];
+        return {
+            sub,
+            tenant_id,
+            groups,
+            email: typeof email === 'string' ? email : undefined,
+            type: typeof type === 'string' ? type : undefined,
+            exp: typeof exp === 'number' ? exp : undefined,
+            iat: typeof iat === 'number' ? iat : undefined,
+            iss: typeof iss === 'string' ? iss : undefined,
+            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`). */
@@ -131,10 +357,12 @@ 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 = {};
@@ -186,14 +414,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 };
@@ -261,6 +494,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;
     }
@@ -399,12 +633,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() {
@@ -414,6 +650,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');
@@ -430,6 +667,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). */
@@ -646,7 +884,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)
@@ -672,6 +910,37 @@ class XCiteDBClient {
     async updateSecurityConfig(config) {
         await this.request('PUT', '/api/v1/security/config', config);
     }
+    /** 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 createBranch(name, fromBranch, fromDate) {
         const body = { name };
         if (fromBranch)
@@ -789,7 +1058,8 @@ class XCiteDBClient {
     }
     /** 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',
         });
     }
@@ -799,7 +1069,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,
         });
@@ -812,92 +1082,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,
@@ -910,7 +1185,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') {
@@ -923,7 +1198,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,
                         });
@@ -931,7 +1206,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,
@@ -945,16 +1220,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);
@@ -962,7 +1238,7 @@ class XCiteDBClient {
     }
     async addMetaByQuery(query, value, path = '', firstMatch = false, opts) {
         const body = {
-            query,
+            query: this.isoPrefixQuery(query),
             value,
             path,
             first_match: firstMatch,
@@ -979,27 +1255,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`.
@@ -1027,7 +1312,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 };
@@ -1039,6 +1324,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)) {
@@ -1046,7 +1337,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 ?? ''),
@@ -1056,6 +1347,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);
                 }
             }
@@ -1069,24 +1363,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,