@xcitedbs/client 0.3.9 → 0.3.10

package/dist/client.d.ts

@@ -188,6 +188,19 @@ export declare class XCiteDBClient {
     /** Sets active project for platform console mode (`X-Project-Id`). */
     setProjectId(projectId: string): void;
     setContext(ctx: DatabaseContext): void;
+    private static mergeContext;
+    /**
+     * Create a child client that shares transport/auth wiring with this one but has an
+     * independent context. Forking does not mutate the parent; child and parent can be used
+     * concurrently with different workspaces, dates, or prefixes. Use this in place of
+     * `setContext → do work → setContext(prev)`.
+     *
+     * Auth tokens (api key, access token, app-user tokens) are copied at fork time. Subsequent
+     * token rotation via `setTokens` / `setAppUserTokens` (or callbacks) updates only the
+     * instance that triggered it; if you fork long-lived clients, keep token state in sync via
+     * the `onSessionTokensUpdated` / `onAppUserTokensUpdated` callbacks supplied at construction.
+     */
+    fork(partial?: Partial<DatabaseContext>): XCiteDBClient;
     setTokens(access: string, refresh?: string): void;
     /** End-user (app) tokens. With developer `accessToken`/`apiKey`, sent as `X-App-User-Token`. */
     setAppUserTokens(access: string, refresh?: string): void;
@@ -751,7 +764,7 @@ export declare class XCiteDBClient {
         merge?: MergeResult;
     }>;
     /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
-    writeXML(xml: string, _options?: WriteDocumentOptions): Promise<void>;
+    writeXML(xml: string, options?: WriteDocumentOptions): Promise<void>;
     /**
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
      * For storing JSON data by key, use `writeJsonDocument`.
@@ -785,21 +798,27 @@ export declare class XCiteDBClient {
      * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
      */
     writeDocumentJson(xml: string, options?: WriteDocumentOptions): Promise<void>;
-    queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
+    queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<string[]>;
     /**
      * Shallow read (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`):
      * root element with inline leaves plus **identifier-bearing stub elements** (`db:stub="true"`) for shredded
      * child slots instead of opaque `db:N*` placeholders. Safe to round-trip with {@link writeXmlDocument}.
      * For sidebar / AST navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
      */
-    queryByIdentifierShallow(identifier: string, filter?: string, pathFilter?: string): Promise<string[]>;
+    queryByIdentifierShallow(identifier: string, filter?: string, pathFilter?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<string[]>;
     /**
      * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
      * The returned array has **length 0 or 1**; when present, index `0` is the full XML string.
      * Use this for editor round-trips. For navigation without loading the full subtree, use
      * {@link queryByIdentifierShallow} plus {@link listIdentifierChildren}.
      */
-    queryByIdentifierFull(identifier: string, filter?: string, pathFilter?: string): Promise<string[]>;
+    queryByIdentifierFull(identifier: string, filter?: string, pathFilter?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<string[]>;
     /** Alias of {@link listIdentifierChildren} — immediate child segments under `parentPath` (identifier hierarchy). */
     listChildIdentifiers(parentPath?: string): Promise<ListIdentifierChildrenResult>;
     queryDocuments(query: XCiteQuery, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
@@ -815,10 +834,12 @@ export declare class XCiteDBClient {
     addMeta(identifier: string, value: unknown, path?: string, opts?: {
         mode?: 'set' | 'append' | 'merge_append';
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     addMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         mode?: 'set' | 'append' | 'merge_append';
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     /**
      * Strict array-extend: `value` must be an array; the stored target at `path` must be an array
@@ -828,9 +849,11 @@ export declare class XCiteDBClient {
      */
     appendMeta(identifier: string, value: unknown[], path?: string, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     appendMetaByQuery(query: XCiteQuery, value: unknown[], path?: string, firstMatch?: boolean, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     /**
      * Deep-extend: walks the payload and extends any nested arrays found in storage. Scalars and
@@ -839,17 +862,31 @@ export declare class XCiteDBClient {
      */
     mergeAppendMeta(identifier: string, value: unknown, path?: string, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     mergeAppendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
     /** Convenience: push a single item. Wraps `item` in `[item]` and calls {@link appendMeta}. */
-    appendItem(identifier: string, item: unknown, path?: string, opts?: {
+    appendItem<T = unknown>(identifier: string, item: T, path?: string, opts?: {
         overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
+    }): Promise<boolean>;
+    /** Convenience: push a single item via query. Wraps `item` in `[item]` and calls {@link appendMetaByQuery}. */
+    appendItemByQuery<T = unknown>(query: XCiteQuery, item: T, path?: string, firstMatch?: boolean, opts?: {
+        overwrite?: boolean;
+        context?: Partial<DatabaseContext>;
+    }): Promise<boolean>;
+    queryMeta<T = MetaValue>(identifier: string, path?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<T>;
+    queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<T>;
+    clearMeta(query: XCiteQuery, opts?: {
+        context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
-    queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
-    queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
-    clearMeta(query: XCiteQuery): Promise<boolean>;
     /**
      * Acquire a cooperative lock. On exclusive conflict the server returns HTTP 409 with a
      * {@link LockConflictBody} body (thrown as {@link XCiteDBError} with `.status === 409`).
@@ -902,7 +939,10 @@ export declare class XCiteDBClient {
      * );
      * ```
      */
-    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: UnqueryTemplate): Promise<T>;
+    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: UnqueryTemplate, opts?: {
+        context?: Partial<DatabaseContext>;
+        strict?: boolean;
+    }): Promise<T>;
     search(q: TextSearchQuery): Promise<TextSearchResult>;
     reindex(): Promise<{
         status: string;

package/dist/client.js

@@ -629,6 +629,15 @@ class XCiteDBClient {
         if (canonical.startsWith('/users/') && !canonical.startsWith(`${ns}/`) && canonical !== ns) {
             return canonical;
         }
+        // Tenant-managed share-alias roots are never under any user namespace; pass them through
+        // unchanged so app users can read documents shared with them via group / public / anonymous
+        // share aliases (server alias paths produced by UserIsolationService::compute*ShareAliasPath).
+        if (canonical.startsWith('/groups/') ||
+            canonical.startsWith('/shared/') ||
+            canonical.startsWith('/shared-readonly/') ||
+            canonical.startsWith('/public/')) {
+            return canonical;
+        }
         const combined = `${ns}${canonical === '/' ? '/' : canonical}`;
         const finalId = combined.replace(/\/+/g, '/');
         if (!finalId.startsWith(ns) || (finalId.length > ns.length && finalId.charAt(ns.length) !== '/')) {
@@ -821,11 +830,33 @@ class XCiteDBClient {
         this.projectId = projectId;
     }
     setContext(ctx) {
-        const next = { ...this.defaultContext, ...ctx };
-        if (ctx.workspace !== undefined) {
-            next.branch = ctx.workspace;
+        this.defaultContext = XCiteDBClient.mergeContext(this.defaultContext, ctx);
+    }
+    static mergeContext(prev, partial) {
+        const next = { ...prev, ...partial };
+        if (partial.workspace !== undefined) {
+            next.branch = partial.workspace;
         }
-        this.defaultContext = next;
+        return next;
+    }
+    /**
+     * Create a child client that shares transport/auth wiring with this one but has an
+     * independent context. Forking does not mutate the parent; child and parent can be used
+     * concurrently with different workspaces, dates, or prefixes. Use this in place of
+     * `setContext → do work → setContext(prev)`.
+     *
+     * Auth tokens (api key, access token, app-user tokens) are copied at fork time. Subsequent
+     * token rotation via `setTokens` / `setAppUserTokens` (or callbacks) updates only the
+     * instance that triggered it; if you fork long-lived clients, keep token state in sync via
+     * the `onSessionTokensUpdated` / `onAppUserTokensUpdated` callbacks supplied at construction.
+     */
+    fork(partial) {
+        const child = Object.create(XCiteDBClient.prototype);
+        Object.assign(child, this);
+        child.defaultContext = XCiteDBClient.mergeContext(this.defaultContext, partial ?? {});
+        // Context can shift the user-isolation prefix; the parent's cached app-user id no longer applies.
+        child.cachedAppUserId = undefined;
+        return child;
     }
     setTokens(access, refresh) {
         this.accessToken = access;
@@ -844,9 +875,9 @@ class XCiteDBClient {
         this.appUserRefreshToken = undefined;
         this.clearAppUserIdCache();
     }
-    contextHeaders() {
+    contextHeaders(override) {
         const h = {};
-        const c = this.defaultContext;
+        const c = override ? XCiteDBClient.mergeContext(this.defaultContext, override) : this.defaultContext;
         const ws = c.workspace ?? c.branch;
         if (ws)
             h['X-Workspace'] = ws;
@@ -907,11 +938,12 @@ class XCiteDBClient {
     async request(method, path, body, extraHeaders, opts) {
         const no401Retry = opts?.no401Retry === true;
         const suppressTestSessionHeader = opts?.suppressTestSessionHeader === true;
+        const contextOverride = opts?.contextOverride;
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
             const headers = {
                 ...this.authHeaders(),
-                ...this.contextHeaders(),
+                ...this.contextHeaders(contextOverride),
                 ...(suppressTestSessionHeader ? {} : this.testHeaders()),
                 ...extraHeaders,
             };
@@ -2067,25 +2099,18 @@ class XCiteDBClient {
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.
      */
     async withWorkspace(workspaceName, fn, options) {
-        const prev = { ...this.defaultContext };
-        const fromWs = options?.fromBranch ?? prev.branch ?? prev.workspace ?? '';
-        let checkpoint;
+        const fromWs = options?.fromBranch ?? this.defaultContext.branch ?? this.defaultContext.workspace ?? '';
+        await this.createWorkspace(workspaceName, fromWs || undefined, this.defaultContext.date || undefined);
+        const child = this.fork({ workspace: workspaceName, branch: workspaceName });
+        const result = await fn(child);
+        const checkpoint = await child.createCheckpoint(options?.message ?? `Workspace ${workspaceName}`, options?.author);
         let publish;
-        try {
-            await this.createWorkspace(workspaceName, fromWs || undefined, prev.date || undefined);
-            this.setContext({ workspace: workspaceName, branch: workspaceName });
-            const result = await fn(this);
-            checkpoint = await this.createCheckpoint(options?.message ?? `Workspace ${workspaceName}`, options?.author);
-            if (options?.autoMerge !== false) {
-                publish = await this.publishWorkspace(fromWs, workspaceName, {
-                    message: options?.message,
-                });
-            }
-            return { result, checkpoint, publish };
-        }
-        finally {
-            this.setContext(prev);
+        if (options?.autoMerge !== false) {
+            publish = await child.publishWorkspace(fromWs, workspaceName, {
+                message: options?.message,
+            });
         }
+        return { result, checkpoint, publish };
     }
     /** @deprecated Use {@link withWorkspace}. */
     async withBranch(branchName, fn, options) {
@@ -2093,11 +2118,9 @@ class XCiteDBClient {
         return { result: r.result, commit: r.checkpoint, merge: r.publish };
     }
     /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
-    async writeXML(xml, _options) {
+    async writeXML(xml, options) {
         const payload = this.isoApplyXmlDbIdentifier(xml);
-        await this.request('POST', '/api/v1/documents', payload, {
-            'Content-Type': 'application/xml',
-        });
+        await this.request('POST', '/api/v1/documents', payload, { 'Content-Type': 'application/xml' }, { contextOverride: options?.context });
     }
     /**
      * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
@@ -2114,7 +2137,7 @@ class XCiteDBClient {
             xml: this.isoApplyXmlDbIdentifier(xml),
             is_top: options?.is_top ?? true,
             compare_attributes: options?.compare_attributes ?? false,
-        });
+        }, undefined, { contextOverride: options?.context });
     }
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
@@ -2194,14 +2217,16 @@ class XCiteDBClient {
     async writeDocumentJson(xml, options) {
         return this.writeXmlDocument(xml, options);
     }
-    async queryByIdentifier(identifier, flags, filter, pathFilter) {
+    async queryByIdentifier(identifier, flags, filter, pathFilter, opts) {
         const q = buildQuery({
             identifier: this.isoPrefixId(identifier),
             flags: flags,
             filter,
             path_filter: pathFilter,
         });
-        return this.request('GET', `/api/v1/documents/by-id${q}`);
+        return this.request('GET', `/api/v1/documents/by-id${q}`, undefined, undefined, {
+            contextOverride: opts?.context,
+        });
     }
     /**
      * Shallow read (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`):
@@ -2209,8 +2234,8 @@ class XCiteDBClient {
      * child slots instead of opaque `db:N*` placeholders. Safe to round-trip with {@link writeXmlDocument}.
      * For sidebar / AST navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
      */
-    async queryByIdentifierShallow(identifier, filter, pathFilter) {
-        return this.queryByIdentifier(identifier, 'NoChildren,KeepIndexNodes,FirstMatch', filter, pathFilter);
+    async queryByIdentifierShallow(identifier, filter, pathFilter, opts) {
+        return this.queryByIdentifier(identifier, 'NoChildren,KeepIndexNodes,FirstMatch', filter, pathFilter, opts);
     }
     /**
      * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
@@ -2218,8 +2243,8 @@ class XCiteDBClient {
      * Use this for editor round-trips. For navigation without loading the full subtree, use
      * {@link queryByIdentifierShallow} plus {@link listIdentifierChildren}.
      */
-    async queryByIdentifierFull(identifier, filter, pathFilter) {
-        return this.queryByIdentifier(identifier, 'FirstMatch,IncludeChildren', filter, pathFilter);
+    async queryByIdentifierFull(identifier, filter, pathFilter, opts) {
+        return this.queryByIdentifier(identifier, 'FirstMatch,IncludeChildren', filter, pathFilter, opts);
     }
     /** Alias of {@link listIdentifierChildren} — immediate child segments under `parentPath` (identifier hierarchy). */
     async listChildIdentifiers(parentPath) {
@@ -2369,7 +2394,9 @@ class XCiteDBClient {
             body.mode = opts.mode;
         if (opts?.overwrite)
             body.overwrite = true;
-        const r = await this.request('POST', '/api/v1/meta', body);
+        const r = await this.request('POST', '/api/v1/meta', body, undefined, {
+            contextOverride: opts?.context,
+        });
         return r?.ok !== false;
     }
     async addMetaByQuery(query, value, path = '', firstMatch = false, opts) {
@@ -2383,7 +2410,9 @@ class XCiteDBClient {
             body.mode = opts.mode;
         if (opts?.overwrite)
             body.overwrite = true;
-        const r = await this.request('POST', '/api/v1/meta', body);
+        const r = await this.request('POST', '/api/v1/meta', body, undefined, {
+            contextOverride: opts?.context,
+        });
         return r?.ok !== false;
     }
     /**
@@ -2413,16 +2442,18 @@ class XCiteDBClient {
     async appendItem(identifier, item, path = '', opts) {
         return this.appendMeta(identifier, [item], path, opts);
     }
-    async queryMeta(identifier, path = '') {
-        return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`);
+    /** Convenience: push a single item via query. Wraps `item` in `[item]` and calls {@link appendMetaByQuery}. */
+    async appendItemByQuery(query, item, path = '', firstMatch = false, opts) {
+        return this.appendMetaByQuery(query, [item], path, firstMatch, opts);
     }
-    async queryMetaByQuery(query, path = '') {
-        return this.request('POST', '/api/v1/meta/query', { query: this.isoPrefixQuery(query), path });
+    async queryMeta(identifier, path = '', opts) {
+        return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`, undefined, undefined, { contextOverride: opts?.context });
     }
-    async clearMeta(query) {
-        const r = await this.request('DELETE', '/api/v1/meta', {
-            query: this.isoPrefixQuery(query),
-        });
+    async queryMetaByQuery(query, path = '', opts) {
+        return this.request('POST', '/api/v1/meta/query', { query: this.isoPrefixQuery(query), path }, undefined, { contextOverride: opts?.context });
+    }
+    async clearMeta(query, opts) {
+        const r = await this.request('DELETE', '/api/v1/meta', { query: this.isoPrefixQuery(query) }, undefined, { contextOverride: opts?.context });
         return r?.ok !== false;
     }
     /**
@@ -2515,8 +2546,9 @@ class XCiteDBClient {
      * );
      * ```
      */
-    async unquery(query, unquery) {
-        return this.request('POST', '/api/v1/unquery', { query: this.isoPrefixQuery(query), unquery });
+    async unquery(query, unquery, opts) {
+        const extraHeaders = opts?.strict ? { 'X-Unquery-Strict': 'true' } : undefined;
+        return this.request('POST', '/api/v1/unquery', { query: this.isoPrefixQuery(query), unquery }, extraHeaders, { contextOverride: opts?.context });
     }
     async search(q) {
         const body = { query: q.query };

package/dist/client.test.js

@@ -611,6 +611,285 @@ const types_js_1 = require("./types.js");
         }
     });
 });
+(0, node_test_1.describe)('client.fork()', () => {
+    (0, node_test_1.it)('child sends overridden workspace; parent keeps original on parallel calls', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            const h = new Headers(init?.headers);
+            seen.push({ url: String(input), workspace: h.get('X-Workspace') });
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const parent = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            const child = parent.fork({ workspace: 'feature-x' });
+            await Promise.all([
+                parent.queryMeta('/d1'),
+                child.queryMeta('/d2'),
+                parent.queryMeta('/d3'),
+            ]);
+            strict_1.default.equal(seen.length, 3);
+            const byUrl = new Map(seen.map((s) => [s.url, s.workspace]));
+            strict_1.default.equal([...byUrl.keys()].some((u) => u.includes('%2Fd1')), true);
+            const ws = (id) => seen.find((s) => s.url.includes(id)).workspace;
+            strict_1.default.equal(ws('%2Fd1'), 'main');
+            strict_1.default.equal(ws('%2Fd2'), 'feature-x');
+            strict_1.default.equal(ws('%2Fd3'), 'main');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('child setContext does not mutate parent', async () => {
+        const c = new client_js_1.XCiteDBClient({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            context: { workspace: 'main', date: '2025-01-01' },
+        });
+        const child = c.fork({ workspace: 'feat' });
+        child.setContext({ workspace: 'feat-v2', date: '2025-12-31' });
+        // Capture parent's headers via a single request.
+        const orig = globalThis.fetch;
+        let parentWs = null;
+        let parentDate = null;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            const h = new Headers(init?.headers);
+            parentWs = h.get('X-Workspace');
+            parentDate = h.get('X-Date');
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            await c.queryMeta('/p');
+            strict_1.default.equal(parentWs, 'main');
+            strict_1.default.equal(parentDate, '2025-01-01');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('fork() with no arg copies parent context verbatim', async () => {
+        const c = new client_js_1.XCiteDBClient({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            context: { workspace: 'w', date: '2025-06-01', prefix: '/p' },
+        });
+        const child = c.fork();
+        let h = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            h = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            await child.queryMeta('/d');
+            strict_1.default.equal(h.get('X-Workspace'), 'w');
+            strict_1.default.equal(h.get('X-Date'), '2025-06-01');
+            strict_1.default.equal(h.get('X-Prefix'), '/p');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('fork({workspace}) mirrors workspace into branch (back-compat alias)', async () => {
+        const c = new client_js_1.XCiteDBClient({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            context: { workspace: 'main', branch: 'main' },
+        });
+        const child = c.fork({ workspace: 'feature-y' });
+        // Inspect via a request: server only sees X-Workspace, but the deprecated branch alias
+        // must update too so legacy code paths inside the SDK that read `branch` see the new value.
+        let h = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            h = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            await child.queryMeta('/d');
+            strict_1.default.equal(h.get('X-Workspace'), 'feature-y');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('per-call opts.context override', () => {
+    (0, node_test_1.it)('queryMeta {context: {workspace}} sends overridden X-Workspace', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.queryMeta('/d', '', { context: { workspace: 'feature-x' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'feature-x');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('opts.context does NOT mutate the client default context', async () => {
+        const seen = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            const h = new Headers(init?.headers);
+            seen.push(h.get('X-Workspace') ?? '');
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.queryMeta('/a', '', { context: { workspace: 'one-off' } });
+            await c.queryMeta('/b'); // should fall back to default 'main'
+            strict_1.default.deepEqual(seen, ['one-off', 'main']);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('addMeta opts.context overrides workspace and date', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main', date: '2025-01-01' },
+            });
+            await c.addMeta('/d', { x: 1 }, '', {
+                context: { workspace: 'feat', date: '2025-12-31' },
+            });
+            strict_1.default.equal(captured.get('X-Workspace'), 'feat');
+            strict_1.default.equal(captured.get('X-Date'), '2025-12-31');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('appendItem opts.context flows through to the wrapped appendMeta call', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+            await c.appendItem('/d', 1, 'list', { context: { workspace: 'w-pc' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'w-pc');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('unquery opts.context overrides workspace', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.unquery({ match_start: '/x/' }, { id: '$identifier' }, { context: { workspace: 'unq' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'unq');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('writeXmlDocument options.context overrides workspace', async () => {
+        let captured = null;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                context: { workspace: 'main' },
+            });
+            await c.writeXmlDocument('<?xml version="1.0"?><doc xmlns:db="http://www.xcitedb.com/schema" db:identifier="/x"/>', { context: { workspace: 'wxd' } });
+            strict_1.default.equal(captured.get('X-Workspace'), 'wxd');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('appendItem / appendItemByQuery', () => {
+    (0, node_test_1.it)('appendItem wraps a typed item in [item] and POSTs mode=append', async () => {
+        const captured = { value: null };
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            captured.value = {
+                url: String(input),
+                body: JSON.parse(String(init?.body ?? '{}')),
+            };
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+            const review = { stars: 5, text: 'great' };
+            const ok = await c.appendItem('/products/p1', review, 'reviews');
+            strict_1.default.equal(ok, true);
+            strict_1.default.match(captured.value.url, /\/api\/v1\/meta$/);
+            const body = captured.value.body;
+            strict_1.default.equal(body.identifier, '/products/p1');
+            strict_1.default.equal(body.path, 'reviews');
+            strict_1.default.equal(body.mode, 'append');
+            strict_1.default.deepEqual(body.value, [review]);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('appendItemByQuery wraps a typed item in [item] and includes first_match', async () => {
+        const captured = { value: null };
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured.value = { body: JSON.parse(String(init?.body ?? '{}')) };
+            return new Response(JSON.stringify({ ok: true }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+            const ok = await c.appendItemByQuery({ match_start: '/products/' }, 42, 'tags', true);
+            strict_1.default.equal(ok, true);
+            const body = captured.value.body;
+            strict_1.default.equal(body.path, 'tags');
+            strict_1.default.equal(body.first_match, true);
+            strict_1.default.equal(body.mode, 'append');
+            strict_1.default.deepEqual(body.value, [42]);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
 (0, node_test_1.describe)('listTriggerEvents', () => {
     (0, node_test_1.it)('passes limit and parses events', async () => {
         let url = '';

package/dist/types.d.ts

@@ -569,6 +569,8 @@ export interface DatabaseContext {
 export interface WriteDocumentOptions {
     is_top?: boolean;
     compare_attributes?: boolean;
+    /** Per-call context override. Merged on top of the client's default context for this request only. */
+    context?: Partial<DatabaseContext>;
 }
 /** Supported source formats for `POST /api/v1/documents/import` (server detects from bytes / filename). */
 export type DocumentImportFormat = 'docx' | 'odt' | 'rtf' | 'pdf' | 'txt' | 'md' | 'adoc';

package/dist/user-isolation.test.js

@@ -118,6 +118,8 @@ wd('user isolation (wet)', () => {
         const slug = `js-iso-doc-${suffix}`;
         try {
             await admin.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            // Default-deny ABAC requires bypass for the platform admin to do data-doc ops in this project.
+            await admin.updateSecurityConfig({ developer_bypass: true });
             const u = await admin.createAppUser(email, password, undefined, [
                 client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
             ]);
@@ -134,6 +136,7 @@ wd('user isolation (wet)', () => {
             await admin.deleteAppUser(u.user_id);
         }
         finally {
+            await admin.updateSecurityConfig({ developer_bypass: false }).catch(() => { });
             await admin.disableUserIsolation().catch(() => { });
         }
     });
@@ -153,6 +156,7 @@ wd('user isolation (wet)', () => {
                 namespace_pattern: '/users/${user.id}',
                 shared_read_paths: [sharedPath],
             });
+            await admin.updateSecurityConfig({ developer_bypass: true });
             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'),
@@ -169,6 +173,7 @@ wd('user isolation (wet)', () => {
             await admin.deleteAppUser(created.user_id);
         }
         finally {
+            await admin.updateSecurityConfig({ developer_bypass: false }).catch(() => { });
             await admin.disableUserIsolation().catch(() => { });
         }
     });
@@ -198,6 +203,7 @@ wd('user isolation (wet)', () => {
                 enabled: true,
                 namespace_pattern: '/users/${user.id}',
             });
+            await admin.updateSecurityConfig({ developer_bypass: true });
             userA = await admin.createAppUser(emailA, password, undefined, [
                 client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
             ]);
@@ -249,6 +255,7 @@ wd('user isolation (wet)', () => {
                 await admin.deleteAppUser(userB.user_id).catch(() => { });
             if (userA)
                 await admin.deleteAppUser(userA.user_id).catch(() => { });
+            await admin.updateSecurityConfig({ developer_bypass: false }).catch(() => { });
             await admin.disableUserIsolation().catch(() => { });
         }
     });

package/package.json

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