@xcitedbs/client 0.2.12 → 0.2.14

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, Flags, 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, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery, UserIsolationConfig } 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, 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 } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -248,7 +248,7 @@ export declare class XCiteDBClient {
     deleteTrigger(name: string): Promise<void>;
     /**
      * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
-     * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `unquery`.
      *
      * @example
      * ```ts
@@ -263,13 +263,12 @@ export declare class XCiteDBClient {
      *   },
      *   '/acme/reports/q1',
      *   'read',
-     *   undefined,
      *   'main'
      * );
      * console.log(r.effect, r.matched_policy_id);
      * ```
      */
-    checkAccess(subject: PolicySubjectInput, identifier: string, action: string, metaPath?: string, branch?: string): Promise<AccessCheckResult>;
+    checkAccess(subject: PolicySubjectInput, identifier: string, action: string, branch?: string): Promise<AccessCheckResult>;
     getSecurityConfig(): Promise<SecurityConfig>;
     /**
      * Update tenant security defaults (`PUT /api/v1/security/config`). When ABAC is enabled, pair
@@ -419,6 +418,10 @@ export declare class XCiteDBClient {
      * For storing JSON data by key, use `writeJsonDocument`.
      */
     writeXmlDocument(xml: string, options?: WriteDocumentOptions): Promise<void>;
+    /**
+     * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
+     */
+    writeXmlDocumentsBatch(items: XmlDocumentBatchItem[]): Promise<DocumentBatchResponse>;
     /**
      * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
      */
@@ -436,12 +439,18 @@ export declare class XCiteDBClient {
     queryLog(query: XCiteQuery, fromDate: string, toDate: string): Promise<LogEntry[]>;
     addMeta(identifier: string, value: unknown, path?: string, opts?: {
         mode?: 'set' | 'append';
+        overwrite?: boolean;
     }): Promise<boolean>;
     addMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
         mode?: 'set' | 'append';
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    appendMeta(identifier: string, value: unknown, path?: string, opts?: {
+        overwrite?: boolean;
+    }): Promise<boolean>;
+    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean, opts?: {
+        overwrite?: boolean;
     }): Promise<boolean>;
-    appendMeta(identifier: string, value: unknown, path?: string): Promise<boolean>;
-    appendMetaByQuery(query: XCiteQuery, value: unknown, path?: string, firstMatch?: boolean): Promise<boolean>;
     queryMeta<T = MetaValue>(identifier: string, path?: string): Promise<T>;
     queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string): Promise<T>;
     clearMeta(query: XCiteQuery): Promise<boolean>;
