@xcitedbs/client 0.2.21 → 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, 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, 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;
@@ -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;
@@ -321,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>;
@@ -399,8 +420,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 +469,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 +517,36 @@ 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`). For sidebar / AST
+     * navigation, pair with {@link listIdentifierChildren} (e.g. `Promise.all` of shallow + children).
+     */
+    queryByIdentifierShallow(identifier: string, filter?: string, pathFilter?: string): Promise<string[]>;
+    /**
+     * 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}.
+     */
+    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>;
@@ -589,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. */