@xcitedbs/client 0.2.9 → 0.2.10

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, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, 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 { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -16,6 +16,8 @@ export declare class XCiteDBClient {
     private onSessionInvalid?;
     private testSessionToken?;
     private testRequireAuth?;
+    private userIsolation?;
+    private cachedAppUserId?;
     constructor(options: XCiteDBClientOptions);
     /**
      * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
@@ -33,6 +35,19 @@ export declare class XCiteDBClient {
      * Use for debugging ABAC (compare `tenant_id` and `groups` to `project:<…>:role` in policies).
      */
     getTokenClaims(): XCiteDBJwtClaims | null;
+    private cacheAppUserIdFromPair;
+    private clearAppUserIdCache;
+    private getAppUserId;
+    private normalizeIsolationNamespaceTemplate;
+    private canonicalId;
+    /** Resolved namespace root, e.g. `/users/abc`, or `null` if isolation is off or no app user id. */
+    private userIsolationNamespace;
+    private allSharedPassthroughPrefixes;
+    private pathMatchesSharedPassthrough;
+    private isoPrefixId;
+    private isoUnprefixId;
+    private isoPrefixQuery;
+    private isoApplyXmlDbIdentifier;
     /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
     destroyTestSession(): Promise<{
         message: string;
@@ -57,6 +72,7 @@ export declare class XCiteDBClient {
     private mergeAppTenant;
     private authHeaders;
     private testHeaders;
+    private requestHeaders;
     private request;
     /** Developer Bearer refresh first, then app-user refresh (no API key refresh). */
     private tryRefreshSessionAfter401;
@@ -266,6 +282,17 @@ export declare class XCiteDBClient {
      * ```
      */
     updateSecurityConfig(config: Partial<SecurityConfig>): Promise<void>;
+    /** Per-tenant user data spaces (`GET /api/v1/security/user-isolation`). Requires security admin. */
+    getUserIsolationConfig(): Promise<UserIsolationConfig>;
+    /** Enable or reconfigure user isolation (`PUT /api/v1/security/user-isolation`). */
+    setUserIsolationConfig(config: Partial<UserIsolationConfig>): Promise<UserIsolationConfig>;
+    /** Disable user isolation and remove generated policies (`DELETE /api/v1/security/user-isolation`). */
+    disableUserIsolation(): Promise<void>;
+    /**
+     * 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.
+     */
+    enableUserIsolation(): Promise<UserIsolationConfig>;
     createBranch(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
     deleteBranch(name: string): Promise<void>;
     deleteRevision(branch: string, date: string): Promise<void>;
@@ -386,6 +413,32 @@ export declare class XCiteDBClient {
         status: string;
         message: string;
     }>;
+    reembedVector(): Promise<{
+        status: string;
+        message: string;
+    }>;
+    /** Project search / FTS / vector / LLM configuration (`GET /api/v1/project/settings/search`). */
+    getProjectSearchSettings(): Promise<ProjectSearchSettings>;
+    /** Update project search settings (`PUT /api/v1/project/settings/search`). Returns the same shape as GET. */
+    updateProjectSearchSettings(patch: ProjectSearchSettingsUpdate): Promise<ProjectSearchSettings>;
+    /** 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. */
+    postVectorIndexEstimateSession(): Promise<VectorIndexEstimate>;
+    getVectorIndexEstimateSession(sessionId: string): Promise<VectorIndexEstimate>;
+    deleteVectorIndexEstimateSession(sessionId: string): Promise<{
+        status?: string;
+    }>;
+    /**
+     * RAG over indexed documents (`POST /api/v1/rag/query` with JSON body).
+     * Requires LLM completion; embedding required when retrieval uses semantic or hybrid.
+     */
+    ragQuery(options: Omit<RagQueryOptions, 'stream'>): Promise<RagQueryResult>;
+    /**
+     * Streaming RAG (`POST /api/v1/rag/query` with `stream: true`). Parses SSE `data: {...}` lines.
+     * The final event has `done: true` and may include `sources`.
+     */
+    ragQueryStream(options: Omit<RagQueryOptions, 'stream'>, onEvent: (ev: RagStreamEvent) => void): Promise<void>;
     writeJsonDocument(identifier: string, data: unknown): Promise<void>;
     readJsonDocument<T = unknown>(identifier: string): Promise<T>;
     deleteJsonDocument(identifier: string): Promise<void>;

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) {
@@ -206,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 = {};
@@ -261,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 };
@@ -336,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;
     }
@@ -474,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() {
@@ -489,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');
@@ -505,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). */
@@ -721,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)
@@ -747,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)
@@ -864,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',
         });
     }
@@ -874,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,
         });
@@ -887,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,
@@ -985,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') {
@@ -998,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,
                         });
@@ -1006,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,
@@ -1020,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);
@@ -1037,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,
@@ -1054,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`.
@@ -1102,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 };
@@ -1114,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)) {
@@ -1121,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 ?? ''),
@@ -1131,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);
                 }
             }
