@xcitedbs/client 0.2.21 → 0.2.24

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}`;
@@ -56,6 +57,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 +609,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) {
@@ -1080,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)
@@ -1221,16 +1414,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 +1489,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 +1574,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 +1633,26 @@ 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`). 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);
+    }
     async queryDocuments(query, flags, filter, pathFilter) {
         const pq = this.isoPrefixQuery(query);
         const params = {
@@ -1727,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, 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, 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");