@xcitedbs/client 0.3.1 → 0.3.3

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, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, 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, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, TriggerEventsResponse, StoredPolicyResponse, TxnRequest, TxnResponse, VerifyAppUserTokenOptions, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -24,6 +24,9 @@ export declare class XCiteDBClient {
     private userIsolation?;
     private cachedAppUserId?;
     private readonly requestTimeoutMs?;
+    private jwksCache?;
+    /** TTL for the JWKS cache; rotations land via `kid` mismatch + force refresh. */
+    private static readonly JWKS_TTL_MS;
     /** Set by {@link XCiteDBClient.createTestSession} when the server returns a `bootstrap` summary. */
     lastTestSessionBootstrap?: TestSessionBootstrapSummary;
     constructor(options: XCiteDBClientOptions);
@@ -47,11 +50,33 @@ export declare class XCiteDBClient {
      */
     static buildProjectGroup(projectId: string, role: 'admin' | 'editor' | 'viewer'): string;
     private static decodeJwtPayloadJson;
+    /** Build {@link XCiteDBJwtClaims} from a decoded JWT payload, or `null` if shape is wrong. */
+    private static claimsFromPayload;
     /**
      * Decode `appUserAccessToken`, or `accessToken` if no app token (platform JWT), without verifying the signature.
      * Use for debugging ABAC (compare `tenant_id` and `groups` to `project:<…>:role` in policies).
      */
     getTokenClaims(): XCiteDBJwtClaims | null;
+    private static decodeJwtHeaderJson;
+    private static base64UrlToBytes;
+    /** Fetch JWKS, honoring the in-memory TTL unless `force` is set. */
+    private fetchJwks;
+    /**
+     * Verify an app-user JWT and return its claims. Validates signature, expiry, and
+     * (unless overridden in {@link VerifyAppUserTokenOptions.expectedTenantId}) tenant scope.
+     *
+     * The verification path depends on the server's `auth.app_users.jwt_algorithm`:
+     * * **`RS256`** — verifies locally against `/.well-known/jwks.json` (cached) using
+     *   `crypto.subtle`. No round-trip per call after the JWKS is cached.
+     * * **`HS256`** — there's no public key the BFF can hold, so the SDK falls back to
+     *   `POST /api/v1/app/auth/verify` (one round-trip). The shape is the same.
+     *
+     * Throws {@link XCiteDBAuthError} on bad signature, expired token, tenant mismatch, or
+     * malformed payload.
+     */
+    verifyAppUserToken(token: string, options?: VerifyAppUserTokenOptions): Promise<XCiteDBJwtClaims>;
+    private verifyRs256Locally;
+    private verifyTokenViaServer;
     private cacheAppUserIdFromPair;
     private clearAppUserIdCache;
     private getAppUserId;
@@ -324,6 +349,13 @@ export declare class XCiteDBClient {
     listTriggers(): Promise<Record<string, TriggerDefinition>>;
     getTrigger(name: string): Promise<StoredTriggerResponse>;
     deleteTrigger(name: string): Promise<void>;
+    /**
+     * Recent trigger firings for the current project (`GET /api/v1/_xcitedb/trigger-events`).
+     *
+     * Newest first. `limit` is clamped server-side to `[1, 500]` (default 100). Only
+     * `admin`/`editor` roles can read this; public-key requests are rejected.
+     */
+    listTriggerEvents(limit?: number): Promise<TriggerEventsResponse>;
     /**
      * 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`, `unquery`.
@@ -838,6 +870,33 @@ export declare class XCiteDBClient {
      * Best-effort batch JSON document writes (`POST /api/v1/json-documents/batch`). Each item is independent; check `results[].ok`.
      */
     writeJsonDocumentsBatch(items: JsonDocumentBatchItem[]): Promise<DocumentBatchResponse>;
+    /**
+     * Atomic multi-operation transaction (`POST /api/v1/txn`). All `operations` and `preconditions`
+     * apply or none do — any failure aborts the whole txn and unexecuted ops carry
+     * `code: 0` with `error: "not executed (atomic txn aborted)"`.
+     *
+     * Operation kinds: `WriteJson`, `WriteXml`, `WriteMeta`, `ClearMetaPath`, `DeleteIdentifier`,
+     * `AddIdentifier`. Precondition kinds: `MetaEquals`, `MetaExists`, `MetaAbsent`,
+     * `DocumentExists`, `DocumentAbsent`. See {@link TxnOperation} / {@link TxnPrecondition} for
+     * field-by-field shapes.
+     *
+     * Pass `idempotency_key` to make safe retries — the server caches the response body for ~24h
+     * so a repeated call returns the original 200 result.
+     *
+     * @example
+     * ```ts
+     * const r = await client.txn({
+     *   preconditions: [{ kind: 'MetaEquals', identifier: '/songs/42', path: 'rating', value: 4 }],
+     *   operations: [
+     *     { kind: 'WriteMeta', identifier: '/songs/42', path: 'rating', value: 5 },
+     *     { kind: 'WriteJson', identifier: '/users/u1/votes/42', data: { score: 5 } },
+     *   ],
+     *   idempotency_key: 'vote-u1-42-v5',
+     * });
+     * if (!r.committed) throw new Error(r.error);
+     * ```
+     */
+    txn(req: TxnRequest): Promise<TxnResponse>;
     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

@@ -9,6 +9,20 @@ function joinUrl(base, path) {
     const p = path.startsWith('/') ? path : `/${path}`;
     return `${b}${p}`;
 }
+function pickJwk(keys, kid) {
+    if (!Array.isArray(keys) || keys.length === 0)
+        return undefined;
+    if (kid) {
+        const byKid = keys.find((k) => k.kid === kid);
+        if (byKid)
+            return byKid;
+    }
+    // No matching kid: only accept a sole RSA signing key — never silently pick from a multi-key set.
+    const rsa = keys.filter((k) => k.kty === 'RSA' && (k.use === 'sig' || k.use === undefined));
+    if (rsa.length === 1)
+        return rsa[0];
+    return undefined;
+}
 function newClientRequestId() {
     const c = globalThis.crypto?.randomUUID?.();
     if (c)
@@ -229,17 +243,8 @@ class XCiteDBClient {
             return null;
         }
     }
-    /**
-     * Decode `appUserAccessToken`, or `accessToken` if no app token (platform JWT), without verifying the signature.
-     * Use for debugging ABAC (compare `tenant_id` and `groups` to `project:<…>:role` in policies).
-     */
-    getTokenClaims() {
-        const raw = this.appUserAccessToken ?? this.accessToken;
-        if (!raw)
-            return null;
-        const p = XCiteDBClient.decodeJwtPayloadJson(raw);
-        if (!p)
-            return null;
+    /** Build {@link XCiteDBJwtClaims} from a decoded JWT payload, or `null` if shape is wrong. */
+    static claimsFromPayload(p) {
         let groups = [];
         const g = p['groups'];
         if (Array.isArray(g)) {
@@ -273,6 +278,209 @@ class XCiteDBClient {
             jti: typeof jti === 'string' ? jti : undefined,
         };
     }
+    /**
+     * Decode `appUserAccessToken`, or `accessToken` if no app token (platform JWT), without verifying the signature.
+     * Use for debugging ABAC (compare `tenant_id` and `groups` to `project:<…>:role` in policies).
+     */
+    getTokenClaims() {
+        const raw = this.appUserAccessToken ?? this.accessToken;
+        if (!raw)
+            return null;
+        const p = XCiteDBClient.decodeJwtPayloadJson(raw);
+        if (!p)
+            return null;
+        return XCiteDBClient.claimsFromPayload(p);
+    }
+    static decodeJwtHeaderJson(token) {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return null;
+        try {
+            let b64 = parts[0].replace(/-/g, '+').replace(/_/g, '/');
+            const pad = (4 - (b64.length % 4)) % 4;
+            b64 += '='.repeat(pad);
+            const g = globalThis;
+            let json = null;
+            if (g.Buffer) {
+                json = g.Buffer.from(b64, 'base64').toString('utf8');
+            }
+            else if (typeof atob === 'function') {
+                json = atob(b64);
+            }
+            if (json === null)
+                return null;
+            return JSON.parse(json);
+        }
+        catch {
+            return null;
+        }
+    }
+    static base64UrlToBytes(b64url) {
+        let b64 = b64url.replace(/-/g, '+').replace(/_/g, '/');
+        const pad = (4 - (b64.length % 4)) % 4;
+        b64 += '='.repeat(pad);
+        const g = globalThis;
+        if (g.Buffer) {
+            const buf = g.Buffer.from(b64, 'base64');
+            // Buffer extends Uint8Array; copy to a fresh view to detach from the underlying pool.
+            return new Uint8Array(buf);
+        }
+        if (typeof atob !== 'function') {
+            throw new types_1.XCiteDBAuthError('No base64 decoder available in this environment', 0, null);
+        }
+        const bin = atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    /** Fetch JWKS, honoring the in-memory TTL unless `force` is set. */
+    async fetchJwks(force) {
+        const now = Date.now();
+        if (!force && this.jwksCache && now - this.jwksCache.fetchedAt < XCiteDBClient.JWKS_TTL_MS) {
+            return this.jwksCache.keys;
+        }
+        const url = joinUrl(this.baseUrl, '/.well-known/jwks.json');
+        const sig = requestTimeoutSignal(this.requestTimeoutMs);
+        const init = { method: 'GET', headers: { Accept: 'application/json' } };
+        if (sig)
+            init.signal = sig;
+        let res;
+        try {
+            res = await fetch(url, init);
+        }
+        catch (e) {
+            throw new types_1.XCiteDBAuthError(`JWKS fetch failed: ${e instanceof Error ? e.message : String(e)}`, 0, null);
+        }
+        if (!res.ok) {
+            throw new types_1.XCiteDBAuthError(`JWKS fetch returned HTTP ${res.status}`, res.status, null);
+        }
+        let body;
+        try {
+            body = (await res.json());
+        }
+        catch {
+            throw new types_1.XCiteDBAuthError('JWKS response was not JSON', 0, null);
+        }
+        const keys = Array.isArray(body?.keys) ? body.keys : [];
+        this.jwksCache = { fetchedAt: now, keys };
+        return keys;
+    }
+    /**
+     * Verify an app-user JWT and return its claims. Validates signature, expiry, and
+     * (unless overridden in {@link VerifyAppUserTokenOptions.expectedTenantId}) tenant scope.
+     *
+     * The verification path depends on the server's `auth.app_users.jwt_algorithm`:
+     * * **`RS256`** — verifies locally against `/.well-known/jwks.json` (cached) using
+     *   `crypto.subtle`. No round-trip per call after the JWKS is cached.
+     * * **`HS256`** — there's no public key the BFF can hold, so the SDK falls back to
+     *   `POST /api/v1/app/auth/verify` (one round-trip). The shape is the same.
+     *
+     * Throws {@link XCiteDBAuthError} on bad signature, expired token, tenant mismatch, or
+     * malformed payload.
+     */
+    async verifyAppUserToken(token, options = {}) {
+        if (typeof token !== 'string' || token.length === 0) {
+            throw new types_1.XCiteDBAuthError('verifyAppUserToken: token must be a non-empty string', 0, null);
+        }
+        const parts = token.split('.');
+        if (parts.length !== 3) {
+            throw new types_1.XCiteDBAuthError('verifyAppUserToken: token is not a compact JWS', 0, null);
+        }
+        const header = XCiteDBClient.decodeJwtHeaderJson(token);
+        const alg = header && typeof header['alg'] === 'string' ? header['alg'] : '';
+        const kid = header && typeof header['kid'] === 'string' ? header['kid'] : '';
+        let claims;
+        if (alg === 'RS256') {
+            claims = await this.verifyRs256Locally(token, kid, options.forceRefreshJwks === true);
+        }
+        else {
+            // HS256 (the server default), or any unknown alg — round-trip to the server.
+            claims = await this.verifyTokenViaServer(token);
+        }
+        const skew = options.clockToleranceSeconds ?? 30;
+        if (typeof claims.exp === 'number') {
+            const nowSec = Math.floor(Date.now() / 1000);
+            if (claims.exp + skew < nowSec) {
+                throw new types_1.XCiteDBAuthError('Token expired', 401, null);
+            }
+        }
+        const expected = options.expectedTenantId !== undefined
+            ? options.expectedTenantId
+            : this.defaultContext.project_id ?? this.defaultContext.tenant_id ?? this.projectId ?? '';
+        if (expected && claims.tenant_id !== expected) {
+            throw new types_1.XCiteDBAuthError(`Token tenant_id "${claims.tenant_id}" does not match expected "${expected}"`, 401, null);
+        }
+        return claims;
+    }
+    async verifyRs256Locally(token, kid, forceRefresh) {
+        const subtle = globalThis.crypto?.subtle;
+        if (!subtle) {
+            throw new types_1.XCiteDBAuthError('verifyAppUserToken: crypto.subtle is unavailable in this environment', 0, null);
+        }
+        let keys = await this.fetchJwks(forceRefresh);
+        let jwk = pickJwk(keys, kid);
+        if (!jwk) {
+            // Possibly a key rotation since we last cached. Force-refresh once and retry.
+            keys = await this.fetchJwks(true);
+            jwk = pickJwk(keys, kid);
+        }
+        if (!jwk) {
+            // JWKS empty → server likely on HS256 (or RS256 not yet provisioned). Fall back.
+            return this.verifyTokenViaServer(token);
+        }
+        let cryptoKey;
+        try {
+            cryptoKey = await subtle.importKey('jwk', jwk, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']);
+        }
+        catch (e) {
+            throw new types_1.XCiteDBAuthError(`JWKS import failed: ${e instanceof Error ? e.message : String(e)}`, 0, null);
+        }
+        const parts = token.split('.');
+        const signed = `${parts[0]}.${parts[1]}`;
+        const sigBytes = XCiteDBClient.base64UrlToBytes(parts[2]);
+        const dataBytes = new TextEncoder().encode(signed);
+        // Copy into fresh ArrayBuffer-backed views — strict TS lib types disallow ArrayBufferLike (SAB).
+        const sigBuf = new ArrayBuffer(sigBytes.byteLength);
+        new Uint8Array(sigBuf).set(sigBytes);
+        const dataBuf = new ArrayBuffer(dataBytes.byteLength);
+        new Uint8Array(dataBuf).set(dataBytes);
+        const ok = await subtle.verify({ name: 'RSASSA-PKCS1-v1_5' }, cryptoKey, sigBuf, dataBuf);
+        if (!ok) {
+            throw new types_1.XCiteDBAuthError('Token signature is invalid', 401, null);
+        }
+        const payload = XCiteDBClient.decodeJwtPayloadJson(token);
+        if (!payload) {
+            throw new types_1.XCiteDBAuthError('Token payload is malformed', 401, null);
+        }
+        const claims = XCiteDBClient.claimsFromPayload(payload);
+        if (!claims) {
+            throw new types_1.XCiteDBAuthError('Token payload is missing required claims', 401, null);
+        }
+        return claims;
+    }
+    async verifyTokenViaServer(token) {
+        try {
+            const r = await this.request('POST', '/api/v1/app/auth/verify', this.mergeAppTenant({ token }));
+            const claims = r?.claims;
+            if (!claims || typeof claims.sub !== 'string' || typeof claims.tenant_id !== 'string') {
+                throw new types_1.XCiteDBAuthError('Server verify returned a malformed claims object', 0, r);
+            }
+            return claims;
+        }
+        catch (e) {
+            if (e instanceof types_1.XCiteDBAuthError)
+                throw e;
+            if (e instanceof types_1.XCiteDBError) {
+                throw new types_1.XCiteDBAuthError(e.message, e.status, e.body, {
+                    reason: e.reason,
+                    serverRequestId: e.serverRequestId,
+                    clientRequestId: e.clientRequestId,
+                });
+            }
+            throw e;
+        }
+    }
     cacheAppUserIdFromPair(pair) {
         if (pair?.user?.user_id) {
             this.cachedAppUserId = pair.user.user_id;
@@ -1201,6 +1409,20 @@ class XCiteDBClient {
         const q = buildQuery({ name });
         await this.request('DELETE', `/api/v1/triggers${q}`);
     }
+    /**
+     * Recent trigger firings for the current project (`GET /api/v1/_xcitedb/trigger-events`).
+     *
+     * Newest first. `limit` is clamped server-side to `[1, 500]` (default 100). Only
+     * `admin`/`editor` roles can read this; public-key requests are rejected.
+     */
+    async listTriggerEvents(limit) {
+        const q = buildQuery({ limit });
+        const r = await this.request('GET', `/api/v1/_xcitedb/trigger-events${q}`);
+        return {
+            events: Array.isArray(r?.events) ? r.events : [],
+            limit: typeof r?.limit === 'number' ? r.limit : 0,
+        };
+    }
     /**
      * 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`, `unquery`.
@@ -2127,6 +2349,8 @@ class XCiteDBClient {
             body.date_from = q.date_from;
         if (q.date_to !== undefined && q.date_to !== '')
             body.date_to = q.date_to;
+        if (q.identifiers && q.identifiers.length > 0)
+            body.identifiers = q.identifiers;
         const data = await this.request('POST', '/api/v1/search', body);
         const hits = [];
         if (Array.isArray(data.hits)) {
@@ -2504,6 +2728,8 @@ class XCiteDBClient {
             body.max_tokens = options.max_tokens;
         if (options.messages?.length)
             body.messages = options.messages;
+        if (options.identifiers && options.identifiers.length > 0)
+            body.identifiers = options.identifiers;
         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);
@@ -2530,6 +2756,9 @@ class XCiteDBClient {
             ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
             ...(options.max_tokens !== undefined ? { max_tokens: options.max_tokens } : {}),
             ...(options.messages?.length ? { messages: options.messages } : {}),
+            ...(options.identifiers && options.identifiers.length > 0
+                ? { identifiers: options.identifiers }
+                : {}),
         });
         for (let attempt = 0; attempt < 2; attempt++) {
             const url = joinUrl(this.baseUrl, path);
@@ -2638,6 +2867,109 @@ class XCiteDBClient {
         }
         return r;
     }
+    /**
+     * Atomic multi-operation transaction (`POST /api/v1/txn`). All `operations` and `preconditions`
+     * apply or none do — any failure aborts the whole txn and unexecuted ops carry
+     * `code: 0` with `error: "not executed (atomic txn aborted)"`.
+     *
+     * Operation kinds: `WriteJson`, `WriteXml`, `WriteMeta`, `ClearMetaPath`, `DeleteIdentifier`,
+     * `AddIdentifier`. Precondition kinds: `MetaEquals`, `MetaExists`, `MetaAbsent`,
+     * `DocumentExists`, `DocumentAbsent`. See {@link TxnOperation} / {@link TxnPrecondition} for
+     * field-by-field shapes.
+     *
+     * Pass `idempotency_key` to make safe retries — the server caches the response body for ~24h
+     * so a repeated call returns the original 200 result.
+     *
+     * @example
+     * ```ts
+     * const r = await client.txn({
+     *   preconditions: [{ kind: 'MetaEquals', identifier: '/songs/42', path: 'rating', value: 4 }],
+     *   operations: [
+     *     { kind: 'WriteMeta', identifier: '/songs/42', path: 'rating', value: 5 },
+     *     { kind: 'WriteJson', identifier: '/users/u1/votes/42', data: { score: 5 } },
+     *   ],
+     *   idempotency_key: 'vote-u1-42-v5',
+     * });
+     * if (!r.committed) throw new Error(r.error);
+     * ```
+     */
+    async txn(req) {
+        if (!req || !Array.isArray(req.operations) || req.operations.length === 0) {
+            throw new types_1.XCiteDBError('txn: operations must be a non-empty array', 400, null);
+        }
+        const operations = req.operations.map((op) => {
+            const out = { kind: op.kind, identifier: this.isoPrefixId(op.identifier) };
+            switch (op.kind) {
+                case 'WriteJson':
+                    out.data = op.data;
+                    if (op.overwrite)
+                        out.overwrite = true;
+                    break;
+                case 'WriteXml':
+                    out.xml = this.isoApplyXmlDbIdentifier(op.xml);
+                    if (op.is_top)
+                        out.is_top = true;
+                    if (op.compare_attributes)
+                        out.compare_attributes = true;
+                    break;
+                case 'WriteMeta':
+                    out.value = op.value;
+                    if (op.path !== undefined)
+                        out.path = op.path;
+                    if (op.mode !== undefined)
+                        out.mode = op.mode;
+                    if (op.overwrite)
+                        out.overwrite = true;
+                    break;
+                case 'ClearMetaPath':
+                    out.path = op.path;
+                    break;
+                case 'DeleteIdentifier':
+                case 'AddIdentifier':
+                    break;
+            }
+            return out;
+        });
+        const body = { operations };
+        if (req.preconditions && req.preconditions.length > 0) {
+            body.preconditions = req.preconditions.map((p) => {
+                const out = { kind: p.kind, identifier: this.isoPrefixId(p.identifier) };
+                switch (p.kind) {
+                    case 'MetaEquals':
+                        out.value = p.value;
+                        if (p.path !== undefined)
+                            out.path = p.path;
+                        break;
+                    case 'MetaExists':
+                    case 'MetaAbsent':
+                        if (p.path !== undefined)
+                            out.path = p.path;
+                        break;
+                    case 'DocumentExists':
+                    case 'DocumentAbsent':
+                        break;
+                }
+                return out;
+            });
+        }
+        if (req.idempotency_key !== undefined)
+            body.idempotency_key = req.idempotency_key;
+        const r = await this.request('POST', '/api/v1/txn', body);
+        // Un-prefix identifiers in the response so callers see what they passed in.
+        if (Array.isArray(r?.results)) {
+            for (const row of r.results) {
+                if (row?.identifier)
+                    row.identifier = this.isoUnprefixId(String(row.identifier));
+            }
+        }
+        if (Array.isArray(r?.preconditions)) {
+            for (const row of r.preconditions) {
+                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) })}`);
     }
@@ -2710,3 +3042,5 @@ class XCiteDBClient {
     }
 }
 exports.XCiteDBClient = XCiteDBClient;
+/** TTL for the JWKS cache; rotations land via `kid` mismatch + force refresh. */
+XCiteDBClient.JWKS_TTL_MS = 10 * 60 * 1000;

package/dist/client.test.js

@@ -385,3 +385,134 @@ const types_js_1 = require("./types.js");
         }
     });
 });
+(0, node_test_1.describe)('txn wrapper', () => {
+    (0, node_test_1.it)('rejects empty operations array client-side', async () => {
+        const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+        await strict_1.default.rejects(c.txn({ operations: [] }), /non-empty/);
+    });
+    (0, node_test_1.it)('serializes mixed ops + preconditions and unprefixes response identifiers', async () => {
+        const captured = { value: null };
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            captured.value = {
+                url: String(input),
+                body: JSON.parse(String(init?.body ?? '{}')),
+            };
+            return new Response(JSON.stringify({
+                committed: true,
+                preconditions: [
+                    { index: 0, identifier: '/users/u1/songs/42', kind: 'MetaEquals', ok: true },
+                ],
+                results: [
+                    { index: 0, identifier: '/users/u1/songs/42', kind: 'WriteMeta', ok: true, code: 200 },
+                    { index: 1, identifier: '/users/u1/votes/42', kind: 'WriteJson', ok: true, code: 200 },
+                ],
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                userIsolation: { enabled: true, namespace: '/users/{userId}' },
+            });
+            c.setAppUserTokens('h.eyJzdWIiOiJ1MSJ9.s');
+            const r = await c.txn({
+                preconditions: [{ kind: 'MetaEquals', identifier: '/songs/42', path: 'rating', value: 4 }],
+                operations: [
+                    { kind: 'WriteMeta', identifier: '/songs/42', path: 'rating', value: 5 },
+                    { kind: 'WriteJson', identifier: '/votes/42', data: { score: 5 } },
+                ],
+                idempotency_key: 'abc',
+            });
+            strict_1.default.equal(r.committed, true);
+            // identifiers come back un-prefixed back to caller's namespace.
+            strict_1.default.equal(r.results[0].identifier, '/songs/42');
+            strict_1.default.equal(r.results[1].identifier, '/votes/42');
+            strict_1.default.equal(r.preconditions[0].identifier, '/songs/42');
+            strict_1.default.ok(captured.value);
+            strict_1.default.match(captured.value.url, /\/api\/v1\/txn$/);
+            const body = captured.value.body;
+            strict_1.default.equal(body.idempotency_key, 'abc');
+            const ops = body.operations;
+            strict_1.default.equal(ops[0].identifier, '/users/u1/songs/42');
+            strict_1.default.equal(ops[0].kind, 'WriteMeta');
+            strict_1.default.equal(ops[0].value, 5);
+            strict_1.default.equal(ops[1].identifier, '/users/u1/votes/42');
+            const pre = body.preconditions;
+            strict_1.default.equal(pre[0].identifier, '/users/u1/songs/42');
+            strict_1.default.equal(pre[0].value, 4);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('verifyAppUserToken', () => {
+    (0, node_test_1.it)('rejects malformed tokens client-side (not a compact JWS)', async () => {
+        const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+        await strict_1.default.rejects(c.verifyAppUserToken('only.two-segments'), /compact JWS/);
+        await strict_1.default.rejects(c.verifyAppUserToken(''), /non-empty/);
+    });
+    (0, node_test_1.it)('falls back to /api/v1/app/auth/verify for HS256 and enforces tenant', async () => {
+        // Token with header alg=HS256 — SDK should not try JWKS, it should POST /verify.
+        // header { alg: HS256 } base64url, payload arbitrary, sig dummy.
+        const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+        const payload = Buffer.from(JSON.stringify({ sub: 'u1', tenant_id: 't1' })).toString('base64url');
+        const token = `${header}.${payload}.sig`;
+        const orig = globalThis.fetch;
+        let path = '';
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            path = String(input);
+            return new Response(JSON.stringify({
+                claims: {
+                    sub: 'u1',
+                    tenant_id: 't1',
+                    groups: ['g'],
+                    email: 'a@b',
+                    exp: Math.floor(Date.now() / 1000) + 3600,
+                },
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                apiKey: 'k',
+                projectId: 't1',
+                context: { project_id: 't1' },
+            });
+            const claims = await c.verifyAppUserToken(token);
+            strict_1.default.match(path, /\/api\/v1\/app\/auth\/verify$/);
+            strict_1.default.equal(claims.sub, 'u1');
+            strict_1.default.equal(claims.tenant_id, 't1');
+            // Tenant mismatch must throw.
+            await strict_1.default.rejects(c.verifyAppUserToken(token, { expectedTenantId: 'other' }), /tenant_id/);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('listTriggerEvents', () => {
+    (0, node_test_1.it)('passes limit and parses events', async () => {
+        let url = '';
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            url = String(input);
+            return new Response(JSON.stringify({
+                events: [{ id: '1', trigger: 't', identifier: '/x', at: '...', status: 'ok' }],
+                limit: 50,
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' });
+            const r = await c.listTriggerEvents(50);
+            strict_1.default.match(url, /\/api\/v1\/_xcitedb\/trigger-events\?limit=50$/);
+            strict_1.default.equal(r.limit, 50);
+            strict_1.default.equal(r.events.length, 1);
+            strict_1.default.equal(r.events[0].trigger, 't');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { XCiteDBClient } from './client';
 export { parseAssetUri, formatAssetUri, collectIdentifiersFromText, ASSET_URI_PREFIX } from './assetUri';
 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, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, 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, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, 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, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TriggerEvent, TriggerEventsResponse, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -55,6 +55,13 @@ export interface TextSearchQuery {
     /** Range FTS filter: interval overlap with [date_from, date_to) (ISO dates). */
     date_from?: string;
     date_to?: string;
+    /**
+     * Restrict hits to documents whose identifier matches one of these patterns.
+     * Same shape as `policies.resources.identifiers` and `triggers.resources.identifiers`:
+     * within one entry the recognized keys AND together (and `contains` arrays AND across substrings);
+     * across the array entries OR. Empty array = no filtering.
+     */
+    identifiers?: PolicyIdentifierPattern[];
 }
 export interface TextSearchHit {
     /** JSON: document id. XML: first non-xcitepath id from db:identifier, else xcitepath (xcitepath also in `xcitepath`). */
@@ -344,6 +351,11 @@ export interface RagQueryOptions {
         role: 'system' | 'user' | 'assistant';
         content: string;
     }[];
+    /**
+     * Restrict the documents pulled into RAG context by identifier pattern.
+     * Same shape as {@link TextSearchQuery.identifiers}.
+     */
+    identifiers?: PolicyIdentifierPattern[];
 }
 export interface RagQueryResult {
     answer: string;
@@ -1115,6 +1127,146 @@ export interface RebaseUserWorkspaceResult {
     auto_mergeable?: string[];
     would_expose?: string[];
 }
+/** One mutation within a {@link XCiteDBClient.txn} call. */
+export type TxnOperation = {
+    kind: 'WriteJson';
+    identifier: string;
+    data: unknown;
+    overwrite?: boolean;
+} | {
+    kind: 'WriteXml';
+    identifier: string;
+    xml: string;
+    is_top?: boolean;
+    compare_attributes?: boolean;
+} | {
+    kind: 'WriteMeta';
+    identifier: string;
+    value: unknown;
+    path?: string;
+    mode?: 'set' | 'append' | 'merge_append';
+    overwrite?: boolean;
+} | {
+    kind: 'ClearMetaPath';
+    identifier: string;
+    path: string;
+} | {
+    kind: 'DeleteIdentifier';
+    identifier: string;
+} | {
+    kind: 'AddIdentifier';
+    identifier: string;
+};
+/** One precondition checked under the same transaction (must pass for the writes to apply). */
+export type TxnPrecondition = {
+    kind: 'MetaEquals';
+    identifier: string;
+    path?: string;
+    value: unknown;
+} | {
+    kind: 'MetaExists';
+    identifier: string;
+    path?: string;
+} | {
+    kind: 'MetaAbsent';
+    identifier: string;
+    path?: string;
+} | {
+    kind: 'DocumentExists';
+    identifier: string;
+} | {
+    kind: 'DocumentAbsent';
+    identifier: string;
+};
+export interface TxnRequest {
+    operations: TxnOperation[];
+    preconditions?: TxnPrecondition[];
+    /**
+     * Optional idempotency key. The server caches the response body for ~24h; replays return the
+     * original 200 with `committed:true` and an additional `idempotency_hit` discriminator can be
+     * inferred from a successful repeat call.
+     */
+    idempotency_key?: string;
+}
+export interface TxnPreconditionResult {
+    index: number;
+    identifier: string;
+    kind: TxnPrecondition['kind'];
+    ok: boolean;
+    error?: string;
+}
+export interface TxnOperationResult {
+    index: number;
+    identifier: string;
+    kind: TxnOperation['kind'];
+    ok: boolean;
+    /** HTTP-style code per op; 0 means "not executed because the txn aborted". */
+    code: number;
+    error?: string;
+}
+export interface TxnResponse {
+    committed: boolean;
+    /** Index of the failing precondition when the txn aborted on a precondition. */
+    first_failed_precond?: number;
+    /** Index of the failing operation when the txn aborted on an op. */
+    first_failure_index?: number;
+    code?: number;
+    error?: string;
+    preconditions: TxnPreconditionResult[];
+    results: TxnOperationResult[];
+}
+/** A persisted trigger firing record. */
+export interface TriggerEvent {
+    /** Unique id for the firing (sortable; newer first when listing). */
+    id?: string;
+    /** Trigger name that fired. */
+    trigger?: string;
+    /** Identifier whose write caused the firing. */
+    identifier?: string;
+    /** Server-assigned ISO timestamp. */
+    at?: string;
+    /** Outcome — `ok` or `error` for synchronous triggers. */
+    status?: string;
+    /** Free-form details (matched value, error message). */
+    detail?: unknown;
+    [key: string]: unknown;
+}
+export interface TriggerEventsResponse {
+    events: TriggerEvent[];
+    limit: number;
+}
+/** Single key entry from `GET /.well-known/jwks.json` (RFC 7517). */
+export interface JwksKey {
+    kty: string;
+    use?: string;
+    alg?: string;
+    kid?: string;
+    /** RSA modulus (base64url) — present for `kty: "RSA"`. */
+    n?: string;
+    /** RSA public exponent (base64url) — present for `kty: "RSA"`. */
+    e?: string;
+    [key: string]: unknown;
+}
+export interface JwksResponse {
+    keys: JwksKey[];
+}
+/** Options for {@link XCiteDBClient.verifyAppUserToken}. */
+export interface VerifyAppUserTokenOptions {
+    /**
+     * Override the expected `tenant_id` claim. When omitted, the client's configured
+     * `tenant_id` / `project_id` is used. Pass an empty string to skip the check.
+     */
+    expectedTenantId?: string;
+    /**
+     * Clock-skew tolerance for `exp` in seconds (default 30). Set to 0 for strict comparison.
+     */
+    clockToleranceSeconds?: number;
+    /**
+     * Force a re-fetch of the JWKS even if a cached copy is fresh. Useful right after a key
+     * rotation — normally the cache TTL handles this on its own.
+     */
+    forceRefreshJwks?: boolean;
+}
 /**
  * Canonical 403 `reason` codes the server can emit. Use as a discriminator on
  * `XCiteDBForbiddenError.reason` in catch sites — TypeScript will warn if you forget a case.

package/llms.txt

@@ -323,6 +323,7 @@ interface XCiteDBClientOptions {
 - `loginAppUser(email, password)` — App end-user sign-in
 - `XCiteDBClient.buildProjectGroup(projectId, 'admin'|'editor'|'viewer')` — Static helper: canonical `project:<tenant_id>:<role>` string
 - `getTokenClaims()` — Decode current `appUserAccessToken` or `accessToken` payload (no signature verification); use for ABAC debugging
+- `verifyAppUserToken(token, options?)` — **BFF token verifier.** Validates signature, expiry, and (by default) the `tenant_id` claim against the client's configured project. RS256 deployments verify locally against `/.well-known/jwks.json` (cached; key rotations land via `kid` mismatch + auto refresh). HS256 deployments fall back to `POST /api/v1/app/auth/verify` (one round-trip; the same shape comes back). Throws `XCiteDBAuthError` on bad signature, expired, or tenant mismatch. Options: `expectedTenantId` (override; pass `''` to skip), `clockToleranceSeconds` (default 30), `forceRefreshJwks`. Returns `XCiteDBJwtClaims` (sub/tenant_id/groups/email/exp/iat/iss/jti/type).
 - `setContext(ctx)` — Update workspace/date context
 - `setProjectId(id)` — Switch active project (platform console)
 
@@ -381,9 +382,9 @@ interface XCiteDBClientOptions {
 - 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).
+- `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). Optional **`identifiers`** — array of pattern objects (`exact` / `match_start` / `match_end` / `contains` / `regex`, same shape as policy `resources.identifiers`) restricts hits to matching documents (entries OR; keys within an entry AND).
 - `reindex()` — Rebuild search index
-- `unquery(query, unqueryDoc)` — Execute Unquery DSL
+- `unquery(query, unqueryDoc)` — Execute Unquery DSL. Postfix slicing supported: `field[start:end]` with optional negative indices on a JSON array yields a sliced array.
 
 **Security & Policies:**
 - `createPolicy(id, policy)` / `listPolicies()` / `updatePolicy()` / `deletePolicy()` — ABAC policies
@@ -392,6 +393,13 @@ interface XCiteDBClientOptions {
 
 **Triggers:**
 - `upsertTrigger(id, trigger)` / `listTriggers()` / `deleteTrigger(name)` — Automation triggers
+- `listTriggerEvents(limit?)` — `GET /api/v1/_xcitedb/trigger-events`; recent firings (newest first; clamp 1..500, default 100). Admin/editor only; public-key contexts rejected.
+
+**Atomic transactions:**
+- `txn({ operations, preconditions?, idempotency_key? })` — `POST /api/v1/txn`. All-or-nothing across mixed kinds (`WriteJson`, `WriteXml`, `WriteMeta`, `ClearMetaPath`, `DeleteIdentifier`, `AddIdentifier`) with optional preconditions (`MetaEquals`, `MetaExists`, `MetaAbsent`, `DocumentExists`, `DocumentAbsent`). Pass `idempotency_key` to make safe retries — server caches the response body for ~24h so a repeated call replays the original 200. Response: `{ committed, first_failed_precond?, first_failure_index?, code?, error?, preconditions[], results[] }`. Unexecuted ops on abort carry `code: 0` with `error: "not executed (atomic txn aborted)"`.
+
+**RAG:**
+- `ragQuery(options)` / `ragQueryStream(options, onEvent)` — Retrieval-augmented Q&A. Optional **`identifiers`** restricts the documents pulled into context (same shape as `search` filter).
 
 ### Advanced: policy expressions (ABAC)
 

package/package.json

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

package/unquery-ai-guide.md

@@ -85,6 +85,7 @@ A path selects a value from the current context.
 | `[n]` | Array index (0-based) | `"Dependants[0].FirstName"` |
 | `[expr]` | Computed index | `"Field1[$index+1]"` |
 | `[]` | Whole array (projection over all elements) | `"Array1[].Field1"` |
+| `[a:b]` | Array **slice** in a context modifier (half-open; negative counts from end) | `"scores:[0:3]"`, `"scores:[-2:]"` |
 | `/Field` | Absolute from document root | `"/employees.$(.)"` |
 | `../Field` | Up one path level (skips array indices) | `"../DBInstanceIdentifier"` |
 | `<<Field` | Read same field in *previous* document context | `"<<Field1"` after a `->$file(...)` |
@@ -259,18 +260,21 @@ Equivalent to SQL `GROUP BY bin`. Combine with aggregate values for grouped stat
 { "$(Title)": "$avg(Salary)" }
 ```
 
-### 5.4 Copy-all keys — `{}` and `{'regex'}`
+### 5.4 Copy-all keys — `{}`, `{'regex'}`, and slice `{a:b}`
 
-`{}` evaluates to *every* key in the queried object. `{'regex'}` evaluates to keys matching the regex.
+`{}` evaluates to *every* key in the queried object. `{'regex'}` evaluates to keys matching the regex. `{a:b}` is a positional **slice** of the source-key sequence (half-open, negative values count from the end) — keys are visited in their stored sort order, so this naturally gives "first K", "last K", or a middle range.
 
 ```json
 { "{}": "value" }                  // every key gets the constant 'value' (rarely useful)
 { "{}:": "." }                     // copy every key → its value (very useful)
 { "{'A.*B'}:": "." }               // copy only keys matching the regex
 { "{}:": ".?$key!='ID'" }          // copy all except ID (predicate filter)
+{ "{:3}:": "." }                   // first 3 keys (alphabetical)
+{ "{-2:}:": "." }                  // last 2 keys
+{ "{2:5}:": "." }                  // keys at positions 2..4 inclusive
 ```
 
-The trailing `:` after `{}` is a context modifier ("for each key, switch context to that key"). Without `:`, `{}` is just the empty-key spec.
+The trailing `:` after `{}` is a context modifier ("for each key, switch context to that key"). Without `:`, `{}` is just the empty-key spec. The slice form `{a:b}` mirrors the array slice `[a:b]` (see §4 path expressions and §6 context modifiers): `{:K}` is the first K, `{-K:}` the last K, `{a:b}` the half-open range.
 
 ### 5.5 Key utility functions
 
@@ -298,7 +302,9 @@ A modifier may be followed by `?cond` (predicate). Modifiers chain freely.
 | `:` (nothing after) | Repeat the key name as the path: `"Field1:"` ≡ `"Field1:Field1"` |
 | `:[]` | Iterate over each array element |
 | `:[n]` | Switch to array index `n` |
+| `:[a:b]` | Iterate over the array **slice** at indices `a..b` (half-open; negative counts from end) |
 | `:{}` | Iterate over each object field |
+| `:{a:b}` | Iterate over the object-key **slice** at positions `a..b` (half-open; negative counts from end) |
 | `:{'regex'}` | Iterate over fields matching regex |
 | `:**` | Recursive descent (every path under current) |
 | `:.` | Stay at current path (rarely needed) |
@@ -308,8 +314,18 @@ A modifier may be followed by `?cond` (predicate). Modifiers chain freely.
 { "result:Customers[]?Balance>100000:Accounts[]": ["accountNumber"] }
 { "result:{}": ["."] }
 { "#return:**": ["$key@unique_ascending"] }
+{ "first:scores[:3]": ["."] }              // first 3 elements of `scores`
+{ "tail:scores[-2:]": ["."] }              // last 2 elements
+{ "middle:scores[2:5]": ["."] }            // elements at positions 2..4
 ```
 
+**Slice semantics** (same shape for arrays and object-key iteration):
+- `[:K]` / `{:K}` — first K (start defaults to 0).
+- `[K:]` / `{K:}` — from index K to end.
+- `[a:b]` / `{a:b}` — half-open range `[a, b)`.
+- `[-K:]` / `{-K:}` — last K (negative values count from the end).
+- Out-of-range bounds are clamped; `b ≤ a` yields an empty result.
+
 ### 6.2 The `:Field` shorthand (very common)
 
 `"FirstName:"` is identical to `"FirstName:FirstName"`. Use it whenever the result key matches the source field:

package/unquery-grammar.md

@@ -151,7 +151,7 @@ Roughly in parse order:
 
 | Prefix / form | AST | Notes |
 |-----------------|-----|--------|
-| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. |
+| `[` optional `]` | `TExprSubfield(TExprField("."), expr?, is_index)` | `[]` = whole array on current `.`; `[e]` = index. (Slice `[a:b]` form is currently parsed only on context modifiers, not in path expressions.) |
 | `$` `(` `expression` `)` | `TExprField(expr)` | Evaluate / path from dynamic name (`$()`). |
 | `$if` `(` `condition` `,` `expression` `,` `expression` `)` | `TExprITE` | |
 | `$call` `(` IDENT `)` | `TExprCall(name)` | Zero-arg user function by name. |
@@ -294,9 +294,12 @@ key ::= '$' '(' expression ')'              (* dynamic key → TQParamKey *)
      | '$' IDENT ... | '%' IDENT ...       (* whole thing parsed as expression() → TQParamKey *)
      | '{' '}'                             (* TQRegexKey empty regex *)
      | '{' QUOTED '}'                      (* TQRegexKey *)
+     | '{' slice '}'                       (* TQRegexKey + slice over source-key sequence *)
      | '#' directive
      | pathId                              (* TQSimpleKey, name may include quoted segments from pathId *)
 
+slice ::= INT? ':' INT?                    (* INT may be `-` INT for negative-from-end *)
+
 directive ::= 'if'
            | 'func' IDENT ( '(' IDENT ( ',' IDENT )* ')' )?   (* register arity; TQFuncDefinition *)
            | 'var' IDENT
@@ -336,8 +339,10 @@ Parsed **after** `key()` from the **same** JSON key string. Mode parameter `Cont
 | `->` … | `Arrow` | See §8.2 (`identifierExpression`, builtins, legacy JSON-field lookup, `->$each`); often `new_frame = true` |
 | `[` `]` | `Array` | traversal |
 | `[` INT `]` | *(string context)* | literal index path segment |
+| `[` (INT)? `:` (INT)? `]` | `Array` + slice | half-open slice; sets `array_slice_set` and the start/end fields on the `TQContextMod`. Negative ints count from end. (`-` token + INT recognized.) |
 | `.` | *(path)* | context string `"."` |
 | IDENT… `[` `]`? | `Array` if trailing `[]`, else path | Empty path + no `[` → **`Reskey`** mode |
+| IDENT… `[` slice `]` | `Array` + slice | `Field[a:b]` after a path |
 | Optional `?` `condition` after each atom | — | Wraps inner mod chain in `TQValueWithCond` |
 
 Recursion: `context_mod(...)` parses the **rest** of the chain; result wrapped in `TQContextMod` (expr or string form).