@xcitedbs/client 0.2.5 → 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, 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;
@@ -14,7 +14,18 @@ export declare class XCiteDBClient {
     private onSessionTokensUpdated?;
     private onAppUserTokensUpdated?;
     private onSessionInvalid?;
+    private testSessionToken?;
+    private testRequireAuth?;
     constructor(options: XCiteDBClientOptions);
+    /**
+     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     */
+    static createTestSession(opts: CreateTestSessionOptions): Promise<XCiteDBClient>;
+    /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
+    destroyTestSession(): Promise<{
+        message: string;
+    }>;
     /** True if this client would send API key or Bearer credentials on a normal request. */
     private sentAuthCredentials;
     /** 401 on these paths is an expected auth flow outcome, not a dead session. */
@@ -34,6 +45,7 @@ export declare class XCiteDBClient {
     /** Include `tenant_id` for public app-auth routes when using only app-user tokens (no developer key/JWT). */
     private mergeAppTenant;
     private authHeaders;
+    private testHeaders;
     private request;
     /** Developer Bearer refresh first, then app-user refresh (no API key refresh). */
     private tryRefreshSessionAfter401;
@@ -83,7 +95,7 @@ export declare class XCiteDBClient {
     createApiKey(name: string, expiresAt?: number, keyType?: 'secret' | 'public'): Promise<unknown>;
     changePassword(currentPassword: string, newPassword: string): Promise<void>;
     revokeApiKey(keyId: string): Promise<void>;
-    registerAppUser(email: string, password: string, displayName?: string, groups?: string[], attributes?: Record<string, unknown>): Promise<AppUser>;
+    registerAppUser(email: string, password: string, displayName?: string, attributes?: Record<string, unknown>): Promise<AppUser>;
     getOAuthProviders(): Promise<OAuthProvidersResponse>;
     /** Relative path + query for browser navigation to start OAuth (append to API base URL). */
     oauthAuthorizePath(provider: string): string;
@@ -117,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>;
@@ -218,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

@@ -31,6 +31,50 @@ class XCiteDBClient {
         this.onSessionTokensUpdated = options.onSessionTokensUpdated;
         this.onAppUserTokensUpdated = options.onAppUserTokensUpdated;
         this.onSessionInvalid = options.onSessionInvalid;
+        this.testSessionToken = options.testSessionToken;
+        this.testRequireAuth = options.testRequireAuth === true;
+    }
+    /**
+     * Create an ephemeral isolated database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
+     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     */
+    static async createTestSession(opts) {
+        const temp = new XCiteDBClient({
+            baseUrl: opts.baseUrl,
+            apiKey: opts.apiKey,
+            accessToken: opts.accessToken,
+            appUserAccessToken: opts.appUserAccessToken,
+            appUserRefreshToken: opts.appUserRefreshToken,
+            context: opts.context,
+            platformConsole: opts.platformConsole,
+            projectId: opts.projectId,
+            onSessionTokensUpdated: opts.onSessionTokensUpdated,
+            onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
+            onSessionInvalid: opts.onSessionInvalid,
+        });
+        const data = await temp.request('POST', '/api/v1/test/sessions', undefined, undefined, { no401Retry: true });
+        return new XCiteDBClient({
+            baseUrl: opts.baseUrl,
+            apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
+            accessToken: opts.testRequireAuth ? opts.accessToken : undefined,
+            appUserAccessToken: opts.testRequireAuth ? opts.appUserAccessToken : undefined,
+            appUserRefreshToken: opts.testRequireAuth ? opts.appUserRefreshToken : undefined,
+            context: opts.context,
+            platformConsole: opts.platformConsole,
+            projectId: opts.projectId,
+            onSessionTokensUpdated: opts.onSessionTokensUpdated,
+            onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
+            onSessionInvalid: opts.onSessionInvalid,
+            testSessionToken: data.session_token,
+            testRequireAuth: opts.testRequireAuth,
+        });
+    }
+    /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
+    async destroyTestSession() {
+        if (!this.testSessionToken) {
+            throw new Error('destroyTestSession: client has no testSessionToken');
+        }
+        return this.request('DELETE', '/api/v1/test/sessions/current', undefined, undefined, { no401Retry: true });
     }
     /** True if this client would send API key or Bearer credentials on a normal request. */
     sentAuthCredentials() {
@@ -132,6 +176,16 @@ class XCiteDBClient {
         }
         return h;
     }
+    testHeaders() {
+        const h = {};
+        if (this.testSessionToken) {
+            h['X-Test-Session'] = this.testSessionToken;
+            if (this.testRequireAuth) {
+                h['X-Test-Auth'] = 'required';
+            }
+        }
+        return h;
+    }
     async request(method, path, body, extraHeaders, opts) {
         const no401Retry = opts?.no401Retry === true;
         for (let attempt = 0; attempt < 2; attempt++) {
@@ -139,6 +193,7 @@ class XCiteDBClient {
             const headers = {
                 ...this.authHeaders(),
                 ...this.contextHeaders(),
+                ...this.testHeaders(),
                 ...extraHeaders,
             };
             let init = { method, headers };
@@ -320,12 +375,10 @@ class XCiteDBClient {
         await this.request('DELETE', `/api/v1/project/keys/${encodeURIComponent(keyId)}`);
     }
     // --- App user auth (requires developer API key or JWT on the same tenant) ---
-    async registerAppUser(email, password, displayName, groups, attributes) {
+    async registerAppUser(email, password, displayName, attributes) {
         const body = { email, password };
         if (displayName !== undefined)
             body.display_name = displayName;
-        if (groups !== undefined)
-            body.groups = groups;
         if (attributes !== undefined)
             body.attributes = attributes;
         return this.request('POST', '/api/v1/app/auth/register', this.mergeAppTenant(body));
@@ -449,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,
@@ -471,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,
@@ -491,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)
@@ -502,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);
     }
@@ -834,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 });
     }
@@ -937,6 +1129,9 @@ class XCiteDBClient {
             ...this.authHeaders(),
             ...this.contextHeaders(),
         };
+        const tid = this.defaultContext.project_id ?? this.defaultContext.tenant_id;
+        if (tid)
+            headers['tenant_id'] = tid;
         const sub = new websocket_1.WebSocketSubscription(wsBase, headers);
         sub.onMessage(callback);
         if (onError)

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, 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;
@@ -205,6 +212,29 @@ export interface XCiteDBClientOptions {
      * Use to clear stored credentials and redirect to sign-in. Not invoked for login/register-style paths.
      */
     onSessionInvalid?: () => void;
+    /**
+     * Ephemeral BaaS test session token from `POST /api/v1/test/sessions`.
+     * Sends `X-Test-Session`; use with {@link XCiteDBClient.createTestSession}.
+     */
+    testSessionToken?: string;
+    /** When true with `testSessionToken`, sends `X-Test-Auth: required` so real credentials are validated. */
+    testRequireAuth?: boolean;
+}
+/** Options for {@link XCiteDBClient.createTestSession} (provisions via API key or Bearer). */
+export interface CreateTestSessionOptions {
+    baseUrl: string;
+    apiKey?: string;
+    accessToken?: string;
+    appUserAccessToken?: string;
+    appUserRefreshToken?: string;
+    context?: DatabaseContext;
+    platformConsole?: boolean;
+    projectId?: string;
+    /** Keep `apiKey` / `accessToken` on the client and send `X-Test-Auth: required` on each request. */
+    testRequireAuth?: boolean;
+    onSessionTokensUpdated?: (pair: TokenPair) => void;
+    onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
+    onSessionInvalid?: () => void;
 }
 /** Application user (tenant-scoped), distinct from developer users. */
 export interface AppUser {
@@ -317,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;
@@ -335,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';
@@ -363,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/dist/websocket.js

@@ -19,6 +19,11 @@ class WebSocketSubscription {
         const token = this.headerParams['Authorization']?.replace(/^Bearer\s+/i, '');
         if (token)
             u.searchParams.set('access_token', token);
+        if (!u.searchParams.has('access_token')) {
+            const appUser = this.headerParams['X-App-User-Token'];
+            if (appUser)
+                u.searchParams.set('access_token', appUser);
+        }
         const apiKey = this.headerParams['X-API-Key'];
         if (apiKey)
             u.searchParams.set('api_key', apiKey);

package/llms-full.txt

@@ -26,6 +26,28 @@ Before reading the full reference, note these critical differences from typical
 
 9. **OpenAPI:** See repository `docs/openapi.yaml` for a machine-readable route map.
 
+10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, normal JWT/API-key checks are bypassed for those requests (synthetic admin for wet tests). Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
+
+## Common Pitfalls
+
+1. **`baseUrl` must be origin-only (no `/api` or `/api/v1` path).** The SDK prepends `/api/v1/…` to every request. If `baseUrl` is `https://host/api/v1`, requests hit `/api/v1/api/v1/…` which typically returns **405 Not Allowed** from the reverse proxy. Use only the scheme + host + optional port: `https://host` or `http://localhost:8080`.
+
+2. **Browser WebSocket requires correct CORS and proxy config.** Browsers add an `Origin` header to WebSocket connections — make sure your project's CORS allowed-origins includes your app's origin. Reverse proxies (nginx) must forward WebSocket `Upgrade` requests to XCiteDB's `/api/v1/ws` endpoint (the default `docker/nginx.conf` already does this). For production deployments that need fine-grained server-side filtering or short-lived auth tickets, consider proxying the WebSocket through your own backend:
+
+   ```
+   Browser ──ws──▶ Your API server ──ws──▶ XCiteDB /api/v1/ws
+            (same origin,            (server-to-server,
+             short ticket)            secret API key + user JWT)
+   ```
+
+3. **Prefer `context.project_id` over `platformConsole` for project-scoped API keys.** `platformConsole` / `projectId` is designed for platform-operator keys that select a project dynamically via the `X-Project-Id` header. For project-scoped keys (which already identify their project), set **`context.project_id`** instead — it adds `tenant_id` to app-auth JSON bodies via `mergeAppTenant()` without sending `X-Project-Id`.
+
+4. **Prefer `https://` in `baseUrl` for remote/production hosts.** XciteDB's default nginx uses a method-preserving **308** redirect (POST stays POST), but third-party proxies or older configurations may use **301** which silently downgrades POST to GET. Using `https://` directly avoids the redirect entirely.
+
+5. **`context.project_id` (or `tenant_id`) is required for app-user self-registration.** `registerAppUser()` uses `mergeAppTenant(body)` to add `tenant_id` to the JSON body only when `context.project_id` or `context.tenant_id` is set. If both are omitted, the server cannot determine which project to register the user in. Always set `project_id` in the constructor `context` when calling `registerAppUser`, `loginAppUser`, and other public app-auth methods.
+
+6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
+
 ---
 
 # Part 1: Product Overview
@@ -162,6 +184,26 @@ Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oau
 
 ---
 
+# Ephemeral test sessions
+
+For **integration and wet tests** against a shared BaaS host without touching production data:
+
+| Step | What to do |
+|------|------------|
+| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). |
+| **Use** | Send **`X-Test-Session: <session_token>`** on document and other data API requests. The server routes to a dedicated LMDB under its data root (`_test/<id>/`), not the caller’s production tenant. **`tenant_id` / `X-Project-Id` semantics do not select production** while the test header is present—the synthetic test tenant is implied. |
+| **Auth** | **Default:** test requests **skip** normal auth (convenient for automated tests). **`X-Test-Auth: required`:** require normal Bearer or API key; identity and ABAC apply, but data still comes from the test session DB. |
+| **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. |
+| **CORS** | Browsers may need **`X-Test-Session`** and **`X-Test-Auth`** in the deployment’s allowed CORS headers (defaults include them). |
+
+**SDK usage (summary):**
+
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })` returns a client configured with `testSessionToken`; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor.
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key` (and optional `test_require_auth`); `destroy_test_session()`.
+
+---
+
 # Health, version & discovery
 
 ## Health
@@ -393,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
@@ -527,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`**
 
 ---
 
@@ -567,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": {}
   }
 }
@@ -588,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
 
@@ -1042,7 +1284,7 @@ interface DatabaseContext {
 - `deleteTrigger(name)` → `void`
 
 ### App User Auth
-- `registerAppUser(email, password, displayName?, groups?, attributes?)` → `AppUser`
+- `registerAppUser(email, password, displayName?, attributes?)` → `AppUser` (groups assigned from server config)
 - `loginAppUser(email, password)` → `AppUserTokenPair`
 - `refreshAppUser()` → `AppUserTokenPair`
 - `logoutAppUser()` → `void`
@@ -1081,6 +1323,9 @@ interface DatabaseContext {
 
 ### WebSocket
 - `subscribe(options: SubscriptionOptions, callback, onError?)` → `WebSocketSubscription`
+- Browser WebSocket cannot send HTTP headers. The SDK maps credentials to query params:
+  `Authorization: Bearer <jwt>` → `?access_token=<jwt>`, `X-App-User-Token` → `?access_token=<jwt>` (fallback),
+  `X-API-Key` → `?api_key=<key>`. The SDK also propagates `context.project_id` as `?tenant_id=`.
 
 ## Key Types
 

package/llms.txt

@@ -22,6 +22,30 @@ These are the most common sources of confusion for developers and AI assistants:
 
 8. **Project vs tenant id.** In the SDK, prefer `context.project_id` (and `listMyProjects` / `switchProject`). Many JSON bodies and JWT claims still use the field name `tenant_id` for the same value — the client sends that wire name automatically.
 
+9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default those requests **skip** normal auth; send **`X-Test-Auth: required`** to exercise real JWT/API-key auth against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). The test DB starts **empty** (no copy of production project config or keys).
+
+## Common Pitfalls
+
+1. **`baseUrl` must be origin-only (no `/api` or `/api/v1` path).** The SDK prepends `/api/v1/…` to every request. If `baseUrl` is `https://host/api/v1`, requests hit `/api/v1/api/v1/…` which typically returns **405 Not Allowed** from the reverse proxy. Use only the scheme + host + optional port: `https://host` or `http://localhost:8080`.
+
+2. **Browser WebSocket requires correct CORS and proxy config.** Browsers add an `Origin` header to WebSocket connections — make sure your project's CORS allowed-origins includes your app's origin. Reverse proxies (nginx) must forward WebSocket `Upgrade` requests to XCiteDB's `/api/v1/ws` endpoint (the default `docker/nginx.conf` already does this). For production deployments that need fine-grained server-side filtering or short-lived auth tickets, consider proxying the WebSocket through your own backend.
+
+3. **Prefer `context.project_id` over `platformConsole` for project-scoped API keys.** `platformConsole` / `projectId` is designed for platform-operator keys that select a project dynamically via the `X-Project-Id` header. For project-scoped keys (which already identify their project), set **`context.project_id`** instead — it adds `tenant_id` to app-auth JSON bodies via `mergeAppTenant()` without sending `X-Project-Id`.
+
+4. **Prefer `https://` in `baseUrl` for remote/production hosts.** XciteDB's default nginx uses a method-preserving **308** redirect (POST stays POST), but third-party proxies or older configurations may use **301** which silently downgrades POST to GET. Using `https://` directly avoids the redirect entirely.
+
+5. **`context.project_id` (or `tenant_id`) is required for app-user self-registration.** `registerAppUser()` uses `mergeAppTenant(body)` to add `tenant_id` to the JSON body only when `context.project_id` or `context.tenant_id` is set. If both are omitted, the server cannot determine which project to register the user in. Always set `project_id` in the constructor `context` when calling `registerAppUser`, `loginAppUser`, and other public app-auth methods.
+
+6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
+
+## Test mode (how to use)
+
+1. **Provision:** `POST /api/v1/test/sessions` with `Authorization: Bearer …` or `X-API-Key` (same as normal API access). Response JSON includes the session token.
+2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Branch` / `context` as needed). Data is stored under the server’s `_test/<session>/` area, not your production tenant.
+3. **Auth behavior:** Omit extra headers for frictionless tests. To test policies and real identities, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
+4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
+5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or manual token + `test_session_token` / `test_require_auth` constructor args. **C++:** `XCiteDBClient::create_test_session(options)`, `destroy_test_session()`, optional `test_require_auth` in options.
+
 ## JavaScript/TypeScript SDK (`@xcitedbs/client`)
 
 Install: `npm install @xcitedbs/client`
@@ -182,13 +206,36 @@ 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()` — Self-registration
+- `registerAppUser(email, password, displayName?, attributes?)` — Self-registration (groups assigned from server config)
 - `getAppAuthConfig()` — Auth configuration
 
 **WebSocket:**
 - `subscribe(options, callback, onError?)` — Real-time document change notifications
+- Browser WebSocket cannot send HTTP headers. The SDK maps credentials to query params:
+  `Authorization: Bearer <jwt>` → `?access_token=<jwt>`, `X-App-User-Token` → `?access_token=<jwt>` (fallback),
+  `X-API-Key` → `?api_key=<key>`. The SDK also propagates `context.project_id` as `?tenant_id=`.
 
 ### Query Flags
 

package/package.json

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