@xcitedbs/client 0.1.0

package/dist/client.js

@@ -0,0 +1,894 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XCiteDBClient = void 0;
+const types_1 = require("./types");
+const websocket_1 = require("./websocket");
+function joinUrl(base, path) {
+    const b = base.replace(/\/+$/, '');
+    const p = path.startsWith('/') ? path : `/${path}`;
+    return `${b}${p}`;
+}
+function buildQuery(params) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+        if (v === undefined || v === '')
+            continue;
+        sp.set(k, String(v));
+    }
+    const s = sp.toString();
+    return s ? `?${s}` : '';
+}
+class XCiteDBClient {
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.accessToken = options.accessToken;
+        this.appUserAccessToken = options.appUserAccessToken;
+        this.appUserRefreshToken = options.appUserRefreshToken;
+        this.defaultContext = options.context ?? {};
+        this.platformConsole = options.platformConsole === true;
+        this.projectId = options.projectId;
+        this.onSessionTokensUpdated = options.onSessionTokensUpdated;
+        this.onAppUserTokensUpdated = options.onAppUserTokensUpdated;
+        this.onSessionInvalid = options.onSessionInvalid;
+    }
+    /** True if this client would send API key or Bearer credentials on a normal request. */
+    sentAuthCredentials() {
+        return !!(this.apiKey || this.accessToken || this.appUserAccessToken);
+    }
+    /** 401 on these paths is an expected auth flow outcome, not a dead session. */
+    isSessionInvalidExcludedPath(path) {
+        const base = path.includes('?') ? path.slice(0, path.indexOf('?')) : path;
+        switch (base) {
+            case '/api/v1/platform/auth/login':
+            case '/api/v1/platform/auth/register':
+            case '/api/v1/platform/auth/refresh':
+            case '/api/v1/platform/auth/change-password':
+            case '/api/v1/app/auth/login':
+            case '/api/v1/app/auth/register':
+            case '/api/v1/app/auth/refresh':
+            case '/api/v1/app/auth/oauth/exchange':
+            case '/api/v1/app/auth/change-password':
+                return true;
+            default:
+                return false;
+        }
+    }
+    notifySessionInvalidIfNeeded(path, status) {
+        if (status !== 401)
+            return;
+        if (!this.sentAuthCredentials())
+            return;
+        if (this.isSessionInvalidExcludedPath(path))
+            return;
+        this.onSessionInvalid?.();
+    }
+    /** Use platform console JWT routes (`/api/v1/platform/auth/*`) for this client instance. */
+    setPlatformConsole(enabled) {
+        this.platformConsole = enabled;
+    }
+    get isPlatformConsole() {
+        return this.platformConsole;
+    }
+    /** Sets active project for platform console mode (`X-Project-Id`). */
+    setProjectId(projectId) {
+        this.projectId = projectId;
+    }
+    setContext(ctx) {
+        this.defaultContext = { ...this.defaultContext, ...ctx };
+    }
+    setTokens(access, refresh) {
+        this.accessToken = access;
+        if (refresh !== undefined)
+            this.refreshToken = refresh;
+    }
+    /** End-user (app) tokens. With developer `accessToken`/`apiKey`, sent as `X-App-User-Token`. */
+    setAppUserTokens(access, refresh) {
+        this.appUserAccessToken = access;
+        if (refresh !== undefined)
+            this.appUserRefreshToken = refresh;
+    }
+    clearAppUserTokens() {
+        this.appUserAccessToken = undefined;
+        this.appUserRefreshToken = undefined;
+    }
+    contextHeaders() {
+        const h = {};
+        const c = this.defaultContext;
+        if (c.branch)
+            h['X-Branch'] = c.branch;
+        if (c.date)
+            h['X-Date'] = c.date;
+        if (c.prefix)
+            h['X-Prefix'] = c.prefix;
+        return h;
+    }
+    /** Include `tenant_id` for public app-auth routes when using only app-user tokens (no developer key/JWT). */
+    mergeAppTenant(body) {
+        const tid = this.defaultContext.tenant_id;
+        if (tid)
+            return { ...body, tenant_id: tid };
+        return body;
+    }
+    authHeaders() {
+        const h = {};
+        if (this.apiKey) {
+            h['X-API-Key'] = this.apiKey;
+            if (this.appUserAccessToken)
+                h['X-App-User-Token'] = this.appUserAccessToken;
+        }
+        else if (this.accessToken) {
+            h['Authorization'] = `Bearer ${this.accessToken}`;
+            if (this.appUserAccessToken)
+                h['X-App-User-Token'] = this.appUserAccessToken;
+        }
+        else if (this.appUserAccessToken) {
+            h['Authorization'] = `Bearer ${this.appUserAccessToken}`;
+        }
+        if (this.platformConsole && this.projectId) {
+            h['X-Project-Id'] = this.projectId;
+        }
+        return h;
+    }
+    async request(method, path, body, extraHeaders, opts) {
+        const no401Retry = opts?.no401Retry === true;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const url = joinUrl(this.baseUrl, path);
+            const headers = {
+                ...this.authHeaders(),
+                ...this.contextHeaders(),
+                ...extraHeaders,
+            };
+            let init = { method, headers };
+            if (body !== undefined) {
+                if (typeof body === 'string') {
+                    init.body = body;
+                }
+                else {
+                    headers['Content-Type'] = 'application/json';
+                    init.body = JSON.stringify(body);
+                }
+            }
+            const res = await fetch(url, init);
+            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);
+            throw new types_1.XCiteDBError(msg || `HTTP ${res.status}`, res.status, data);
+        }
+        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) {
+            try {
+                await this.refresh();
+                return true;
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        if (!this.apiKey && this.appUserAccessToken && this.appUserRefreshToken) {
+            try {
+                await this.refreshAppUserNoRetry();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+        return false;
+    }
+    async refreshAppUserNoRetry() {
+        if (!this.appUserRefreshToken)
+            throw new Error('No app user refresh token');
+        const pair = await this.request('POST', '/api/v1/app/auth/refresh', this.mergeAppTenant({ refresh_token: this.appUserRefreshToken }), undefined, { no401Retry: true });
+        this.appUserAccessToken = pair.access_token;
+        this.appUserRefreshToken = pair.refresh_token;
+        this.onAppUserTokensUpdated?.(pair);
+        return pair;
+    }
+    async health() {
+        return this.request('GET', '/api/v1/health');
+    }
+    async version() {
+        return this.request('GET', '/api/v1/version');
+    }
+    /**
+     * Platform console sign-in. The first argument is the account **email** (e.g. `admin@localhost`).
+     * Legacy `/api/v1/auth/login` has been removed.
+     */
+    async login(email, password) {
+        return this.platformLogin(email, password);
+    }
+    /** Platform console sign-in (`email` + `password`). Project context is `X-Project-Id`, not the JWT. */
+    async platformLogin(email, password) {
+        const pair = await this.request('POST', '/api/v1/platform/auth/login', { email, password });
+        this.accessToken = pair.access_token;
+        this.refreshToken = pair.refresh_token;
+        return pair;
+    }
+    async refresh() {
+        if (!this.refreshToken)
+            throw new Error('No refresh token');
+        const pair = await this.request('POST', '/api/v1/platform/auth/refresh', {
+            refresh_token: this.refreshToken,
+        }, undefined, { no401Retry: true });
+        this.accessToken = pair.access_token;
+        this.refreshToken = pair.refresh_token;
+        this.onSessionTokensUpdated?.(pair);
+        return pair;
+    }
+    async logout() {
+        await this.request('POST', '/api/v1/platform/auth/logout', {
+            refresh_token: this.refreshToken,
+        });
+        this.accessToken = undefined;
+        this.refreshToken = undefined;
+    }
+    async me() {
+        return this.request('GET', '/api/v1/platform/auth/me');
+    }
+    async platformRegistrationConfig() {
+        return this.request('GET', '/api/v1/platform/auth/registration-config');
+    }
+    async platformRegister(body) {
+        return this.request('POST', '/api/v1/platform/auth/register', body);
+    }
+    async platformWorkspaces() {
+        return this.request('GET', '/api/v1/platform/auth/workspaces');
+    }
+    async listMyTenants() {
+        const w = await this.platformWorkspaces();
+        const tenants = (w.projects ?? []).map((p) => {
+            const r = p;
+            return {
+                tenant_id: r.tenant_id || r.project_id || '',
+                org_id: r.org_id,
+                name: r.name,
+                status: r.status,
+                created_at: r.created_at,
+                updated_at: r.updated_at,
+                config: r.config,
+                owner_user_id: r.owner_user_id,
+            };
+        });
+        if (this.platformConsole && !this.projectId && tenants.length > 0 && tenants[0].tenant_id) {
+            this.projectId = tenants[0].tenant_id;
+        }
+        return tenants;
+    }
+    /** Alias for {@link listMyTenants} (organization/project terminology). */
+    async listMyProjects() {
+        return this.listMyTenants();
+    }
+    /**
+     * Switch active tenant/project for API calls. Platform console: updates `X-Project-Id` only (no token exchange).
+     * Legacy `/api/v1/auth/switch-tenant` has been removed; non-platform callers should set context instead.
+     */
+    async switchTenant(tenantId) {
+        if (this.platformConsole) {
+            this.projectId = tenantId;
+            return;
+        }
+        throw new types_1.XCiteDBError('switchTenant is only supported for platform console clients; set context.tenant_id / use app-user tenant instead', 410, null);
+    }
+    /** Alias for {@link switchTenant}. */
+    async switchProject(projectId) {
+        return this.switchTenant(projectId);
+    }
+    async listApiKeys() {
+        return this.request('GET', '/api/v1/project/keys');
+    }
+    async createApiKey(name, expiresAt = 0, keyType = 'secret') {
+        return this.request('POST', '/api/v1/project/keys', {
+            name,
+            expires_at: expiresAt,
+            key_type: keyType,
+        });
+    }
+    async changePassword(currentPassword, newPassword) {
+        await this.request('POST', '/api/v1/platform/auth/change-password', {
+            current_password: currentPassword,
+            new_password: newPassword,
+        });
+    }
+    async revokeApiKey(keyId) {
+        await this.request('DELETE', `/api/v1/project/keys/${encodeURIComponent(keyId)}`);
+    }
+    // --- App user auth (requires developer API key or JWT on the same tenant) ---
+    async registerAppUser(email, password, displayName, groups, attributes) {
+        const body = { email, password };
+        if (displayName !== undefined)
+            body.display_name = displayName;
+        if (groups !== undefined)
+            body.groups = groups;
+        if (attributes !== undefined)
+            body.attributes = attributes;
+        return this.request('POST', '/api/v1/app/auth/register', this.mergeAppTenant(body));
+    }
+    async getOAuthProviders() {
+        const tid = this.defaultContext.tenant_id;
+        const q = buildQuery({ tenant_id: tid && String(tid).length > 0 ? String(tid) : 'default' });
+        return this.request('GET', `/api/v1/app/auth/oauth/providers${q}`);
+    }
+    /** Relative path + query for browser navigation to start OAuth (append to API base URL). */
+    oauthAuthorizePath(provider) {
+        const tid = this.defaultContext.tenant_id && String(this.defaultContext.tenant_id).length > 0
+            ? String(this.defaultContext.tenant_id)
+            : 'default';
+        return `/api/v1/app/auth/oauth/${encodeURIComponent(provider)}/authorize${buildQuery({ tenant_id: tid })}`;
+    }
+    /** Exchange one-time session code from OAuth browser redirect (public + tenant_id). */
+    async exchangeOAuthCode(code) {
+        const pair = await this.request('POST', '/api/v1/app/auth/oauth/exchange', this.mergeAppTenant({ code }));
+        this.appUserAccessToken = pair.access_token;
+        this.appUserRefreshToken = pair.refresh_token;
+        return pair;
+    }
+    async loginAppUser(email, password) {
+        const pair = await this.request('POST', '/api/v1/app/auth/login', this.mergeAppTenant({ email, password }));
+        this.appUserAccessToken = pair.access_token;
+        this.appUserRefreshToken = pair.refresh_token;
+        return pair;
+    }
+    async refreshAppUser() {
+        return this.refreshAppUserNoRetry();
+    }
+    async logoutAppUser() {
+        await this.request('POST', '/api/v1/app/auth/logout', this.mergeAppTenant({ refresh_token: this.appUserRefreshToken }));
+        this.appUserAccessToken = undefined;
+        this.appUserRefreshToken = undefined;
+    }
+    async appUserMe() {
+        return this.request('GET', '/api/v1/app/auth/me');
+    }
+    async updateAppUserProfile(displayName, attributes) {
+        const body = {};
+        if (displayName !== undefined)
+            body.display_name = displayName;
+        if (attributes !== undefined)
+            body.attributes = attributes;
+        return this.request('PUT', '/api/v1/app/auth/me', body);
+    }
+    async exchangeCustomToken(token) {
+        const pair = await this.request('POST', '/api/v1/app/auth/custom-token', { token });
+        this.appUserAccessToken = pair.access_token;
+        this.appUserRefreshToken = pair.refresh_token;
+        return pair;
+    }
+    /** Change app-user password (requires valid app-user access token). */
+    async changeAppUserPassword(currentPassword, newPassword) {
+        await this.request('POST', '/api/v1/app/auth/change-password', {
+            current_password: currentPassword,
+            new_password: newPassword,
+        });
+    }
+    /** Request a password-reset token (developer-authenticated). Token omitted when delivery is smtp/webhook success. */
+    async forgotAppUserPassword(email) {
+        return this.request('POST', '/api/v1/app/auth/forgot-password', { email });
+    }
+    /** Complete password reset with token from `forgotAppUserPassword` (public; set `context.tenant_id` if no developer auth). */
+    async resetAppUserPassword(token, newPassword) {
+        await this.request('POST', '/api/v1/app/auth/reset-password', this.mergeAppTenant({ token, new_password: newPassword }));
+    }
+    /** Issue email verification token (developer-authenticated). Token omitted when delivery is smtp/webhook success. */
+    async sendAppUserVerification(userId) {
+        return this.request('POST', '/api/v1/app/auth/send-verification', {
+            user_id: userId,
+        });
+    }
+    async getAppAuthConfig() {
+        return this.request('GET', '/api/v1/app/auth/config');
+    }
+    async getEmailConfig() {
+        return this.request('GET', '/api/v1/app/email/config');
+    }
+    async updateEmailConfig(config) {
+        return this.request('PUT', '/api/v1/app/email/config', config);
+    }
+    async getEmailTemplates() {
+        return this.request('GET', '/api/v1/app/email/templates');
+    }
+    async updateEmailTemplates(templates) {
+        return this.request('PUT', '/api/v1/app/email/templates', templates);
+    }
+    async sendTestEmail(to) {
+        return this.request('POST', '/api/v1/app/email/test', { to });
+    }
+    /** Verify email with token (public; set `context.tenant_id` if no developer auth). */
+    async verifyAppUserEmail(token) {
+        await this.request('POST', '/api/v1/app/auth/verify-email', this.mergeAppTenant({ token }));
+    }
+    // --- App user management (developer admin/editor) ---
+    async listAppUsers() {
+        return this.request('GET', '/api/v1/app/users');
+    }
+    async getAppUser(userId) {
+        return this.request('GET', `/api/v1/app/users/${encodeURIComponent(userId)}`);
+    }
+    async createAppUser(email, password, displayName, groups, attributes) {
+        const body = { email, password };
+        if (displayName !== undefined)
+            body.display_name = displayName;
+        if (groups !== undefined)
+            body.groups = groups;
+        if (attributes !== undefined)
+            body.attributes = attributes;
+        return this.request('POST', '/api/v1/app/users', body);
+    }
+    async deleteAppUser(userId) {
+        await this.request('DELETE', `/api/v1/app/users/${encodeURIComponent(userId)}`);
+    }
+    async updateAppUserGroups(userId, groups) {
+        await this.request('PUT', `/api/v1/app/users/${encodeURIComponent(userId)}/groups`, { groups });
+    }
+    async updateAppUserStatus(userId, status) {
+        await this.request('PUT', `/api/v1/app/users/${encodeURIComponent(userId)}/status`, { status });
+    }
+    // --- Security policies (developer admin/editor) ---
+    async createPolicy(policyId, policy) {
+        return this.request('POST', '/api/v1/security/policies', {
+            policy_id: policyId,
+            policy,
+        });
+    }
+    async listPolicies() {
+        const r = await this.request('GET', '/api/v1/security/policies');
+        if (r == null || typeof r !== 'object' || Array.isArray(r))
+            return {};
+        return r;
+    }
+    async getPolicy(policyId) {
+        return this.request('GET', `/api/v1/security/policies/${encodeURIComponent(policyId)}`);
+    }
+    async updatePolicy(policyId, policy) {
+        return this.request('PUT', `/api/v1/security/policies/${encodeURIComponent(policyId)}`, policy);
+    }
+    async deletePolicy(policyId) {
+        await this.request('DELETE', `/api/v1/security/policies/${encodeURIComponent(policyId)}`);
+    }
+    // --- Triggers (developer admin/editor) ---
+    async upsertTrigger(triggerId, trigger) {
+        return this.request('POST', '/api/v1/triggers', {
+            trigger_id: triggerId,
+            trigger,
+        });
+    }
+    async listTriggers() {
+        const r = await this.request('GET', '/api/v1/triggers');
+        if (r == null || typeof r !== 'object' || Array.isArray(r))
+            return {};
+        return r;
+    }
+    async getTrigger(name) {
+        const q = buildQuery({ name });
+        return this.request('GET', `/api/v1/triggers${q}`);
+    }
+    async deleteTrigger(name) {
+        const q = buildQuery({ name });
+        await this.request('DELETE', `/api/v1/triggers${q}`);
+    }
+    async checkAccess(subject, identifier, action, metaPath, branch) {
+        const body = { subject, identifier, action };
+        if (metaPath !== undefined)
+            body.meta_path = metaPath;
+        if (branch !== undefined)
+            body.branch = branch;
+        return this.request('POST', '/api/v1/security/check', body);
+    }
+    async getSecurityConfig() {
+        return this.request('GET', '/api/v1/security/config');
+    }
+    async updateSecurityConfig(config) {
+        await this.request('PUT', '/api/v1/security/config', config);
+    }
+    async createBranch(name, fromBranch, fromDate) {
+        const body = { name };
+        if (fromBranch)
+            body.from_branch = fromBranch;
+        if (fromDate)
+            body.from_date = fromDate;
+        await this.request('POST', '/api/v1/branches', body);
+    }
+    async deleteBranch(name) {
+        await this.request('DELETE', `/api/v1/branches/${encodeURIComponent(name)}`);
+    }
+    async deleteRevision(branch, date) {
+        await this.request('DELETE', `/api/v1/branches/${encodeURIComponent(branch)}/revisions/${encodeURIComponent(date)}`);
+    }
+    async listBranches() {
+        const r = await this.request('GET', '/api/v1/branches');
+        return r.branches ?? [];
+    }
+    async getBranch(name) {
+        const r = await this.request('GET', `/api/v1/branches/${encodeURIComponent(name)}`);
+        return r.branch;
+    }
+    async createCommit(message, author) {
+        const body = { message };
+        if (author)
+            body.author = author;
+        const r = await this.request('POST', '/api/v1/commits', body);
+        return r.commit;
+    }
+    async listCommits(options) {
+        const q = buildQuery({
+            branch: options?.branch,
+            limit: options?.limit,
+            offset: options?.offset,
+        });
+        return this.request('GET', `/api/v1/commits${q}`);
+    }
+    async getCommit(commitId) {
+        const r = await this.request('GET', `/api/v1/commits/${encodeURIComponent(commitId)}`);
+        return r.commit;
+    }
+    async rollbackToCommit(commitId, _confirm) {
+        return this.request('POST', `/api/v1/commits/${encodeURIComponent(commitId)}/rollback`, {
+            confirm: true,
+        });
+    }
+    async cherryPick(commitId, message, author) {
+        const body = {};
+        if (message)
+            body.message = message;
+        if (author)
+            body.author = author;
+        const r = await this.request('POST', `/api/v1/commits/${encodeURIComponent(commitId)}/cherry-pick`, body);
+        return r.commit;
+    }
+    async createTag(name, commitId, message, author) {
+        const body = { name, commit_id: commitId };
+        if (message)
+            body.message = message;
+        if (author)
+            body.author = author;
+        const r = await this.request('POST', '/api/v1/tags', body);
+        return r.tag;
+    }
+    async listTags(options) {
+        const q = buildQuery({ limit: options?.limit, offset: options?.offset });
+        return this.request('GET', `/api/v1/tags${q}`);
+    }
+    async getTag(name) {
+        const r = await this.request('GET', `/api/v1/tags/${encodeURIComponent(name)}`);
+        return r.tag;
+    }
+    async deleteTag(name) {
+        await this.request('DELETE', `/api/v1/tags/${encodeURIComponent(name)}`);
+    }
+    async diff(from, to, includeContent) {
+        return this.request('POST', '/api/v1/diff', {
+            from,
+            to,
+            include_content: includeContent ?? false,
+        });
+    }
+    async mergeBranch(targetBranch, sourceBranch, options) {
+        const body = { source_branch: sourceBranch };
+        if (options?.message)
+            body.message = options.message;
+        body.auto_resolve = options?.autoResolve ?? 'none';
+        return this.request('POST', `/api/v1/branches/${encodeURIComponent(targetBranch)}/merge`, body);
+    }
+    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeDocumentJson`. */
+    async writeXML(xml, _options) {
+        await this.request('POST', '/api/v1/documents', xml, {
+            'Content-Type': 'application/xml',
+        });
+    }
+    async writeDocumentJson(xml, options) {
+        await this.request('POST', '/api/v1/documents', {
+            xml,
+            is_top: options?.is_top ?? true,
+            compare_attributes: options?.compare_attributes ?? false,
+        });
+    }
+    async queryByIdentifier(identifier, flags, filter, pathFilter) {
+        const q = buildQuery({
+            identifier,
+            flags: flags,
+            filter,
+            path_filter: pathFilter,
+        });
+        return this.request('GET', `/api/v1/documents/by-id${q}`);
+    }
+    async queryDocuments(query, flags, filter, pathFilter) {
+        const params = {
+            match: query.match,
+            match_start: query.match_start,
+            match_end: query.match_end,
+            regex: query.regex,
+            flags: flags,
+            filter,
+            path_filter: pathFilter,
+        };
+        if (query.contains !== undefined) {
+            const c = Array.isArray(query.contains) ? query.contains.join(',') : query.contains;
+            params.contains = c;
+        }
+        if (query.required_meta_paths !== undefined && query.required_meta_paths.length > 0) {
+            params.required_meta_paths = query.required_meta_paths.join(',');
+        }
+        if (query.filter_any_meta === true) {
+            params.any_meta = '1';
+        }
+        return this.request('GET', `/api/v1/documents${buildQuery(params)}`);
+    }
+    async deleteDocument(identifier) {
+        await this.request('DELETE', `/api/v1/documents/by-id${buildQuery({ identifier })}`);
+    }
+    async addIdentifier(identifier) {
+        const r = await this.request('POST', '/api/v1/documents/identifiers', {
+            identifier,
+        });
+        return r?.ok !== false;
+    }
+    async addAlias(original, alias) {
+        const r = await this.request('POST', '/api/v1/documents/identifiers/alias', { original, alias });
+        return r?.ok !== false;
+    }
+    async queryChangeDate(identifier) {
+        const r = await this.request('GET', `/api/v1/documents/change-date${buildQuery({ identifier })}`);
+        return r?.change_date ?? r?.date ?? '';
+    }
+    async getXcitepath(identifier) {
+        const r = await this.request('GET', `/api/v1/documents/xcitepath${buildQuery({ identifier })}`);
+        return r?.xcitepath ?? '';
+    }
+    async changedIdentifiers(branch, fromDate, toDate) {
+        return this.request('GET', `/api/v1/documents/changed${buildQuery({ branch, from_date: fromDate, to_date: toDate })}`);
+    }
+    async listIdentifiers(query) {
+        const params = {
+            match: query.match,
+            match_start: query.match_start,
+            match_end: query.match_end,
+            regex: query.regex,
+            limit: query.limit,
+            offset: query.offset,
+        };
+        if (query.contains !== undefined) {
+            params.contains = Array.isArray(query.contains)
+                ? query.contains.join(',')
+                : query.contains;
+        }
+        if (query.required_meta_paths !== undefined && query.required_meta_paths.length > 0) {
+            params.required_meta_paths = query.required_meta_paths.join(',');
+        }
+        if (query.filter_any_meta === true) {
+            params.any_meta = '1';
+        }
+        const data = await this.request('GET', `/api/v1/documents/identifiers${buildQuery(params)}`);
+        // Older servers returned a bare string[]; paginated API returns { identifiers, total, offset, limit }.
+        if (Array.isArray(data)) {
+            return {
+                identifiers: data,
+                total: data.length,
+                offset: 0,
+                limit: data.length,
+            };
+        }
+        if (data !== null && typeof data === 'object') {
+            const o = data;
+            const ids = Array.isArray(o.identifiers) ? o.identifiers : [];
+            return {
+                identifiers: ids,
+                total: typeof o.total === 'number' ? o.total : ids.length,
+                offset: typeof o.offset === 'number' ? o.offset : 0,
+                limit: typeof o.limit === 'number' ? o.limit : ids.length,
+            };
+        }
+        return { identifiers: [], total: 0, offset: 0, limit: 0 };
+    }
+    async listIdentifierChildren(parentPath) {
+        const params = {};
+        if (parentPath !== undefined && parentPath !== '') {
+            params.parent_path = parentPath;
+        }
+        const data = await this.request('GET', `/api/v1/documents/identifier-children${buildQuery(params)}`);
+        if (data !== null && typeof data === 'object') {
+            const o = data;
+            const raw = o.children;
+            const children = [];
+            if (Array.isArray(raw)) {
+                for (const row of raw) {
+                    if (row !== null && typeof row === 'object') {
+                        const r = row;
+                        children.push({
+                            segment: typeof r.segment === 'string' ? r.segment : '',
+                            full_path: typeof r.full_path === 'string' ? r.full_path : '',
+                            is_identifier: r.is_identifier === true,
+                            has_children: r.has_children === true,
+                        });
+                    }
+                }
+            }
+            return {
+                parent_path: typeof o.parent_path === 'string' ? o.parent_path : '',
+                parent_is_identifier: o.parent_is_identifier === true,
+                hierarchy_index_available: o.hierarchy_index_available === true,
+                children,
+            };
+        }
+        return {
+            parent_path: '',
+            parent_is_identifier: false,
+            hierarchy_index_available: false,
+            children: [],
+        };
+    }
+    async queryLog(query, fromDate, toDate) {
+        const params = {
+            match_start: query.match_start,
+            match: query.match,
+            from_date: fromDate,
+            to_date: toDate,
+        };
+        return this.request('GET', `/api/v1/documents/log${buildQuery(params)}`);
+    }
+    async addMeta(identifier, value, path = '', opts) {
+        const body = { identifier, value, path };
+        if (opts?.mode === 'append')
+            body.mode = 'append';
+        const r = await this.request('POST', '/api/v1/meta', body);
+        return r?.ok !== false;
+    }
+    async addMetaByQuery(query, value, path = '', firstMatch = false, opts) {
+        const body = {
+            query,
+            value,
+            path,
+            first_match: firstMatch,
+        };
+        if (opts?.mode === 'append')
+            body.mode = 'append';
+        const r = await this.request('POST', '/api/v1/meta', body);
+        return r?.ok !== false;
+    }
+    async appendMeta(identifier, value, path = '') {
+        return this.addMeta(identifier, value, path, { mode: 'append' });
+    }
+    async appendMetaByQuery(query, value, path = '', firstMatch = false) {
+        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append' });
+    }
+    async queryMeta(identifier, path = '') {
+        return this.request('GET', `/api/v1/meta${buildQuery({ identifier, path })}`);
+    }
+    async queryMetaByQuery(query, path = '') {
+        return this.request('POST', '/api/v1/meta/query', { query, path });
+    }
+    async clearMeta(query) {
+        const r = await this.request('DELETE', '/api/v1/meta', { query });
+        return r?.ok !== false;
+    }
+    async acquireLock(identifier, expires = 0) {
+        return this.request('POST', '/api/v1/locks', { identifier, expires });
+    }
+    async releaseLock(identifier, lockId) {
+        const r = await this.request('DELETE', '/api/v1/locks', {
+            identifier,
+            lock_id: lockId,
+        });
+        return r?.ok !== false;
+    }
+    async findLocks(identifier) {
+        return this.request('GET', `/api/v1/locks${buildQuery({ identifier })}`);
+    }
+    async unquery(query, unquery) {
+        return this.request('POST', '/api/v1/unquery', { query, unquery });
+    }
+    async search(q) {
+        const body = { query: q.query };
+        if (q.doc_types?.length)
+            body.doc_types = q.doc_types;
+        if (q.branch !== undefined)
+            body.branch = q.branch;
+        if (q.offset !== undefined)
+            body.offset = q.offset;
+        if (q.limit !== undefined)
+            body.limit = q.limit;
+        const data = await this.request('POST', '/api/v1/search', body);
+        const hits = [];
+        if (Array.isArray(data.hits)) {
+            for (const h of data.hits) {
+                if (h && typeof h === 'object') {
+                    const o = h;
+                    const hit = {
+                        identifier: String(o.identifier ?? ''),
+                        path: String(o.path ?? ''),
+                        doc_type: o.doc_type === 'json' ? 'json' : 'xml',
+                        branch: String(o.branch ?? ''),
+                        snippet: String(o.snippet ?? ''),
+                        score: typeof o.score === 'number' ? o.score : 0,
+                    };
+                    if (typeof o.xcitepath === 'string' && o.xcitepath.length > 0) {
+                        hit.xcitepath = o.xcitepath;
+                    }
+                    hits.push(hit);
+                }
+            }
+        }
+        return {
+            hits,
+            total: typeof data.total === 'number' ? data.total : hits.length,
+            query: typeof data.query === 'string' ? data.query : q.query,
+        };
+    }
+    async reindex() {
+        return this.request('POST', '/api/v1/search/reindex', {});
+    }
+    async writeJsonDocument(identifier, data) {
+        await this.request('POST', '/api/v1/json-documents', { identifier, data });
+    }
+    async readJsonDocument(identifier) {
+        return this.request('GET', `/api/v1/json-documents${buildQuery({ identifier })}`);
+    }
+    async deleteJsonDocument(identifier) {
+        await this.request('DELETE', `/api/v1/json-documents${buildQuery({ identifier })}`);
+    }
+    async listJsonDocuments(match, limit, offset) {
+        const data = await this.request('GET', `/api/v1/json-documents/list${buildQuery({ match, limit, offset })}`);
+        if (Array.isArray(data)) {
+            const identifiers = data;
+            return { identifiers, total: identifiers.length, offset: 0, limit: identifiers.length };
+        }
+        if (data !== null && typeof data === 'object') {
+            const o = data;
+            const ids = Array.isArray(o.identifiers) ? o.identifiers : [];
+            return {
+                identifiers: ids,
+                total: typeof o.total === 'number' ? o.total : ids.length,
+                offset: typeof o.offset === 'number' ? o.offset : 0,
+                limit: typeof o.limit === 'number' ? o.limit : ids.length,
+            };
+        }
+        return { identifiers: [], total: 0, offset: 0, limit: 0 };
+    }
+    /**
+     * WebSocket `/api/v1/ws` — optional initial subscription pattern.
+     * Uses `access_token` or `api_key` query params when headers are not available (browser).
+     */
+    subscribe(options, callback, onError) {
+        let httpBase = this.baseUrl;
+        if (!httpBase && typeof globalThis !== 'undefined') {
+            const loc = globalThis.location;
+            if (loc?.origin) {
+                httpBase = loc.origin;
+            }
+        }
+        const wsBase = httpBase.replace(/^http/, 'ws');
+        const headers = {
+            ...this.authHeaders(),
+            ...this.contextHeaders(),
+        };
+        const sub = new websocket_1.WebSocketSubscription(wsBase, headers);
+        sub.onMessage(callback);
+        if (onError)
+            sub.onError(onError);
+        sub.connect();
+        sub.subscribePattern(options);
+        return sub;
+    }
+}
+exports.XCiteDBClient = XCiteDBClient;