@@ -1144,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,

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, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, 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 { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -41,6 +41,12 @@ export interface TextSearchQuery {
     branch?: string;
     offset?: number;
     limit?: number;
+    /** Default `fts`. `semantic` / `hybrid` require vector search (and hybrid requires FTS). */
+    mode?: 'fts' | 'semantic' | 'hybrid';
+    /** Minimum cosine similarity for semantic / hybrid vector leg (default 0.3). */
+    min_score?: number;
+    /** Hybrid only: weight of semantic vs FTS in weighted RRF (0–1, default 0.5). */
+    semantic_weight?: number;
 }
 export interface TextSearchHit {
     identifier: string;
@@ -51,12 +57,138 @@ export interface TextSearchHit {
     branch: string;
     snippet: string;
     score: number;
+    /** Present for semantic / hybrid search. */
+    source?: 'fts' | 'semantic' | 'both';
 }
 export interface TextSearchResult {
     hits: TextSearchHit[];
     total: number;
     query: string;
 }
+/** Progress object when the server is indexing (FTS or vector). */
+export interface SearchIndexingProgress {
+    done: number;
+    total: number;
+}
+/** Last finished vector re-embed job (`vector_index_job` in project settings). */
+export interface VectorIndexingLastJob {
+    ok?: boolean;
+    finished_at_ms?: number;
+    message?: string;
+    detail?: string;
+    phase?: string;
+    rows_indexed?: number;
+}
+/**
+ * Vector index workload + indicative cost.
+ * Blocking scan: `GET /api/v1/project/settings/search/vector-index-estimate` (no `session`).
+ * Incremental UI: `POST` same path, then `GET` / `DELETE` with `?session=`.
+ */
+export interface VectorIndexEstimate {
+    document_count?: number;
+    chunk_count?: number;
+    approx_input_tokens?: number;
+    approx_input_tokens_xml?: number;
+    approx_input_tokens_json?: number;
+    /** Serialized XML on disk (only docs that produced ≥1 embed chunk). */
+    xml_source_serialized_bytes_total?: number;
+    /** UTF-8 bytes of XML embed text (text nodes only; same as embedding input). */
+    xml_embed_text_bytes_total?: number;
+    /** Raw JSON document bytes (only docs that produced ≥1 embed chunk). */
+    json_source_bytes_total?: number;
+    /** UTF-8 bytes of JSON scalar chunks sent to the embedder. */
+    json_embed_text_bytes_total?: number;
+    token_estimate_note?: string;
+    embedding_provider?: string;
+    embedding_model?: string;
+    embedding_configured?: boolean;
+    pricing_info_url?: string;
+    /** Null when unknown (e.g. openai_compatible). */
+    usd_per_million_tokens_indicative?: number | null;
+    estimated_cost_usd_indicative?: number | null;
+    cost_disclaimer?: string;
+    /** Async session responses only (`POST` / `GET ?session=`). */
+    session_id?: string;
+    branches_done?: number;
+    branches_total?: number;
+    estimate_complete?: boolean;
+    estimate_cancelled?: boolean;
+    estimate_error?: string;
+}
+/** `GET /api/v1/project/settings/search` (and returned after `PUT`). */
+export interface ProjectSearchSettings {
+    search_enabled?: boolean;
+    search_language?: string;
+    indexing_status?: 'indexing' | 'idle';
+    indexing_progress?: SearchIndexingProgress;
+    vector_search_enabled?: boolean;
+    embedding_provider?: string;
+    embedding_model?: string;
+    embedding_base_url?: string;
+    llm_provider?: string;
+    llm_model?: string;
+    llm_base_url?: string;
+    embedding_configured?: boolean;
+    llm_configured?: boolean;
+    vector_indexing_status?: 'indexing' | 'scheduled' | 'idle';
+    vector_indexing_progress?: SearchIndexingProgress | null;
+    vector_indexing_last_job?: VectorIndexingLastJob | null;
+    [key: string]: unknown;
+}
+/**
+ * `PUT /api/v1/project/settings/search` body (all keys optional).
+ * `embedding_api_key` / `llm_api_key` are write-only: send a new secret or empty string to clear.
+ * While `vector_search_enabled` is true, changing embedding provider/model/base URL triggers a full vector re-embed on the server.
+ */
+export interface ProjectSearchSettingsUpdate {
+    search_enabled?: boolean;
+    search_language?: string;
+    vector_search_enabled?: boolean;
+    embedding_provider?: string;
+    embedding_model?: string;
+    embedding_base_url?: string | null;
+    embedding_api_key?: string;
+    llm_provider?: string;
+    llm_model?: string;
+    llm_base_url?: string | null;
+    llm_api_key?: string;
+}
+/** `POST /api/v1/rag/query` (non-streaming: set `stream: false` or omit). */
+export interface RagQueryOptions {
+    question: string;
+    branch?: string;
+    max_context_docs?: number;
+    doc_types?: ('xml' | 'json')[];
+    /** Default `false` for JSON response with `answer` and `sources`. */
+    stream?: boolean;
+    /** Default `auto`: hybrid if FTS+vector enabled, else best available mode. */
+    search_mode?: 'auto' | 'hybrid' | 'semantic' | 'fts';
+    /** Minimum cosine similarity for semantic / hybrid vector leg (default 0.35). */
+    min_score?: number;
+    /** Hybrid retrieval only: semantic vs FTS weight in weighted RRF (0–1, default 0.5). */
+    semantic_weight?: number;
+}
+export interface RagQueryResult {
+    answer: string;
+    sources: unknown;
+}
+/** One SSE JSON payload from streaming RAG (`stream: true`). */
+export type RagStreamEvent = {
+    text: string;
+    done: false;
+    sources?: undefined;
+    error?: undefined;
+} | {
+    text?: string;
+    done: true;
+    sources?: unknown;
+    error?: undefined;
+} | {
+    error: string;
+    done: true;
+    text?: undefined;
+    sources?: undefined;
+};
 /** Response from `GET /api/v1/documents/identifiers` */
 export interface ListIdentifiersResult {
     identifiers: string[];
@@ -206,6 +338,24 @@ export interface RealtimeEvent {
     timestamp?: number;
     tenant_id?: string;
 }
+/** When enabled, prefixes document/meta paths with the app user's namespace (e.g. `/users/{userId}/…`) for convenience; ABAC still enforces access on the server. */
+export interface UserIsolationOptions {
+    enabled: boolean;
+    /** Template with `{userId}` or server-style `${user.id}` replaced from JWT or login response; default `/users/{userId}`. */
+    namespace?: string;
+    /** Paths left unchanged by prefixing (optional; {@link XCiteDBClient.enableUserIsolation} fills from server). */
+    shared_read_paths?: string[];
+    shared_write_paths?: string[];
+}
+/** Effective user isolation settings from `GET /api/v1/security/user-isolation`. */
+export interface UserIsolationConfig {
+    enabled: boolean;
+    namespace_pattern: string;
+    shared_read_paths: string[];
+    shared_write_paths: string[];
+    shared_write_groups: string[];
+    generated_policies?: string[];
+}
 export interface XCiteDBClientOptions {
     baseUrl: string;
     apiKey?: string;
@@ -234,6 +384,8 @@ export interface XCiteDBClientOptions {
     testSessionToken?: string;
     /** When true with `testSessionToken`, sends `X-Test-Auth: required` so real credentials are validated. */
     testRequireAuth?: boolean;
+    /** Auto-prefix identifiers for app-user sessions (see {@link UserIsolationOptions}). */
+    userIsolation?: UserIsolationOptions;
 }
 /** Options for {@link XCiteDBClient.createTestSession} (provisions via API key or Bearer). */
 export interface CreateTestSessionOptions {
@@ -250,6 +402,7 @@ export interface CreateTestSessionOptions {
     onSessionTokensUpdated?: (pair: TokenPair) => void;
     onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
     onSessionInvalid?: () => void;
+    userIsolation?: UserIsolationOptions;
 }
 /** Application user (tenant-scoped), distinct from developer users. */
 export interface AppUser {

package/dist/user-isolation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/user-isolation.test.js

@@ -0,0 +1,175 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Wet tests: set XCITEDB_BASE_URL, XCITEDB_ADMIN_TOKEN, XCITEDB_TENANT_ID (platform + project).
+ * Run: npm test (builds then runs node:test).
+ */
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_crypto_1 = require("node:crypto");
+const client_js_1 = require("./client.js");
+function wetEnv() {
+    const baseUrl = process.env.XCITEDB_BASE_URL?.trim();
+    const accessToken = process.env.XCITEDB_ADMIN_TOKEN?.trim();
+    const tenantId = process.env.XCITEDB_TENANT_ID?.trim();
+    if (!baseUrl || !accessToken || !tenantId)
+        return null;
+    return { baseUrl, accessToken, tenantId };
+}
+function adminClient(e) {
+    return new client_js_1.XCiteDBClient({
+        baseUrl: e.baseUrl,
+        accessToken: e.accessToken,
+        platformConsole: true,
+        projectId: e.tenantId,
+        context: { branch: 'main', project_id: e.tenantId },
+    });
+}
+async function openTestSession(e) {
+    const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions`;
+    const r = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${e.accessToken}`,
+            'X-Project-Id': e.tenantId,
+            'X-Branch': 'main',
+        },
+        body: '{}',
+    });
+    const data = (await r.json());
+    if (!r.ok || !data.session_token) {
+        throw new Error(`test session failed ${r.status}: ${JSON.stringify(data)}`);
+    }
+    const client = new client_js_1.XCiteDBClient({
+        baseUrl: e.baseUrl,
+        accessToken: e.accessToken,
+        platformConsole: true,
+        projectId: e.tenantId,
+        context: { branch: 'main', project_id: e.tenantId },
+        testSessionToken: data.session_token,
+        testRequireAuth: true,
+    });
+    return { client, token: data.session_token };
+}
+const w = wetEnv();
+const wd = w ? node_test_1.describe : node_test_1.describe.skip;
+wd('user isolation (wet)', () => {
+    (0, node_test_1.it)('setUserIsolationConfig enables isolation (round-trip)', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const c = adminClient(e);
+        try {
+            const out = await c.setUserIsolationConfig({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+            });
+            strict_1.default.equal(out.enabled, true);
+            const again = await c.getUserIsolationConfig();
+            strict_1.default.equal(again.enabled, true);
+        }
+        finally {
+            await c.disableUserIsolation().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('getUserIsolationConfig returns disabled in fresh test session', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const { client: s, token } = await openTestSession(e);
+        try {
+            const cfg = await s.getUserIsolationConfig();
+            strict_1.default.equal(cfg.enabled, false);
+        }
+        finally {
+            await fetch(`${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions/current`, {
+                method: 'DELETE',
+                headers: { 'X-Test-Session': token },
+            });
+        }
+    });
+    (0, node_test_1.it)('disableUserIsolation after enable', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const c = adminClient(e);
+        try {
+            await c.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            await c.disableUserIsolation();
+            const cfg = await c.getUserIsolationConfig();
+            strict_1.default.equal(cfg.enabled, false);
+        }
+        finally {
+            await c.disableUserIsolation().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('document write uses transparent prefix for app user', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const email = `js_iso_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        const slug = `js-iso-doc-${suffix}`;
+        try {
+            await admin.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            const u = await admin.createAppUser(email, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const app = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await app.loginAppUser(email, password);
+            await app.writeJsonDocument(`/${slug}`, { _xcite_json_doc: true, v: 1 });
+            const doc = await app.readJsonDocument(`/${slug}`);
+            strict_1.default.equal(doc.v, 1);
+            await admin.deleteJsonDocument(`/users/${u.user_id}/${slug}`);
+            await admin.deleteAppUser(u.user_id);
+        }
+        finally {
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('shared_read_paths passthrough: app reads shared path without double-prefix', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const email = `js_shr_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        const sharedPath = `/shared-read-${suffix}`;
+        const docPath = `${sharedPath}/doc`;
+        try {
+            await admin.setUserIsolationConfig({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+                shared_read_paths: [sharedPath],
+            });
+            await admin.writeJsonDocument(docPath, { _xcite_json_doc: true, tag: 'shared' });
+            const created = await admin.createAppUser(email, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const app = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true, shared_read_paths: [sharedPath] },
+            });
+            await app.loginAppUser(email, password);
+            const doc = await app.readJsonDocument(docPath);
+            strict_1.default.equal(doc.tag, 'shared');
+            await admin.deleteJsonDocument(docPath);
+            await admin.deleteAppUser(created.user_id);
+        }
+        finally {
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
+});

package/llms-full.txt

@@ -518,7 +518,7 @@ Can also use `"query"` instead of `"identifier"` to target multiple documents by
 
 # Search
 
-Full-text search (backed by Meilisearch or Elasticsearch).
+Full-text search uses embedded XciteFTS (enable per project in server settings).
 
 **Base path:** `/api/v1/search`
 

package/llms.txt

@@ -161,7 +161,7 @@ const lock = await client.acquireLock('/manual/v1/intro');
 // ... edit ...
 await client.releaseLock('/manual/v1/intro', lock.lock_id);
 
-// Full-text search (requires Meilisearch or Elasticsearch backend)
+// Full-text search (embedded XciteFTS; enable per project in server settings)
 const results = await client.search({ query: 'installation guide', limit: 20 });
 
 // Subscribe to real-time changes via WebSocket

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "node --test dist/**/*.test.js 2>/dev/null || echo 'No tests'"
+    "test": "npm run build && node --test dist/**/*.test.js",
+    "test:only": "node --test dist/**/*.test.js"
   },
   "keywords": [
     "xcitedb",
@@ -34,6 +35,7 @@
   },
   "dependencies": {},
   "devDependencies": {
+    "@types/node": "^20.14.0",
     "typescript": "^5.0.0"
   },
   "files": [