@xcitedbs/client 0.2.6 → 0.2.7

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteQuery } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteQuery } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -129,17 +129,131 @@ export declare class XCiteDBClient {
     deleteAppUser(userId: string): Promise<void>;
     updateAppUserGroups(userId: string, groups: string[]): Promise<void>;
     updateAppUserStatus(userId: string, status: 'active' | 'disabled' | 'pending_verification'): Promise<void>;
+    /**
+     * Create an ABAC policy (`POST /api/v1/security/policies`). Requires admin/editor role.
+     * Use `conditions.expression` for attribute-based rules (same predicate syntax as Unquery `?` conditions).
+     * Policy actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     *
+     * @example Tenant isolation: first path segment must equal app-user attribute `tenant_code`.
+     * ```ts
+     * await client.createPolicy('tenant_isolation', {
+     *   effect: 'allow',
+     *   priority: 100,
+     *   subjects: { type: 'app_user' },
+     *   actions: ['read'],
+     *   resources: { identifiers: [{ match_start: '/' }] },
+     *   conditions: { expression: 'resource.path[0] = subject.attr.tenant_code' },
+     * });
+     * ```
+     *
+     * @example Deny viewers write access under `/admin/`.
+     * ```ts
+     * await client.createPolicy('deny_viewers_admin', {
+     *   effect: 'deny',
+     *   priority: 10,
+     *   subjects: { type: 'app_user', groups: ['viewers'] },
+     *   resources: { identifiers: [{ match_start: '/admin/' }] },
+     *   actions: ['write', 'delete', 'meta:write'],
+     * });
+     * ```
+     *
+     * @example Branch-only rule via `conditions.branches`.
+     * ```ts
+     * await client.createPolicy('staging_only', {
+     *   effect: 'allow',
+     *   priority: 50,
+     *   subjects: { type: 'app_user', groups: ['qa'] },
+     *   actions: ['read', 'write'],
+     *   resources: { identifiers: [{ match_start: '/staging/' }] },
+     *   conditions: { branches: ['stg', 'stg*'] },
+     * });
+     * ```
+     */
     createPolicy(policyId: string, policy: SecurityPolicy): Promise<StoredPolicyResponse>;
     listPolicies(): Promise<Record<string, SecurityPolicy>>;
     getPolicy(policyId: string): Promise<StoredPolicyResponse>;
     updatePolicy(policyId: string, policy: SecurityPolicy): Promise<PolicyUpdateResponse>;
     deletePolicy(policyId: string): Promise<void>;
+    /**
+     * Create or update a trigger (`POST /api/v1/triggers`). Definitions live under `/_xcitedb/triggers`.
+     * After matching events, the server runs `action.unquery` over `action.query` and writes JSON to
+     * `action.meta_path` on `action.target_identifier` (use `"$trigger_identifier"` for the firing doc).
+     * Unquery can use `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`.
+     *
+     * @example On meta change under `/projects/`, append a snapshot entry to an index document.
+     * ```ts
+     * await client.upsertTrigger('project_meta_index', {
+     *   event: 'meta_changed',
+     *   match: {
+     *     identifiers: [{ match_start: '/projects/' }],
+     *     match_meta_path: 'status',
+     *   },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { lastId: '$trigger_identifier', path: '$trigger_meta_path' },
+     *     target_identifier: '/indexes/project_meta',
+     *     meta_path: 'entries',
+     *     mode: 'append',
+     *   },
+     * });
+     * ```
+     *
+     * @example On document write, write a computed summary onto the same identifier's meta.
+     * ```ts
+     * await client.upsertTrigger('doc_written_summary', {
+     *   event: 'document_written',
+     *   match: { identifiers: [{ match_start: '/articles/' }] },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { id: '$identifier', nodeCount: '$count' },
+     *     target_identifier: '$trigger_identifier',
+     *     meta_path: 'stats',
+     *   },
+     * });
+     * ```
+     */
     upsertTrigger(triggerId: string, trigger: TriggerDefinition): Promise<StoredTriggerResponse>;
     listTriggers(): Promise<Record<string, TriggerDefinition>>;
     getTrigger(name: string): Promise<StoredTriggerResponse>;
     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`.
+     *
+     * @example
+     * ```ts
+     * const r = await client.checkAccess(
+     *   {
+     *     type: 'app_user',
+     *     user_id: 'u1',
+     *     email: 'alice@example.com',
+     *     groups: ['editors'],
+     *     role: 'app_user',
+     *     attributes: { tenant_code: 'acme', level: 5 },
+     *   },
+     *   '/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>;
     getSecurityConfig(): Promise<SecurityConfig>;
+    /**
+     * Update tenant security defaults (`PUT /api/v1/security/config`). When ABAC is enabled, pair
+     * `app_user_default_effect: 'deny'` with explicit allow policies for least privilege.
+     *
+     * @example
+     * ```ts
+     * await client.updateSecurityConfig({
+     *   app_user_default_effect: 'deny',
+     *   default_effect: 'allow',
+     *   developer_bypass: true,
+     * });
+     * ```
+     */
     updateSecurityConfig(config: Partial<SecurityConfig>): Promise<void>;
     createBranch(name: string, fromBranch?: string, fromDate?: string): Promise<void>;
     deleteBranch(name: string): Promise<void>;
@@ -230,7 +344,32 @@ export declare class XCiteDBClient {
     acquireLock(identifier: string, expires?: number): Promise<LockInfo>;
     releaseLock(identifier: string, lockId: string): Promise<boolean>;
     findLocks(identifier: string): Promise<LockInfo[]>;
-    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: unknown): Promise<T>;
+    /**
+     * Run Unquery (`POST /api/v1/unquery`): declarative analytics over documents matching `query`.
+     * The `unquery` argument is a JSON template; keys are output fields, string values are expressions.
+     *
+     * @example Project a meta field into a result key.
+     * ```ts
+     * const out = await client.unquery<{ tag: string }>(
+     *   { match_start: '/manual/' },
+     *   { title: 'chapter_title' }
+     * );
+     * ```
+     *
+     * @example Count matching documents.
+     * ```ts
+     * const out = await client.unquery<{ total: number }>({ match_start: '/orders/' }, { total: '$count' });
+     * ```
+     *
+     * @example XPath from XML (string value must escape quotes for TS).
+     * ```ts
+     * const out = await client.unquery<{ heading: string }>(
+     *   { match: '/book/ch1' },
+     *   { heading: '$xpath("//h1")' }
+     * );
+     * ```
+     */
+    unquery<T = UnqueryResult>(query: XCiteQuery, unquery: UnqueryTemplate): Promise<T>;
     search(q: TextSearchQuery): Promise<TextSearchResult>;
     reindex(): Promise<{
         status: string;

package/dist/client.js

@@ -502,6 +502,46 @@ class XCiteDBClient {
         await this.request('PUT', `/api/v1/app/users/${encodeURIComponent(userId)}/status`, { status });
     }
     // --- Security policies (developer admin/editor) ---
+    /**
+     * Create an ABAC policy (`POST /api/v1/security/policies`). Requires admin/editor role.
+     * Use `conditions.expression` for attribute-based rules (same predicate syntax as Unquery `?` conditions).
+     * Policy actions: `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+     *
+     * @example Tenant isolation: first path segment must equal app-user attribute `tenant_code`.
+     * ```ts
+     * await client.createPolicy('tenant_isolation', {
+     *   effect: 'allow',
+     *   priority: 100,
+     *   subjects: { type: 'app_user' },
+     *   actions: ['read'],
+     *   resources: { identifiers: [{ match_start: '/' }] },
+     *   conditions: { expression: 'resource.path[0] = subject.attr.tenant_code' },
+     * });
+     * ```
+     *
+     * @example Deny viewers write access under `/admin/`.
+     * ```ts
+     * await client.createPolicy('deny_viewers_admin', {
+     *   effect: 'deny',
+     *   priority: 10,
+     *   subjects: { type: 'app_user', groups: ['viewers'] },
+     *   resources: { identifiers: [{ match_start: '/admin/' }] },
+     *   actions: ['write', 'delete', 'meta:write'],
+     * });
+     * ```
+     *
+     * @example Branch-only rule via `conditions.branches`.
+     * ```ts
+     * await client.createPolicy('staging_only', {
+     *   effect: 'allow',
+     *   priority: 50,
+     *   subjects: { type: 'app_user', groups: ['qa'] },
+     *   actions: ['read', 'write'],
+     *   resources: { identifiers: [{ match_start: '/staging/' }] },
+     *   conditions: { branches: ['stg', 'stg*'] },
+     * });
+     * ```
+     */
     async createPolicy(policyId, policy) {
         return this.request('POST', '/api/v1/security/policies', {
             policy_id: policyId,
@@ -524,6 +564,44 @@ class XCiteDBClient {
         await this.request('DELETE', `/api/v1/security/policies/${encodeURIComponent(policyId)}`);
     }
     // --- Triggers (developer admin/editor) ---
+    /**
+     * Create or update a trigger (`POST /api/v1/triggers`). Definitions live under `/_xcitedb/triggers`.
+     * After matching events, the server runs `action.unquery` over `action.query` and writes JSON to
+     * `action.meta_path` on `action.target_identifier` (use `"$trigger_identifier"` for the firing doc).
+     * Unquery can use `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`.
+     *
+     * @example On meta change under `/projects/`, append a snapshot entry to an index document.
+     * ```ts
+     * await client.upsertTrigger('project_meta_index', {
+     *   event: 'meta_changed',
+     *   match: {
+     *     identifiers: [{ match_start: '/projects/' }],
+     *     match_meta_path: 'status',
+     *   },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { lastId: '$trigger_identifier', path: '$trigger_meta_path' },
+     *     target_identifier: '/indexes/project_meta',
+     *     meta_path: 'entries',
+     *     mode: 'append',
+     *   },
+     * });
+     * ```
+     *
+     * @example On document write, write a computed summary onto the same identifier's meta.
+     * ```ts
+     * await client.upsertTrigger('doc_written_summary', {
+     *   event: 'document_written',
+     *   match: { identifiers: [{ match_start: '/articles/' }] },
+     *   action: {
+     *     query: { match: '$trigger_identifier' },
+     *     unquery: { id: '$identifier', nodeCount: '$count' },
+     *     target_identifier: '$trigger_identifier',
+     *     meta_path: 'stats',
+     *   },
+     * });
+     * ```
+     */
     async upsertTrigger(triggerId, trigger) {
         return this.request('POST', '/api/v1/triggers', {
             trigger_id: triggerId,
@@ -544,6 +622,29 @@ class XCiteDBClient {
         const q = buildQuery({ name });
         await this.request('DELETE', `/api/v1/triggers${q}`);
     }
+    /**
+     * 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`.
+     *
+     * @example
+     * ```ts
+     * const r = await client.checkAccess(
+     *   {
+     *     type: 'app_user',
+     *     user_id: 'u1',
+     *     email: 'alice@example.com',
+     *     groups: ['editors'],
+     *     role: 'app_user',
+     *     attributes: { tenant_code: 'acme', level: 5 },
+     *   },
+     *   '/acme/reports/q1',
+     *   'read',
+     *   undefined,
+     *   'main'
+     * );
+     * console.log(r.effect, r.matched_policy_id);
+     * ```
+     */
     async checkAccess(subject, identifier, action, metaPath, branch) {
         const body = { subject, identifier, action };
         if (metaPath !== undefined)
@@ -555,6 +656,19 @@ class XCiteDBClient {
     async getSecurityConfig() {
         return this.request('GET', '/api/v1/security/config');
     }
+    /**
+     * Update tenant security defaults (`PUT /api/v1/security/config`). When ABAC is enabled, pair
+     * `app_user_default_effect: 'deny'` with explicit allow policies for least privilege.
+     *
+     * @example
+     * ```ts
+     * await client.updateSecurityConfig({
+     *   app_user_default_effect: 'deny',
+     *   default_effect: 'allow',
+     *   developer_bypass: true,
+     * });
+     * ```
+     */
     async updateSecurityConfig(config) {
         await this.request('PUT', '/api/v1/security/config', config);
     }
@@ -887,6 +1001,31 @@ class XCiteDBClient {
     async findLocks(identifier) {
         return this.request('GET', `/api/v1/locks${buildQuery({ identifier })}`);
     }
+    /**
+     * Run Unquery (`POST /api/v1/unquery`): declarative analytics over documents matching `query`.
+     * The `unquery` argument is a JSON template; keys are output fields, string values are expressions.
+     *
+     * @example Project a meta field into a result key.
+     * ```ts
+     * const out = await client.unquery<{ tag: string }>(
+     *   { match_start: '/manual/' },
+     *   { title: 'chapter_title' }
+     * );
+     * ```
+     *
+     * @example Count matching documents.
+     * ```ts
+     * const out = await client.unquery<{ total: number }>({ match_start: '/orders/' }, { total: '$count' });
+     * ```
+     *
+     * @example XPath from XML (string value must escape quotes for TS).
+     * ```ts
+     * const out = await client.unquery<{ heading: string }>(
+     *   { match: '/book/ch1' },
+     *   { heading: '$xpath("//h1")' }
+     * );
+     * ```
+     */
     async unquery(query, unquery) {
         return this.request('POST', '/api/v1/unquery', { query, unquery });
     }

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, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, UnqueryResult, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -20,6 +20,13 @@ export type JsonDocumentData = Record<string, unknown>;
 export type MetaValue = unknown;
 /** Result of `unquery` (shape depends on the unquery definition). */
 export type UnqueryResult = unknown;
+/**
+ * Unquery DSL template document. Object keys become output field names; string values are
+ * expressions (e.g. `"$count"`, `"$xpath(\"//title\")"`, or a meta field name). Supports nested
+ * objects, arrays, and `$`-prefixed builtins. See `llms-full.txt` shipped with this package for
+ * the full DSL reference.
+ */
+export type UnqueryTemplate = Record<string, unknown>;
 /** Typical `POST /api/v1/platform/auth/register` response (fields vary by registration policy). */
 export interface PlatformRegisterResult {
     user_id?: string;
@@ -340,6 +347,12 @@ export interface PolicyResources {
 }
 export interface PolicyConditions {
     branches?: string[];
+    /**
+     * Unquery condition expression.
+     * Policies: evaluated against `{ subject, resource, env }`.
+     * Triggers: evaluated against `{ trigger, value, resource, env }` (see server docs).
+     */
+    expression?: string;
 }
 export interface SecurityPolicy {
     description?: string;
@@ -358,6 +371,8 @@ export interface PolicySubjectInput {
     groups?: string[];
     role?: string;
     username?: string;
+    /** Custom app-user attributes (mirrors stored user `attributes`); used by `conditions.expression`. */
+    attributes?: Record<string, unknown>;
 }
 export interface SecurityConfig {
     default_effect: 'allow' | 'deny';
@@ -386,8 +401,29 @@ export interface PolicyUpdateResponse {
     policy: SecurityPolicy;
     warnings?: string[];
 }
-/** Stored trigger document under /_xcitedb/triggers (server-defined shape). */
-export type TriggerDefinition = Record<string, unknown>;
+/** `match` block for stored triggers (`/_xcitedb/triggers`). */
+export interface TriggerMatch {
+    /** Non-empty array of identifier patterns (same shape as policy `resources.identifiers`). */
+    identifiers: PolicyIdentifierPattern[];
+    match_meta_path?: string;
+    match_operation?: 'set' | 'append' | 'delete';
+}
+/** `action` block: run unquery and write result to target meta. */
+export interface TriggerAction {
+    query: XCiteQuery;
+    unquery: UnqueryTemplate;
+    target_identifier: string;
+    meta_path: string;
+    mode?: 'set' | 'append';
+}
+/** Stored trigger document under /_xcitedb/triggers. */
+export interface TriggerDefinition {
+    enabled?: boolean;
+    event: 'meta_changed' | 'document_written' | 'document_deleted';
+    match: TriggerMatch;
+    conditions?: PolicyConditions;
+    action: TriggerAction;
+}
 export interface StoredTriggerResponse {
     trigger_id: string;
     trigger: TriggerDefinition;

package/llms-full.txt

@@ -435,6 +435,122 @@ Executes a structured query document (JSON DSL) for advanced analytics, bulk exp
 
 Unquery supports: hierarchical navigation (self, parents, ancestors, children, descendants), XPath queries on XML, JSON path navigation, counts, sums, string operations, type casting, and conditional branching. Results are always structured JSON.
 
+## Unquery DSL reference
+
+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.
+
+### Core expression builtins (string values)
+
+- **Document / path:** `$identifier`, `$identifier(n)` (path segment by index), `$key`, `$index`, `$path`
+- **XML:** `$xpath("expr")`, `$lxpath("expr")` (leaf / no-children variant), `$xml`, `$xml_no_children`, `$node`, `$attr("name")`, `$child("name")`, `$text(expr)`
+- **Aggregates / size:** `$count`, `$sum(expr)`, `$avg(expr)`, `$min(expr)`, `$max(expr)`, `$size(expr)` (array length), `$length(expr)` (string length)
+- **String ops:** `$lower(expr)`, `$upper(expr)`, `$substr(s,start,len?)`, `$replace(src,from,to,all?)`, `$split(s,delim)`, `$join(arr,delim?)`, `$find`, `$ifind`
+- **Time / casts:** `$now`, `$to_time(expr,fmt?)`, `$time_to_str(expr,fmt?)`, `$string`, `$number`, `$int`, `$float`, `$bool(expr)`
+- **Control:** `$if(cond, then, else)`, `$var(name)` or `%name` (template variables), `$call(name)` (user `#func`), `$prev(default)`
+- **Other:** `$node_date`, `$data_date(expr?)`, `$in_filter("name")`, `$file`, `$csv`, `$env`, `$filename` (last three blocked in safety mode for standalone `evaluateCondition`)
+
+### Key-side syntax (JSON object member **names**, not values)
+
+- Plain names, dotted paths, `[index]`, `$(expression)` / `$expr` for dynamic keys
+- **`#if`**, **`#var`**, **`#assign`**, **`#func name (a,b,…)`**, **`#exists`**, **`#notexists`**, **`#return`**, **`#returnif`**
+- Suffixes on keys: `?condition` (filter branch), `@ ascending` / `@ descending` / `@ unique_ascending` / `@ unique_descending` on values
+- **Context navigation** after `->` (in key paths): `$self`, `$parent`, `$ancestors`, `$ancestors_and_self`, `$children`, `$descendants`, `$descendants_and_self`, `$date`, `$branch`, `$all`, `$var`, `$file`, `$csv`
+
+### Conditions (same grammar as policy `conditions.expression` and Unquery `?` on keys)
+
+Operators: `=`, `!=`, `<`, `>`, `<=`, `>=`, `in`, `not_in`, `contains`, `starts_with`, `ends_with`, `matches`, `is_array`, `is_object`, `is_string`, `is_number`, `is_int`, `is_float`, `is_bool`, `is_literal`. Logic: `&` (AND), `|` (OR), `!` (NOT). Postfix `!` on an expression tests **field exists**.
+
+### Graded examples
+
+**1. Project one meta field into an output key** (per matching document, then combined per engine rules):
+
+```json
+{
+  "query": { "match_start": "/manual/" },
+  "unquery": { "title": "chapter_title" }
+}
+```
+
+**2. Count documents in a prefix:**
+
+```json
+{
+  "query": { "match_start": "/orders/" },
+  "unquery": { "total": "$count" }
+}
+```
+
+**3. XPath from XML:**
+
+```json
+{
+  "query": { "match": "/book/ch1" },
+  "unquery": { "heading": "$xpath(\"//h1\")" }
+}
+```
+
+**4. Nested object with conditional key** (illustrative; exact key syntax may use `#if` blocks for complex trees):
+
+```json
+{
+  "query": { "match_start": "/items/" },
+  "unquery": {
+    "id": "$identifier",
+    "summary": {
+      "len": "$length(title_field)"
+    }
+  }
+}
+```
+
+SDK: `UnqueryTemplate` in `@xcitedbs/client` types; method `unquery(query, unquery)`.
+
+## ABAC policy expression language
+
+Policies may set **`conditions.expression`** (optional) and **`conditions.branches`** (optional array). If `branches` is non-empty, the request branch must match an entry (`"*"`, exact name, or `prefix*`).
+
+### Evaluation context for **policies** (`conditions.expression`)
+
+```json
+{
+  "subject": {
+    "id": "...",
+    "email": "...",
+    "type": "app_user|developer|...",
+    "role": "...",
+    "groups": ["..."],
+    "attr": { }
+  },
+  "resource": {
+    "identifier": "/full/path",
+    "path": ["segment", "segment"]
+  },
+  "env": { "branch": "..." }
+}
+```
+
+`subject.attr` mirrors app-user **custom attributes** from the user record. `resource.path` is the identifier split on `/` (non-empty segments only).
+
+### Operators (predicates)
+
+`=`, `!=`, `>=`, `<=`, `>`, `<`, `in`, `contains`, `starts_with`, `ends_with`, `&`, `|`, `!`, `+` (string concat), postfix `!` (exists).
+
+### Policy action strings (in `actions` arrays)
+
+Use: **`read`**, **`write`**, **`delete`**, **`list`**, **`meta:read`**, **`meta:write`**, **`unquery`**. (Do not use legacy `document:write`-style names in new policies.)
+
+### Copy-pasteable expression recipes (from integration tests)
+
+| Scenario | `conditions.expression` |
+|----------|-------------------------|
+| Tenant isolation (first path segment = user attr) | `resource.path[0] = subject.attr.tenant_code` |
+| Numeric level | `subject.attr.level >= 5` |
+| Project membership (second segment in array attr) | `resource.path[1] in subject.attr.projects` |
+| Boolean feature flag | `subject.attr.beta = true` |
+| Compound + branch (also use `conditions.branches` when needed) | `subject.email ends_with '@company.com' \| (subject.email ends_with '@partner.com' & env.branch = 'stg')` |
+
+Dry-run: **`POST /api/v1/security/check`** with `subject`, `identifier`, `action`, optional `meta_path`, `branch`.
+
 ---
 
 # Branches
@@ -569,27 +685,111 @@ Returns lock info. **`409`** if already locked.
 
 **Base path:** `/api/v1/triggers`
 
+Definitions are stored as JSON under **`/_xcitedb/triggers`**. After a matching event, the server runs **`action.unquery`** over documents selected by **`action.query`**, then writes the resulting JSON to **`action.meta_path`** on **`action.target_identifier`** (elevated privileges inside the same transaction). Nested trigger evaluation is blocked (no infinite loops).
+
 ## Create or update trigger
 
 **`POST /api/v1/triggers`**
 
 ```json
 {
-  "trigger_id": "on_status_review",
+  "trigger_id": "on_project_status_meta",
+  "trigger": {
+    "enabled": true,
+    "event": "meta_changed",
+    "match": {
+      "identifiers": [{ "match_start": "/projects/" }],
+      "match_meta_path": "status",
+      "match_operation": "set"
+    },
+    "conditions": {
+      "branches": ["*", "main"],
+      "expression": "trigger.meta_path = \"status\""
+    },
+    "action": {
+      "query": { "match": "$trigger_identifier" },
+      "unquery": { "id": "$identifier", "status": "status" },
+      "target_identifier": "/indexes/project_status",
+      "meta_path": "entries",
+      "mode": "append"
+    }
+  }
+}
+```
+
+### Trigger fields
+
+| Field | Required | Description |
+|--------|----------|-------------|
+| `enabled` | No (default true) | If false, trigger is skipped. |
+| `event` | Yes | `meta_changed`, `document_written`, or `document_deleted`. |
+| `match` | Yes | Must include **`identifiers`**: non-empty array of identifier patterns (`exact`, `match_start`, `match_end`, `contains`, `regex`). Optional **`match_meta_path`**: exact path or prefix ending with `*`. Optional **`match_operation`**: `set`, `append`, or `delete` (meta / delete ops). |
+| `conditions` | No | Optional **`branches`** (same as policies) and **`expression`** (see below). |
+| `action` | Yes | **`query`** (`XCiteQuery`), **`unquery`** (Unquery DSL template), **`target_identifier`** (literal or `"$trigger_identifier"`), **`meta_path`**, optional **`mode`**: `set` (default) or `append`. |
+
+### Expression context for **triggers** (`conditions.expression`)
+
+Not the same as policies: there is **no `subject`**. Context object:
+
+- **`trigger`**: `{ "event", "meta_path", "operation" }` (`operation`: `set` / `append` / `delete`)
+- **`value`**: JSON written at `meta_path` for `meta_changed`, or null
+- **`resource`**: `{ "identifier", "path" }` for the firing identifier
+- **`env`**: `{ "branch" }`
+
+### Unquery variables injected for triggers
+
+String template vars: **`$trigger_identifier`**, **`$trigger_meta_path`**, **`$trigger_operation`**. JSON var: **`$trigger_value`** (the written value when applicable).
+
+### Recipes
+
+**Meta change → append row to an index document**
+
+```json
+{
+  "trigger_id": "meta_index",
+  "trigger": {
+    "event": "meta_changed",
+    "match": {
+      "identifiers": [{ "match_start": "/docs/" }],
+      "match_meta_path": "reviewed"
+    },
+    "action": {
+      "query": { "match": "$trigger_identifier" },
+      "unquery": { "doc": "$trigger_identifier", "at": "$trigger_meta_path" },
+      "target_identifier": "/indexes/reviews",
+      "meta_path": "log",
+      "mode": "append"
+    }
+  }
+}
+```
+
+**Document written → write stats meta on the same identifier**
+
+```json
+{
+  "trigger_id": "article_stats",
   "trigger": {
-    "match": { "meta_key": "status", "meta_value": "review" },
-    "action": { "type": "webhook", "url": "https://hooks.example.com/xcite" }
+    "event": "document_written",
+    "match": { "identifiers": [{ "match_start": "/articles/" }] },
+    "action": {
+      "query": { "match": "$trigger_identifier" },
+      "unquery": { "id": "$identifier", "nodes": "$count" },
+      "target_identifier": "$trigger_identifier",
+      "meta_path": "stats",
+      "mode": "set"
+    }
   }
 }
 ```
 
 ## List triggers
 
-**`GET /api/v1/triggers`** — Returns map of `{ trigger_id: trigger_definition }`.
+**`GET /api/v1/triggers`** — Returns map of `{ trigger_id: trigger_definition }`. Optional **`?name=`** returns one trigger as `{ trigger_id, trigger }`.
 
 ## Delete trigger
 
-**`DELETE /api/v1/triggers?name=on_status_review`**
+**`DELETE /api/v1/triggers?name=on_project_status_meta`**
 
 ---
 
@@ -609,7 +809,7 @@ Returns lock info. **`409`** if already locked.
     "priority": 10,
     "subjects": { "type": "app_user", "groups": ["viewers"] },
     "resources": { "identifiers": [{ "match_start": "/admin/" }] },
-    "actions": ["document:write", "document:delete"],
+    "actions": ["write", "delete", "meta:write"],
     "conditions": {}
   }
 }
@@ -630,11 +830,11 @@ Returns lock info. **`409`** if already locked.
 {
   "subject": { "type": "app_user", "groups": ["editors"] },
   "identifier": "/admin/config",
-  "action": "document:write"
+  "action": "write"
 }
 ```
 
-Returns `{ effect: "allow"|"deny", matched_policy_id? }`.
+Returns `{ effect: "allow"|"deny", matched_policy_id?, expression_context? }`.
 
 ## Security config
 

package/llms.txt

@@ -206,6 +206,26 @@ interface XCiteDBClientOptions {
 **Triggers:**
 - `upsertTrigger(id, trigger)` / `listTriggers()` / `deleteTrigger(name)` — Automation triggers
 
+### Advanced: policy expressions (ABAC)
+
+- **Actions** (use in `policy.actions`): `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
+- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id`, `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments), `env.branch`.
+- **Operators:** `=`, `!=`, `>=`, `<=`, `>`, `<`, `in`, `contains`, `starts_with`, `ends_with`, `&`, `|`, `!`, `+` (string concat), postfix `!` (exists).
+- **Examples:** `resource.path[0] = subject.attr.tenant_code` — tenant isolation; `subject.attr.level >= 5` — numeric attribute gate.
+
+### Advanced: triggers (stored under `/_xcitedb/triggers`)
+
+- **Events:** `meta_changed`, `document_written`, `document_deleted`.
+- **`match`:** required non-empty **`identifiers`** (same pattern objects as policy `resources.identifiers`); optional **`match_meta_path`** (exact or `prefix*`); optional **`match_operation`:** `set` | `append` | `delete`.
+- **`action`:** **`query`** (document query), **`unquery`** (Unquery template), **`target_identifier`** (or `"$trigger_identifier"`), **`meta_path`**, **`mode`:** `set` | `append`.
+- **Unquery vars:** `$trigger_identifier`, `$trigger_meta_path`, `$trigger_operation`, `$trigger_value`. **Trigger `conditions.expression` context:** `trigger.{event,meta_path,operation}`, `value`, `resource`, `env.branch` (no `subject`).
+
+### Advanced: Unquery DSL (`unquery(query, unqueryDoc)`)
+
+- 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.
+
 **App Users (admin):**
 - `listAppUsers()` / `createAppUser()` / `deleteAppUser()` — Manage end-user accounts
 - `registerAppUser(email, password, displayName?, attributes?)` — Self-registration (groups assigned from server config)

package/package.json

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