@xcitedbs/client 0.3.0 → 0.3.2

package/dist/bootstrap-real.test.d.ts

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

package/dist/bootstrap-real.test.js

@@ -0,0 +1,264 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Wet-test reproduction of the client developer's "DB-reset Forbidden" bug, end-to-end.
+ *
+ * Set XCITEDB_BASE_URL, XCITEDB_ADMIN_TOKEN, XCITEDB_TENANT_ID to run; otherwise skipped.
+ *
+ * Each `it` exercises one of the four stacked failures from the original incident report:
+ *   1. `default_groups: []` + `registration_enabled: true` produces ghost users → server now
+ *      surfaces `warnings: ["default_groups_empty"]` and the BFF can act on it before users
+ *      register.
+ *   2. SPA tries `PUT /api/v1/app/users/:id/groups` with a public API key → server now returns
+ *      `403 reason: "role_forbidden_public_key"` (previously bare 403 with no reason).
+ *   3. `loginAppUser` sends a stale `Authorization: Bearer …` from a previous session → SDK
+ *      now clears tokens before the request; if a hand-rolled client skips that, server returns
+ *      `403 reason: "already_authenticated"` so the failure is diagnosable.
+ *   4. The `X-Test-Auth: preserve` mode lets us reproduce #2 in a wet test (under legacy bypass
+ *      the public-key context is erased, so the bug couldn't be reproduced in tests at all).
+ */
+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");
+const types_js_1 = require("./types.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 };
+}
+const w = wetEnv();
+const wd = w ? node_test_1.describe : node_test_1.describe.skip;
+wd('bootstrap reproduction (wet)', () => {
+    (0, node_test_1.it)('default_groups_empty warning surfaces, updateAppAuthConfig clears it', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        // Use preserve mode so admin auth is faithful; we still need real admin credentials to PUT
+        // /api/v1/app/auth/config. The test session is just isolation, not auth bypass.
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            // First: clear default_groups so the warning condition holds.
+            await admin.updateAppAuthConfig({ registration_enabled: true, default_groups: [] });
+            const before = await admin.getAppAuthConfig();
+            strict_1.default.deepEqual(before.default_groups, [], 'precondition: default_groups must be empty');
+            strict_1.default.ok(Array.isArray(before.warnings) && before.warnings.includes('default_groups_empty'), `getAppAuthConfig must surface "default_groups_empty" — got warnings=${JSON.stringify(before.warnings)}`);
+            // Now patch it.
+            const after = await admin.updateAppAuthConfig({ default_groups: ['editor'] });
+            strict_1.default.deepEqual(after.default_groups, ['editor']);
+            strict_1.default.ok(!after.warnings || !after.warnings.includes('default_groups_empty'), 'warning must clear once default_groups is non-empty');
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('register + login on the same client succeeds (token auto-cleared)', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            // Bootstrap: registration on, default_groups set so the user can do things.
+            await admin.updateAppAuthConfig({
+                registration_enabled: true,
+                default_groups: [client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor')],
+            });
+            // Anonymous app client (no apiKey, no accessToken). Reuses the test session via header
+            // propagation through the testSessionToken on the parent client; spawn a sibling
+            // anon client that shares the test session.
+            const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+            const email = `js_boot_${suffix}@apitest.invalid`;
+            const password = `Js_${suffix}!aA1`;
+            const anon = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                // Same test session so the user lives in the ephemeral DB.
+                testSessionToken: admin.testSessionToken,
+                // Required so the app-auth endpoints see anonymous_app_client (project_id propagates anonymously).
+                testAuth: 'preserve',
+            });
+            // First flow: register, then login on the same client. Without the SDK's clear-before-login
+            // fix this would 403 with reason="already_authenticated" because the register response would
+            // (in some flows) have set a token, and the next login would reuse it.
+            await anon.registerAppUser(email, password);
+            const pair = await anon.loginAppUser(email, password);
+            strict_1.default.ok(pair.access_token.length > 0, 'login returned an access token');
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('hand-rolled stale-bearer login returns 403 reason="already_authenticated"', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            await admin.updateAppAuthConfig({
+                registration_enabled: true,
+                default_groups: [client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor')],
+            });
+            const sessionToken = admin.testSessionToken;
+            const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+            const email = `js_stale_${suffix}@apitest.invalid`;
+            const password = `Js_${suffix}!aA1`;
+            // Step 1: register and login normally to get a real app-user JWT.
+            const anon = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                testSessionToken: sessionToken,
+                testAuth: 'preserve',
+            });
+            await anon.registerAppUser(email, password);
+            const pair = await anon.loginAppUser(email, password);
+            strict_1.default.ok(pair.access_token);
+            // Step 2: simulate a buggy client that re-issues login while still carrying the stale Bearer.
+            // Bypass the SDK (which would clear-before-login) by sending raw fetch.
+            const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/app/auth/login`;
+            const r = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${pair.access_token}`,
+                    'X-Test-Session': sessionToken,
+                    'X-Test-Auth': 'preserve',
+                },
+                body: JSON.stringify({ email, password, tenant_id: e.tenantId }),
+            });
+            strict_1.default.equal(r.status, 403, 'stale-bearer login must 403');
+            const body = (await r.json());
+            strict_1.default.equal(body.reason, 'already_authenticated', `body.reason must be "already_authenticated"; got ${JSON.stringify(body)}`);
+            strict_1.default.ok(body.hint && body.hint.length > 0, 'response must carry a hint');
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('public API key cannot PUT /api/v1/app/users/:id/groups; 403 reason="role_forbidden_public_key"', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        // We need a real public API key to exercise this path. The test session is a separate concern
+        // — the public-key denial is enforced by the role check before any test-session logic. Use
+        // the PROJECT public API key from env if available; otherwise skip with a clear message.
+        const publicKey = process.env.XCITEDB_PUBLIC_API_KEY?.trim();
+        if (!publicKey) {
+            // Run against the real tenant with a public key; not via test session because public keys
+            // can't always provision sessions and the failure mode is the role gate, not the storage.
+            console.log('  ⏭  skipped — set XCITEDB_PUBLIC_API_KEY (a public project key) to verify role_forbidden_public_key');
+            return;
+        }
+        const admin = new client_js_1.XCiteDBClient({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+        });
+        // Create a real app user to target. Don't use a test session — the developer's bug was on
+        // the production tenant, and the role gate fires the same way regardless.
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const email = `js_pk_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        let userId = null;
+        try {
+            const u = await admin.createAppUser(email, password);
+            userId = u.user_id;
+            const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/app/users/${encodeURIComponent(u.user_id)}/groups`;
+            const r = await fetch(url, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': publicKey,
+                    'X-Project-Id': e.tenantId,
+                },
+                body: JSON.stringify({ groups: [client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor')] }),
+            });
+            strict_1.default.equal(r.status, 403, 'public key on admin-write endpoint must 403');
+            const body = (await r.json());
+            strict_1.default.equal(body.reason, 'role_forbidden_public_key', `body.reason must be "role_forbidden_public_key"; got ${JSON.stringify(body)} — this is the bug the developer hit`);
+        }
+        finally {
+            if (userId)
+                await admin.deleteAppUser(userId).catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('preserve mode reproduces public-key denials that bypass mode would mask', async () => {
+        // Sanity check that the new preserve mode actually evaluates auth normally inside a test
+        // session — the whole point of E in the plan. We don't need a public API key to verify
+        // this; we just need to confirm that an unauthenticated request to an admin endpoint
+        // returns 403 (with reason) rather than being silently admined-through.
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            const sessionToken = admin.testSessionToken;
+            // Send an admin GET (/api/v1/app/auth/config) with no credentials at all under preserve mode.
+            // Under bypass mode this would be silently approved (synthesized admin). Under preserve, the
+            // AuthFilter sees no credentials and rejects.
+            const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/app/auth/config`;
+            const r = await fetch(url, {
+                method: 'GET',
+                headers: { 'X-Test-Session': sessionToken, 'X-Test-Auth': 'preserve' },
+            });
+            strict_1.default.ok(r.status === 401 || r.status === 403, `preserve mode must enforce auth; got status ${r.status} — likely regressed back to bypass`);
+            if (r.status === 403) {
+                const body = (await r.json());
+                strict_1.default.ok(body.reason && body.reason.length > 0, '403 must carry a reason');
+            }
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+});
+// Type-level sanity check: confirm the typed XCiteDBForbiddenReason union covers the reasons we
+// assert above. This costs nothing at runtime; if the reasons get renamed server-side without an
+// SDK update, this block will fail to typecheck.
+//
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function _typeFenceForReasons() {
+    const _e = new types_js_1.XCiteDBForbiddenError('Forbidden', 403);
+    // Each branch must compile.
+    const r = 'already_authenticated';
+    const r2 = 'role_forbidden_public_key';
+    const r3 = 'auth_admin_required';
+    void r;
+    void r2;
+    void r3;
+}

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, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, 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, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -502,6 +502,26 @@ export declare class XCiteDBClient {
         includeContent?: boolean;
         matchStart?: string;
     }): Promise<DiffResult>;
+    /**
+     * Compare two XML provision trees structurally + textually and write the resulting
+     * diff document — annotated with `<ins>`, `<del>`, `<moved-to>`, `<moved-from>` and
+     * `diff:<key>` metadata attributes — to the target location.
+     *
+     * The output document carries `diff:document="true"` on its root. If the target
+     * identifier already holds a regular (non-diff) document, the call returns 409
+     * `target_not_smart_diff`; existing smart-diff documents are silently overwritten.
+     */
+    smartDiff(from: SmartDiffRef, to: SmartDiffRef, target: SmartDiffRef, metadata?: Record<string, string>, options?: {
+        diffText?: boolean;
+        excludeTags?: string[];
+        maxTextDiffBytes?: number;
+        /**
+         * Hard cap (bytes) on the combined approximate size of source A + source B.
+         * The server returns 413 `smart_diff_sources_too_large` when exceeded.
+         * Defaults to 8 MiB server-side.
+         */
+        maxSourceBytes?: number;
+    }): Promise<SmartDiffResult>;
     publishWorkspace(targetWorkspace: string, sourceWorkspace: string, options?: {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';

package/dist/client.js

@@ -1566,6 +1566,30 @@ class XCiteDBClient {
         }
         return this.compare(from, to, third);
     }
+    /**
+     * Compare two XML provision trees structurally + textually and write the resulting
+     * diff document — annotated with `<ins>`, `<del>`, `<moved-to>`, `<moved-from>` and
+     * `diff:<key>` metadata attributes — to the target location.
+     *
+     * The output document carries `diff:document="true"` on its root. If the target
+     * identifier already holds a regular (non-diff) document, the call returns 409
+     * `target_not_smart_diff`; existing smart-diff documents are silently overwritten.
+     */
+    async smartDiff(from, to, target, metadata = {}, options = {}) {
+        const body = {
+            from,
+            to,
+            target,
+            metadata,
+            options: {
+                diff_text: options.diffText,
+                exclude_tags: options.excludeTags,
+                max_text_diff_bytes: options.maxTextDiffBytes,
+                max_source_bytes: options.maxSourceBytes,
+            },
+        };
+        return this.request('POST', '/api/v1/smart-diff', body);
+    }
     async publishWorkspace(targetWorkspace, sourceWorkspace, options) {
         const body = {
             source_workspace: sourceWorkspace,

package/dist/client.test.js

@@ -89,3 +89,299 @@ const types_js_1 = require("./types.js");
         }
     });
 });
+(0, node_test_1.describe)('app-user auth flows clear tokens before request', () => {
+    // The bug: a previously-logged-in client sent Authorization: Bearer <stale-token> on
+    // /app/auth/login, and the server (correctly) 403'd it as already_authenticated.
+    // SDK fix: each of login/register/oauth-exchange/custom-token clears tokens FIRST so the
+    // request goes out unauthenticated. These tests freeze that contract.
+    async function runWithMockedFetch(cb, response) {
+        const requests = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            requests.push({ url: String(input), headers: new Headers(init?.headers) });
+            return response();
+        });
+        try {
+            await cb(() => null);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+        return { requests };
+    }
+    (0, node_test_1.it)('loginAppUser drops a stale Authorization: Bearer before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                // No apiKey/accessToken — the only credential is the stale app-user token below.
+                appUserAccessToken: 'stale-jwt-from-previous-login',
+                context: { project_id: 't1' },
+            });
+            await c.loginAppUser('alice@example.com', 'pw');
+        }, () => new Response(JSON.stringify({ access_token: 'new-jwt', refresh_token: 'new-refresh', expires_in: 3600 }), { status: 200 }));
+        strict_1.default.equal(requests.length, 1);
+        strict_1.default.equal(requests[0].headers.get('Authorization'), null, 'login request must not carry the stale Bearer; otherwise server rejects with already_authenticated');
+        strict_1.default.equal(requests[0].headers.get('X-App-User-Token'), null);
+    });
+    (0, node_test_1.it)('registerAppUser drops stale tokens before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                appUserAccessToken: 'stale-jwt',
+                appUserRefreshToken: 'stale-refresh',
+                context: { project_id: 't1' },
+            });
+            await c.registerAppUser('bob@example.com', 'pw');
+        }, () => new Response(JSON.stringify({ user_id: 'u-bob', email: 'bob@example.com' }), { status: 201 }));
+        strict_1.default.equal(requests[0].headers.get('Authorization'), null);
+    });
+    (0, node_test_1.it)('exchangeOAuthCode drops stale tokens before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                appUserAccessToken: 'stale-jwt',
+                context: { project_id: 't1' },
+            });
+            await c.exchangeOAuthCode('one-time-code');
+        }, () => new Response(JSON.stringify({ access_token: 'new', refresh_token: 'r', expires_in: 3600 }), { status: 200 }));
+        strict_1.default.equal(requests[0].headers.get('Authorization'), null);
+    });
+    (0, node_test_1.it)('exchangeCustomToken drops stale tokens before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                appUserAccessToken: 'stale-jwt',
+                // Mixed with an apiKey so the request would otherwise carry both.
+                apiKey: 'pub-key',
+            });
+            await c.exchangeCustomToken('outside-jwt');
+        }, () => new Response(JSON.stringify({ access_token: 'new', refresh_token: 'r', expires_in: 3600 }), { status: 200 }));
+        // X-API-Key is still allowed; X-App-User-Token must be gone.
+        strict_1.default.equal(requests[0].headers.get('X-API-Key'), 'pub-key');
+        strict_1.default.equal(requests[0].headers.get('X-App-User-Token'), null);
+    });
+    (0, node_test_1.it)('loginAppUser stores the new tokens on success', async () => {
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => new Response(JSON.stringify({ access_token: 'new-jwt', refresh_token: 'new-refresh', expires_in: 3600 }), { status: 200 }));
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                context: { project_id: 't1' },
+            });
+            const pair = await c.loginAppUser('alice', 'pw');
+            strict_1.default.equal(pair.access_token, 'new-jwt');
+            // Side effect: token is cached for subsequent requests.
+            let captured = null;
+            globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+                captured = new Headers(init?.headers);
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await c.appUserMe();
+            strict_1.default.equal(captured.get('Authorization'), 'Bearer new-jwt');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('updateAppAuthConfig', () => {
+    (0, node_test_1.it)('PUTs the patch and returns the effective config', async () => {
+        let capturedMethod = '';
+        let capturedBody = '';
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            capturedMethod = String(init?.method ?? 'GET');
+            capturedBody = String(init?.body ?? '');
+            return new Response(JSON.stringify({
+                enabled: true,
+                registration_enabled: true,
+                default_groups: ['editor'],
+                warnings: [],
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'admin-key' });
+            const cfg = await c.updateAppAuthConfig({ default_groups: ['editor'] });
+            strict_1.default.equal(capturedMethod, 'PUT');
+            strict_1.default.match(capturedBody, /"default_groups":\["editor"\]/);
+            strict_1.default.deepEqual(cfg.default_groups, ['editor']);
+            strict_1.default.deepEqual(cfg.warnings, []);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('getAppAuthConfig surfaces default_groups_empty warning when present', async () => {
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => new Response(JSON.stringify({
+            enabled: true,
+            registration_enabled: true,
+            default_groups: [],
+            warnings: ['default_groups_empty'],
+        }), { status: 200 }));
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'admin-key' });
+            const cfg = await c.getAppAuthConfig();
+            strict_1.default.deepEqual(cfg.warnings, ['default_groups_empty']);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('createTestSession testAuth modes', () => {
+    // The legacy bypass mode lets tests pass while the matching production code path can't
+    // possibly succeed (public-key context erased). The SDK now defaults to 'required' so
+    // wet tests are production-faithful by default. These tests freeze the resolution rules.
+    function mockSessionCreate() {
+        return node_test_1.mock.fn(async () => new Response(JSON.stringify({
+            session_token: 'tok-123',
+            expires_at: Date.now() + 60000,
+            session_ttl_seconds: 60,
+        }), { status: 201 }));
+    }
+    async function captureHeadersFromFollowupRequest(create) {
+        const orig = globalThis.fetch;
+        globalThis.fetch = mockSessionCreate();
+        let client;
+        try {
+            client = await create();
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+        let captured = null;
+        const orig2 = 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 {
+            await client.health();
+        }
+        finally {
+            globalThis.fetch = orig2;
+        }
+        return captured;
+    }
+    (0, node_test_1.it)('default sends X-Test-Auth: required and keeps credentials', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'required');
+        strict_1.default.equal(h.get('X-Test-Session'), 'tok-123');
+        strict_1.default.equal(h.get('X-API-Key'), 'k', 'creds preserved in required mode');
+    });
+    (0, node_test_1.it)("testAuth: 'preserve' sends X-Test-Auth: preserve and keeps credentials", async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testAuth: 'preserve',
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'preserve');
+        strict_1.default.equal(h.get('X-API-Key'), 'k');
+    });
+    (0, node_test_1.it)("testAuth: 'bypass' omits X-Test-Auth and drops credentials", async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testAuth: 'bypass',
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), null);
+        strict_1.default.equal(h.get('X-API-Key'), null, 'bypass drops creds — server synthesizes admin');
+    });
+    (0, node_test_1.it)('legacy testRequireAuth: false maps to bypass', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testRequireAuth: false,
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), null);
+        strict_1.default.equal(h.get('X-API-Key'), null);
+    });
+    (0, node_test_1.it)('legacy testRequireAuth: true maps to required', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testRequireAuth: true,
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'required');
+        strict_1.default.equal(h.get('X-API-Key'), 'k');
+    });
+    (0, node_test_1.it)('explicit testAuth wins over legacy testRequireAuth', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testAuth: 'preserve',
+            testRequireAuth: false,
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'preserve');
+    });
+});
+(0, node_test_1.describe)('enableUserIsolation', () => {
+    (0, node_test_1.it)('with explicit config, configures prefixing without any HTTP call', async () => {
+        let calls = 0;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => {
+            calls += 1;
+            return new Response('{}', { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9' });
+            const cfg = await c.enableUserIsolation({ namespace: '/users/{userId}' });
+            strict_1.default.equal(calls, 0, 'explicit config skips the network round-trip');
+            strict_1.default.equal(cfg.enabled, true);
+            strict_1.default.equal(cfg.namespace_pattern, '/users/{userId}');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('no-arg form prefers the public endpoint', async () => {
+        let lastPath = '';
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            lastPath = String(input);
+            return new Response(JSON.stringify({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+                shared_read_paths: [],
+                shared_write_paths: [],
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'public-key' });
+            await c.enableUserIsolation();
+            strict_1.default.match(lastPath, /\/api\/v1\/security\/user-isolation\/public$/);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('falls back to admin endpoint when public 404s (older servers)', async () => {
+        const calls = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            const url = String(input);
+            calls.push(url);
+            if (url.endsWith('/public')) {
+                return new Response(JSON.stringify({ message: 'Not found' }), { status: 404 });
+            }
+            return new Response(JSON.stringify({
+                enabled: true,
+                namespace_pattern: '/spaces/${user.id}',
+                shared_read_paths: ['/public'],
+                shared_write_paths: [],
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'admin-key' });
+            const cfg = await c.enableUserIsolation();
+            strict_1.default.equal(calls.length, 2);
+            strict_1.default.match(calls[0], /\/public$/);
+            strict_1.default.ok(!calls[1].endsWith('/public'));
+            strict_1.default.deepEqual(cfg.shared_read_paths, ['/public']);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { XCiteDBClient } from './client';
 export { parseAssetUri, formatAssetUri, collectIdentifiersFromText, ASSET_URI_PREFIX } from './assetUri';
 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, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, 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, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, 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, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, 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, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -1057,6 +1057,35 @@ export interface CompareResult {
 }
 /** @deprecated Use {@link CompareResult}. */
 export type DiffResult = CompareResult;
+/**
+ * Reference to a single document version in a workspace/branch — used by `smartDiff()`
+ * to address Source A, Source B, and the Target. Supports `branch`+`date` (or `date_key`)
+ * or a `checkpoint_id`.
+ */
+export interface SmartDiffRef {
+    /** Identifier of the document or subtree. Required. */
+    identifier: string;
+    branch?: string;
+    date?: string;
+    date_key?: string;
+    checkpoint_id?: string;
+}
+export interface SmartDiffStats {
+    matched: number;
+    ins: number;
+    del: number;
+    moved_parent: number;
+    moved_order: number;
+}
+export interface SmartDiffResult {
+    status: 'ok';
+    target: {
+        identifier: string;
+        branch: string;
+        date: string;
+    };
+    stats: SmartDiffStats;
+}
 export interface PublishConflict {
     identifier: string;
     source_action: string;

package/package.json

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

package/unquery-ai-guide.md

@@ -85,6 +85,7 @@ A path selects a value from the current context.
 | `[n]` | Array index (0-based) | `"Dependants[0].FirstName"` |
 | `[expr]` | Computed index | `"Field1[$index+1]"` |
 | `[]` | Whole array (projection over all elements) | `"Array1[].Field1"` |
+| `[a:b]` | Array **slice** in a context modifier (half-open; negative counts from end) | `"scores:[0:3]"`, `"scores:[-2:]"` |
 | `/Field` | Absolute from document root | `"/employees.$(.)"` |
 | `../Field` | Up one path level (skips array indices) | `"../DBInstanceIdentifier"` |
 | `<<Field` | Read same field in *previous* document context | `"<<Field1"` after a `->$file(...)` |
@@ -259,18 +260,21 @@ Equivalent to SQL `GROUP BY bin`. Combine with aggregate values for grouped stat
 { "$(Title)": "$avg(Salary)" }
 ```
 
-### 5.4 Copy-all keys — `{}` and `{'regex'}`
+### 5.4 Copy-all keys — `{}`, `{'regex'}`, and slice `{a:b}`
 
-`{}` evaluates to *every* key in the queried object. `{'regex'}` evaluates to keys matching the regex.
+`{}` evaluates to *every* key in the queried object. `{'regex'}` evaluates to keys matching the regex. `{a:b}` is a positional **slice** of the source-key sequence (half-open, negative values count from the end) — keys are visited in their stored sort order, so this naturally gives "first K", "last K", or a middle range.
 
 ```json
 { "{}": "value" }                  // every key gets the constant 'value' (rarely useful)
 { "{}:": "." }                     // copy every key → its value (very useful)
 { "{'A.*B'}:": "." }               // copy only keys matching the regex
 { "{}:": ".?$key!='ID'" }          // copy all except ID (predicate filter)
+{ "{:3}:": "." }                   // first 3 keys (alphabetical)
+{ "{-2:}:": "." }                  // last 2 keys
+{ "{2:5}:": "." }                  // keys at positions 2..4 inclusive
 ```
 
-The trailing `:` after `{}` is a context modifier ("for each key, switch context to that key"). Without `:`, `{}` is just the empty-key spec.
+The trailing `:` after `{}` is a context modifier ("for each key, switch context to that key"). Without `:`, `{}` is just the empty-key spec. The slice form `{a:b}` mirrors the array slice `[a:b]` (see §4 path expressions and §6 context modifiers): `{:K}` is the first K, `{-K:}` the last K, `{a:b}` the half-open range.
 
 ### 5.5 Key utility functions
 
@@ -298,7 +302,9 @@ A modifier may be followed by `?cond` (predicate). Modifiers chain freely.
 | `:` (nothing after) | Repeat the key name as the path: `"Field1:"` ≡ `"Field1:Field1"` |
 | `:[]` | Iterate over each array element |
 | `:[n]` | Switch to array index `n` |
+| `:[a:b]` | Iterate over the array **slice** at indices `a..b` (half-open; negative counts from end) |
 | `:{}` | Iterate over each object field |
+| `:{a:b}` | Iterate over the object-key **slice** at positions `a..b` (half-open; negative counts from end) |
 | `:{'regex'}` | Iterate over fields matching regex |
 | `:**` | Recursive descent (every path under current) |
 | `:.` | Stay at current path (rarely needed) |
@@ -308,8 +314,18 @@ A modifier may be followed by `?cond` (predicate). Modifiers chain freely.
 { "result:Customers[]?Balance>100000:Accounts[]": ["accountNumber"] }
 { "result:{}": ["."] }
 { "#return:**": ["$key@unique_ascending"] }
+{ "first:scores[:3]": ["."] }              // first 3 elements of `scores`
+{ "tail:scores[-2:]": ["."] }              // last 2 elements
+{ "middle:scores[2:5]": ["."] }            // elements at positions 2..4
 ```
 
+**Slice semantics** (same shape for arrays and object-key iteration):
+- `[:K]` / `{:K}` — first K (start defaults to 0).
+- `[K:]` / `{K:}` — from index K to end.
+- `[a:b]` / `{a:b}` — half-open range `[a, b)`.
+- `[-K:]` / `{-K:}` — last K (negative values count from the end).
+- Out-of-range bounds are clamped; `b ≤ a` yields an empty result.
+
 ### 6.2 The `:Field` shorthand (very common)
 
 `"FirstName:"` is identical to `"FirstName:FirstName"`. Use it whenever the result key matches the source field:

package/unquery-grammar.md

@@ -151,7 +151,7 @@ Roughly in parse order:
 
 | Prefix / form | AST | Notes |
 |-----------------|-----|--------|
-| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. |
+| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. (Slice `[a:b]` form is currently parsed only on context modifiers, not in path expressions.) |
 | `$` `(` `expression` `)` | `TExprField(expr)` | Evaluate / path from dynamic name (`$()`). |
 | `$if` `(` `condition` `,` `expression` `,` `expression` `)` | `TExprITE` | |
 | `$call` `(` IDENT `)` | `TExprCall(name)` | Zero-arg user function by name. |
@@ -294,9 +294,12 @@ key ::= '$' '(' expression ')'              (* dynamic key → TQParamKey *)
      | '$' IDENT ... | '%' IDENT ...       (* whole thing parsed as expression() → TQParamKey *)
      | '{' '}'                             (* TQRegexKey empty regex *)
      | '{' QUOTED '}'                      (* TQRegexKey *)
+     | '{' slice '}'                       (* TQRegexKey + slice over source-key sequence *)
      | '#' directive
      | pathId                              (* TQSimpleKey, name may include quoted segments from pathId *)
 
+slice ::= INT? ':' INT?                    (* INT may be `-` INT for negative-from-end *)
+
 directive ::= 'if'
            | 'func' IDENT ( '(' IDENT ( ',' IDENT )* ')' )?   (* register arity; TQFuncDefinition *)
            | 'var' IDENT
@@ -336,8 +339,10 @@ Parsed **after** `key()` from the **same** JSON key string. Mode parameter `Cont
 | `->` … | `Arrow` | See §8.2 (`identifierExpression`, builtins, legacy JSON-field lookup, `->$each`); often `new_frame = true` |
 | `[` `]` | `Array` | traversal |
 | `[` INT `]` | *(string context)* | literal index path segment |
+| `[` (INT)? `:` (INT)? `]` | `Array` + slice | half-open slice; sets `array_slice_set` and the start/end fields on the `TQContextMod`. Negative ints count from end. (`-` token + INT recognized.) |
 | `.` | *(path)* | context string `"."` |
 | IDENT… `[` `]`? | `Array` if trailing `[]`, else path | Empty path + no `[` → **`Reskey`** mode |
+| IDENT… `[` slice `]` | `Array` + slice | `Field[a:b]` after a path |
 | Optional `?` `condition` after each atom | — | Wraps inner mod chain in `TQValueWithCond` |
 
 Recursion: `context_mod(...)` parses the **rest** of the chain; result wrapped in `TQContextMod` (expr or string form).