@xcitedbs/client 0.2.23 → 0.2.24

package/dist/assetUri.d.ts

@@ -0,0 +1,14 @@
+/** URI prefix for asset identifiers embedded in documents (`xcitedb:asset:/path/...`). */
+export declare const ASSET_URI_PREFIX: "xcitedb:asset:";
+/**
+ * Parses `xcitedb:asset:<identifier>` where identifier must start with `/`.
+ * Percent-decodes the path portion then normalizes slashes.
+ */
+export declare function parseAssetUri(s: string): string | null;
+/** Build `xcitedb:asset:<identifier>`; identifier must begin with `/` after normalization. */
+export declare function formatAssetUri(identifier: string): string;
+/**
+ * Scan arbitrary text for `xcitedb:asset:` paths (GC / reference discovery).
+ * Paths are normalized the same way as {@link parseAssetUri} would accept.
+ */
+export declare function collectIdentifiersFromText(text: string, out: Set<string>): void;

package/dist/assetUri.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASSET_URI_PREFIX = void 0;
+exports.parseAssetUri = parseAssetUri;
+exports.formatAssetUri = formatAssetUri;
+exports.collectIdentifiersFromText = collectIdentifiersFromText;
+/** URI prefix for asset identifiers embedded in documents (`xcitedb:asset:/path/...`). */
+exports.ASSET_URI_PREFIX = 'xcitedb:asset:';
+function isPchar(c) {
+    if ((c >= 0x41 && c <= 0x5a) || (c >= 0x61 && c <= 0x7a) || (c >= 0x30 && c <= 0x39)) {
+        return true;
+    }
+    switch (c) {
+        case 0x2d: // -
+        case 0x2e: // .
+        case 0x5f: // _
+        case 0x7e: // ~
+        case 0x25: // %
+        case 0x3a: // :
+        case 0x40: // @
+        case 0x21: // !
+        case 0x24: // $
+        case 0x26: // &
+        case 0x27: // '
+        case 0x28: // (
+        case 0x29: // )
+        case 0x2a: // *
+        case 0x2b: // +
+        case 0x2c: // ,
+        case 0x3b: // ;
+        case 0x3d: // =
+            return true;
+        default:
+            return false;
+    }
+}
+/** Normalize path: collapse slashes, ensure leading `/`. */
+function normalizeIdentifierPath(p) {
+    let s = p.trim().replace(/\/+/g, '/');
+    if (!s.startsWith('/')) {
+        s = `/${s}`;
+    }
+    return s;
+}
+/**
+ * Parses `xcitedb:asset:<identifier>` where identifier must start with `/`.
+ * Percent-decodes the path portion then normalizes slashes.
+ */
+function parseAssetUri(s) {
+    const t = s.trim();
+    if (!t.startsWith(exports.ASSET_URI_PREFIX)) {
+        return null;
+    }
+    let rest = t.slice(exports.ASSET_URI_PREFIX.length);
+    if (!rest.startsWith('/')) {
+        return null;
+    }
+    try {
+        rest = decodeURIComponent(rest);
+    }
+    catch {
+        return null;
+    }
+    const id = normalizeIdentifierPath(rest);
+    if (id === '/' || id.length < 2) {
+        return null;
+    }
+    return id;
+}
+/** Build `xcitedb:asset:<identifier>`; identifier must begin with `/` after normalization. */
+function formatAssetUri(identifier) {
+    const id = normalizeIdentifierPath(identifier);
+    if (id === '/' || !id.startsWith('/')) {
+        throw new Error('formatAssetUri: identifier must be a non-root absolute path');
+    }
+    return `${exports.ASSET_URI_PREFIX}${id}`;
+}
+/**
+ * Scan arbitrary text for `xcitedb:asset:` paths (GC / reference discovery).
+ * Paths are normalized the same way as {@link parseAssetUri} would accept.
+ */
+function collectIdentifiersFromText(text, out) {
+    const p = exports.ASSET_URI_PREFIX;
+    let pos = 0;
+    while (pos < text.length) {
+        const f = text.indexOf(p, pos);
+        if (f < 0) {
+            break;
+        }
+        let i = f + p.length;
+        if (i >= text.length || text.charCodeAt(i) !== 0x2f) {
+            pos = f + 1;
+            continue;
+        }
+        let j = i;
+        while (j < text.length) {
+            const c = text.charCodeAt(j);
+            if (c === 0x2f || isPchar(c)) {
+                j += 1;
+                continue;
+            }
+            break;
+        }
+        if (j > i) {
+            const raw = text.slice(i, j);
+            try {
+                const decoded = decodeURIComponent(raw);
+                const id = normalizeIdentifierPath(decoded);
+                if (id.length > 1) {
+                    out.add(id);
+                }
+            }
+            catch {
+                // skip malformed percent-encoding
+            }
+        }
+        pos = j;
+    }
+}

package/dist/assetUri.test.d.ts

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

