@xcitedbs/client 0.2.21 → 0.2.23

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, Flags, JsonDocumentBatchItem, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, 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, 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 { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -93,6 +93,12 @@ export declare class XCiteDBClient {
     private testHeaders;
     private requestHeaders;
     private request;
+    /**
+     * POST `multipart/form-data` without forcing JSON `Content-Type` (boundary is set by the runtime).
+     */
+    private requestFormPost;
+    /** GET binary response (e.g. document export); errors are parsed as JSON when possible. */
+    private requestBinaryGet;
     /** Developer Bearer refresh first, then app-user refresh (no API key refresh). */
     private tryRefreshSessionAfter401;
     private refreshAppUserNoRetry;
@@ -399,8 +405,16 @@ export declare class XCiteDBClient {
     /** @deprecated Use {@link deleteBookmark}. */
     deleteTag(name: string): Promise<void>;
     compare(from: CompareRef, to: CompareRef, includeContent?: boolean): Promise<CompareResult>;
+    compare(from: CompareRef, to: CompareRef, options?: {
+        includeContent?: boolean;
+        matchStart?: string;
+    }): Promise<CompareResult>;
     /** @deprecated Use {@link compare}. */
     diff(from: DiffRef, to: DiffRef, includeContent?: boolean): Promise<DiffResult>;
+    diff(from: DiffRef, to: DiffRef, options?: {
+        includeContent?: boolean;
+        matchStart?: string;
+    }): Promise<DiffResult>;
     publishWorkspace(targetWorkspace: string, sourceWorkspace: string, options?: {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';
@@ -440,6 +454,13 @@ export declare class XCiteDBClient {
         message?: string;
         autoResolve?: string;
     }): Promise<Record<string, unknown>>;
+    /**
+     * Advance the user workspace fork to the current parent tip (`POST /api/v1/user-workspaces/{id}/rebase`).
+     * On overlap with local edits, returns **409** with `conflicts` (same shape as publish) unless `autoResolve` resolves it.
+     */
+    rebaseUserWorkspace(id: string, options?: {
+        autoResolve?: 'none' | 'source' | 'target';
+    }): Promise<RebaseUserWorkspaceResult>;
     /**
      * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.
@@ -481,11 +502,37 @@ export declare class XCiteDBClient {
      * Rows with `error === 'lock_conflict'` include `current_lock` (code **423** per row).
      */
     writeXmlDocumentsBatch(items: XmlDocumentBatchItem[]): Promise<DocumentBatchResponse>;
+    /**
+     * Import a document (`POST /api/v1/documents/import`). Server converts DOCX, ODF, RTF, PDF, Markdown, AsciiDoc, or plain text
+     * to shredded XML. Field name must be `file` (multipart).
+     */
+    importDocument(file: Blob | ArrayBuffer | Uint8Array, options?: ImportDocumentOptions): Promise<ImportDocumentResult>;
+    /**
+     * Export a document (`GET /api/v1/documents/export`). Returns binary bytes and response metadata.
+     */
+    exportDocument(identifier: string, format?: DocumentExportFormat, options?: {
+        strict?: boolean;
+    }): Promise<ExportDocumentResult>;
     /**
      * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
      */
     writeDocumentJson(xml: string, options?: WriteDocumentOptions): Promise<void>;
     queryByIdentifier(identifier: string, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
+    /**
+     * 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.
+     */
+    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`).
+     */
+    queryByIdentifierWithChildren(identifier: string, filter?: string, pathFilter?: string): Promise<{
+        node: string[];
+        children: IdentifierChildNode[];
+    }>;
     queryDocuments(query: XCiteQuery, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
     deleteDocument(identifier: string): Promise<void>;
     addIdentifier(identifier: string): Promise<boolean>;

package/dist/client.js

@@ -56,6 +56,24 @@ function buildQuery(params) {
     const s = sp.toString();
     return s ? `?${s}` : '';
 }
+/** Best-effort filename from `Content-Disposition` (attachment; filename="…"). */
+function parseContentDispositionFilename(cd) {
+    if (!cd)
+        return undefined;
+    const mStar = cd.match(/filename\*=(?:UTF-8'')?([^;]+)/i);
+    if (mStar?.[1]) {
+        try {
+            return decodeURIComponent(mStar[1].trim().replace(/^"|"$/g, ''));
+        }
+        catch {
+            return mStar[1].trim().replace(/^"|"$/g, '');
+        }
+    }
+    const m = cd.match(/filename\s*=\s*("?)([^";]+)\1/i);
+    if (m?.[2])
+        return m[2].trim();
+    return undefined;
+}
 function warnIfHttpOnTlsPort(baseUrl) {
     try {
         const u = new URL(baseUrl);
@@ -590,6 +608,122 @@ class XCiteDBClient {
         this.notifySessionInvalidIfNeeded(path, 401);
         throw new types_1.XCiteDBError('Request failed after retry', 401, null);
     }
+    /**
+     * POST `multipart/form-data` without forcing JSON `Content-Type` (boundary is set by the runtime).
+     */
+    async requestFormPost(path, form, opts) {
+        const no401Retry = opts?.no401Retry === true;
+        const suppressTestSessionHeader = opts?.suppressTestSessionHeader === true;
+        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: 'POST', headers, body: form };
+            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) {
+                return data;
+            }
+            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(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);
+    }
+    /** GET binary response (e.g. document export); errors are parsed as JSON when possible. */
+    async requestBinaryGet(path, opts) {
+        const no401Retry = opts?.no401Retry === true;
+        const suppressTestSessionHeader = opts?.suppressTestSessionHeader === true;
+        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: 'GET', 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 buf = new Uint8Array(await res.arrayBuffer());
+                const contentType = res.headers.get('Content-Type') ?? 'application/octet-stream';
+                const fn = parseContentDispositionFilename(res.headers.get('Content-Disposition')) ?? 'export.bin';
+                const rt = res.headers.get('X-XciteDB-Export-RoundTrip');
+                const roundTrip = rt === 'exact' || rt === 'lossy' ? rt : undefined;
+                const w = res.headers.get('X-XciteDB-Export-Warning');
+                return {
+                    bytes: buf,
+                    contentType,
+                    filename: fn,
+                    ...(roundTrip ? { roundTrip } : {}),
+                    ...(w ? { warning: w } : {}),
+                };
+            }
+            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);
+    }
     /** Developer Bearer refresh first, then app-user refresh (no API key refresh). */
     async tryRefreshSessionAfter401() {
         if (this.accessToken && this.refreshToken) {
@@ -1221,16 +1355,35 @@ class XCiteDBClient {
     async deleteTag(name) {
         return this.deleteBookmark(name);
     }
-    async compare(from, to, includeContent) {
-        return this.request('POST', '/api/v1/compare', {
+    async compare(from, to, third) {
+        let include_content = false;
+        let match_start;
+        if (typeof third === 'boolean') {
+            include_content = third;
+        }
+        else if (third !== undefined && typeof third === 'object') {
+            include_content = third.includeContent ?? false;
+            match_start = third.matchStart;
+        }
+        const body = {
             from,
             to,
-            include_content: includeContent ?? false,
-        });
+            include_content,
+        };
+        if (match_start !== undefined && match_start !== '') {
+            body.match_start = this.isoPrefixId(match_start);
+        }
+        const r = await this.request('POST', '/api/v1/compare', body);
+        if (r && typeof r === 'object' && typeof r.match_start === 'string' && r.match_start.length > 0) {
+            r.match_start = this.isoUnprefixId(r.match_start);
+        }
+        return r;
     }
-    /** @deprecated Use {@link compare}. */
-    async diff(from, to, includeContent) {
-        return this.compare(from, to, includeContent);
+    async diff(from, to, third) {
+        if (third === undefined || typeof third === 'boolean') {
+            return this.compare(from, to, third);
+        }
+        return this.compare(from, to, third);
     }
     async publishWorkspace(targetWorkspace, sourceWorkspace, options) {
         const body = {
@@ -1277,6 +1430,14 @@ class XCiteDBClient {
             body.message = options.message;
         return this.request('POST', `/api/v1/user-workspaces/${encodeURIComponent(id)}/publish`, body);
     }
+    /**
+     * Advance the user workspace fork to the current parent tip (`POST /api/v1/user-workspaces/{id}/rebase`).
+     * On overlap with local edits, returns **409** with `conflicts` (same shape as publish) unless `autoResolve` resolves it.
+     */
+    async rebaseUserWorkspace(id, options) {
+        const body = { auto_resolve: options?.autoResolve ?? 'none' };
+        return this.request('POST', `/api/v1/user-workspaces/${encodeURIComponent(id)}/rebase`, body);
+    }
     /**
      * Create `workspaceName` from {@link options.fromBranch} (or current context), run `fn` scoped to that workspace,
      * create a checkpoint, then publish back unless {@link options.autoMerge} is `false`.
@@ -1354,6 +1515,49 @@ class XCiteDBClient {
         }
         return r;
     }
+    /**
+     * Import a document (`POST /api/v1/documents/import`). Server converts DOCX, ODF, RTF, PDF, Markdown, AsciiDoc, or plain text
+     * to shredded XML. Field name must be `file` (multipart).
+     */
+    async importDocument(file, options) {
+        const form = new FormData();
+        const blob = file instanceof Blob
+            ? file
+            : file instanceof ArrayBuffer
+                ? new Blob([file], { type: 'application/octet-stream' })
+                : new Blob([Uint8Array.from(file)], { type: 'application/octet-stream' });
+        const uploadName = options?.filename ??
+            (typeof File !== 'undefined' && file instanceof File ? file.name : 'upload.bin');
+        form.append('file', blob, uploadName);
+        const q = buildQuery({
+            ...(options?.identifier !== undefined && options.identifier !== ''
+                ? { identifier: this.isoPrefixId(options.identifier) }
+                : {}),
+        });
+        const r = await this.requestFormPost(`/api/v1/documents/import${q}`, form);
+        if (r && typeof r === 'object' && 'identifier' in r && typeof r.identifier === 'string') {
+            r.identifier = this.isoUnprefixId(r.identifier);
+        }
+        return r;
+    }
+    /**
+     * Export a document (`GET /api/v1/documents/export`). Returns binary bytes and response metadata.
+     */
+    async exportDocument(identifier, format = 'docx', options) {
+        const q = buildQuery({
+            identifier: this.isoPrefixId(identifier),
+            format,
+            strict: options?.strict ? '1' : undefined,
+        });
+        const r = await this.requestBinaryGet(`/api/v1/documents/export${q}`);
+        return {
+            bytes: r.bytes,
+            contentType: r.contentType,
+            filename: r.filename,
+            ...(r.roundTrip ? { roundTrip: r.roundTrip } : {}),
+            ...(r.warning ? { warning: r.warning } : {}),
+        };
+    }
     /**
      * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
      */
@@ -1370,6 +1574,28 @@ class XCiteDBClient {
         const rows = await this.request('GET', `/api/v1/documents/by-id${q}`);
         return Array.isArray(rows) ? rows.map((x) => this.isoUnprefixId(String(x))) : rows;
     }
+    /**
+     * 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.
+     */
+    async queryByIdentifierShallow(identifier, filter, pathFilter) {
+        return this.queryByIdentifier(identifier, 'NoChildren,KeepIndexNodes,FirstMatch', 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 = {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { XCiteDBClient } from './client';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, 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, 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

@@ -399,6 +399,31 @@ export interface WriteDocumentOptions {
     is_top?: boolean;
     compare_attributes?: boolean;
 }
+/** Supported source formats for `POST /api/v1/documents/import` (server detects from bytes / filename). */
+export type DocumentImportFormat = 'docx' | 'odt' | 'rtf' | 'pdf' | 'txt' | 'md' | 'adoc';
+/** JSON body on successful import (`201 Created`). */
+export interface ImportDocumentResult {
+    identifier: string;
+    section_count: number;
+    source_format: string;
+}
+export interface ImportDocumentOptions {
+    /** Override root `db:identifier`; default is `/imported/<sanitized-filename>`. */
+    identifier?: string;
+    /** Original filename (helps sniff format when `File` is not available, e.g. Node `Blob` only). */
+    filename?: string;
+}
+/** `GET /api/v1/documents/export?format=…` */
+export type DocumentExportFormat = 'xml' | 'docx' | 'odt' | 'pdf' | 'txt' | 'md' | 'adoc';
+export interface ExportDocumentResult {
+    bytes: Uint8Array;
+    contentType: string;
+    filename: string;
+    /** Present for txt/md/adoc when server sends `X-XciteDB-Export-RoundTrip`. */
+    roundTrip?: 'exact' | 'lossy';
+    /** From `X-XciteDB-Export-Warning` when present. */
+    warning?: string;
+}
 /** One row in `POST /api/v1/documents/batch` or `POST /api/v1/json-documents/batch` response `results`. */
 export interface DocumentBatchResultRow {
     index: number;
@@ -835,6 +860,8 @@ export interface CompareResult {
         date_key?: string;
     };
     total_changes: number;
+    /** Echo of request `match_start` when path-scoped compare was used. */
+    match_start?: string;
 }
 /** @deprecated Use {@link CompareResult}. */
 export type DiffResult = CompareResult;
@@ -857,6 +884,16 @@ export interface PublishResult {
 }
 /** @deprecated Use {@link PublishResult}. */
 export type MergeResult = PublishResult;
+/** `POST /api/v1/user-workspaces/{id}/rebase` */
+export interface RebaseUserWorkspaceResult {
+    status: 'completed' | 'conflicts';
+    message?: string;
+    old_from_date_key?: string;
+    new_from_date_key?: string;
+    conflicts?: PublishConflict[];
+    auto_mergeable?: string[];
+    would_expose?: string[];
+}
 export type XCiteDBErrorExtras = {
     reason?: string;
     policyId?: string;

package/llms-full.txt

@@ -35,7 +35,7 @@ Before reading the full reference, note these critical differences from typical
 - **Write at a specific date:** Set `X-Date` / `context.date` and write — every dated write is a **temporal revision**; no workspace or checkpoint required.
 - **Read as-of a date:** Set `X-Date` and read; the engine returns the revision at or before that instant.
 - **Isolated editing (draft → publish):** Create a **workspace**, edit, then **publish** to the target timeline; optional **checkpoints** for named snapshots.
-- **App-user user workspaces (`_uw/<owner>/<slug>`):** **`GET/POST /api/v1/user-workspaces`**, grants, publish — see repository **`web/src/docs/content/user-workspaces.md`**.
+- **App-user user workspaces (`_uw/<owner>/<slug>`):** **`GET/POST /api/v1/user-workspaces`**, grants, publish, **rebase** — see repository **`web/src/docs/content/user-workspaces.md`**.
 - **Audit trail:** Checkpoints carry messages and affected identifiers; **bookmarks** name a checkpoint.
 - **Undo a batch:** **Revert** to a prior checkpoint on that workspace.
 
@@ -434,6 +434,16 @@ The identifier is extracted from the `db:identifier` attribute in the root XML e
 
 Query parameters: `identifier` (required), `flags` (optional: `FirstMatch`, `IncludeChildren`, `NoChildren`, `KeepIndexNodes`), `filter`, `path_filter`.
 
+### Shallow node + subtree navigation
+
+- **`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).
+
+### 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.
+
 ## Delete document
 
 **`DELETE /api/v1/documents/by-id?identifier=/book/ch1`**
@@ -526,7 +536,7 @@ Returns `{ identifiers: string[], total, offset, limit }`.
 
 ## Export document
 
-**`GET /api/v1/documents/export?id=/book/ch1&format=...`**
+**`GET /api/v1/documents/export?identifier=/book/ch1&format=...`**
 
 ## Export provision
 
@@ -847,6 +857,22 @@ Returns `{ status: "completed"|"conflicts", checkpoint?, commit?, merged_identif
 
 ---
 
+# App-user workspaces (`/api/v1/user-workspaces`)
+
+Per-user draft branches (`_uw/<owner>/<slug>`). See also **`web/src/docs/content/user-workspaces.md`**.
+
+## Rebase user workspace
+
+**`POST /api/v1/user-workspaces/{id}/rebase`**
+
+```json
+{ "auto_resolve": "none" }
+```
+
+Advances the workspace branch fork metadata to the **current tip** of its parent branch. Returns **`200`** with `{ status: "completed", message?, old_from_date_key, new_from_date_key, would_expose[], auto_mergeable[], conflicts: [] }`, or **`409`** with `{ status: "conflicts", conflicts: [...], auto_mergeable?, would_expose? }` when the same identifiers changed on both parent and workspace since the fork (same conflict shape as workspace publish).
+
+---
+
 # Checkpoints, bookmarks & compare
 
 ## Create checkpoint
@@ -896,13 +922,16 @@ Returns `{ checkpoints: [...], commits: [...], total, branch }` (mirrors).
 {
   "from": { "branch": "", "date": "2024-01-15T00:00:00" },
   "to": { "branch": "feature-x" },
-  "include_content": true
+  "include_content": true,
+  "match_start": "/spaces/u/docs/doc1"
 }
 ```
 
+Optional **`match_start`**: when set, only identifiers equal to that path or under it (prefix + `/`) are included in **`changes`** (tenant-wide noise is dropped).
+
 (Deprecated: **`POST /api/v1/diff`**; `date_key` still accepted internally but prefer **`date`**.)
 
-Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_content?, to_content? }], total_changes }`.
+Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_content?, to_content? }], total_changes, match_start? }` ( **`match_start`** echoed when the filter was used).
 
 ---
 
@@ -1506,7 +1535,12 @@ interface DatabaseContext {
 ### XML Documents
 - `writeXmlDocument(xml, options?)` → `void` — XML via JSON body (recommended). Deprecated: `writeDocumentJson`.
 - `writeXML(xml)` → `void` — Raw XML body
+- `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[]`
+- `queryByIdentifierShallow(identifier, filter?, pathFilter?)` → `string[]` — `NoChildren,KeepIndexNodes,FirstMatch`
+- `listChildIdentifiers(parentPath?)` → `ListIdentifierChildrenResult` — alias of `listIdentifierChildren`
+- `queryByIdentifierWithChildren(identifier, filter?, pathFilter?)` → `{ node, children }`
 - `queryDocuments(query: XCiteQuery, flags?, filter?, pathFilter?)` → `string[]`
 - `deleteDocument(identifier)` → `void`
 - `listIdentifiers(query: XCiteQuery)` → `ListIdentifiersResult`
@@ -1544,6 +1578,13 @@ interface DatabaseContext {
 - `publishWorkspace(targetWorkspace, sourceWorkspace, options?)` → `PublishResult`
 - **Deprecated:** `withBranch`, `createBranch`, `listBranches`, `getBranch`, `deleteBranch`, `mergeBranch` (same HTTP behavior)
 
+### App-user user workspaces (`_uw/…`)
+- `listUserWorkspaces()` → `{ user_workspaces: unknown[] }`
+- `createUserWorkspace(name, options?)` → `Record<string, unknown>`
+- `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)`
+- `publishUserWorkspace(id, options?)` → `PublishResult`-shaped JSON
+- `rebaseUserWorkspace(id, options?)` → `RebaseUserWorkspaceResult` — advances fork onto parent tip; **409** + `conflicts` on overlap (optional `autoResolve`: `none` | `source` | `target`)
+
 ### Checkpoints
 - `createCheckpoint(message, author?)` → `CheckpointRecord`
 - `listCheckpoints(options?)` → `{ checkpoints, total, branch }` (wire JSON may also include `commits` mirror)
@@ -1560,7 +1601,7 @@ interface DatabaseContext {
 - **Deprecated:** `createTag`, `listTags`, `getTag`, `deleteTag`
 
 ### Compare
-- `compare(from: CompareRef, to: CompareRef, includeContent?)` → `CompareResult`
+- `compare(from: CompareRef, to: CompareRef, includeContent?)` or `compare(from, to, { includeContent?, matchStart? })` → `CompareResult`
 - **Deprecated:** `diff(from: DiffRef, …)` — alias of `compare`
 
 ### Locks

package/llms.txt

@@ -158,6 +158,10 @@ When you build a backend that calls XCiteDB on behalf of users:
 - **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path` (arrays are replaced in range; excess old indices cleared); **`append`** appends array elements after existing ones at `path`. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta`** or **`addMeta(..., { mode: 'append' })`**; Python/C++: **`append_meta`** or **`add_meta`** with **`mode`** / **`overwrite`** (see SDK sections below).
 - **Prefer dictionary-style objects.** **Shredded** JSON metadata is stored in **fragment-level** keys (e.g. per field name). **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
 
+## XML subtree writes (shredded model)
+
+- **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.
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -191,6 +195,11 @@ await client.writeXmlDocument(
   '<chapter db:identifier="/manual/v1/intro"><title>Introduction</title></chapter>'
 );
 
+// Import DOCX/PDF (etc.) server-side — shredded into XML (`POST /api/v1/documents/import`, multipart field `file`)
+// const fileBlob = …; // Blob from <input type="file"> or fetch
+// await client.importDocument(fileBlob, { identifier: '/manual/imported/spec', filename: 'spec.docx' });
+// const out = await client.exportDocument('/manual/imported/spec', 'docx'); // bytes in `out.bytes`
+
 // Write a JSON document
 await client.writeJsonDocument('app.settings', { theme: 'dark', locale: 'en' });
 
@@ -274,7 +283,12 @@ interface XCiteDBClientOptions {
 **XML Documents:**
 - `writeXmlDocument(xml, options?)` — Store XML via JSON body (identifier inside XML). Deprecated alias: `writeDocumentJson`.
 - `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
+- `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
 - `queryDocuments(query, flags?)` — List/filter documents
 - `deleteDocument(identifier)` — Delete by identifier
 - `listIdentifiers(query)` — List known identifiers with pagination
@@ -299,12 +313,12 @@ interface XCiteDBClientOptions {
 - `listWorkspaces()` — List workspaces
 - `publishWorkspace(target, source, options?)` — Publish workspace changes to a target timeline
 - `deleteWorkspace(name)` — Delete workspace
-- `listUserWorkspaces()` / `createUserWorkspace(name, options?)` / `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)` / `publishUserWorkspace(id, options?)` — App-user **`_uw/…`** workspaces
+- `listUserWorkspaces()` / `createUserWorkspace(name, options?)` / `getUserWorkspace(id)` / `deleteUserWorkspace(id)` / `addUserWorkspaceGrant(id, body)` / `removeUserWorkspaceGrant(id, body)` / `publishUserWorkspace(id, options?)` / `rebaseUserWorkspace(id, options?)` — App-user **`_uw/…`** workspaces (`rebase` advances the fork onto the parent tip; **409** + `conflicts` on overlap, like publish)
 - `createCheckpoint(message, author?)` — Named snapshot of current state
 - `listCheckpoints(options?)` — List checkpoints
 - `revertToCheckpoint(checkpointId)` — Revert workspace to a prior checkpoint
 - `applyCheckpoint(checkpointId, message?)` — Apply another checkpoint’s changes here
-- `compare(from, to, includeContent?)` — Compare revisions
+- `compare(from, to, includeContent?)` or `compare(from, to, { includeContent?, matchStart? })` — Compare revisions; optional **`matchStart`** restricts results to that identifier and descendants (same as document `match_start` query semantics)
 - `createBookmark(name, checkpointId, message?)` — Bookmark a checkpoint
 - `listBookmarks()` / `deleteBookmark(name)` — Manage bookmarks
 - **Deprecated aliases:** `withBranch`, `createBranch`, `listBranches`, `mergeBranch`, `deleteBranch`, `createCommit`, `listCommits`, `rollbackToCommit`, `cherryPick`, `diff`, `createTag`, `listTags`, `deleteTag` (same HTTP behavior)
@@ -369,6 +383,8 @@ When calling `queryByIdentifier` or `queryDocuments`, the `flags` parameter cont
 - `'NoChildren'` — Exclude children
 - `'KeepIndexNodes'` — Include index/structural nodes
 
+**Sidebar / AST navigation:** combine **`'NoChildren,KeepIndexNodes,FirstMatch'`** (or `queryByIdentifierShallow`) with **`listChildIdentifiers`** / **`listIdentifierChildren`** so each expansion is one shallow XML read plus one child list, instead of `IncludeChildren` loading the entire subtree.
+
 ### Errors
 
 All API errors throw `XCiteDBError` with `.status` (HTTP code) and `.body` (parsed response). Common codes: `401` unauthenticated, `403` forbidden by policy or RBAC, `404` not found, `409` conflict (lock), `422` validation, `423` project encrypted and locked, `429` rate limited. Many **ABAC** denials return `403` with `"message":"Forbidden"` plus optional **`policy_id`** and **`hint`** (check JWT `tenant_id` vs `project:` group middle segment).

package/package.json

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