@xcitedbs/client 0.2.16 → 0.2.17

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, 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, 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, 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, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -460,8 +460,18 @@ export declare class XCiteDBClient {
     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>;
+    /**
+     * Acquire a cooperative lock. On exclusive conflict the server returns HTTP 409 with a
+     * {@link LockConflictBody} body (thrown as {@link XCiteDBError} with `.status === 409`).
+     */
+    acquireLock(identifier: string, expiresOrOpts?: number | AcquireLockOptions): Promise<LockInfo>;
     releaseLock(identifier: string, lockId: string): Promise<boolean>;
+    /**
+     * Force-release a lock using `force_unlock` ABAC authority. Pass the **raw** stored identifier
+     * from {@link findLocks} (no iso-prefix); often the path as returned by the server for another principal.
+     */
+    forceReleaseLock(identifier: string, lockId: string): Promise<boolean>;
+    extendLock(identifier: string, lockId: string, ttlSeconds: number): Promise<LockInfo>;
     findLocks(identifier: string): Promise<LockInfo[]>;
     /**
      * Run Unquery (`POST /api/v1/unquery`): declarative analytics over documents matching `query`.

package/dist/client.js

@@ -1424,11 +1424,23 @@ class XCiteDBClient {
         });
         return r?.ok !== false;
     }
-    async acquireLock(identifier, expires = 0) {
-        const lock = await this.request('POST', '/api/v1/locks', {
+    /**
+     * Acquire a cooperative lock. On exclusive conflict the server returns HTTP 409 with a
+     * {@link LockConflictBody} body (thrown as {@link XCiteDBError} with `.status === 409`).
+     */
+    async acquireLock(identifier, expiresOrOpts = 0) {
+        const opts = typeof expiresOrOpts === 'number' ? { ttlSeconds: expiresOrOpts } : expiresOrOpts ?? {};
+        const body = {
             identifier: this.isoPrefixId(identifier),
-            expires,
-        });
+        };
+        if (opts.ttlSeconds !== undefined && opts.ttlSeconds > 0) {
+            body.ttl_seconds = opts.ttlSeconds;
+        }
+        if (opts.mode)
+            body.mode = opts.mode;
+        if (opts.waitMs !== undefined && opts.waitMs > 0)
+            body.wait_ms = opts.waitMs;
+        const lock = await this.request('POST', '/api/v1/locks', body);
         return { ...lock, identifier: this.isoUnprefixId(lock.identifier) };
     }
     async releaseLock(identifier, lockId) {
@@ -1438,6 +1450,26 @@ class XCiteDBClient {
         });
         return r?.ok !== false;
     }