package/dist/assetUri.test.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const assetUri_1 = require("./assetUri");
+(0, node_test_1.default)('parseAssetUri accepts xcitedb:asset path', () => {
+    strict_1.default.equal((0, assetUri_1.parseAssetUri)(`${assetUri_1.ASSET_URI_PREFIX}/users/u1/assets/a.png`), '/users/u1/assets/a.png');
+});
+(0, node_test_1.default)('formatAssetUri round-trip', () => {
+    const id = '/assets/photos/x';
+    strict_1.default.equal((0, assetUri_1.parseAssetUri)((0, assetUri_1.formatAssetUri)(id)), id);
+});
+(0, node_test_1.default)('collectIdentifiersFromText', () => {
+    const s = new Set();
+    (0, assetUri_1.collectIdentifiersFromText)(`see ${assetUri_1.ASSET_URI_PREFIX}/a/b and done`, s);
+    strict_1.default.ok(s.has('/a/b'));
+});

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, IdentifierChildNode, 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, 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, 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, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, 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;
@@ -327,6 +327,21 @@ export declare class XCiteDBClient {
      * When {@link XCiteDBClient.enableUserIsolation} / `userIsolation` is active, `identifier` is prefixed like other document APIs.
      */
     createUserIsolationShare(params: UserIsolationCreateShareParams): Promise<UserIsolationShareResult>;
+    /** Share an asset path via prefix alias (`POST /api/v1/security/user-isolation/asset-shares`). */
+    createAssetShare(params: AssetShareRequest): Promise<UserIsolationShareResult>;
+    /** Remove an asset share (`DELETE /api/v1/security/user-isolation/asset-shares`). */
+    deleteAssetShare(params: AssetUnshareRequest): Promise<void>;
+    /** List incoming/public asset share aliases (`GET /api/v1/security/user-isolation/asset-shares`). */
+    listAssetShares(opts?: {
+        direction?: 'incoming' | 'outgoing' | 'public';
+        scope?: string;
+    }): Promise<AssetShareListResponse>;
+    /** Issue a time-limited magic link for one asset identifier (`POST /api/v1/security/asset-magic-links`). */
+    createAssetMagicLink(body: CreateAssetMagicLinkRequest): Promise<AssetMagicLinkResult>;
+    /** List issued magic links (no secrets) (`GET /api/v1/security/asset-magic-links`). */
+    listAssetMagicLinks(): Promise<AssetMagicLinkListResponse>;
+    /** Revoke a magic link (`DELETE /api/v1/security/asset-magic-links/{token_id}`). */
+    revokeAssetMagicLink(tokenId: string): Promise<void>;
     createWorkspace(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
     /** @deprecated Use {@link createWorkspace}. */
     createBranch(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
@@ -520,19 +535,18 @@ export declare class XCiteDBClient {
     queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
     /**
      * Shallow read: root element with inline leaves plus `db:N*` placeholders for shredded child slots
-     * (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`). Use with {@link listChildIdentifiers}
-     * or {@link queryByIdentifierWithChildren} for sidebar / AST navigation without loading the full subtree.
+     * (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`). For sidebar / AST
+     * navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
      */
     queryByIdentifierShallow(identifier: string, filter?: string, pathFilter?: string): Promise<string[]>;
-    /** Alias of {@link listIdentifierChildren} — immediate child segments under `parentPath` (identifier hierarchy). */
-    listChildIdentifiers(parentPath?: string): Promise<ListIdentifierChildrenResult>;
     /**
-     * Parallel shallow node + one level of identifier children (`GET /by-id` + `GET /identifier-children`).
+     * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
+     * Use this for editor round-trips. For navigation without loading the full subtree, use
+     * {@link queryByIdentifierShallow} plus {@link listIdentifierChildren}.
      */
-    queryByIdentifierWithChildren(identifier: string, filter?: string, pathFilter?: string): Promise<{
-        node: string[];
-        children: IdentifierChildNode[];
-    }>;
+    queryByIdentifierFull(identifier: string, filter?: string, pathFilter?: string): 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[]>;
     deleteDocument(identifier: string): Promise<void>;
     addIdentifier(identifier: string): Promise<boolean>;
@@ -636,6 +650,38 @@ export declare class XCiteDBClient {
     }): Promise<ProjectDocConfResponse>;
     /** Remove project override; server uses platform default (`DELETE /api/v1/project/settings/doc-conf`). */
     deleteProjectDocConf(): Promise<ProjectDocConfResponse>;
+    /** Admin: asset storage v2 (`GET /api/v1/project/settings/asset-storage`). */
+    getProjectAssetStorage(): Promise<ProjectAssetStorageConfig>;
+    /** Admin: save asset storage v2 (`PUT /api/v1/project/settings/asset-storage`). */
+    updateProjectAssetStorage(body: ProjectAssetStorageConfig): Promise<ProjectAssetStorageConfig>;
+    private resolveAssetIdentifier;
+    /** URL path under `/api/v1/assets/…` with per-segment encoding. */
+    private assetRequestPath;
+    private assetQuerySuffix;
+    /**
+     * Upload raw bytes (`POST /api/v1/assets`). Returns canonical `identifier` and `xcitedb:asset:…` `uri`.
+     */
+    uploadAsset(bytes: Blob | ArrayBuffer | Uint8Array, opts: UploadAssetOptions): Promise<AssetUploadResult>;
+    /**
+     * Download asset bytes (`GET /api/v1/assets/…`). Follows `302` to presigned S3 URLs.
+     * Pass `ml` for magic-link access (same token as `Authorization: MagicLink …` when not using cookies).
+     */
+    getAsset(uriOrIdentifier: string, opts?: {
+        ifNoneMatch?: string;
+        ml?: string;
+    }): Promise<Blob>;
+    /** Delete an asset (`DELETE /api/v1/assets/…`). */
+    deleteAsset(uriOrIdentifier: string, opts?: {
+        ml?: string;
+    }): Promise<void>;
+    /** `HEAD /api/v1/assets/…` — metadata only. */
+    headAsset(uriOrIdentifier: string, opts?: {
+        ml?: string;
+    }): Promise<AssetHeadResult>;
+    /** Admin: GC dry-run — manifest vs live meta references (`POST /api/v1/admin/assets/gc/dry-run`). */
+    adminAssetsGcDryRun(opts?: {
+        ownerUserId?: string;
+    }): Promise<AssetGcDryRunResult>;
     /** Embedded platform default `document.conf` text (`GET /api/v1/platform/default-doc-conf`). */
     getPlatformDefaultDocConf(): Promise<PlatformDefaultDocConfResponse>;
     /** Blocking full DB scan (admin; no calls to embedding API). Prefer {@link postVectorIndexEstimateSession} for UI. */

package/dist/client.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.XCiteDBClient = void 0;
 const types_1 = require("./types");
 const websocket_1 = require("./websocket");
+const assetUri_1 = require("./assetUri");
 function joinUrl(base, path) {
     const b = base.replace(/\/+$/, '');
     const p = path.startsWith('/') ? path : `/${path}`;
@@ -1214,6 +1215,64 @@ class XCiteDBClient {
             mode: params.mode,
         });
     }
+    /** Share an asset path via prefix alias (`POST /api/v1/security/user-isolation/asset-shares`). */
+    async createAssetShare(params) {
+        const body = {
+            target_user_id: params.target_user_id,
+            mode: params.mode,
+        };
+        if (params.source_uri !== undefined && params.source_uri !== '') {
+            body.source_uri = params.source_uri;
+        }
+        else if (params.identifier !== undefined && params.identifier !== '') {
+            body.identifier = this.isoPrefixId(params.identifier);
+        }
+        else {
+            throw new types_1.XCiteDBError('createAssetShare requires identifier or source_uri', 400, null);
+        }
+        return this.request('POST', '/api/v1/security/user-isolation/asset-shares', body);
+    }
+    /** Remove an asset share (`DELETE /api/v1/security/user-isolation/asset-shares`). */
+    async deleteAssetShare(params) {
+        const body = {};
+        if (params.source_uri !== undefined && params.source_uri !== '') {
+            body.source_uri = params.source_uri;
+        }
+        else if (params.identifier !== undefined && params.identifier !== '') {
+            body.identifier = this.isoPrefixId(params.identifier);
+        }
+        else {
+            throw new types_1.XCiteDBError('deleteAssetShare requires identifier or source_uri', 400, null);
+        }
+        if (params.target_user_id !== undefined) {
+            body.target_user_id = params.target_user_id;
+        }
+        if (params.sharer_user_id !== undefined) {
+            body.sharer_user_id = params.sharer_user_id;
+        }
+        await this.request('DELETE', '/api/v1/security/user-isolation/asset-shares', body);
+    }
+    /** List incoming/public asset share aliases (`GET /api/v1/security/user-isolation/asset-shares`). */
+    async listAssetShares(opts) {
+        const q = buildQuery({
+            direction: opts?.direction ?? 'incoming',
+            ...(opts?.scope ? { scope: opts.scope } : {}),
+        });
+        return this.request('GET', `/api/v1/security/user-isolation/asset-shares${q}`);
+    }
+    /** Issue a time-limited magic link for one asset identifier (`POST /api/v1/security/asset-magic-links`). */
+    async createAssetMagicLink(body) {
+        return this.request('POST', '/api/v1/security/asset-magic-links', body);
+    }
+    /** List issued magic links (no secrets) (`GET /api/v1/security/asset-magic-links`). */
+    async listAssetMagicLinks() {
+        return this.request('GET', '/api/v1/security/asset-magic-links');
+    }
+    /** Revoke a magic link (`DELETE /api/v1/security/asset-magic-links/{token_id}`). */
+    async revokeAssetMagicLink(tokenId) {
+        const id = encodeURIComponent(tokenId.trim());
+        await this.request('DELETE', `/api/v1/security/asset-magic-links/${id}`);
+    }
     async createWorkspace(name, fromBranch, fromDate) {
         const body = { name };
         if (fromBranch)
@@ -1576,26 +1635,24 @@ class XCiteDBClient {
     }
     /**
      * Shallow read: root element with inline leaves plus `db:N*` placeholders for shredded child slots
-     * (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`). Use with {@link listChildIdentifiers}
-     * or {@link queryByIdentifierWithChildren} for sidebar / AST navigation without loading the full subtree.
+     * (`flags=NoChildren,KeepIndexNodes,FirstMatch` on `GET /api/v1/documents/by-id`). 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);
     }
+    /**
+     * Load a document with all shredded children inlined (`FirstMatch,IncludeChildren` on `GET /by-id`).
+     * 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);
+    }
     /** Alias of {@link listIdentifierChildren} — immediate child segments under `parentPath` (identifier hierarchy). */
     async listChildIdentifiers(parentPath) {
         return this.listIdentifierChildren(parentPath);
     }
-    /**
-     * Parallel shallow node + one level of identifier children (`GET /by-id` + `GET /identifier-children`).
-     */
-    async queryByIdentifierWithChildren(identifier, filter, pathFilter) {
-        const [node, listed] = await Promise.all([
-            this.queryByIdentifierShallow(identifier, filter, pathFilter),
-            this.listIdentifierChildren(identifier),
-        ]);
-        return { node, children: listed.children };
-    }
     async queryDocuments(query, flags, filter, pathFilter) {
         const pq = this.isoPrefixQuery(query);
         const params = {
@@ -1953,6 +2010,260 @@ class XCiteDBClient {
     async deleteProjectDocConf() {
         return this.request('DELETE', '/api/v1/project/settings/doc-conf');
     }
+    /** Admin: asset storage v2 (`GET /api/v1/project/settings/asset-storage`). */
+    async getProjectAssetStorage() {
+        return this.request('GET', '/api/v1/project/settings/asset-storage');
+    }
+    /** Admin: save asset storage v2 (`PUT /api/v1/project/settings/asset-storage`). */
+    async updateProjectAssetStorage(body) {
+        return this.request('PUT', '/api/v1/project/settings/asset-storage', body);
+    }
+    resolveAssetIdentifier(uriOrIdentifier) {
+        const trimmed = uriOrIdentifier.trim();
+        const fromUri = (0, assetUri_1.parseAssetUri)(trimmed);
+        if (fromUri) {
+            return this.canonicalId(fromUri);
+        }
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(trimmed)) {
+            return `/assets/${trimmed.toLowerCase()}`;
+        }
+        return this.canonicalId(trimmed);
+    }
+    /** URL path under `/api/v1/assets/…` with per-segment encoding. */
+    assetRequestPath(uriOrIdentifier) {
+        const id = this.resolveAssetIdentifier(uriOrIdentifier);
+        const segments = id.split('/').filter((s) => s.length > 0).map((s) => encodeURIComponent(s));
+        return `/api/v1/assets/${segments.join('/')}`;
+    }
+    assetQuerySuffix(opts) {
+        const ml = opts?.ml?.trim();
+        if (!ml) {
+            return '';
+        }
+        return `?ml=${encodeURIComponent(ml)}`;
+    }
+    /**
+     * Upload raw bytes (`POST /api/v1/assets`). Returns canonical `identifier` and `xcitedb:asset:…` `uri`.
+     */
+    async uploadAsset(bytes, opts) {
+        let bodyBytes;
+        if (bytes instanceof Blob) {
+            bodyBytes = await bytes.arrayBuffer();
+        }
+        else if (bytes instanceof ArrayBuffer) {
+            bodyBytes = bytes;
+        }
+        else {
+            bodyBytes = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        }
+        const ct = opts.contentType.trim() || 'application/octet-stream';
+        const qParts = [];
+        if (opts.scope === 'public') {
+            qParts.push('scope=public');
+        }
+        if (opts.identifier !== undefined && opts.identifier !== '') {
+            qParts.push(`identifier=${encodeURIComponent(opts.identifier)}`);
+        }
+        const q = qParts.length ? `?${qParts.join('&')}` : '';
+        const no401Retry = false;
+        const suppressTestSessionHeader = false;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const url = joinUrl(this.baseUrl, `/api/v1/assets${q}`);
+            const outgoingRequestId = newClientRequestId();
+            const headers = {
+                ...this.authHeaders(),
+                ...this.contextHeaders(),
+                ...(suppressTestSessionHeader ? {} : this.testHeaders()),
+                'X-Request-Id': outgoingRequestId,
+                'Content-Type': ct,
+            };
+            const init = { method: 'POST', headers, body: bodyBytes };
+            const sig = requestTimeoutSignal(this.requestTimeoutMs);
+            if (sig)
+                init.signal = sig;
+            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 {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                data = text;
+            }
+            if (res.ok) {
+                if (!data || typeof data !== 'object') {
+                    throw new types_1.XCiteDBError('Invalid asset upload response', res.status, data);
+                }
+                const o = data;
+                const identifier = typeof o.identifier === 'string' ? o.identifier : '';
+                const uri = typeof o.uri === 'string' ? o.uri : '';
+                if (!identifier || !uri) {
+                    throw new types_1.XCiteDBError('Invalid asset upload response', res.status, data);
+                }
+                const out = { identifier, uri };
+                if (typeof o.target_name === 'string')
+                    out.target_name = o.target_name;
+                if (typeof o.content_type === 'string')
+                    out.content_type = o.content_type;
+                if (typeof o.size === 'number')
+                    out.size = o.size;
+                if (typeof o.sha256 === 'string')
+                    out.sha256 = o.sha256;
+                if (typeof o.etag === 'string')
+                    out.etag = o.etag;
+                return out;
+            }
+            if (res.status === 401 &&
+                attempt === 0 &&
+                !no401Retry &&
+                (await this.tryRefreshSessionAfter401())) {
+                continue;
+            }
+            const msg = typeof data === 'object' && data !== null && 'message' in data
+                ? String(data.message)
+                : res.statusText;
+            this.notifySessionInvalidIfNeeded('/api/v1/assets', res.status);
+            throwForFailedHttp(res.status, '/api/v1/assets', data, msg || `HTTP ${res.status}`, res.headers.get('X-Request-Id') ?? undefined, res.headers.get('X-Client-Request-Id') ?? undefined);
+        }
+        this.notifySessionInvalidIfNeeded('/api/v1/assets', 401);
+        throw new types_1.XCiteDBError('Request failed after retry', 401, null);
+    }
+    /**
+     * Download asset bytes (`GET /api/v1/assets/…`). Follows `302` to presigned S3 URLs.
+     * Pass `ml` for magic-link access (same token as `Authorization: MagicLink …` when not using cookies).
+     */
+    async getAsset(uriOrIdentifier, opts) {
+        const path = `${this.assetRequestPath(uriOrIdentifier)}${this.assetQuerySuffix({ ml: opts?.ml })}`;
+        const no401Retry = false;
+        const suppressTestSessionHeader = false;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const url = joinUrl(this.baseUrl, path);
+            const outgoingRequestId = newClientRequestId();
+            const headers = {
+                ...this.authHeaders(),
+                ...this.contextHeaders(),
+                ...(suppressTestSessionHeader ? {} : this.testHeaders()),
+                'X-Request-Id': outgoingRequestId,
+            };
+            if (opts?.ifNoneMatch) {
+                headers['If-None-Match'] = opts.ifNoneMatch;
+            }
+            const init = { method: 'GET', headers, redirect: 'follow' };
+            const sig = requestTimeoutSignal(this.requestTimeoutMs);
+            if (sig)
+                init.signal = sig;
+            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 });
+            }
+            if (res.status === 304) {
+                return new Blob();
+            }
+            if (res.ok) {
+                return await res.blob();
+            }
+            if (res.status === 401 &&
+                attempt === 0 &&
+                !no401Retry &&
+                (await this.tryRefreshSessionAfter401())) {
+                continue;
+            }
+            const text = await res.text();
+            let data;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                data = text;
+            }
+            const msg = typeof data === 'object' && data !== null && 'message' in data
+                ? String(data.message)
+                : res.statusText;
+            this.notifySessionInvalidIfNeeded(path, res.status);
+            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);
+    }
+    /** Delete an asset (`DELETE /api/v1/assets/…`). */
+    async deleteAsset(uriOrIdentifier, opts) {
+        const path = `${this.assetRequestPath(uriOrIdentifier)}${this.assetQuerySuffix({ ml: opts?.ml })}`;
+        await this.request('DELETE', path);
+    }
+    /** `HEAD /api/v1/assets/…` — metadata only. */
+    async headAsset(uriOrIdentifier, opts) {
+        const path = `${this.assetRequestPath(uriOrIdentifier)}${this.assetQuerySuffix({ ml: opts?.ml })}`;
+        const no401Retry = false;
+        const suppressTestSessionHeader = false;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const url = joinUrl(this.baseUrl, path);
+            const outgoingRequestId = newClientRequestId();
+            const headers = {
+                ...this.authHeaders(),
+                ...this.contextHeaders(),
+                ...(suppressTestSessionHeader ? {} : this.testHeaders()),
+                'X-Request-Id': outgoingRequestId,
+            };
+            const init = { method: 'HEAD', headers };
+            const sig = requestTimeoutSignal(this.requestTimeoutMs);
+            if (sig)
+                init.signal = sig;
+            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 });
+            }
+            if (res.ok) {
+                const etagRaw = res.headers.get('ETag') ?? undefined;
+                const ct = res.headers.get('Content-Type') ?? 'application/octet-stream';
+                const len = res.headers.get('Content-Length');
+                const size = len ? parseInt(len, 10) : 0;
+                return { contentType: ct, size: Number.isFinite(size) ? size : 0, etag: etagRaw };
+            }
+            if (res.status === 401 &&
+                attempt === 0 &&
+                !no401Retry &&
+                (await this.tryRefreshSessionAfter401())) {
+                continue;
+            }
+            const text = await res.text();
+            let data;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                data = text;
+            }
+            const msg = typeof data === 'object' && data !== null && 'message' in data
+                ? String(data.message)
+                : res.statusText;
+            this.notifySessionInvalidIfNeeded(path, res.status);
+            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);
+    }
+    /** Admin: GC dry-run — manifest vs live meta references (`POST /api/v1/admin/assets/gc/dry-run`). */
+    async adminAssetsGcDryRun(opts) {
+        const q = opts?.ownerUserId && opts.ownerUserId.trim()
+            ? `?owner=${encodeURIComponent(opts.ownerUserId.trim())}`
+            : '';
+        return this.request('POST', `/api/v1/admin/assets/gc/dry-run${q}`, {});
+    }
     /** Embedded platform default `document.conf` text (`GET /api/v1/platform/default-doc-conf`). */
     async getPlatformDefaultDocConf() {
         return this.request('GET', '/api/v1/platform/default-doc-conf');

package/dist/index.d.ts

@@ -1,4 +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, 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, 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, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, 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/index.js

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

package/dist/types.d.ts

@@ -170,6 +170,125 @@ export interface ProjectDocConfResponse {
     has_project_override: boolean;
     doc_conf_text: string | null;
 }
+/** `POST /api/v1/assets` success body (`201`). */
+export interface AssetUploadResult {
+    identifier: string;
+    uri: string;
+    target_name?: string;
+    content_type?: string;
+    size?: number;
+    sha256?: string;
+    etag?: string;
+}
+/** Options for {@link XCiteDBClient.uploadAsset}. */
+export interface UploadAssetOptions {
+    contentType: string;
+    /** When set (with default scope), uploaded to this path after user-isolation prefixing rules on the server. */
+    identifier?: string;
+    /** `public` writes under `/public/assets/…`. Default project/user scope when omitted. */
+    scope?: 'project' | 'public';
+}
+/** Result of {@link XCiteDBClient.headAsset}. */
+export interface AssetHeadResult {
+    contentType: string;
+    size: number;
+    etag?: string;
+}
+/** `POST /api/v1/admin/assets/gc/dry-run` (admin). */
+export interface AssetGcDryRunResult {
+    manifest_count: number;
+    referenced_asset_count: number;
+    orphan_count: number;
+    orphan_sample: string[];
+}
+export type AssetStorageTargetType = 'internal' | 's3';
+/** One named storage target in `asset_storage_v2` (`GET/PUT /api/v1/project/settings/asset-storage`). */
+export interface AssetStorageTarget {
+    type: AssetStorageTargetType;
+    writable?: boolean;
+    s3_endpoint_url?: string;
+    s3_bucket?: string;
+    s3_region?: string;
+    access_key_id?: string;
+    /** On GET, redacted as `***` when set. */
+    secret_access_key?: string;
+    small_file_threshold_bytes?: number;
+    redirect_threshold_bytes?: number;
+    import_head_cache_ttl_seconds?: number;
+    [key: string]: unknown;
+}
+export interface AssetStorageMount {
+    path: string;
+    target: string;
+    key_template: string;
+}
+export interface AssetStorageImport {
+    path: string;
+    target: string;
+    key: string;
+    tree?: boolean;
+    content_type?: string;
+}
+/** Project asset storage v2 (`GET/PUT /api/v1/project/settings/asset-storage`). */
+export interface ProjectAssetStorageConfig {
+    targets: Record<string, AssetStorageTarget>;
+    mounts: AssetStorageMount[];
+    imports: AssetStorageImport[];
+}
+/** Body for `POST /api/v1/security/user-isolation/asset-shares`. */
+export interface AssetShareRequest {
+    /** Canonical or app-relative asset path (subject to user-isolation prefixing when enabled). */
+    identifier?: string;
+    /** `xcitedb:asset:/…` or raw `/…` path; not prefixed by the client. */
+    source_uri?: string;
+    target_user_id: string;
+    mode: UserIsolationShareMode;
+}
+/** Body for `DELETE /api/v1/security/user-isolation/asset-shares`. */
+export interface AssetUnshareRequest {
+    identifier?: string;
+    source_uri?: string;
+    target_user_id?: string;
+    sharer_user_id?: string;
+}
+export interface AssetShareListEntry {
+    identifier: string;
+    mode: string;
+}
+/** `GET /api/v1/security/user-isolation/asset-shares` */
+export interface AssetShareListResponse {
+    direction: string;
+    identifiers: AssetShareListEntry[];
+    scope?: string;
+    note?: string;
+}
+/** `POST /api/v1/security/asset-magic-links` */
+export interface CreateAssetMagicLinkRequest {
+    source_uri: string;
+    actions: ('read' | 'write')[];
+    expires_in_seconds: number;
+    max_uses?: number;
+}
+export interface AssetMagicLinkResult {
+    token: string;
+    token_id?: string;
+    expires_at: string;
+    link_url: string;
+}
+export interface AssetMagicLinkRecord {
+    token_id: string;
+    identifier: string;
+    actions?: unknown;
+    issued_by_user_id?: string;
+    issued_at?: string;
+    expires_at?: string;
+    max_uses?: number;
+    uses?: number;
+    revoked?: boolean;
+}
+export interface AssetMagicLinkListResponse {
+    tokens: AssetMagicLinkRecord[];
+}
 /** `GET /api/v1/platform/default-doc-conf` */
 export interface PlatformDefaultDocConfResponse {
     doc_conf_text: string;
@@ -429,6 +548,11 @@ export interface DocumentBatchResultRow {
     index: number;
     identifier: string;
     ok: boolean;
+    /**
+     * When `ok` is false, server batch precheck / write reason. Includes:
+     * `duplicate_identifier_in_batch` (409), `parent_inlines_batch_member` (409),
+     * `lock_conflict` (423), and other parse/policy strings.
+     */
     error?: string;
     code?: number;
     /** Present when `error === 'lock_conflict'` (HTTP-style code 423 in batch row). */

package/llms-full.txt

@@ -12,7 +12,7 @@ Before reading the full reference, note these critical differences from typical
 
 2. **Identifiers are hierarchical, path-like strings** — e.g. `/us/bills/hr1`, `/manual/v2/chapter3`. They are NOT auto-generated UUIDs. The leading `/` is part of the identifier. Parent/child relationships are derived from the path structure.
 
-3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type. JSON documents are a parallel store. Both are fully versioned.
+3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type. JSON documents are a parallel store. Both are fully versioned. **Binary files** use the separate **assets** subsystem (not document shredding): canonical paths like `/assets/<uuid>`, stable **`xcitedb:asset:/…`** URIs, **`POST` / `GET` / `HEAD` / `DELETE /api/v1/assets/…`**, project **`asset-storage` v2** config, optional user-isolation **asset-shares**, and **asset magic links** (`?ml=`).
 
 4. **Context (workspace + date) travels as HTTP headers** (`X-Workspace` preferred, `X-Branch` alias, `X-Date`, and optionally `X-Unversioned` for explicit flat writes), not URL path segments.
 
@@ -28,7 +28,9 @@ Before reading the full reference, note these critical differences from typical
 
 10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. With a default body (omit or `{}`), the test LMDB starts **empty** (no cloned production project config).
 
-11. **Overlay test sessions.** Same **`POST`**, with JSON **`{"overlay":true}`**, while authenticated for the **project to debug** (project-scoped API key, or platform Bearer + **`X-Project-Id`**). The session metadata records overlay mode; subsequent requests need only **`X-Test-Session`**. The server opens **`XCiteDB(_test/<uuid>/data, <production data path>)`**: production is used as a **read-only base**; reads merge overlay + base; **writes never modify production**. If the production data directory is missing, opening the session database fails. JS **`createTestSession({ …, overlay: true })`**, C++ **`test_session_overlay`** + **`create_test_session`**, MCP **`create_test_session`** tool **`overlay: true`**.
+11. **Overlay test sessions.** Same **`POST`**, with JSON **`{"overlay":true}`**, while authenticated for the **project to debug** (project-scoped API key, or platform Bearer + **`X-Project-Id`**). The session metadata records overlay mode; subsequent requests need only **`X-Test-Session`**. The server opens **`XCiteDB(_test/<uuid>/data, <production data path>)`**: production is used as a **read-only base**; reads merge overlay + base; **writes never modify production**. If the production data directory is missing, opening the session database fails. JS **`createTestSession({ …, overlay: true })`**, C++ **`test_session_overlay`** + **`create_test_session`**, MCP **`create_test_session`** tool **`overlay: true`**. **Locks:** cooperative lock metadata is read from the **base** layer as well as the overlay, but lock acquire/release only affects the overlay—so **`lock_conflict`** during overlay tests can reflect a lock still held in production; use **`findLocks` / `forceReleaseLock`** on your paths or a non-overlay session when testing locks.
+
+12. **SDK asset helpers.** JavaScript: `uploadAsset`, `getAsset`, `headAsset`, `deleteAsset`, `resolveAssetIdentifier`, `formatAssetUri`, `collectIdentifiersFromText`, plus `createAssetShare` / `createAssetMagicLink` and related APIs. Python: `upload_asset`, `get_asset`, `head_asset`, `xcitedb.asset_uri`. C++: `xcitedb/asset_uri.hpp`, `XCiteDBClient::upload_asset`, `get_asset_raw`, `head_asset_raw`, `delete_asset`, and security helpers mirroring the other SDKs.
 
 ## Choosing the Right Versioning Approach
 
@@ -63,6 +65,8 @@ Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain
 
 7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real LMDB under `_test/<uuid>/` (empty by default, or **overlay** on read-only production with **`{"overlay":true}`** / **`overlay: true`** / **`test_session_overlay`**). See "Ephemeral test sessions" below.
 
+8. **Identifier strings (minting).** The engine rejects identifiers containing byte **`0x01`**. The API canonicalizes hierarchical paths (**leading `/`**, **no trailing `/`**). Reserved namespaces include **`/_xcitedb/`**, **`/assets/`**, **`/public/assets/`**, and **`/public/shared/<tenant>/assets/`**. **`identifier_hierarchy_max_depth`** (default **4**) tunes hierarchy indexing; deeper paths still work but **`GET …/identifier-children`** may scan.
+
 ---
 
 # Part 1: Product Overview
@@ -438,12 +442,53 @@ Query parameters: `identifier` (required), `flags` (optional: `FirstMatch`, `Inc
 
 - **`flags=NoChildren,KeepIndexNodes,FirstMatch`**: returns the matching node with inline leaf content plus **`db:N1`**, **`db:N2`**, … placeholders for shredded child slots (avoids loading the full deep subtree in one response).
 - Combine with **`GET /api/v1/documents/identifier-children?parent_path=…`** for the next level of hierarchy (`segment`, `full_path`, `is_identifier`, `has_children`).
-- **JavaScript SDK:** `queryByIdentifierShallow(id)`, `listChildIdentifiers(parentPath?)`, `queryByIdentifierWithChildren(id)` (shallow XML + children in parallel).
+- **JavaScript SDK:** `queryByIdentifierFull(id)` loads **`FirstMatch,IncludeChildren`** for editor round-trips; **`queryByIdentifierShallow(id)`** + **`listChildIdentifiers(id)`** (e.g. `Promise.all` client-side) for sidebar / tree expansion.
 
 ### Standalone subtree write (shredded model)
 
 You may `POST /api/v1/documents` with a root element whose `db:identifier` is a nested path (e.g. `/spaces/u/docs/doc1/sec-1`) without re-posting the parent document: the engine writes that subtree only and updates the identifier hierarchy index for the parent automatically. Keep `is_top: true` (default) on the write.
 
+### XML shredding semantics (must read)
+
+- **Auto-shred.** Any element with **`db:identifier`** is stored as its own LMDB row. The parent’s stored XML keeps a **`<db:N…/>`** placeholder for that slot. There is **no** size threshold and **no** opt-out.
+- **`is_top` is a marker only.** It registers a **`TOP:<xcitepath>`** alias for tooling; it does **not** change shredding, merge, or overwrite behavior.
+- **Batch ordering.** **`POST /api/v1/documents/batch`** processes **`items[]`** **sequentially**. Each item’s XML is shredded so **every** `db:identifier` in that payload becomes (or overwrites) its own row. Precheck returns per-row **`409`**: **`duplicate_identifier_in_batch`** when the same canonical root id appears in more than one item (the **later** row is rejected), and **`parent_inlines_batch_member`** when one item’s XML still contains **full** markup for another item’s **root** id in the same batch (prevents silently overwriting a fresher child row with a stale parent).
+- **Save the smallest dirty subtree.** Do not include live descendant XML for ids you also flush as standalone batch rows; use placeholders from a shallow read when you must touch the parent in the same request.
+
+**Round-trip:** Element structure, child order, and text are preserved. The server may add **`db:order`**, **`db:xcitepath`**, **`xmlns:db`**. Attribute order and insignificant whitespace are **not** byte-stable—compare by DOM, not raw bytes.
+
+### Batch XML writes
+
+**`POST /api/v1/documents/batch`** — JSON body **`{ "items": [ { "xml": "<…>", "is_top": true, "compare_attributes": false, "identifier": "/optional/match" }, … ] }`**. Response **`200`** with **`{ "results": [ { "index", "ok", "identifier", "error"?, "code"?, "current_lock"? } ] }`** (best-effort: later rows still run when earlier rows fail). JavaScript: **`writeXmlDocumentsBatch`**. Python: **`write_xml_documents_batch`**. C++: **`write_xml_documents_batch`**.
+
+### Minimal SPA editor recipe
+
+```typescript
+await client.enableUserIsolation();
+client.setContext({ workspace: '', project_id: projectId });
+
+async function loadDocForEditor(id: string) {
+  return client.queryByIdentifierFull(id);
+}
+
+async function sidebarRow(id: string) {
+  const [node, listed] = await Promise.all([
+    client.queryByIdentifierShallow(id),
+    client.listIdentifierChildren(id),
+  ]);
+  return { node, children: listed.children };
+}
+
+async function saveDirty(items: XmlDocumentBatchItem[]) {
+  const { results } = await client.writeXmlDocumentsBatch(items);
+  results.forEach((r, i) => {
+    if (!r.ok) console.warn(i, r.error, r.code);
+  });
+}
+```
+
+**Save rules:** (1) At most **one** batch item per flush may use a given root **`db:identifier`**. (2) Never ship a parent that **inlines** another item’s root id in the same batch. (3) **`is_top`** does not relax (1) or (2).
+
 ## Delete document
 
 **`DELETE /api/v1/documents/by-id?identifier=/book/ch1`**
@@ -1538,9 +1583,10 @@ interface DatabaseContext {
 - `importDocument(file, options?)` → `ImportDocumentResult` — multipart `POST /api/v1/documents/import`
 - `exportDocument(identifier, format?, options?)` → `ExportDocumentResult` — binary `GET /api/v1/documents/export`
 - `queryByIdentifier(identifier, flags?, filter?, pathFilter?)` → `string[]`
+- `queryByIdentifierFull(identifier, filter?, pathFilter?)` → `string[]` — `FirstMatch,IncludeChildren` (editor load)
 - `queryByIdentifierShallow(identifier, filter?, pathFilter?)` → `string[]` — `NoChildren,KeepIndexNodes,FirstMatch`
 - `listChildIdentifiers(parentPath?)` → `ListIdentifierChildrenResult` — alias of `listIdentifierChildren`
-- `queryByIdentifierWithChildren(identifier, filter?, pathFilter?)` → `{ node, children }`
+- `writeXmlDocumentsBatch(items)` → `DocumentBatchResponse` — `POST /api/v1/documents/batch` (per-row `409`: `duplicate_identifier_in_batch`, `parent_inlines_batch_member`)
 - `queryDocuments(query: XCiteQuery, flags?, filter?, pathFilter?)` → `string[]`
 - `deleteDocument(identifier)` → `void`
 - `listIdentifiers(query: XCiteQuery)` → `ListIdentifiersResult`

package/llms.txt

@@ -22,7 +22,9 @@ These are the most common sources of confusion for developers and AI assistants:
 
 8. **Project vs tenant id.** In the SDK, prefer `context.project_id` (and `listMyProjects` / `switchProject`). Many JSON bodies and JWT claims still use the field name `tenant_id` for the same value — the client sends that wire name automatically.
 
-9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). By default the test LMDB starts **empty** (no production data). **Overlay mode:** same **`POST`** with JSON body **`{"overlay":true}`** (while authenticated for the project you want to inspect—project-scoped API key, or platform Bearer + **`X-Project-Id`**). The server opens a **writable** LMDB under `_test/<uuid>/` with that project’s on-disk store as a **read-only base** (dual LMDB): reads see production + overlay deltas; **writes never touch production**. **`XCiteDBClient.createTestSession({ …, overlay: true })`** sends that body. After creation, only **`X-Test-Session`** is required on requests (overlay is stored in session metadata).
+9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). By default the test LMDB starts **empty** (no production data). **Overlay mode:** same **`POST`** with JSON body **`{"overlay":true}`** (while authenticated for the project you want to inspect—project-scoped API key, or platform Bearer + **`X-Project-Id`**). The server opens a **writable** LMDB under `_test/<uuid>/` with that project’s on-disk store as a **read-only base** (dual LMDB): reads see production + overlay deltas; **writes never touch production**. **`XCiteDBClient.createTestSession({ …, overlay: true })`** sends that body. After creation, only **`X-Test-Session`** is required on requests (overlay is stored in session metadata). **Overlay + locks:** cooperative locks are stored in LMDB meta; overlay sessions **read through** to **base-layer** locks, but **`acquireLock` / `releaseLock`** only mutate the overlay—so a `lock_conflict` in an overlay test can still mean a lock held in production; clear with **`findLocks`** / **`forceReleaseLock`** or use a non-overlay session for lock-sensitive tests.
+
+10. **Binary assets (v2) are not XML/JSON documents.** Files live under canonical asset identifiers (e.g. `/assets/<uuid>`) and stable **`xcitedb:asset:/…`** URIs. **`POST /api/v1/assets`** uploads raw bytes; **`GET` / `HEAD` / `DELETE /api/v1/assets/…`** use per-segment URL encoding (optional **`?ml=`** magic-link bearer). Project routing is **`GET/PUT /api/v1/project/settings/asset-storage`** (`targets`, `mounts`, `imports`). User-isolation **asset-shares** and **asset magic links** live under **`/api/v1/security/user-isolation/asset-shares`** and **`/api/v1/security/asset-magic-links`**. JS/Python/C++ SDKs expose upload/get/head/delete + URI helpers (`parseAssetUri`, `asset_uri.parse`, `asset_uri::parse`) and share/magic-link clients.
 
 ## Choosing the Right Versioning Approach
 
@@ -72,6 +74,8 @@ Legacy REST paths (`/api/v1/branches`, `/commits`, `/tags`, `/diff`) remain as *
 
 12. **`X-Date` / `context.date` is not “server clock only.”** Revisions are keyed by the **instant you send**, not an implicit “now” when you set the header. To record a document under a **business date** (published, approved, effective), set **`X-Date`** or **`context.date`** to that instant before writing. Omitting **`X-Date`** does **not** substitute the current time on the write path — it selects **flat** writes (see convention 4).
 
+13. **Identifier strings (minting).** The engine rejects identifiers containing byte **`0x01`** (LMDB key separator). The API canonicalizes paths (**leading `/`**, **no trailing `/`**). Reserved namespaces include **`/_xcitedb/`**, **`/assets/`**, **`/public/assets/`**, and **`/public/shared/<tenant>/assets/`**. Server config **`identifier_hierarchy_max_depth`** defaults to **4**—deeper paths still work, but **`identifier-children`** listing may fall back to a scan.
+
 ## API key capability matrix (typical)
 
 | Capability | API key `role` | Public key allowed? |
@@ -162,6 +166,46 @@ When you build a backend that calls XCiteDB on behalf of users:
 
 - **Standalone subtree root.** Because XCiteDB shreds XML per identifier, you can `writeXmlDocument('<sec db:identifier="/spaces/u/docs/doc1/sec-1">…</sec>')` and the engine writes only that subtree — you do **not** need to re-send the parent document. The parent's children index (`id_hier`) is updated automatically. Keep `is_top: true` (default) on `POST /api/v1/documents` even when the `db:identifier` is nested under another path. Use `compare_attributes: true` only when you need attribute-level diffing for triggers.
 
+## XML shredding semantics (must read)
+
+- **Auto-shred.** Any element with **`db:identifier`** is stored as its own LMDB row. The parent’s stored XML keeps a **`<db:N…/>`** placeholder for that slot. There is **no** size threshold and **no** opt-out.
+- **`is_top` is a marker only.** It registers a **`TOP:<xcitepath>`** alias for tooling; it does **not** change shredding, merge, or overwrite behavior. Leaving **`true`** on every write is normal.
+- **`POST /api/v1/documents/batch`** runs items **in order**; each item’s write replaces LMDB rows for **every** `db:identifier` present in that item’s XML. The server prechecks each row and may return **`409`** with **`duplicate_identifier_in_batch`** (same root id in two items) or **`parent_inlines_batch_member`** (a parent’s XML still contains another item’s root id—a stale inlined child). Check **`results[i].ok`** on the JSON response.
+- **Save the smallest dirty subtree.** Do not flush a parent that still contains full XML for an identified child you also write in the same batch. Prefer placeholders from **`queryByIdentifierShallow`**, or write only the changed child documents.
+
+**Round-trip:** Element structure, child order, and text are preserved. The server may add **`db:order`**, **`db:xcitepath`**, **`xmlns:db`**. Attribute order and insignificant whitespace are **not** byte-stable—compare by DOM, not raw bytes.
+
+## Minimal SPA editor recipe
+
+```typescript
+await client.enableUserIsolation(); // if app users edit under namespaced paths
+client.setContext({ workspace: '', project_id: projectId });
+
+/** Full document for the editor (all shredded children inlined). */
+async function loadDocForEditor(id: string) {
+  return client.queryByIdentifierFull(id);
+  // same as: queryByIdentifier(id, 'FirstMatch,IncludeChildren')
+}
+
+/** Sidebar / tree: shallow shell + one hierarchy level (two parallel requests). */
+async function sidebarRow(id: string) {
+  const [node, listed] = await Promise.all([
+    client.queryByIdentifierShallow(id),
+    client.listIdentifierChildren(id),
+  ]);
+  return { node, children: listed.children };
+}
+
+async function saveDirty(items: XmlDocumentBatchItem[]) {
+  const { results } = await client.writeXmlDocumentsBatch(items);
+  results.forEach((r, i) => {
+    if (!r.ok) console.warn(i, r.error, r.code);
+  });
+}
+```
+
+**Three save rules:** (1) Each intended root **`db:identifier`** appears as the **root** of **at most one** batch item per flush. (2) Never ship a parent’s **full** subtree for a child id that is also its **own** batch row in the same request. (3) **`is_top`** does not relax (1) or (2).
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -282,13 +326,14 @@ interface XCiteDBClientOptions {
 
 **XML Documents:**
 - `writeXmlDocument(xml, options?)` — Store XML via JSON body (identifier inside XML). Deprecated alias: `writeDocumentJson`.
+- `writeXmlDocumentsBatch(items)` — `POST /api/v1/documents/batch`; per-row `ok` / `error` / `code` (see shredding section for `409` batch conflicts)
 - `writeXML(xml)` — Store raw XML with `Content-Type: application/xml`
 - `importDocument(file, options?)` — `POST /api/v1/documents/import` (multipart `file`). Server converts DOCX, ODF, RTF, PDF, Markdown, AsciiDoc, or plain text into shredded XML. Optional `identifier` query override; optional `filename` for sniffing when not a `File`.
 - `exportDocument(id, format?, options?)` — `GET /api/v1/documents/export` binary (`xml` | `docx` | `odt` | `pdf` | `txt` | `md` | `adoc`). Optional `strict` for text exports.
 - `queryByIdentifier(id, flags?, filter?)` — Get document(s) by identifier
+- `queryByIdentifierFull(id, filter?, pathFilter?)` — Same as `flags=FirstMatch,IncludeChildren` (editor load: full subtree)
 - `queryByIdentifierShallow(id, filter?, pathFilter?)` — Same as `flags=NoChildren,KeepIndexNodes,FirstMatch` (skeleton: placeholders `db:N*` for shredded slots; avoids full subtree)
-- `listChildIdentifiers(parentPath?)` — Alias of `listIdentifierChildren`; next level of identifier hierarchy
-- `queryByIdentifierWithChildren(id, filter?, pathFilter?)` — `Promise.all` of shallow node + `identifier-children` for one expansion step
+- `listChildIdentifiers(parentPath?)` — Alias of `listIdentifierChildren`; next level of identifier hierarchy (pair with `queryByIdentifierShallow` for sidebars—`Promise.all` both if you want one round-trip client-side)
 - `queryDocuments(query, flags?)` — List/filter documents
 - `deleteDocument(identifier)` — Delete by identifier
 - `listIdentifiers(query)` — List known identifiers with pagination

package/package.json

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

package/unquery-ai-guide.md

@@ -4,6 +4,8 @@
 
 Unquery is a declarative language for querying and transforming structured documents (JSON and XML). It is the query language of XCiteDB and the `unq` command-line tool. Every query is itself a JSON document. The result is also JSON.
 
+> **Maintainers — parse regression tests:** Fenced `json` / `text` examples in this file, plus Unquery listings in [`web/src/docs/content/unquery-tutorial.html`](../web/src/docs/content/unquery-tutorial.html), feed the generated fixture [`XCiteDB2/tests/fixtures/unquery_tutorial_parse_cases.json`](../XCiteDB2/tests/fixtures/unquery_tutorial_parse_cases.json) (do not edit by hand). After changing examples here or in that HTML file, regenerate from the repo root with `python3 scripts/gen_unquery_tutorial_parse_cases.py`, then commit the updated JSON. CI / local builds run `unquery_tutorial_parse_test` (see [`XCiteDB2/tests/run_tests.sh`](../XCiteDB2/tests/run_tests.sh)).
+
 ---
 
 ## 0. AI preamble — must-read before writing a query