@xcitedbs/client 0.2.13 → 0.2.15

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.
      */
@@ -526,6 +529,10 @@ export declare class XCiteDBClient {
     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>;

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.
      */
@@ -1562,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);
@@ -1585,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);
@@ -1664,6 +1696,30 @@ class XCiteDBClient {
             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) })}`);
     }

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

@@ -613,6 +613,8 @@ Unquery supports: hierarchical navigation (self, parents, ancestors, children, d
 
 The `unquery` body is a **JSON template**: each **object key** names an output field; each **value** is either a nested object/array (recursed) or a **string parsed as an expression**. Arrays produce JSON arrays in order.
 
+**Parser-faithful grammar / AST** (for syntax checking, static typing, and tooling): see **`unquery-grammar.md`** shipped next to this file in SDK packages (canonical document in the XciteDB-server repository: `docs/unquery-grammar.md`). The MCP server also exposes it as the resource URI **`xcitedb://unquery-grammar`**.
+
 ### Core expression builtins (string values)
 
 - **Document / path:** `$identifier`, `$identifier(n)` (path segment by index), `$key`, `$index`, `$path`

package/llms.txt

@@ -301,7 +301,7 @@ interface XCiteDBClientOptions {
 
 - JSON **keys** = output fields; **string values** = expressions referencing meta/XML (e.g. field name `"title"` reads meta key `title`).
 - **Common builtins:** `$count`, `$sum(expr)`, `$avg(expr)`, `$min(expr)`, `$max(expr)`, `$xpath("…")`, `$identifier`, `$size(expr)`, `$length(expr)`, `$if(cond, a, b)`, `$var(name)` / `%name`.
-- **Example:** `{ "query": { "match_start": "/orders/" }, "unquery": { "n": "$count" } }` — count documents. Full grammar: **`llms-full.txt`** in this package.
+- **Example:** `{ "query": { "match_start": "/orders/" }, "unquery": { "n": "$count" } }` — count documents. Human-oriented reference: **`llms-full.txt`** in this package. **AI-first writing guide (read this before generating any Unquery query):** **`unquery-ai-guide.md`** (canonical source in the server repo: `docs/unquery-ai-guide.md`; MCP resource `xcitedb://unquery-guide`). **Parser-faithful grammar / parse tree** (syntax + static checks for tooling): **`unquery-grammar.md`** (canonical: `docs/unquery-grammar.md`; MCP resource `xcitedb://unquery-grammar`).
 
 **App Users (admin):**
 - `listAppUsers()` / `createAppUser()` / `deleteAppUser()` — Manage end-user accounts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -41,7 +41,9 @@
   "files": [
     "dist",
     "llms.txt",
-    "llms-full.txt"
+    "llms-full.txt",
+    "unquery-grammar.md",
+    "unquery-ai-guide.md"
   ],
   "license": "MIT"
 }