+    /**
+     * Force-release a lock using `force_unlock` ABAC authority. Pass the **raw** stored identifier
+     * from {@link findLocks} (no iso-prefix); often the path as returned by the server for another principal.
+     */
+    async forceReleaseLock(identifier, lockId) {
+        const r = await this.request('DELETE', '/api/v1/locks', {
+            identifier,
+            lock_id: lockId,
+            force: true,
+        });
+        return r?.ok !== false;
+    }
+    async extendLock(identifier, lockId, ttlSeconds) {
+        const lock = await this.request('PATCH', '/api/v1/locks', {
+            identifier: this.isoPrefixId(identifier),
+            lock_id: lockId,
+            ttl_seconds: ttlSeconds,
+        });
+        return { ...lock, identifier: this.isoUnprefixId(lock.identifier) };
+    }
     async findLocks(identifier) {
         const locks = await this.request('GET', `/api/v1/locks${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
         return Array.isArray(locks)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { XCiteDBClient } from './client';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, 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, XCiteDBClientOptions, 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, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, 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, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/locks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/locks.test.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Wet tests: set XCITEDB_BASE_URL, XCITEDB_ADMIN_TOKEN, XCITEDB_TENANT_ID.
+ * Run: npm test
+ */
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const client_js_1 = require("./client.js");
+function wetEnv() {
+    const baseUrl = process.env.XCITEDB_BASE_URL?.trim();
+    const accessToken = process.env.XCITEDB_ADMIN_TOKEN?.trim();
+    const tenantId = process.env.XCITEDB_TENANT_ID?.trim();
+    if (!baseUrl || !accessToken || !tenantId)
+        return null;
+    return { baseUrl, accessToken, tenantId };
+}
+async function openTestSession(e) {
+    const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions`;
+    const r = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${e.accessToken}`,
+            'X-Project-Id': e.tenantId,
+            'X-Branch': 'main',
+        },
+        body: '{}',
+    });
+    const data = (await r.json());
+    if (!r.ok || !data.session_token) {
+        throw new Error(`test session failed ${r.status}`);
+    }
+    const client = new client_js_1.XCiteDBClient({
+        baseUrl: e.baseUrl,
+        accessToken: e.accessToken,
+        platformConsole: true,
+        projectId: e.tenantId,
+        context: { branch: 'main', project_id: e.tenantId },
+        testSessionToken: data.session_token,
+        testRequireAuth: true,
+    });
+    return { client, token: data.session_token };
+}
+const w = wetEnv();
+const wd = w ? node_test_1.describe : node_test_1.describe.skip;
+wd('locks (wet)', () => {
+    (0, node_test_1.it)('acquire, extend, release', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const { client: c, token } = await openTestSession(e);
+        try {
+            const path = '/sdk_locks/js_wet_roundtrip';
+            await c.writeJsonDocument(path, { k: 1 }, { overwrite: true });
+            const lock = await c.acquireLock(path, { ttlSeconds: 120, mode: 'exclusive' });
+            strict_1.default.ok(lock.lock_id);
+            strict_1.default.equal(lock.mode, 'exclusive');
+            const ext = await c.extendLock(path, lock.lock_id, 180);
+            strict_1.default.ok((ext.version ?? 0) >= (lock.version ?? 1));
+            const ok = await c.releaseLock(path, lock.lock_id);
+            strict_1.default.ok(ok);
+        }
+        finally {
+            await fetch(`${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions/current`, {
+                method: 'DELETE',
+                headers: { 'X-Test-Session': token },
+            });
+        }
+    });
+});

package/dist/types.d.ts

@@ -253,6 +253,24 @@ export interface LockInfo {
     time: number;
     expiration: number;
     branch: string;
+    holder?: string;
+    mode?: 'exclusive' | 'advisory';
+    version?: number;
+    acquired_at?: string;
+    expires_at?: string;
+}
+/** Options for {@link XCiteDBClient.acquireLock}. */
+export interface AcquireLockOptions {
+    /** Seconds until lock expires; server clamps (default 60). */
+    ttlSeconds?: number;
+    mode?: 'exclusive' | 'advisory';
+    /** Max milliseconds to wait when another exclusive lock is held. */
+    waitMs?: number;
+}
+/** Body returned with HTTP 409 on exclusive lock conflict. */
+export interface LockConflictBody {
+    error: 'lock_conflict';
+    current_lock: LockInfo;
 }
 export interface TokenPair {
     access_token: string;

package/llms-full.txt

@@ -843,17 +843,43 @@ Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_co
 
 ## Acquire lock
 
-**`POST /api/v1/locks`** — `{ "identifier": "/book/ch1", "expires": 600 }`
+**`POST /api/v1/locks`**
 
-Returns lock info. **`409`** if already locked.
+```json
+{
+  "identifier": "/book/ch1",
+  "ttl_seconds": 120,
+  "mode": "exclusive",
+  "wait_ms": 5000
+}
+```
+
+- **`ttl_seconds`** preferred; legacy **`expires`** is an alias. Omitted or `0` → server default (**60s**), clamped to **5–600s**.
+- **`mode`**: `exclusive` (blocks other exclusives; multiple `advisory` locks can coexist; an existing **exclusive** blocks new `advisory`).
+- **`wait_ms`**: optional 0–30000; server retries acquire every ~100ms until granted or timeout, then **`409`** with `{ "error":"lock_conflict", "current_lock": { ... } }`.
+
+Returns **`201`** with `LockInfo`: `lock_id`, `identifier`, `time`, `expiration`, `branch`, `holder`, `mode`, `version`, `acquired_at`, `expires_at` (ISO UTC).
+
+## Extend lock
+
+**`PATCH /api/v1/locks`** — `{ "identifier": "...", "lock_id": "...", "ttl_seconds": 120 }` — holder-only; bumps `version` and sets new expiry from **now**.
 
 ## Release lock
 
-**`DELETE /api/v1/locks`** — `{ "identifier": "/book/ch1", "lock_id": "..." }`
+**`DELETE /api/v1/locks`** — `{ "identifier": "...", "lock_id": "...", "force": false }`
+
+- Normal release: **`403`** `lock_holder_mismatch` if the lock exists but the identifier path does not match this principal (e.g. user isolation); **`404`** if `lock_id` unknown.
+- **`force: true`**: deletes the lock blob without path check; requires ABAC **`force_unlock`** (policies with **`write`** still satisfy this via synonym fallback).
 
 ## Query locks
 
-**`GET /api/v1/locks?identifier=...`** — Lists active locks.
+**`GET /api/v1/locks?identifier=...`** or **`?prefix=...`** — Lists active locks (same resolution). Response entries include **`holder`**.
+
+### Caveats
+
+- SDK **user isolation** rewrites identifiers; **`findLocks`** returns the **stored** path in `identifier` — use that for **`forceReleaseLock`** when releasing another principal’s lock.
+- Locks are keyed on the **resolved path at acquire time**. Renaming/moving an ancestor invalidates listing under the new path; **release locks before structural moves**, then reacquire.
+- **`lock_expired`** events are emitted when an expired lock row is garbage-collected on read (best-effort), not on a wall-clock timer.
 
 ---
 
@@ -1447,8 +1473,10 @@ interface DatabaseContext {
 - **Deprecated:** `diff(from: DiffRef, …)` — alias of `compare`
 
 ### Locks
-- `acquireLock(identifier, expires?)` → `LockInfo`
+- `acquireLock(identifier, ttlSeconds | { ttlSeconds, mode, waitMs })` → `LockInfo` (throws **`XCiteDBError`** with **409** and `lock_conflict` body on conflict)
 - `releaseLock(identifier, lockId)` → `boolean`
+- `forceReleaseLock(identifier, lockId)` → `boolean` (raw identifier when using isolation)
+- `extendLock(identifier, lockId, ttlSeconds)` → `LockInfo`
 - `findLocks(identifier)` → `LockInfo[]`
 
 ### Search

package/llms.txt

@@ -178,10 +178,12 @@ await client.publishWorkspace('', 'feature-x'); // publish into root (default) w
 // Attach JSON metadata to a document
 await client.addMeta('/manual/v1/intro', { status: 'draft', owner: 'alice' });
 
-// Acquire a cooperative lock
-const lock = await client.acquireLock('/manual/v1/intro');
+// Cooperative locks (exclusive blocks others; advisory is informational)
+const lock = await client.acquireLock('/manual/v1/intro', { ttlSeconds: 120, mode: 'exclusive' });
 // ... edit ...
 await client.releaseLock('/manual/v1/intro', lock.lock_id);
+// Force-release (requires force_unlock ABAC): use raw identifier from findLocks, no iso-prefix
+// await client.forceReleaseLock(storedIdentifier, lock.lock_id);
 
 // Full-text search (embedded XciteFTS; optional temporal filters on the query body)
 const results = await client.search({ query: 'installation guide', limit: 20, mode: 'fts' });
@@ -266,9 +268,12 @@ interface XCiteDBClientOptions {
 - **Deprecated aliases:** `withBranch`, `createBranch`, `listBranches`, `mergeBranch`, `deleteBranch`, `createCommit`, `listCommits`, `rollbackToCommit`, `cherryPick`, `diff`, `createTag`, `listTags`, `deleteTag` (same HTTP behavior)
 
 **Locks:**
-- `acquireLock(identifier, expires?)` — Acquire cooperative lock
-- `releaseLock(identifier, lockId)` — Release lock
-- `findLocks(identifier)` — Query active locks
+- `acquireLock(identifier, options?)` — `options`: `ttlSeconds` (server clamps 5–600, default 60), `mode` `exclusive`|`advisory`, `waitMs` (0–30000). Legacy `acquireLock(identifier, expiresNumber)` still works (maps to `ttlSeconds`). Body fields `ttl_seconds` and legacy `expires` accepted server-side.
+- `releaseLock(identifier, lockId)` — Holder release; 403 `lock_holder_mismatch` if path does not match principal; 404 if unknown `lockId`
+- `forceReleaseLock(identifier, lockId)` — Admin/owner release; pass **raw** stored identifier from `findLocks` when using user isolation
+- `extendLock(identifier, lockId, ttlSeconds)` — Refresh TTL (holder only)
+- `findLocks(identifier)` — Returns `holder`, `mode`, `version`, `acquired_at`, `expires_at`
+- ABAC actions: `lock`, `unlock`, `force_unlock`; policies with `write` only still authorize all three (compat)
 
 **Search & Analytics:**
 - `search(query)` — Full-text search (embedded FTS). Optional **`at_date`**, **`date_from`**, **`date_to`** on the query for temporal keyword search (use **`mode: 'fts'`**). Hits may include **`valid_from`** / **`valid_to`** (7-char internal keys).

package/package.json

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

package/unquery-ai-guide.md

@@ -1128,6 +1128,7 @@ Before returning a query, scan it against this checklist. These rules come strai
 ## 13. Cross-reference
 
 - [`docs/unquery-grammar.md`](./unquery-grammar.md) — Parser-faithful EBNF, AST nodes, lexer tokens, every static rule. Use this for syntax-checking, error attribution, or when extending Unquery tooling. MCP resource: `xcitedb://unquery-grammar`.
+- [Unquery playground](https://unquery-playground.vercel.app/) — Browser tool to try templates and expressions interactively (no XCiteDB server required for basic experiments).
 - [`web/src/docs/content/unquery-language-reference.html`](../web/src/docs/content/unquery-language-reference.html) — Human-oriented reference manual.
 - [`web/src/docs/content/unquery-tutorial.html`](../web/src/docs/content/unquery-tutorial.html) — Hands-on tutorial with the employees dataset.
 - XCiteDB-specific bits (workspaces, branches, identifiers, `->$date`, `->$branch`, `->$all`, `$xml*`, `$attr`, `$xpath`, `$node_date`, `$data_date`) only apply when running against XCiteDB. With the `unq` CLI on plain JSON files, ignore them.

package/unquery-grammar.md

@@ -2,7 +2,7 @@
 
 This document is the **ground truth** for Unquery syntax as implemented in the XCiteDB engine. It is derived from `TParser` in [`XCiteDB2/XCiteDB/src/TemplateParser.cpp`](../XCiteDB2/XCiteDB/src/TemplateParser.cpp) and the AST in [`XCiteDB2/XCiteDB/include/TemplateQuery.h`](../XCiteDB2/XCiteDB/include/TemplateQuery.h). Use it for **syntax checking** and **conservative static typing** of expressions inside JSON templates.
 
-Human-oriented prose and examples: [Unquery reference manual](../web/src/docs/content/unquery-language-reference.html) (Asciidoc source: `web/src/docs/unquery-source/unquery-language-reference.adoc`).
+Human-oriented prose and examples: [Unquery reference manual](../web/src/docs/content/unquery-language-reference.html) (Asciidoc source: `web/src/docs/unquery-source/unquery-language-reference.adoc`). Try queries in the browser: [Unquery playground](https://unquery-playground.vercel.app/).
 
 ---