@xcitedbs/client 0.2.18 → 0.2.19

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, Flags, JsonDocumentBatchItem, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, Flags, JsonDocumentBatchItem, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -19,6 +19,8 @@ export declare class XCiteDBClient {
     private userIsolation?;
     private cachedAppUserId?;
     private readonly requestTimeoutMs?;
+    /** Set by {@link XCiteDBClient.createTestSession} when the server returns a `bootstrap` summary. */
+    lastTestSessionBootstrap?: TestSessionBootstrapSummary;
     constructor(options: XCiteDBClientOptions);
     /**
      * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
@@ -269,6 +271,10 @@ export declare class XCiteDBClient {
      * ```
      */
     checkAccess(subject: PolicySubjectInput, identifier: string, action: string, branch?: string): Promise<AccessCheckResult>;
+    /**
+     * Dry-run access (`POST /api/v1/security/check`). Same as {@link checkAccess}; use for debugging 403s.
+     */
+    diagnoseAccess(subject: PolicySubjectInput, identifier: string, action: string, branch?: string): Promise<AccessCheckResult>;
     getSecurityConfig(): Promise<SecurityConfig>;
     /**
      * Update tenant security defaults (`PUT /api/v1/security/config`). When ABAC is enabled, pair

package/dist/client.js

@@ -8,6 +8,44 @@ function joinUrl(base, path) {
     const p = path.startsWith('/') ? path : `/${path}`;
     return `${b}${p}`;
 }
+function newClientRequestId() {
+    const c = globalThis.crypto?.randomUUID?.();
+    if (c)
+        return c;
+    const a = new Uint8Array(16);
+    if (globalThis.crypto?.getRandomValues)
+        globalThis.crypto.getRandomValues(a);
+    else
+        for (let i = 0; i < 16; i++)
+            a[i] = Math.floor(Math.random() * 256);
+    return Array.from(a, (x) => x.toString(16).padStart(2, '0')).join('');
+}
+function extrasFromErrorBody(data, serverRequestId, clientRequestId) {
+    const bodyObj = typeof data === 'object' && data !== null ? data : undefined;
+    return {
+        reason: bodyObj && typeof bodyObj.reason === 'string' ? bodyObj.reason : undefined,
+        policyId: bodyObj && typeof bodyObj.policy_id === 'string' ? bodyObj.policy_id : undefined,
+        hint: bodyObj && typeof bodyObj.hint === 'string' ? bodyObj.hint : undefined,
+        expectedRole: bodyObj && typeof bodyObj.expected_role === 'string' ? bodyObj.expected_role : undefined,
+        actualRole: bodyObj && typeof bodyObj.actual_role === 'string' ? bodyObj.actual_role : undefined,
+        serverRequestId,
+        clientRequestId,
+    };
+}
+/** @internal */
+function throwForFailedHttp(status, path, data, msg, serverRequestId, clientRequestId) {
+    const extras = extrasFromErrorBody(data, serverRequestId, clientRequestId);
+    const Ctor = status === 403
+        ? types_1.XCiteDBForbiddenError
+        : status === 404
+            ? types_1.XCiteDBNotFoundError
+            : status === 401
+                ? types_1.XCiteDBAuthError
+                : status === 409 || status === 423
+                    ? types_1.XCiteDBLockConflictError
+                    : types_1.XCiteDBError;
+    throw new Ctor(msg || `HTTP ${status}`, status, data, extras);
+}
 function buildQuery(params) {
     const sp = new URLSearchParams();
     for (const [k, v] of Object.entries(params)) {
@@ -83,8 +121,13 @@ class XCiteDBClient {
             userIsolation: opts.userIsolation,
             requestTimeoutMs: opts.requestTimeoutMs,
         });
-        const data = await temp.request('POST', '/api/v1/test/sessions', opts.overlay === true ? { overlay: true } : undefined, undefined, { no401Retry: true });
-        return new XCiteDBClient({
+        const sessionBody = {};
+        if (opts.overlay === true)
+            sessionBody.overlay = true;
+        if (opts.bootstrap !== undefined)
+            sessionBody.bootstrap = opts.bootstrap;
+        const data = await temp.request('POST', '/api/v1/test/sessions', Object.keys(sessionBody).length ? sessionBody : undefined, undefined, { no401Retry: true });
+        const child = new XCiteDBClient({
             baseUrl: opts.baseUrl,
             apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
             accessToken: opts.testRequireAuth ? opts.accessToken : undefined,
@@ -101,6 +144,10 @@ class XCiteDBClient {
             userIsolation: opts.userIsolation,
             requestTimeoutMs: opts.requestTimeoutMs,
         });
+        if (data.bootstrap && typeof data.bootstrap === 'object') {
+            child.lastTestSessionBootstrap = data.bootstrap;
+        }
+        return child;
     }
     /**
      * Canonical `project:<tenant_id>:<role>` group string. The middle segment must match the app JWT `tenant_id`
@@ -464,6 +511,8 @@ class XCiteDBClient {
                 ...this.requestHeaders(),
                 ...extraHeaders,
             };
+            const outgoingRequestId = newClientRequestId();
+            headers['X-Request-Id'] = outgoingRequestId;
             let init = { method, headers };
             if (body !== undefined) {
                 if (typeof body === 'string') {
@@ -477,7 +526,14 @@ class XCiteDBClient {
             const sig = requestTimeoutSignal(this.requestTimeoutMs);
             if (sig)
                 init.signal = sig;
-            const res = await fetch(url, init);
+            let res;
+            try {
+                res = await fetch(url, init);
+            }
+            catch (e) {
+                const m = e instanceof Error ? e.message : 'Network error';
+                throw new types_1.XCiteDBError(m, 0, null, { clientRequestId: outgoingRequestId });
+            }
             const text = await res.text();
             let data;
             try {
@@ -499,7 +555,7 @@ class XCiteDBClient {
                 ? String(data.message)
                 : res.statusText;
             this.notifySessionInvalidIfNeeded(path, res.status);
-            throw new types_1.XCiteDBError(msg || `HTTP ${res.status}`, res.status, data);
+            throwForFailedHttp(res.status, path, data, msg || `HTTP ${res.status}`, res.headers.get('X-Request-Id') ?? undefined, res.headers.get('X-Client-Request-Id') ?? undefined);
         }
         this.notifySessionInvalidIfNeeded(path, 401);
         throw new types_1.XCiteDBError('Request failed after retry', 401, null);
@@ -926,6 +982,12 @@ class XCiteDBClient {
             body.branch = branch;
         return this.request('POST', '/api/v1/security/check', body);
     }
+    /**
+     * Dry-run access (`POST /api/v1/security/check`). Same as {@link checkAccess}; use for debugging 403s.
+     */
+    async diagnoseAccess(subject, identifier, action, branch) {
+        return this.checkAccess(subject, identifier, action, branch);
+    }
     async getSecurityConfig() {
         return this.request('GET', '/api/v1/security/config');
     }
@@ -1680,9 +1742,11 @@ class XCiteDBClient {
         });
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
+            const outgoingRequestId = newClientRequestId();
             const headers = {
                 ...this.requestHeaders(),
                 'Content-Type': 'application/json',
+                'X-Request-Id': outgoingRequestId,
             };
             const res = await fetch(url, { method: 'POST', headers, body: payload });
             if (res.status === 401 &&
@@ -1703,12 +1767,15 @@ class XCiteDBClient {
                     ? String(data.message)
                     : res.statusText;
                 this.notifySessionInvalidIfNeeded(path, res.status);
-                throw new types_1.XCiteDBError(msg || `HTTP ${res.status}`, res.status, data);
+                throwForFailedHttp(res.status, path, data, msg || `HTTP ${res.status}`, res.headers.get('X-Request-Id') ?? undefined, res.headers.get('X-Client-Request-Id') ?? undefined);
             }
             const streamBody = res.body;
             if (!streamBody) {
                 const text = await res.text();
-                throw new types_1.XCiteDBError('RAG stream: empty response body', res.status, text);
+                throw new types_1.XCiteDBError('RAG stream: empty response body', res.status, text, {
+                    serverRequestId: res.headers.get('X-Request-Id') ?? undefined,
+                    clientRequestId: res.headers.get('X-Client-Request-Id') ?? undefined,
+                });
             }
             const reader = streamBody.getReader();
             const decoder = new TextDecoder();

package/dist/client.test.d.ts

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

package/dist/client.test.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Unit tests for HTTP error mapping (mocked fetch).
+ */
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const client_js_1 = require("./client.js");
+const types_js_1 = require("./types.js");
+(0, node_test_1.describe)('XCiteDBClient error mapping', () => {
+    (0, node_test_1.it)('403 becomes XCiteDBForbiddenError with policy_id and request ids', async () => {
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => {
+            return new Response(JSON.stringify({
+                message: 'Forbidden',
+                reason: 'tenant_security_unconfigured',
+                policy_id: 'abac_denied',
+                hint: 'add policies',
+            }), {
+                status: 403,
+                headers: {
+                    'X-Request-Id': 'srv-req-1',
+                    'X-Client-Request-Id': 'cli-req-1',
+                },
+            });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'test-key' });
+            await c.health();
+            strict_1.default.fail('expected error');
+        }
+        catch (e) {
+            strict_1.default.ok(e instanceof types_js_1.XCiteDBForbiddenError);
+            const err = e;
+            strict_1.default.equal(err.policyId, 'abac_denied');
+            strict_1.default.equal(err.reason, 'tenant_security_unconfigured');
+            strict_1.default.equal(err.hint, 'add policies');
+            strict_1.default.equal(err.serverRequestId, 'srv-req-1');
+            strict_1.default.equal(err.clientRequestId, 'cli-req-1');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});

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

package/dist/index.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XCiteDBError = exports.WebSocketSubscription = exports.XCiteDBClient = void 0;
+exports.XCiteDBLockConflictError = exports.XCiteDBAuthError = exports.XCiteDBNotFoundError = exports.XCiteDBForbiddenError = exports.XCiteDBError = exports.WebSocketSubscription = exports.XCiteDBClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "XCiteDBClient", { enumerable: true, get: function () { return client_1.XCiteDBClient; } });
 var websocket_1 = require("./websocket");
 Object.defineProperty(exports, "WebSocketSubscription", { enumerable: true, get: function () { return websocket_1.WebSocketSubscription; } });
 var types_1 = require("./types");
 Object.defineProperty(exports, "XCiteDBError", { enumerable: true, get: function () { return types_1.XCiteDBError; } });
+Object.defineProperty(exports, "XCiteDBForbiddenError", { enumerable: true, get: function () { return types_1.XCiteDBForbiddenError; } });
+Object.defineProperty(exports, "XCiteDBNotFoundError", { enumerable: true, get: function () { return types_1.XCiteDBNotFoundError; } });
+Object.defineProperty(exports, "XCiteDBAuthError", { enumerable: true, get: function () { return types_1.XCiteDBAuthError; } });
+Object.defineProperty(exports, "XCiteDBLockConflictError", { enumerable: true, get: function () { return types_1.XCiteDBLockConflictError; } });

package/dist/types.d.ts

@@ -504,6 +504,26 @@ export interface XCiteDBClientOptions {
      */
     requestTimeoutMs?: number;
 }
+/** `bootstrap` payload for `POST /api/v1/test/sessions` (see server docs / `llms.txt`). */
+export interface TestSessionBootstrap {
+    user_isolation?: {
+        enabled: boolean;
+        namespace_pattern: string;
+        shared_read_paths?: string[];
+        shared_write_paths?: string[];
+    };
+    developer_bypass?: boolean;
+    policies?: Array<{
+        policy_id: string;
+        policy: SecurityPolicy;
+    }>;
+}
+/** `bootstrap` summary returned by the server after a bootstrapped test session is created. */
+export interface TestSessionBootstrapSummary {
+    user_isolation_applied?: boolean;
+    developer_bypass_applied?: boolean;
+    policies_created?: string[];
+}
 /** Options for {@link XCiteDBClient.createTestSession} (provisions via API key or Bearer). */
 export interface CreateTestSessionOptions {
     baseUrl: string;
@@ -518,6 +538,8 @@ export interface CreateTestSessionOptions {
      * When true, creates an overlay test session: writable ephemeral LMDB with production project data as read-only base.
      */
     overlay?: boolean;
+    /** Optional server-side bootstrap (user isolation, developer_bypass, policies). */
+    bootstrap?: TestSessionBootstrap;
     /** Keep `apiKey` / `accessToken` on the client and send `X-Test-Auth: required` on each request. */
     testRequireAuth?: boolean;
     onSessionTokensUpdated?: (pair: TokenPair) => void;
@@ -677,6 +699,7 @@ export interface SecurityConfig {
 export interface AccessCheckResult {
     effect: 'allow' | 'deny';
     matched_policy_id?: string;
+    reason?: string;
 }
 export interface StoredPolicyResponse {
     policy_id: string;
@@ -826,8 +849,36 @@ export interface PublishResult {
 }
 /** @deprecated Use {@link PublishResult}. */
 export type MergeResult = PublishResult;
+export type XCiteDBErrorExtras = {
+    reason?: string;
+    policyId?: string;
+    hint?: string;
+    expectedRole?: string;
+    actualRole?: string;
+    serverRequestId?: string;
+    clientRequestId?: string;
+};
 export declare class XCiteDBError extends Error {
     readonly status: number;
     readonly body?: unknown | undefined;
-    constructor(message: string, status: number, body?: unknown | undefined);
+    reason?: string;
+    policyId?: string;
+    hint?: string;
+    expectedRole?: string;
+    actualRole?: string;
+    serverRequestId?: string;
+    clientRequestId?: string;
+    constructor(message: string, status: number, body?: unknown | undefined, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBForbiddenError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBNotFoundError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBAuthError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
+}
+export declare class XCiteDBLockConflictError extends XCiteDBError {
+    constructor(message: string, status: number, body?: unknown, extras?: XCiteDBErrorExtras);
 }

package/dist/types.js

@@ -1,12 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XCiteDBError = void 0;
+exports.XCiteDBLockConflictError = exports.XCiteDBAuthError = exports.XCiteDBNotFoundError = exports.XCiteDBForbiddenError = exports.XCiteDBError = void 0;
 class XCiteDBError extends Error {
-    constructor(message, status, body) {
+    constructor(message, status, body, extras) {
         super(message);
         this.status = status;
         this.body = body;
         this.name = 'XCiteDBError';
+        if (extras) {
+            this.reason = extras.reason;
+            this.policyId = extras.policyId;
+            this.hint = extras.hint;
+            this.expectedRole = extras.expectedRole;
+            this.actualRole = extras.actualRole;
+            this.serverRequestId = extras.serverRequestId;
+            this.clientRequestId = extras.clientRequestId;
+        }
     }
 }
 exports.XCiteDBError = XCiteDBError;
+class XCiteDBForbiddenError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBForbiddenError';
+    }
+}
+exports.XCiteDBForbiddenError = XCiteDBForbiddenError;
+class XCiteDBNotFoundError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBNotFoundError';
+    }
+}
+exports.XCiteDBNotFoundError = XCiteDBNotFoundError;
+class XCiteDBAuthError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBAuthError';
+    }
+}
+exports.XCiteDBAuthError = XCiteDBAuthError;
+class XCiteDBLockConflictError extends XCiteDBError {
+    constructor(message, status, body, extras) {
+        super(message, status, body, extras);
+        this.name = 'XCiteDBLockConflictError';
+    }
+}
+exports.XCiteDBLockConflictError = XCiteDBLockConflictError;

package/llms-full.txt

@@ -199,6 +199,19 @@ Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oau
 
 ---
 
+## When a request returns 403
+
+XCiteDB returns one of two 403 shapes; both include `reason`:
+
+- Generic role/credential 403: `{ "error": "Error", "message": "Forbidden", "code": 403, "reason": "role_forbidden_*"|"auth_*" }`. The credential failed before ABAC ran. Verify that the API key is not a `public` key for write controllers, that the app-user JWT has `project:<tenant>:admin|editor`, and that for `POST /api/v1/security/policies` the credential resolves to `role: "admin"`.
+- ABAC 403: also includes `policy_id` ("abac_denied" / "reserved_namespace" / explicit deny rule id) and `hint`. When `reason == "tenant_security_unconfigured"`, the tenant has zero policies and default-deny took over — typical inside a fresh test session.
+
+First debugging step: call `POST /api/v1/security/check` with the same subject + identifier + action to get `effect` and `matched_policy_id` without state changes.
+
+The server's request id is in the `X-Request-Id` response header. If you also send your own `X-Request-Id` on the request, XCiteDB echoes it back as `X-Client-Request-Id` and includes it in activity logs (search via `GET /api/v1/project/logs?request_id=<uuid>`).
+
+SDKs surface these fields on typed errors (e.g. `XCiteDBForbiddenError.policyId`, `serverRequestId`, `clientRequestId` in JavaScript; `policy_id`, `server_request_id` in Python/C++).
+
 # Ephemeral test sessions
 
 > **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised. Provision a session in `beforeAll` / `setUp` / test fixture setup and destroy it in `afterAll` / `tearDown` / fixture teardown.
@@ -215,9 +228,23 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 
 **SDK usage (summary):**
 
-- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
-- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor. For overlay until the helper accepts a flag, call **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`** then construct the client with the returned token.
-- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay = true`**, and optional `test_require_auth`; `destroy_test_session()`.
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`; optional **`bootstrap`** (`user_isolation`, `developer_bypass`, `policies`); read **`lastTestSessionBootstrap`** on the returned client when the server included a summary. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …, bootstrap={…})` provisions and tears down; or **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`**, **`bootstrap`**, or both, then construct the client with the returned token; **`client.last_test_session_bootstrap`** mirrors the server summary.
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay`**, optional **`test_session_bootstrap`** on `XCiteDBClientOptions`, optional `test_require_auth`; **`last_test_session_bootstrap()`** on the returned client; `destroy_test_session()`.
+
+**A fresh test session is an empty tenant with zero policies.** With `X-Test-Auth: required`, ABAC default-deny applies until you bootstrap user isolation and/or policies. Typical `POST /api/v1/test/sessions` body:
+
+```json
+{
+  "bootstrap": {
+    "user_isolation": { "enabled": true, "namespace_pattern": "/spaces/${user.id}" },
+    "developer_bypass": true,
+    "policies": []
+  }
+}
+```
+
+Skipping bootstrap yields 403 with `reason: "tenant_security_unconfigured"` for app-user reads/writes under `/spaces/<userId>/...`.
 
 **JavaScript/TypeScript — complete test scaffold (Vitest / Jest):**
 
@@ -681,6 +708,15 @@ Operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `in`, `not_in`, `contains`, `starts_
 
 SDK: `UnqueryTemplate` in `@xcitedbs/client` types; method `unquery(query, unquery)`.
 
+### `reason` / `policy_id` markers (403 debugging)
+
+| reason | policy_id | Meaning |
+|--------|------------|---------|
+| `abac_explicit_deny` | &lt;your-rule-id&gt; | An explicit deny rule matched. |
+| `abac_default_deny` | `abac_denied` | No allow policy matched; tenant `default_effect` (or `app_user_default_effect`) deny took over. |
+| `tenant_security_unconfigured` | `abac_denied` | Same as default deny but the tenant has **zero** policies — usual for a fresh test session without bootstrap. |
+| `abac_reserved_namespace` | `reserved_namespace` | App-user or public-key request touched `_xcitedb*` reserved identifiers. |
+
 ## ABAC policy expression language
 
 Policies may set **`conditions.expression`** (optional) and **`conditions.branches`** (optional array). If `branches` is non-empty, the request branch must match an entry (`"*"`, exact name, or `prefix*`).
@@ -1314,12 +1350,34 @@ For logged-in users (not only platform admins):
 
 ---
 
+## Wrapping XCiteDB in a higher-level service
+
+When you build a backend that calls XCiteDB on behalf of users:
+
+- Never collapse upstream errors to a generic `xcitedb_upstream` code. Pass `body.policy_id`, `body.hint`, `body.reason`, `body.expected_role`, `body.actual_role` through your error wrapper. They are stable, low-cardinality, and safe to surface to test fixtures.
+- Capture `X-Request-Id` from XCiteDB's response and log it next to your own request id. Send your service's own request id as `X-Request-Id` on outgoing calls; XCiteDB will echo it as `X-Client-Request-Id`.
+- Distinguish service-key calls vs end-user-token calls in your error trace; tag the call site so a 403 from a user-token spine read and a 403 from an admin `createPolicy` are distinguishable.
+- Do not assume an end-user implicitly has read access to documents under `/spaces/<their_user_id>/....` That is only true when user isolation is enabled on the tenant with the matching `namespace_pattern`. In production tenants this is one-time setup; in test sessions use the bootstrap option on `POST /api/v1/test/sessions`.
+
 # Part 3: SDK Reference
 
 # JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
 
+### Typed 403 handling
+
+```typescript
+import { XCiteDBClient, XCiteDBForbiddenError } from '@xcitedbs/client';
+try {
+  await client.readJsonDocument('/spaces/u1/docs/d/spine.json');
+} catch (e) {
+  if (e instanceof XCiteDBForbiddenError) {
+    console.error({ reason: e.reason, policyId: e.policyId, hint: e.hint, requestId: e.serverRequestId });
+  }
+}
+```
+
 ## Quick Start
 
 ```typescript
@@ -1592,6 +1650,19 @@ class XCiteDBError extends Error {
 
 Install: `pip install xcitedb`
 
+### Typed 403 handling
+
+```python
+from xcitedb import XCiteDBClient, XCiteDBForbiddenError
+
+async def main():
+    client = XCiteDBClient("http://localhost:8080", api_key="your-key")
+    try:
+        await client.read_json_document("/spaces/u1/docs/d/spine.json")
+    except XCiteDBForbiddenError as e:
+        print(e.reason, e.policy_id, e.hint, e.server_request_id)
+```
+
 ```python
 import asyncio
 from xcitedb import (
@@ -1644,6 +1715,21 @@ q.match_start = "/manual/";
 auto ids = client.query_documents(q);
 ```
 
-Synchronous (blocking) HTTP client. Methods mirror the JavaScript SDK with C++ naming (`write_xml_document`, deprecated `write_document_json`). Errors throw `xcitedb::XCiteDBError` with `.status()` and `.body()`.
+Synchronous (blocking) HTTP client. Methods mirror the JavaScript SDK with C++ naming (`write_xml_document`, deprecated `write_document_json`). Errors throw `xcitedb::XCiteDBError` (or subclasses such as `xcitedb::XCiteDBForbiddenError`) with `.status()`, `.body()`, `.reason()`, `.policy_id()`, `.hint()`, `.server_request_id()`, and `.client_request_id()`.
+
+### Typed 403 handling
+
+```cpp
+#include <xcitedb/xcitedb.hpp>
+#include <iostream>
+
+void example(xcitedb::XCiteDBClient& client) {
+  try {
+    client.read_json_document("/spaces/u1/docs/d/spine.json");
+  } catch (const xcitedb::XCiteDBForbiddenError& e) {
+    std::cerr << e.reason() << " " << e.policy_id() << " " << e.hint() << " " << e.server_request_id() << "\n";
+  }
+}
+```
 
 Includes optional `xcitevcs` CLI for command-line operations (legacy branch/commit vocabulary on the wire, documents, search, import/export).

package/llms.txt

@@ -101,6 +101,19 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 
 **Python:** `XCiteDBClient.build_project_group(project_id, "editor")` or module `build_project_group`. **C++:** `XCiteDBClient::build_project_group(project_id, "editor")`.
 
+## When a request returns 403
+
+XCiteDB returns one of two 403 shapes; both include `reason`:
+
+- Generic role/credential 403: `{ "error": "Error", "message": "Forbidden", "code": 403, "reason": "role_forbidden_*"|"auth_*" }`. The credential failed before ABAC ran. Verify that the API key is not a `public` key for write controllers, that the app-user JWT has `project:<tenant>:admin|editor`, and that for `POST /api/v1/security/policies` the credential resolves to `role: "admin"`.
+- ABAC 403: also includes `policy_id` ("abac_denied" / "reserved_namespace" / explicit deny rule id) and `hint`. When `reason == "tenant_security_unconfigured"`, the tenant has zero policies and default-deny took over — typical inside a fresh test session.
+
+First debugging step: call `POST /api/v1/security/check` with the same subject + identifier + action to get `effect` and `matched_policy_id` without state changes.
+
+The server's request id is in the `X-Request-Id` response header. If you also send your own `X-Request-Id` on the request, XCiteDB echoes it back as `X-Client-Request-Id` and includes it in activity logs (search via `GET /api/v1/project/logs?request_id=<uuid>`).
+
+SDKs surface these fields on typed errors (e.g. `XCiteDBForbiddenError.policyId`, `serverRequestId`, `clientRequestId` in JavaScript; `policy_id`, `server_request_id` in Python/C++).
+
 ## Test mode (how to use)
 
 > **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised.
@@ -109,7 +122,32 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Workspace` / `context` as needed). Data writes go under the server’s `_test/<session>/` tree; overlay sessions **do not** write to production paths.
 3. **Auth behavior:** Developer auth (API key / platform JWT) is bypassed by default for frictionless tests. **App-user identity** (`X-App-User-Token` or Bearer app-user JWT) **is still recognized** in default mode, so `registerAppUser` → `loginAppUser` → `appUserMe` works inside a test session. To also exercise developer auth and ABAC policies, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
-5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `overlay: true`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or provision with **`POST /api/v1/test/sessions`** and JSON **`{"overlay":true}`** when you need overlay, then pass `test_session_token` / `test_require_auth` to the constructor. **C++:** `XCiteDBClient::create_test_session(options)` with optional `test_session_overlay = true`, `destroy_test_session()`, optional `test_require_auth` in options.
+5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })`, optional `overlay: true`, optional `testRequireAuth`, optional `bootstrap` (`user_isolation`, `developer_bypass`, `policies`), then read `lastTestSessionBootstrap` on the returned client; `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(..., bootstrap={...})` or provision with **`POST /api/v1/test/sessions`** (JSON may include **`{"overlay":true}`** and/or **`bootstrap`**); use `client.last_test_session_bootstrap` after creation; pass `test_session_token` / `test_require_auth` to the constructor as before. **C++:** `XCiteDBClient::create_test_session(options)` with optional `test_session_overlay`, optional `test_session_bootstrap` on `XCiteDBClientOptions`, `last_test_session_bootstrap()` on the returned client, `destroy_test_session()`, optional `test_require_auth`.
+
+**A fresh test session is an empty tenant with zero policies.** With `X-Test-Auth: required` the AuthFilter runs normally and ABAC is enforced against the test tenant — default-deny rejects every app-user read/write until you either enable user isolation or add explicit allow policies. The standard recipe is to use the bootstrap option on `POST /api/v1/test/sessions`:
+
+```json
+{
+  "bootstrap": {
+    "user_isolation": { "enabled": true, "namespace_pattern": "/spaces/${user.id}" },
+    "developer_bypass": true,
+    "policies": []
+  }
+}
+```
+
+If you skip the bootstrap, an app-user JWT cannot read or write `/spaces/<userId>/...` — even paths the user "owns" — and you will see 403 with reason `tenant_security_unconfigured`.
+
+**SDK one-liners for bootstrap:** **JS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, testRequireAuth: true, bootstrap: { user_isolation: { enabled: true, namespace_pattern: '/spaces/${user.id}' }, developer_bypass: true } })`. **Python:** `async with XCiteDBClient.test_session(base_url, api_key=sk, test_require_auth=True, bootstrap={...}) as c:`. **C++:** set `options.test_session_bootstrap = nlohmann::json::parse(R"(...)");` then `XCiteDBClient::create_test_session(options)`.
+
+## Wrapping XCiteDB in a higher-level service
+
+When you build a backend that calls XCiteDB on behalf of users:
+
+- Never collapse upstream errors to a generic `xcitedb_upstream` code. Pass `body.policy_id`, `body.hint`, `body.reason`, `body.expected_role`, `body.actual_role` through your error wrapper. They are stable, low-cardinality, and safe to surface to test fixtures.
+- Capture `X-Request-Id` from XCiteDB's response and log it next to your own request id. Send your service's own request id as `X-Request-Id` on outgoing calls; XCiteDB will echo it as `X-Client-Request-Id`.
+- Distinguish service-key calls vs end-user-token calls in your error trace; tag the call site so a 403 from a user-token spine read and a 403 from an admin `createPolicy` are distinguishable.
+- Do not assume an end-user implicitly has read access to documents under `/spaces/<their_user_id>/....` That is only true when user isolation is enabled on the tenant with the matching `namespace_pattern`. In production tenants this is one-time setup; in test sessions use the bootstrap option.
 
 ## JSON documents and metadata (merge, overwrite, efficiency)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.18",
+  "version": "0.2.19",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",