@xcitedbs/client 0.1.0 → 0.2.5

package/README.md

@@ -26,11 +26,12 @@ import { XCiteDBClient } from '@xcitedbs/client';
 const client = new XCiteDBClient({
   baseUrl: 'http://localhost:8080',
   apiKey: process.env.XCITEDB_API_KEY,
-  context: { branch: 'main', date: '03/27/2026' },
+  context: { branch: '', date: '' },
 });
 
 await client.health();
 const docs = await client.queryByIdentifier('/test1', 'FirstMatch');
+await client.put('app.settings', { theme: 'dark' });
 ```
 
 ### WebSocket

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, PolicySubjectInput, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, OwnedTenantInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -48,8 +48,8 @@ export declare class XCiteDBClient {
         api_version: string;
     }>;
     /**
-     * Platform console sign-in. The first argument is the account **email** (e.g. `admin@localhost`).
-     * Legacy `/api/v1/auth/login` has been removed.
+     * @deprecated Use {@link platformLogin} for platform operator sign-in, or {@link loginAppUser} for app end-users.
+     * This method only performs platform console login.
      */
     login(email: string, password: string): Promise<TokenPair>;
     /** Platform console sign-in (`email` + `password`). Project context is `X-Project-Id`, not the JWT. */
@@ -67,14 +67,14 @@ export declare class XCiteDBClient {
         org_name?: string;
         org_id?: string;
         attributes?: Record<string, unknown>;
-    }): Promise<unknown>;
+    }): Promise<PlatformRegisterResult>;
     platformWorkspaces(): Promise<PlatformWorkspacesResponse>;
-    listMyTenants(): Promise<OwnedTenantInfo[]>;
-    /** Alias for {@link listMyTenants} (organization/project terminology). */
-    listMyProjects(): Promise<OwnedTenantInfo[]>;
+    /** @deprecated Prefer {@link listMyProjects}. */
+    listMyTenants(): Promise<ProjectInfo[]>;
+    /** Lists projects the platform user can access (from workspaces). */
+    listMyProjects(): Promise<ProjectInfo[]>;
     /**
-     * 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.
+     * @deprecated Use {@link switchProject}. Platform console: updates `X-Project-Id` only (no token exchange).
      */
     switchTenant(tenantId: string): Promise<void>;
     /** Alias for {@link switchTenant}. */
@@ -165,8 +165,33 @@ export declare class XCiteDBClient {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';
     }): Promise<MergeResult>;
-    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeDocumentJson`. */
+    /**
+     * Create `branchName` from {@link options.fromBranch} (or current context branch), run `fn` scoped to that branch,
+     * create a commit, then merge back into the parent branch unless {@link options.autoMerge} is `false`.
+     * Restores previous {@link DatabaseContext} afterward.
+     */
+    withBranch<T>(branchName: string, fn: (client: XCiteDBClient) => Promise<T>, options?: {
+        message?: string;
+        /** When true (default), merge `branchName` into the parent branch after commit. */
+        autoMerge?: boolean;
+        /** Branch to fork from (default: current `context.branch`, or `""`). */
+        fromBranch?: string;
+        author?: string;
+    }): Promise<{
+        result: T;
+        commit?: CommitRecord;
+        merge?: MergeResult;
+    }>;
+    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
     writeXML(xml: string, _options?: WriteDocumentOptions): Promise<void>;
