@xcitedbs/client 0.2.7 → 0.2.8

package/llms-full.txt

@@ -26,7 +26,7 @@ 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).
+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, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
 
 ## Common Pitfalls
 
@@ -48,6 +48,8 @@ Before reading the full reference, note these critical differences from typical
 
 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()`.
 
+7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Ephemeral test sessions" below.
+
 ---
 
 # Part 1: Product Overview
@@ -186,13 +188,15 @@ Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oau
 
 # Ephemeral test sessions
 
+> **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised. Provision a session in `beforeAll` / `setUp` / test fixture setup and destroy it in `afterAll` / `tearDown` / fixture teardown.
+
 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. |
+| **Auth** | **Default:** developer auth (API key / platform JWT) is **bypassed** with a synthetic admin identity. However, **app-user identity is still recognized**: if `X-App-User-Token` or a Bearer app-user JWT is present, the request runs as that app user (for routes like `/app/auth/me`). **`X-Test-Auth: required`:** all auth is validated normally; ABAC applies, 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). |
 
@@ -202,6 +206,126 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 - **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()`.
 
+**JavaScript/TypeScript — complete test scaffold (Vitest / Jest):**
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { XCiteDBClient } from '@xcitedbs/client';
+
+describe('XciteDB integration', () => {
+  let client: XCiteDBClient;
+
+  beforeAll(async () => {
+    // Provisions an isolated, throwaway LMDB — production data is never touched.
+    client = await XCiteDBClient.createTestSession({
+      baseUrl: process.env.XCITEDB_URL ?? 'http://localhost:8080',
+      apiKey: process.env.XCITEDB_API_KEY!,
+    });
+  });
+
+  afterAll(async () => {
+    await client.destroyTestSession();
+  });
+
+  it('writes and reads a JSON document', async () => {
+    await client.writeJsonDocument('test.config', { env: 'test' });
+    const doc = await client.readJsonDocument<{ env: string }>('test.config');
+    expect(doc).toMatchObject({ env: 'test' });
+  });
+
+  it('writes and reads an XML document', async () => {
+    await client.writeXmlDocument(
+      '<doc db:identifier="/test/doc1"><title>Hello</title></doc>'
+    );
+    const xml = await client.queryByIdentifier('/test/doc1', 'FirstMatch');
+    expect(xml).toContain('<title>Hello</title>');
+  });
+
+  it('creates a branch, commits, and merges', async () => {
+    await client.withBranch('feature-test', async (c) => {
+      await c.writeJsonDocument('test.feature', { active: true });
+    }, { message: 'Add feature flag', autoMerge: true });
+    const doc = await client.readJsonDocument<{ active: boolean }>('test.feature');
+    expect(doc.active).toBe(true);
+  });
+});
+```
+
+**Python — complete test scaffold (pytest + pytest-asyncio):**
+
+```python
+import os
+import pytest
+import pytest_asyncio
+from xcitedb import XCiteDBClient
+
+@pytest_asyncio.fixture
+async def db():
+    # Provisions an isolated, throwaway LMDB — production data is never touched.
+    async with XCiteDBClient.test_session(
+        os.environ.get("XCITEDB_URL", "http://localhost:8080"),
+        api_key=os.environ["XCITEDB_API_KEY"],
+    ) as client:
+        yield client  # session is destroyed automatically on exit
+
+@pytest.mark.asyncio
+async def test_json_document(db):
+    await db.write_json_document("test.config", {"env": "test"})
+    doc = await db.read_json_document("test.config")
+    assert doc == {"env": "test"}
+
+@pytest.mark.asyncio
+async def test_xml_document(db):
+    await db.write_xml_document(
+        '<doc db:identifier="/test/doc1"><title>Hello</title></doc>'
+    )
+    result = await db.query_by_identifier("/test/doc1", "FirstMatch")
+    assert "<title>Hello</title>" in result
+
+@pytest.mark.asyncio
+async def test_branch_and_merge(db):
+    async with db.with_branch("feature-test", message="Add flag", auto_merge=True):
+        await db.put("test.feature", {"active": True})
+    doc = await db.get("test.feature")
+    assert doc["active"] is True
+```
+
+**C++ — complete test scaffold (Catch2):**
+
+```cpp
+#include <xcitedb/xcitedb.hpp>
+#include <catch2/catch_test_macros.hpp>
+#include <cstdlib>
+
+// Provisions an isolated, throwaway LMDB — production data is never touched.
+static xcitedb::XCiteDBClient make_test_client() {
+    xcitedb::XCiteDBClientOptions opt;
+    opt.base_url = std::getenv("XCITEDB_URL") ? std::getenv("XCITEDB_URL")
+                                               : "http://127.0.0.1:8080";
+    opt.api_key = std::getenv("XCITEDB_API_KEY");
+    return xcitedb::XCiteDBClient::create_test_session(opt);
+}
+
+TEST_CASE("XciteDB JSON document round-trip") {
+    auto client = make_test_client();
+    client.write_json_document("test.config", R"({"env":"test"})");
+    auto doc = client.read_json_document("test.config");
+    REQUIRE(doc.find("\"env\"") != std::string::npos);
+    REQUIRE(doc.find("\"test\"") != std::string::npos);
+    client.destroy_test_session();
+}
+
+TEST_CASE("XciteDB XML document round-trip") {
+    auto client = make_test_client();
+    client.write_xml_document(
+        R"(<doc db:identifier="/test/doc1"><title>Hello</title></doc>)"
+    );
+    auto xml = client.query_by_identifier("/test/doc1", "FirstMatch");
+    REQUIRE(xml.find("<title>Hello</title>") != std::string::npos);
+    client.destroy_test_session();
+}
+```
+
 ---
 
 # Health, version & discovery
@@ -1284,6 +1408,9 @@ interface DatabaseContext {
 - `deleteTrigger(name)` → `void`
 
 ### App User Auth
+
+**App-user auth in test sessions.** The full app-user lifecycle works inside a test session: `registerAppUser` → `loginAppUser` → `appUserMe` / `updateAppUserProfile` / etc. App user records are stored in the test session’s isolated LMDB and cleaned up with the session. No `X-Test-Auth: required` is needed for this flow — the default bypass mode recognizes app-user tokens while still skipping developer auth.
+
 - `registerAppUser(email, password, displayName?, attributes?)` → `AppUser` (groups assigned from server config)
 - `loginAppUser(email, password)` → `AppUserTokenPair`
 - `refreshAppUser()` → `AppUserTokenPair`

package/llms.txt

@@ -22,7 +22,7 @@ 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).
+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 **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC 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
 
@@ -38,11 +38,15 @@ These are the most common sources of confusion for developers and AI assistants:
 
 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()`.
 
+7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Test mode" below.
+
 ## Test mode (how to use)
 
+> **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised.
+
 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.
+3. **Auth behavior:** Developer auth (API key / platform JWT) is bypassed by default for frictionless tests. **App-user identity** (`X-App-User-Token` or Bearer app-user JWT) **is still recognized** in default mode, so `registerAppUser` → `loginAppUser` → `appUserMe` works inside a test session. To also exercise developer auth and ABAC policies, 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.
 

package/package.json

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