@xcitedbs/client 0.2.9 → 0.2.11

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

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[];
@@ -175,6 +307,12 @@ export interface ApiKeyInfo {
 }
 export type Flags = 'None' | 'FirstMatch' | 'IncludeChildren' | 'NoChildren' | 'KeepIndexNodes' | 'PrevIfDeleted' | string;
 export interface DatabaseContext {
+    /**
+     * Workspace name (isolated editing environment). Empty / unset = main timeline.
+     * Sent as `X-Workspace` (preferred); see also {@link DatabaseContext.branch}.
+     */
+    workspace?: string;
+    /** @deprecated Prefer {@link DatabaseContext.workspace}. Sent as `X-Branch` when `workspace` is unset. */
     branch?: string;
     date?: string;
     prefix?: string;
@@ -206,6 +344,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 +390,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 +408,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 {
@@ -443,83 +602,115 @@ export interface StoredTriggerResponse {
     trigger_id: string;
     trigger: TriggerDefinition;
 }
-/** Version control / commit metadata (git-like layer). */
-export interface CommitRecord {
+/** Named snapshot on a workspace (checkpoint). */
+export interface CheckpointRecord {
     id: string;
+    /** Same as `id` when returned by newer APIs. */
+    checkpoint_id?: string;
     branch: string;
-    /** Internal LMDB date key for this commit snapshot. */
-    date_key: string;
-    date_human?: string;
-    /** Alias for human-readable date (same as date_human when present). */
+    /** Human-readable revision date/time. */
     date?: string;
+    date_human?: string;
+    /** @deprecated Internal key; omitted from newer API responses. */
+    date_key?: string;
     message: string;
     author: string;
     parent_id: string | null;
     merge_source?: {
         branch: string;
-        commit_id: string;
+        checkpoint_id?: string;
+        commit_id?: string;
     };
     cherry_picked_from?: string;
     affected_identifiers: string[];
     status: 'active' | 'rolled_back';
     created_at: number;
 }
-/** Branch row from GET /api/v1/branches (also exposed as BranchListItem). */
-export interface BranchInfo {
+/** @deprecated Use {@link CheckpointRecord}. */
+export type CommitRecord = CheckpointRecord;
+/** Workspace row from `GET /api/v1/workspaces` (legacy: `/api/v1/branches`). */
+export interface WorkspaceInfo {
     name: string;
     from_branch: string;
     from_date: string;
-    /** Internal LMDB fork date key when present. */
-    from_date_key?: string;
-    tip_commit?: CommitRecord;
-}
-export type BranchListItem = BranchInfo;
-export interface TagRecord {
+    tip_checkpoint?: CheckpointRecord;
+    /** @deprecated Alias of {@link WorkspaceInfo.tip_checkpoint}. */
+    tip_commit?: CheckpointRecord;
+}
+/** @deprecated Use {@link WorkspaceInfo}. */
+export type BranchInfo = WorkspaceInfo;
+/** @deprecated Use {@link WorkspaceInfo}. */
+export type BranchListItem = WorkspaceInfo;
+export interface BookmarkRecord {
     name: string;
-    commit_id: string;
+    checkpoint_id: string;
+    /** @deprecated Same as `checkpoint_id`. */
+    commit_id?: string;
     branch: string;
-    date_key: string;
+    date?: string;
+    /** @deprecated */
+    date_key?: string;
     message?: string;
     author?: string;
     created_at: number;
 }
-export interface DiffEntry {
+/** @deprecated Use {@link BookmarkRecord}. */
+export type TagRecord = BookmarkRecord;
+export interface CompareEntry {
     identifier: string;
     action: 'added' | 'modified' | 'deleted';
     from_content?: string;
     to_content?: string;
 }
-export interface DiffRef {
+/** @deprecated Use {@link CompareEntry}. */
+export type DiffEntry = CompareEntry;
+export interface CompareRef {
     branch?: string;
-    /** Internal date key (preferred for exact revision). */
+    /** Human-readable date (preferred). */
+    date?: string;
+    checkpoint_id?: string;
+    /** @deprecated Undocumented fallback. */
     date_key?: string;
+    /** @deprecated Use {@link CompareRef.checkpoint_id}. */
     commit_id?: string;
 }
-export interface DiffResult {
-    changes: DiffEntry[];
+/** @deprecated Use {@link CompareRef}. */
+export type DiffRef = CompareRef;
+export interface CompareResult {
+    changes: CompareEntry[];
     from: {
         branch?: string;
+        date?: string;
         date_key?: string;
     };
     to: {
         branch?: string;
+        date?: string;
         date_key?: string;
     };
     total_changes: number;
 }
-export interface MergeConflict {
+/** @deprecated Use {@link CompareResult}. */
+export type DiffResult = CompareResult;
+export interface PublishConflict {
     identifier: string;
     source_action: string;
     target_action: string;
 }
-export interface MergeResult {
+/** @deprecated Use {@link PublishConflict}. */
+export type MergeConflict = PublishConflict;
+export interface PublishResult {
     status: 'completed' | 'conflicts';
-    commit?: CommitRecord;
+    checkpoint?: CheckpointRecord;
+    /** @deprecated Alias of {@link PublishResult.checkpoint}. */
+    commit?: CheckpointRecord;
     merged_identifiers?: string[];
-    conflicts?: MergeConflict[];
+    conflicts?: PublishConflict[];
     auto_mergeable?: string[];
     message?: string;
 }
+/** @deprecated Use {@link PublishResult}. */
+export type MergeResult = PublishResult;
 export declare class XCiteDBError extends Error {
     readonly status: number;
     readonly body?: unknown | undefined;

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(() => { });
+        }
+    });
+});