+    /**
+     * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
+     * For storing JSON data by key, use `writeJsonDocument`.
+     */
+    writeXmlDocument(xml: string, options?: WriteDocumentOptions): Promise<void>;
+    /**
+     * @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[]>;
     queryDocuments(query: XCiteQuery, flags?: Flags, filter?: string, pathFilter?: string): Promise<string[]>;
@@ -187,22 +212,30 @@ export declare class XCiteDBClient {
     }): Promise<boolean>;
     appendMeta(identifier: string, value: unknown, path?: string): Promise<boolean>;
     appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean): Promise<boolean>;
-    queryMeta(identifier: string, path?: string): Promise<unknown>;
-    queryMetaByQuery(query: XCiteQuery, path?: string): Promise<unknown>;
+    queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
+    queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
     clearMeta(query: XCiteQuery): Promise<boolean>;
     acquireLock(identifier: string, expires?: number): Promise<LockInfo>;
     releaseLock(identifier: string, lockId: string): Promise<boolean>;
     findLocks(identifier: string): Promise<LockInfo[]>;
-    unquery(query: XCiteQuery, unquery: unknown): Promise<unknown>;
+    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: unknown): Promise<T>;
     search(q: TextSearchQuery): Promise<TextSearchResult>;
     reindex(): Promise<{
         status: string;
         message: string;
     }>;
     writeJsonDocument(identifier: string, data: unknown): Promise<void>;
-    readJsonDocument(identifier: string): Promise<unknown>;
+    readJsonDocument<T = unknown>(identifier: string): Promise<T>;
     deleteJsonDocument(identifier: string): Promise<void>;
     listJsonDocuments(match?: string, limit?: number, offset?: number): Promise<ListIdentifiersResult>;
+    /** JSON document shorthand — same as {@link writeJsonDocument}. */
+    put(identifier: string, data: unknown): Promise<void>;
+    /** JSON document read — same as {@link readJsonDocument}. */
+    get<T = unknown>(identifier: string): Promise<T>;
+    /** JSON document delete — same as {@link deleteJsonDocument}. */
+    remove(identifier: string): Promise<void>;
+    /** List JSON document keys — same as {@link listJsonDocuments}. */
+    list(match?: string, limit?: number, offset?: number): Promise<ListIdentifiersResult>;
     /**
      * WebSocket `/api/v1/ws` — optional initial subscription pattern.
      * Uses `access_token` or `api_key` query params when headers are not available (browser).

package/dist/client.js

@@ -101,11 +101,13 @@ class XCiteDBClient {
             h['X-Date'] = c.date;
         if (c.prefix)
             h['X-Prefix'] = c.prefix;
+        if (c.unversioned)
+            h['X-Unversioned'] = 'true';
         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;
+        const tid = this.defaultContext.project_id ?? this.defaultContext.tenant_id;
         if (tid)
             return { ...body, tenant_id: tid };
         return body;
@@ -214,8 +216,8 @@ class XCiteDBClient {
         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.
+     * @deprecated Use {@link platformLogin} for platform operator sign-in, or {@link loginAppUser} for app end-users.
+     * This method only performs platform console login.
      */
     async login(email, password) {
         return this.platformLogin(email, password);
@@ -257,12 +259,19 @@ class XCiteDBClient {
     async platformWorkspaces() {
         return this.request('GET', '/api/v1/platform/auth/workspaces');
     }
+    /** @deprecated Prefer {@link listMyProjects}. */
     async listMyTenants() {
+        return this.listMyProjects();
+    }
+    /** Lists projects the platform user can access (from workspaces). */
+    async listMyProjects() {
         const w = await this.platformWorkspaces();
         const tenants = (w.projects ?? []).map((p) => {
             const r = p;
+            const id = r.tenant_id || r.project_id || '';
             return {
-                tenant_id: r.tenant_id || r.project_id || '',
+                project_id: id,
+                tenant_id: id,
                 org_id: r.org_id,
                 name: r.name,
                 status: r.status,
@@ -277,13 +286,8 @@ class XCiteDBClient {
         }
         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.
+     * @deprecated Use {@link switchProject}. Platform console: updates `X-Project-Id` only (no token exchange).
      */
     async switchTenant(tenantId) {
         if (this.platformConsole) {
@@ -327,15 +331,14 @@ class XCiteDBClient {
         return this.request('POST', '/api/v1/app/auth/register', this.mergeAppTenant(body));
     }
     async getOAuthProviders() {
-        const tid = this.defaultContext.tenant_id;
+        const tid = this.defaultContext.project_id ?? 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';
+        const raw = this.defaultContext.project_id ?? this.defaultContext.tenant_id;
+        const tid = raw && String(raw).length > 0 ? String(raw) : '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). */
@@ -591,19 +594,55 @@ class XCiteDBClient {
         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`. */
+    /**
+     * Create `branchName` from {@link options.fromBranch} (or current context branch), run `fn` scoped to that branch,
+     * create a commit, then merge back into the parent branch unless {@link options.autoMerge} is `false`.
+     * Restores previous {@link DatabaseContext} afterward.
+     */
+    async withBranch(branchName, fn, options) {
+        const prev = { ...this.defaultContext };
+        const fromBranch = options?.fromBranch ?? prev.branch ?? '';
+        let commit;
+        let merge;
+        try {
+            await this.createBranch(branchName, fromBranch || undefined, prev.date || undefined);
+            this.setContext({ branch: branchName });
+            const result = await fn(this);
+            commit = await this.createCommit(options?.message ?? `Branch ${branchName}`, options?.author);
+            if (options?.autoMerge !== false) {
+                merge = await this.mergeBranch(fromBranch, branchName, {
+                    message: options?.message,
+                });
+            }
+            return { result, commit, merge };
+        }
+        finally {
+            this.setContext(prev);
+        }
+    }
+    /** Send raw XML body (`Content-Type: application/xml`). For JSON wrapper + options use `writeXmlDocument`. */
     async writeXML(xml, _options) {
         await this.request('POST', '/api/v1/documents', xml, {
             'Content-Type': 'application/xml',
         });
     }
-    async writeDocumentJson(xml, options) {
+    /**
+     * Write an **XML** document using a JSON request body (`xml` field). The identifier is taken from `db:identifier` on the root element.
+     * For storing JSON data by key, use `writeJsonDocument`.
+     */
+    async writeXmlDocument(xml, options) {
         await this.request('POST', '/api/v1/documents', {
             xml,
             is_top: options?.is_top ?? true,
             compare_attributes: options?.compare_attributes ?? false,
         });
     }
+    /**
+     * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
+     */
+    async writeDocumentJson(xml, options) {
+        return this.writeXmlDocument(xml, options);
+    }
     async queryByIdentifier(identifier, flags, filter, pathFilter) {
         const q = buildQuery({
             identifier,
@@ -865,6 +904,22 @@ class XCiteDBClient {
         }
         return { identifiers: [], total: 0, offset: 0, limit: 0 };
     }
+    /** JSON document shorthand — same as {@link writeJsonDocument}. */
+    async put(identifier, data) {
+        return this.writeJsonDocument(identifier, data);
+    }
+    /** JSON document read — same as {@link readJsonDocument}. */
+    async get(identifier) {
+        return this.readJsonDocument(identifier);
+    }
+    /** JSON document delete — same as {@link deleteJsonDocument}. */
+    async remove(identifier) {
+        return this.deleteJsonDocument(identifier);
+    }
+    /** List JSON document keys — same as {@link listJsonDocuments}. */
+    async list(match, limit, offset) {
+        return this.listJsonDocuments(match, limit, offset);
+    }
     /**
      * WebSocket `/api/v1/ws` — optional initial subscription pattern.
      * Uses `access_token` or `api_key` query params when headers are not available (browser).

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, DatabaseContext, Flags, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, XCiteDBClientOptions, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, XCiteDBClientOptions, UnqueryResult, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -14,6 +14,19 @@ export interface XCiteQuery {
     /** Skip this many rows (for pagination). */
     offset?: number;
 }
+/** Root object returned by `readJsonDocument` (use generics for app-specific shapes). */
+export type JsonDocumentData = Record<string, unknown>;
+/** JSON metadata from meta APIs (structure is document-specific). */
+export type MetaValue = unknown;
+/** Result of `unquery` (shape depends on the unquery definition). */
+export type UnqueryResult = unknown;
+/** Typical `POST /api/v1/platform/auth/register` response (fields vary by registration policy). */
+export interface PlatformRegisterResult {
+    user_id?: string;
+    status?: string;
+    message?: string;
+    [key: string]: unknown;
+}
 /** Full-text search (`POST /api/v1/search`) */
 export interface TextSearchQuery {
     query: string;
@@ -77,8 +90,14 @@ export interface TokenPair {
     refresh_token: string;
     expires_in: number;
 }
-/** Projects from `GET /api/v1/platform/auth/workspaces` (mapped for compatibility). */
-export interface OwnedTenantInfo {
+/**
+ * Project row from `GET /api/v1/platform/auth/workspaces` and related APIs.
+ * The server often labels the id as `tenant_id`; both fields are set when mapped by the SDK.
+ */
+export interface ProjectInfo {
+    /** Project id (wire alias: `tenant_id` in many JSON bodies). */
+    project_id: string;
+    /** Same id as `project_id` (legacy / wire field name). */
     tenant_id: string;
     org_id?: string;
     name: string;
@@ -88,6 +107,8 @@ export interface OwnedTenantInfo {
     config?: unknown;
     owner_user_id?: string;
 }
+/** @deprecated Use {@link ProjectInfo}. */
+export type OwnedTenantInfo = ProjectInfo;
 export interface UserInfo {
     user_id: string;
     username: string;
@@ -117,7 +138,7 @@ export interface PlatformWorkspaceOrg {
 }
 export interface PlatformWorkspacesResponse {
     orgs: PlatformWorkspaceOrg[];
-    projects: OwnedTenantInfo[];
+    projects: ProjectInfo[];
 }
 /** One row from `GET /api/v1/project/keys` (secret is never returned). */
 export interface ApiKeyInfo {
@@ -127,13 +148,24 @@ export interface ApiKeyInfo {
     expires_at: number;
     /** `secret` = server-side full access; `public` = client-safe, restricted. */
     key_type?: 'secret' | 'public';
+    /** Project id this key belongs to. */
+    tenant_id?: string;
 }
 export type Flags = 'None' | 'FirstMatch' | 'IncludeChildren' | 'NoChildren' | 'KeepIndexNodes' | 'PrevIfDeleted' | string;
 export interface DatabaseContext {
     branch?: string;
     date?: string;
     prefix?: string;
-    /** Project/tenant id; sent as `tenant_id` in app-user public auth bodies when no developer token is used. */
+    /**
+     * When true, sends `X-Unversioned: true` so writes use flat LMDB keys (no date revision).
+     * Do not combine with `date`; the server returns 400 if both are set.
+     */
+    unversioned?: boolean;
+    /** Preferred: project id; sent as `tenant_id` in app-user public auth bodies when no developer token is used. */
+    project_id?: string;
+    /**
+     * @deprecated Use {@link DatabaseContext.project_id} (same JSON field name on the wire: `tenant_id`).
+     */
     tenant_id?: string;
 }
 export interface WriteDocumentOptions {
@@ -162,7 +194,7 @@ export interface XCiteDBClientOptions {
     context?: DatabaseContext;
     /** When true, sends `X-Project-Id` for console requests; developer JWTs are always platform tokens. */
     platformConsole?: boolean;
-    /** Active project id for platform console requests (`X-Project-Id` header). */
+    /** Active project id for platform console requests (`X-Project-Id` header). Alias of {@link DatabaseContext.project_id} for console mode. */
     projectId?: string;
     /** Persist developer session tokens after refresh (e.g. localStorage). */
     onSessionTokensUpdated?: (pair: TokenPair) => void;