@@ -517,12 +526,20 @@ export declare class XCiteDBClient {
      * The final event has `done: true` and may include `sources`.
      */
     ragQueryStream(options: Omit<RagQueryOptions, 'stream'>, onEvent: (ev: RagStreamEvent) => void): Promise<void>;
-    writeJsonDocument(identifier: string, data: unknown): Promise<void>;
+    writeJsonDocument(identifier: string, data: unknown, opts?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    /**
+     * Best-effort batch JSON document writes (`POST /api/v1/json-documents/batch`). Each item is independent; check `results[].ok`.
+     */
+    writeJsonDocumentsBatch(items: JsonDocumentBatchItem[]): Promise<DocumentBatchResponse>;
     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>;
+    put(identifier: string, data: unknown, opts?: {
+        overwrite?: boolean;
+    }): Promise<void>;
     /** JSON document read — same as {@link readJsonDocument}. */
     get<T = unknown>(identifier: string): Promise<T>;
     /** JSON document delete — same as {@link deleteJsonDocument}. */

package/dist/client.js

@@ -900,7 +900,7 @@ class XCiteDBClient {
     }
     /**
      * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
-     * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `unquery`.
      *
      * @example
      * ```ts
@@ -915,16 +915,13 @@ class XCiteDBClient {
      *   },
      *   '/acme/reports/q1',
      *   'read',
-     *   undefined,
      *   'main'
      * );
      * console.log(r.effect, r.matched_policy_id);
      * ```
      */
-    async checkAccess(subject, identifier, action, metaPath, branch) {
+    async checkAccess(subject, identifier, action, branch) {
         const body = { subject, identifier: this.isoPrefixId(identifier), action };
-        if (metaPath !== undefined)
-            body.meta_path = metaPath;
         if (branch !== undefined)
             body.branch = branch;
         return this.request('POST', '/api/v1/security/check', body);
@@ -1193,6 +1190,32 @@ class XCiteDBClient {
             compare_attributes: options?.compare_attributes ?? false,
         });
     }
+    /**
+     * Best-effort batch XML writes (`POST /api/v1/documents/batch`). Each item is independent; check `results[].ok`.
+     */
+    async writeXmlDocumentsBatch(items) {
+        const body = {
+            items: items.map((it) => {
+                const row = {
+                    xml: this.isoApplyXmlDbIdentifier(it.xml),
+                    is_top: it.is_top ?? true,
+                    compare_attributes: it.compare_attributes ?? false,
+                };
+                if (it.identifier !== undefined && it.identifier !== '') {
+                    row.identifier = this.isoPrefixId(it.identifier);
+                }
+                return row;
+            }),
+        };
+        const r = await this.request('POST', '/api/v1/documents/batch', body);
+        if (r?.results) {
+            for (const row of r.results) {
+                if (row.identifier)
+                    row.identifier = this.isoUnprefixId(String(row.identifier));
+            }
+        }
+        return r;
+    }
     /**
      * @deprecated Use {@link writeXmlDocument}. This name was misleading: it writes **XML** via a JSON wrapper, not a JSON document.
      */
@@ -1352,6 +1375,8 @@ class XCiteDBClient {
         const body = { identifier: this.isoPrefixId(identifier), value, path };
         if (opts?.mode === 'append')
             body.mode = 'append';
+        if (opts?.overwrite)
+            body.overwrite = true;
         const r = await this.request('POST', '/api/v1/meta', body);
         return r?.ok !== false;
     }
@@ -1364,14 +1389,16 @@ class XCiteDBClient {
         };
         if (opts?.mode === 'append')
             body.mode = 'append';
+        if (opts?.overwrite)
+            body.overwrite = true;
         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 appendMeta(identifier, value, path = '', opts) {
+        return this.addMeta(identifier, value, path, { mode: 'append', ...opts });
     }
-    async appendMetaByQuery(query, value, path = '', firstMatch = false) {
-        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append' });
+    async appendMetaByQuery(query, value, path = '', firstMatch = false, opts) {
+        return this.addMetaByQuery(query, value, path, firstMatch, { mode: 'append', ...opts });
     }
     async queryMeta(identifier, path = '') {
         return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`);
@@ -1558,6 +1585,12 @@ class XCiteDBClient {
             body.min_score = options.min_score;
         if (options.semantic_weight !== undefined)
             body.semantic_weight = options.semantic_weight;
+        if (options.temperature !== undefined)
+            body.temperature = options.temperature;
+        if (options.max_tokens !== undefined)
+            body.max_tokens = options.max_tokens;
+        if (options.messages?.length)
+            body.messages = options.messages;
         const data = await this.request('POST', '/api/v1/rag/query', body);
         if (!data || typeof data !== 'object') {
             throw new types_1.XCiteDBError('Invalid RAG response', 500, data);
@@ -1581,6 +1614,9 @@ class XCiteDBClient {
             ...(options.search_mode !== undefined ? { search_mode: options.search_mode } : {}),
             ...(options.min_score !== undefined ? { min_score: options.min_score } : {}),
             ...(options.semantic_weight !== undefined ? { semantic_weight: options.semantic_weight } : {}),
+            ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+            ...(options.max_tokens !== undefined ? { max_tokens: options.max_tokens } : {}),
+            ...(options.messages?.length ? { messages: options.messages } : {}),
         });
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
@@ -1654,8 +1690,35 @@ class XCiteDBClient {
         }
         throw new types_1.XCiteDBError('RAG stream failed after retry', 401, null);
     }
-    async writeJsonDocument(identifier, data) {
-        await this.request('POST', '/api/v1/json-documents', { identifier: this.isoPrefixId(identifier), data });
+    async writeJsonDocument(identifier, data, opts) {
+        const body = { identifier: this.isoPrefixId(identifier), data };
+        if (opts?.overwrite)
+            body.overwrite = true;
+        await this.request('POST', '/api/v1/json-documents', body);
+    }
+    /**
+     * Best-effort batch JSON document writes (`POST /api/v1/json-documents/batch`). Each item is independent; check `results[].ok`.
+     */
+    async writeJsonDocumentsBatch(items) {
+        const body = {
+            items: items.map((it) => {
+                const row = {
+                    identifier: this.isoPrefixId(it.identifier),
+                    data: it.data,
+                };
+                if (it.overwrite)
+                    row.overwrite = true;
+                return row;
+            }),
+        };
+        const r = await this.request('POST', '/api/v1/json-documents/batch', body);
+        if (r?.results) {
+            for (const row of r.results) {
+                if (row.identifier)
+                    row.identifier = this.isoUnprefixId(String(row.identifier));
+            }
+        }
+        return r;
     }
     async readJsonDocument(identifier) {
         return this.request('GET', `/api/v1/json-documents${buildQuery({ identifier: this.isoPrefixId(identifier) })}`);
@@ -1684,8 +1747,8 @@ 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);
+    async put(identifier, data, opts) {
+        return this.writeJsonDocument(identifier, data, opts);
     }
     /** JSON document read — same as {@link readJsonDocument}. */
     async get(identifier) {

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, Flags, JsonDocumentData, 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, UserIsolationOptions, WorkspaceInfo, WriteDocumentOptions, 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, 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, UserIsolationOptions, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -57,6 +57,7 @@ export interface TextSearchQuery {
     date_to?: string;
 }
 export interface TextSearchHit {
+    /** JSON: document id. XML: first non-xcitepath id from db:identifier, else xcitepath (xcitepath also in `xcitepath`). */
     identifier: string;
     /** Canonical db:xcitepath for XML hits; omitted or empty for JSON. */
     xcitepath?: string;
@@ -67,7 +68,7 @@ export interface TextSearchHit {
     score: number;
     /** Present for semantic / hybrid search. */
     source?: 'fts' | 'semantic' | 'both';
-    /** FTS temporal window for this hit (internal 7-char keys), when returned by the server. */
+    /** FTS temporal validity window for this hit (human-readable UTC, MM/DD/YYYY HH:MM:SS), when returned by the server. */
     valid_from?: string;
     valid_to?: string;
 }
@@ -187,6 +188,15 @@ export interface RagQueryOptions {
     min_score?: number;
     /** Hybrid retrieval only: semantic vs FTS weight in weighted RRF (0–1, default 0.5). */
     semantic_weight?: number;
+    /** Overrides project default when set (0–2). */
+    temperature?: number;
+    /** Overrides project default when set (1–32768). */
+    max_tokens?: number;
+    /** Prior turns; roles `system` | `user` | `assistant`. Current question is separate. */
+    messages?: {
+        role: 'system' | 'user' | 'assistant';
+        content: string;
+    }[];
 }
 export interface RagQueryResult {
     answer: string;
@@ -194,9 +204,9 @@ export interface RagQueryResult {
 }
 /** One SSE JSON payload from streaming RAG (`stream: true`). */
 export type RagStreamEvent = {
-    text: string;
+    text?: string;
     done: false;
-    sources?: undefined;
+    sources?: unknown;
     error?: undefined;
 } | {
     text?: string;
@@ -357,6 +367,29 @@ export interface WriteDocumentOptions {
     is_top?: boolean;
     compare_attributes?: boolean;
 }
+/** One row in `POST /api/v1/documents/batch` or `POST /api/v1/json-documents/batch` response `results`. */
+export interface DocumentBatchResultRow {
+    index: number;
+    identifier: string;
+    ok: boolean;
+    error?: string;
+    code?: number;
+}
+export interface DocumentBatchResponse {
+    results: DocumentBatchResultRow[];
+}
+export interface XmlDocumentBatchItem {
+    xml: string;
+    is_top?: boolean;
+    compare_attributes?: boolean;
+    /** When set, must match canonical root `db:identifier` in `xml` (after server normalization). */
+    identifier?: string;
+}
+export interface JsonDocumentBatchItem {
+    identifier: string;
+    data: unknown;
+    overwrite?: boolean;
+}
 export interface SubscriptionOptions {
     pattern: string;
     event_type?: string;
@@ -551,7 +584,6 @@ export interface PolicyIdentifierPattern {
 }
 export interface PolicyResources {
     identifiers?: PolicyIdentifierPattern[];
-    meta_paths?: string[];
     xml_paths?: string[];
 }
 export interface PolicyConditions {

package/llms-full.txt

@@ -452,14 +452,23 @@ Returns `{ parent_path, parent_is_identifier, children: [{ segment, full_path, i
 
 **`POST /api/v1/json-documents`**
 
+JSON body fields:
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `identifier` | yes | Document path key |
+| `data` | yes | JSON value to merge or store |
+| `overwrite` | no (default `false`) | When `true`, delete all metadata under the document root first, then write `data` only. When `false`, **`data` is merged** into any existing document (nested objects combine fields; nested arrays follow meta merge rules—see Metadata). |
+
 ```json
 {
   "identifier": "app.settings",
-  "data": { "theme": "dark", "maxUploadMb": 25 }
+  "data": { "theme": "dark", "maxUploadMb": 25 },
+  "overwrite": false
 }
 ```
 
-Note: The SDK method uses `identifier` and `data` fields. Some older documentation shows `key` and `value`.
+Note: SDKs use `identifier` and `data` (optional `overwrite`). Some older documentation shows `key` and `value`.
 
 ## Read JSON document
 
@@ -503,15 +512,26 @@ Attach structured **JSON metadata** to documents or nodes.
 
 **`POST /api/v1/meta`**
 
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `identifier` **or** `query` | one required | Target document id or document query |
+| `value` | yes | JSON to write (omit only for string-specific query batch paths handled by the server) |
+| `path` | no (default `""`) | Meta path (dot-separated keys; `[i]` for array indices) |
+| `mode` | no (default `"set"`) | `"set"` — write/replace at `path`. For **arrays** at `path`, indices `0..n-1` are written and any previous tail beyond the new length is cleared. `"append"` — for **arrays** at `path`, new elements are written after existing indices (extend in place). |
+| `overwrite` | no (default `false`) | When `true`, delete existing metadata under `path` before applying `value`. |
+| `first_match` | no | With `query`, only the first matching identifier is updated when `true`. |
+
 ```json
 {
   "identifier": "/book/ch1",
   "value": { "status": "review", "owner": "alice" },
-  "path": ""
+  "path": "",
+  "mode": "set",
+  "overwrite": false
 }
 ```
 
-Optional `"mode": "append"` to append rather than overwrite.
+Use `"mode": "append"` to extend arrays at `path` instead of replacing them.
 
 Can also use `"query"` instead of `"identifier"` to target multiple documents by query filter.
 
@@ -527,6 +547,12 @@ Can also use `"query"` instead of `"identifier"` to target multiple documents by
 
 **`DELETE /api/v1/meta`** — `{ "query": {...} }`
 
+## JSON metadata storage model (best practices)
+
+- **Field-indexed objects.** Metadata and standalone JSON documents share the same shredded-key storage. **JSON objects** map to named paths so fields can be read or updated without loading a monolithic blob.
+- **Dictionary threshold.** When the **set of distinct field names** on an object reaches the server threshold (default **32**, native setting `meta_dict_field_threshold`), XCiteDB switches that object to **dictionary storage** (`{*}` plus per-field keys) for scalable indexed access.
+- **Modeling guidance.** Prefer stable **`{ "key": value, ... }`** / nested-object shapes for records you look up by key. Arrays are appropriate for ordered lists; use **`mode: "append"`** when appending to a stored array.
+
 ---
 
 # Search
@@ -1374,17 +1400,17 @@ interface DatabaseContext {
 - `queryLog(query, fromDate, toDate)` → `LogEntry[]`
 
 ### JSON Documents
-- `writeJsonDocument(identifier, data)` → `void`
+- `writeJsonDocument(identifier, data, opts?)` → `void` — merge by default; `opts?.overwrite` replaces root
 - `readJsonDocument<T>(identifier)` → `T` (default `unknown`)
 - `deleteJsonDocument(identifier)` → `void`
 - `listJsonDocuments(match?, limit?, offset?)` → `ListIdentifiersResult`
-- `put(identifier, data)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases
+- `put(identifier, data, opts?)` / `get<T>(identifier)` / `remove(identifier)` / `list(match?, limit?, offset?)` — JSON CRUD aliases (`opts` same as `writeJsonDocument`)
 
 ### Metadata
-- `addMeta(identifier, value, path?, opts?)` → `boolean`
+- `addMeta(identifier, value, path?, opts?)` → `boolean` — `opts`: `mode?: 'set'|'append'`, `overwrite?: boolean`
 - `addMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
-- `appendMeta(identifier, value, path?)` → `boolean`
-- `appendMetaByQuery(query, value, path?, firstMatch?)` → `boolean`
+- `appendMeta(identifier, value, path?, opts?)` → `boolean` — same as `addMeta` with `mode: 'append'`
+- `appendMetaByQuery(query, value, path?, firstMatch?, opts?)` → `boolean`
 - `queryMeta<T>(identifier, path?)` → `T`
 - `queryMetaByQuery<T>(query, path?)` → `T`
 - `clearMeta(query)` → `boolean`

package/llms.txt

@@ -111,6 +111,12 @@ await app.writeJsonDocument('userdata/alice/profile', { ok: true });
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
 5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `overlay: true`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or provision with **`POST /api/v1/test/sessions`** and JSON **`{"overlay":true}`** when you need overlay, then pass `test_session_token` / `test_require_auth` to the constructor. **C++:** `XCiteDBClient::create_test_session(options)` with optional `test_session_overlay = true`, `destroy_test_session()`, optional `test_require_auth` in options.
 
+## JSON documents and metadata (merge, overwrite, efficiency)
+
+- **JSON documents merge by default.** `POST /api/v1/json-documents` merges the posted `data` into the existing document (object fields combined per XCiteDB meta merge rules). Send **`overwrite: true`** to clear all stored JSON under that document root first, then write only the new payload. SDKs accept the same flag (e.g. `writeJsonDocument(id, data, { overwrite: true })` in JavaScript).
+- **Metadata `mode` and arrays.** **`POST /api/v1/meta`** uses **`mode`**: default **`set`** writes or replaces at `path` (arrays are replaced in range; excess old indices cleared); **`append`** appends array elements after existing ones at `path`. Optional **`overwrite: true`** clears metadata under `path` before writing. JavaScript: **`appendMeta`** or **`addMeta(..., { mode: 'append' })`**; Python/C++: **`append_meta`** or **`add_meta`** with **`mode`** / **`overwrite`** (see SDK sections below).
+- **Prefer dictionary-style objects.** Shredded JSON metadata is keyed by field names. **Object maps** get per-field storage; when an object accumulates enough distinct field names (server default threshold **32**), XCiteDB switches automatically to **dictionary storage** (`{*}` plus per-field keys) for efficient indexed access. For lookup-heavy or wide records, use **`{ "key": value, ... }`** shapes (or one document per logical row) rather than opaque arrays when you need keyed reads.
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -232,15 +238,15 @@ interface XCiteDBClientOptions {
 - `listIdentifierChildren(parentPath?)` — Navigate identifier hierarchy
 
 **JSON Documents:**
-- `writeJsonDocument(identifier, data)` — Store a JSON document
+- `writeJsonDocument(identifier, data, opts?)` — Store or merge a JSON document (`opts?.overwrite` replaces entire document root)
 - `readJsonDocument(identifier)` — Read a JSON document (generic `readJsonDocument<T>()` supported)
 - `deleteJsonDocument(identifier)` — Delete a JSON document
 - `listJsonDocuments(match?, limit?, offset?)` — List JSON document keys
 - **Quick JSON aliases:** `put`, `get`, `remove`, `list` — same as the four methods above
 
 **Metadata (JSON on XML):**
-- `addMeta(identifier, value, path?)` — Set metadata on a document
-- `appendMeta(identifier, value, path?)` — Append to metadata
+- `addMeta(identifier, value, path?, opts?)` — Set or append metadata (`opts?.mode`: `set`|`append`; `opts?.overwrite`)
+- `appendMeta(identifier, value, path?, opts?)` — Append at `path` (same as `addMeta` with `mode: 'append'`)
 - `queryMeta(identifier, path?)` — Read metadata
 - `clearMeta(query)` — Remove metadata
 

package/package.json

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