@xcitedbs/client 0.2.17 → 0.2.18

package/dist/client.d.ts

@@ -422,10 +422,13 @@ export declare class XCiteDBClient {
     /**
      * 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`.
+     *
+     * On cooperative-lock conflict the server returns **423** with a {@link LockConflictBody} shape in {@link XCiteDBError.body}.
      */
     writeXmlDocument(xml: string, options?: WriteDocumentOptions): Promise<void>;
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
+     * Rows with `error === 'lock_conflict'` include `current_lock` (code **423** per row).
      */
     writeXmlDocumentsBatch(items: XmlDocumentBatchItem[]): Promise<DocumentBatchResponse>;
     /**
@@ -465,14 +468,28 @@ export declare class XCiteDBClient {
      * {@link LockConflictBody} body (thrown as {@link XCiteDBError} with `.status === 409`).
      */
     acquireLock(identifier: string, expiresOrOpts?: number | AcquireLockOptions): Promise<LockInfo>;
+    /**
+     * Release a lock. **404** with {@link LockUnknownBody} if the lock id is unknown; **410** with
+     * {@link LockExpiredBody} if the lock TTL expired and was garbage-collected (same server process hint).
+     */
     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>;
+    /**
+     * Extend lock TTL (holder must match). **404** {@link LockUnknownBody} / **410** {@link LockExpiredBody}
+     * behave like {@link releaseLock}.
+     */
     extendLock(identifier: string, lockId: string, ttlSeconds: number): Promise<LockInfo>;
-    findLocks(identifier: string): Promise<LockInfo[]>;
+    /**
+     * List locks visible under the given path. Pass `metaId` style paths (e.g. `/spaces/owner/docs/docId`).
+     * With `{ asPrefix: true }`, calls `GET /api/v1/locks?prefix=...` (same truncation rules as `identifier`).
+     */
+    findLocks(identifier: string, opts?: {
+        asPrefix?: boolean;
+    }): Promise<LockInfo[]>;
     /**
      * Run Unquery (`POST /api/v1/unquery`): declarative analytics over documents matching `query`.
      * The `unquery` argument is a JSON template; keys are output fields, string values are expressions.

package/dist/client.js

@@ -1194,6 +1194,8 @@ class XCiteDBClient {
     /**
      * 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`.
+     *
+     * On cooperative-lock conflict the server returns **423** with a {@link LockConflictBody} shape in {@link XCiteDBError.body}.
      */
     async writeXmlDocument(xml, options) {
         await this.request('POST', '/api/v1/documents', {
@@ -1204,6 +1206,7 @@ class XCiteDBClient {
     }
     /**
      * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
+     * Rows with `error === 'lock_conflict'` include `current_lock` (code **423** per row).
      */
     async writeXmlDocumentsBatch(items) {
         const body = {
@@ -1443,6 +1446,10 @@ class XCiteDBClient {
         const lock = await this.request('POST', '/api/v1/locks', body);
         return { ...lock, identifier: this.isoUnprefixId(lock.identifier) };
     }
+    /**
+     * Release a lock. **404** with {@link LockUnknownBody} if the lock id is unknown; **410** with
+     * {@link LockExpiredBody} if the lock TTL expired and was garbage-collected (same server process hint).
+     */
     async releaseLock(identifier, lockId) {
         const r = await this.request('DELETE', '/api/v1/locks', {
             identifier: this.isoPrefixId(identifier),
@@ -1462,6 +1469,10 @@ class XCiteDBClient {
         });
         return r?.ok !== false;
     }
+    /**
+     * Extend lock TTL (holder must match). **404** {@link LockUnknownBody} / **410** {@link LockExpiredBody}
+     * behave like {@link releaseLock}.
+     */
     async extendLock(identifier, lockId, ttlSeconds) {
         const lock = await this.request('PATCH', '/api/v1/locks', {
             identifier: this.isoPrefixId(identifier),
@@ -1470,8 +1481,13 @@ class XCiteDBClient {
         });
         return { ...lock, identifier: this.isoUnprefixId(lock.identifier) };
     }
-    async findLocks(identifier) {
-        const locks = await this.request('GET', `/api/v1/locks${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
+    /**
+     * List locks visible under the given path. Pass `metaId` style paths (e.g. `/spaces/owner/docs/docId`).
+     * With `{ asPrefix: true }`, calls `GET /api/v1/locks?prefix=...` (same truncation rules as `identifier`).
+     */
+    async findLocks(identifier, opts) {
+        const key = opts?.asPrefix ? 'prefix' : 'identifier';
+        const locks = await this.request('GET', `/api/v1/locks${buildQuery({ [key]: this.isoPrefixId(identifier) })}`);
         return Array.isArray(locks)
             ? locks.map((L) => ({ ...L, identifier: this.isoUnprefixId(L.identifier) }))
             : 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, 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 type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, Flags, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/locks.test.js

@@ -26,7 +26,6 @@ async function openTestSession(e) {
             'Content-Type': 'application/json',
             Authorization: `Bearer ${e.accessToken}`,
             'X-Project-Id': e.tenantId,
-            'X-Branch': 'main',
         },
         body: '{}',
     });
@@ -39,7 +38,7 @@ async function openTestSession(e) {
         accessToken: e.accessToken,
         platformConsole: true,
         projectId: e.tenantId,
-        context: { branch: 'main', project_id: e.tenantId },
+        context: { project_id: e.tenantId },
         testSessionToken: data.session_token,
         testRequireAuth: true,
     });

package/dist/types.d.ts

@@ -267,11 +267,25 @@ export interface AcquireLockOptions {
     /** Max milliseconds to wait when another exclusive lock is held. */
     waitMs?: number;
 }
-/** Body returned with HTTP 409 on exclusive lock conflict. */
+/**
+ * Body returned with HTTP **409** on `acquireLock` conflict, or **423** on XML document write blocked by a lock.
+ * Inspect via {@link XCiteDBError} (`status` and `body`).
+ */
 export interface LockConflictBody {
     error: 'lock_conflict';
     current_lock: LockInfo;
 }
+/** Body returned with HTTP **410** when `extendLock` / `releaseLock` target a lock id that TTL-expired recently. */
+export interface LockExpiredBody {
+    error: 'lock_expired';
+    message?: string;
+    expired_at?: number;
+}
+/** Body returned with HTTP **404** when the lock id does not exist (or never existed) for the given identifier. */
+export interface LockUnknownBody {
+    error: 'lock_unknown';
+    message?: string;
+}
 export interface TokenPair {
     access_token: string;
     refresh_token: string;
@@ -392,6 +406,8 @@ export interface DocumentBatchResultRow {
     ok: boolean;
     error?: string;
     code?: number;
+    /** Present when `error === 'lock_conflict'` (HTTP-style code 423 in batch row). */
+    current_lock?: LockInfo;
 }
 export interface DocumentBatchResponse {
     results: DocumentBatchResultRow[];

package/package.json

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