@xcitedbs/client 0.2.5 → 0.2.6

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, 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;

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));
@@ -937,6 +990,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, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -205,6 +205,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 {

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
@@ -1042,7 +1084,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 +1123,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`
@@ -184,11 +208,14 @@ interface XCiteDBClientOptions {
 
 **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.6",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",