@xcitedbs/client 0.3.10 → 0.3.11

package/dist/client.d.ts

@@ -143,6 +143,22 @@ export declare class XCiteDBClient {
         message: string;
         session_token: string;
     }>;
+    /**
+     * Seal a *standalone* sandbox as a fixture base (`POST /api/v1/sandboxes/{name}/seal`).
+     *
+     * Stamps the supplied fingerprint on the fixture's metadata. Test sessions and dev sandboxes
+     * can then attach to this fixture by passing the matching `expectedBaseFingerprint`. Mismatch
+     * is `409 fingerprint_mismatch` — consumers MUST re-run setup, not retry.
+     */
+    sealSandbox(name: string, opts: import('./types').SealSandboxOptions): Promise<import('./types').SandboxInfo>;
+    /**
+     * Unseal a fixture sandbox (`POST /api/v1/sandboxes/{name}/unseal`).
+     *
+     * Clears the seal + fingerprint and bumps `reset_generation` so any cached overlay routing
+     * forces a fresh validation. Typical re-seed flow: `unseal → resetSandbox → re-populate →
+     * sealSandbox` at a new fingerprint.
+     */
+    unsealSandbox(name: string): Promise<import('./types').SandboxInfo>;
     /** Destroy a sandbox; revokes bound API keys and removes membership rows. Owner only. */
     destroySandbox(name: string): Promise<{
         message: string;

package/dist/client.js

@@ -201,6 +201,11 @@ class XCiteDBClient {
             sessionBody.additional_keys = opts.additionalKeys;
         if (opts.bootstrap !== undefined)
             sessionBody.bootstrap = opts.bootstrap;
+        if (opts.baseSandboxName)
+            sessionBody.base_sandbox_name = opts.baseSandboxName;
+        if (opts.expectedBaseFingerprint) {
+            sessionBody.expected_base_fingerprint = opts.expectedBaseFingerprint;
+        }
         const data = await temp.request('POST', '/api/v1/test/sessions', Object.keys(sessionBody).length ? sessionBody : undefined, undefined, { no401Retry: true });
         const mode = resolveTestAuthMode(opts.testAuth, opts.testRequireAuth) ?? 'required';
         const keepCreds = mode !== 'bypass';
@@ -727,7 +732,18 @@ class XCiteDBClient {
      * a fresh client constructed with that key (no header threading needed).
      */
     async createSandbox(opts) {
-        return this.request('POST', '/api/v1/sandboxes', opts, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+        // Translate camelCase fixture-attach options to the snake_case wire format
+        // the server expects. Other fields pass through unchanged.
+        const body = { ...opts };
+        if (opts.baseSandboxName) {
+            body.base_sandbox_name = opts.baseSandboxName;
+            delete body.baseSandboxName;
+        }
+        if (opts.expectedBaseFingerprint) {
+            body.expected_base_fingerprint = opts.expectedBaseFingerprint;
+            delete body.expectedBaseFingerprint;
+        }
+        return this.request('POST', '/api/v1/sandboxes', body, undefined, { suppressTestSessionHeader: true, no401Retry: true });
     }
     /** List sandboxes for the current project (`GET /api/v1/sandboxes`). */
     async listSandboxes() {
@@ -746,6 +762,26 @@ class XCiteDBClient {
     async resetSandbox(name) {
         return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/reset`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
     }
+    /**
+     * Seal a *standalone* sandbox as a fixture base (`POST /api/v1/sandboxes/{name}/seal`).
+     *
+     * Stamps the supplied fingerprint on the fixture's metadata. Test sessions and dev sandboxes
+     * can then attach to this fixture by passing the matching `expectedBaseFingerprint`. Mismatch
+     * is `409 fingerprint_mismatch` — consumers MUST re-run setup, not retry.
+     */
+    async sealSandbox(name, opts) {
+        return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/seal`, { fingerprint: opts.fingerprint }, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
+    /**
+     * Unseal a fixture sandbox (`POST /api/v1/sandboxes/{name}/unseal`).
+     *
+     * Clears the seal + fingerprint and bumps `reset_generation` so any cached overlay routing
+     * forces a fresh validation. Typical re-seed flow: `unseal → resetSandbox → re-populate →
+     * sealSandbox` at a new fingerprint.
+     */
+    async unsealSandbox(name) {
+        return this.request('POST', `/api/v1/sandboxes/${encodeURIComponent(name)}/unseal`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });
+    }
     /** Destroy a sandbox; revokes bound API keys and removes membership rows. Owner only. */
     async destroySandbox(name) {
         return this.request('DELETE', `/api/v1/sandboxes/${encodeURIComponent(name)}`, undefined, undefined, { suppressTestSessionHeader: true, no401Retry: true });

package/dist/types.d.ts

@@ -854,6 +854,26 @@ export interface CreateTestSessionOptions {
      * When true, creates an overlay test session: writable ephemeral LMDB with production project data as read-only base.
      */
     overlay?: boolean;
+    /**
+     * When set, attach the new test session to a sealed standalone sandbox (a "fixture") instead of the
+     * production project as the read-only base. Implies `overlay: true`.
+     *
+     * Use this for e2e suites where many tests share the same expensive setup (created users, seeded
+     * data, etc.) — set up the fixture once via the sandbox API, seal it with a content fingerprint,
+     * then point each test session at it. Multiple test sessions can attach to the same fixture
+     * concurrently; each gets its own ephemeral overlay layer.
+     */
+    baseSandboxName?: string;
+    /**
+     * Required iff {@link baseSandboxName} is set. The fingerprint your setup script stamped on the
+     * fixture (typically `hash(seed_inputs) + schema_version + git_sha`).
+     *
+     * On mismatch the server returns **`409 fingerprint_mismatch`** — the recovery action is to
+     * **re-run setup** to refresh the fixture, NOT to retry. The whole feature's safety property
+     * hinges on consumers handling this error correctly: a stale fixture must never silently serve
+     * old data.
+     */
+    expectedBaseFingerprint?: string;
     /**
      * API keys to snapshot into the new session's config DB so requests carrying any of these keys
      * (alongside `X-Test-Session: <token>`) authenticate against the session, not production.
@@ -910,6 +930,22 @@ export interface SandboxInfo {
     owner_member_id: string;
     /** Present in list responses: the requesting member's role in this sandbox, or "" if not a member. */
     my_role?: 'owner' | 'editor' | 'viewer' | '';
+    /**
+     * True for *fixture* sandboxes — empty initial DB, no production overlay underneath. Eligible
+     * to be sealed and used as a base for test sessions or other sandboxes. Mutually exclusive
+     * with `base_sandbox_name` on create.
+     */
+    standalone?: boolean;
+    /** True when this standalone sandbox has been sealed as a fixture base. */
+    sealed?: boolean;
+    /** Content fingerprint set when this sandbox was last sealed (only present on fixtures). */
+    base_fingerprint?: string;
+    /** Unix seconds at which the fixture was last sealed. */
+    sealed_at?: number;
+    /** First 8 chars of the parent fixture token, when this sandbox attached to a fixture base. */
+    base_sandbox_token_prefix?: string;
+    /** Echoed at create time when this sandbox is attached to a fixture base. */
+    expected_base_fingerprint?: string;
 }
 /** Options for {@link XCiteDBClient.createSandbox}. */
 export interface CreateSandboxOptions {
@@ -923,6 +959,31 @@ export interface CreateSandboxOptions {
     base_branch?: string;
     /** Defaults to "log" — webhooks/auth-emails get captured instead of firing. */
     effects_policy?: 'real' | 'log' | 'mock';
+    /**
+     * Fixture mode: an empty initial DB with no production overlay. Required for sealing the
+     * sandbox as a fixture base later. At most one standalone sandbox is allowed per
+     * `(org_id, project_id)`. Mutually exclusive with {@link baseSandboxName} and
+     * `effects_policy: 'real'`.
+     */
+    standalone?: boolean;
+    /**
+     * Attach this dev sandbox to a sealed standalone fixture as its base. The fixture provides the
+     * read-only baseline; this sandbox holds the writable overlay. Same fingerprint contract as
+     * {@link CreateTestSessionOptions.baseSandboxName} — mismatch is `409 fingerprint_mismatch`.
+     * Mutually exclusive with {@link standalone}.
+     */
+    baseSandboxName?: string;
+    /** Required iff {@link baseSandboxName} is set. */
+    expectedBaseFingerprint?: string;
+}
+/** Body for {@link XCiteDBClient.sealSandbox}. */
+export interface SealSandboxOptions {
+    /**
+     * Content fingerprint to stamp on the fixture. Should be derived from your seed inputs +
+     * schema version + app version (typically git SHA). On a subsequent attach, consumers must
+     * pass the same fingerprint via `expectedBaseFingerprint` — mismatch is a hard failure.
+     */
+    fingerprint: string;
 }
 /** Response from {@link XCiteDBClient.mintSandboxApiKey}. The `api_key` value is shown once. */
 export interface SandboxApiKeyMintResult {

package/llms.txt

@@ -159,6 +159,24 @@ If you skip the bootstrap, an app-user JWT cannot read or write `/spaces/<userId
 
 **SDK one-liners for bootstrap:** **JS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, testRequireAuth: true, bootstrap: { user_isolation: { enabled: true, namespace_pattern: '/spaces/${user.id}' }, developer_bypass: true } })`. **Python:** `async with XCiteDBClient.test_session(base_url, api_key=sk, test_require_auth=True, bootstrap={...}) as c:`. **C++:** set `options.test_session_bootstrap = nlohmann::json::parse(R"(...)");` then `XCiteDBClient::create_test_session(options)`.
 
+### Fixture-base test sessions (e2e shared setup)
+
+When an e2e suite (Playwright etc.) re-runs the same expensive setup before every test — create users, seed documents, configure policies — that setup dominates wall-clock time. **Fixture-base mode** lets you do the setup **once per CI run**, share it across many tests in parallel, and treat staleness as a hard failure rather than a silent bug.
+
+Lifecycle:
+
+1. **Create a fixture sandbox** (one-time per project): `POST /api/v1/sandboxes` with `{"name":"e2e-fixture","standalone":true}`. A standalone sandbox has an empty initial DB and no production overlay underneath. **Only one standalone sandbox is allowed per `(org, project)`** — bumping fingerprints, not creating new fixtures, is the way to evolve.
+2. **Populate it** via the regular API (open a sandbox session against it, run your seed script, etc.). Effects policy `real` is rejected for standalone sandboxes; `log` (default) or `mock` are valid.
+3. **Seal it** with a content fingerprint: `POST /api/v1/sandboxes/e2e-fixture/seal` with `{"fingerprint":"<hash>"}`. The fingerprint should encode anything that affects stored shape: at minimum `hash(seed_inputs) + schema_version + git_sha` (every commit pessimistically invalidates the fixture — the friction of a manual version bump is worse than rerunning a fast API-only setup).
+4. **Attach test sessions to the fixture:** `POST /api/v1/test/sessions` with `{"overlay":true,"base_sandbox_name":"e2e-fixture","expected_base_fingerprint":"<hash>"}`. Many test sessions can attach concurrently; each gets its own ephemeral overlay layer; reads see the fixture's data, writes go to the test's overlay only. Mismatch on `expected_base_fingerprint` is **`409 fingerprint_mismatch` — the recovery action is to RE-RUN SETUP, not to retry**. This is the safety property of the cache: a stale fixture must never silently serve old data.
+5. **Re-seed** when the app or seed inputs change: `POST /api/v1/sandboxes/e2e-fixture/unseal` → `POST /api/v1/sandboxes/e2e-fixture/reset` → repopulate via API → `POST /api/v1/sandboxes/e2e-fixture/seal` at the new fingerprint.
+
+**Dev sandboxes can also attach to a fixture** (interactive testing on top of fixture data instead of production): `POST /api/v1/sandboxes` with `{"name":"my-feature","base_sandbox_name":"e2e-fixture","expected_base_fingerprint":"<hash>"}`. Same fingerprint contract; if the fixture is later re-sealed, the dev sandbox's next request fails with `fixture_fingerprint_changed` — recovery in v1 is to delete and recreate the dev sandbox.
+
+**Security:** the fixture-base resolver is keyed on the **caller's** `(org, project)`, not user input — there is no way for tenant A to attach to tenant B's fixture by name. The membership check (caller must be owner/editor of the fixture) returns a generic 404 for both not-found and not-a-member, so cross-tenant existence cannot be probed.
+
+**SDK helpers:** **JS:** `client.createTestSession({ baseUrl, apiKey, baseSandboxName, expectedBaseFingerprint })`, `client.createSandbox({ name, baseSandboxName, expectedBaseFingerprint })`, `client.sealSandbox(name, { fingerprint })`, `client.unsealSandbox(name)`. **Python:** `XCiteDBClient.test_session(base_url, base_sandbox_name=..., expected_base_fingerprint=...)`, `client.seal_sandbox(name, fingerprint=...)`, `client.unseal_sandbox(name)`. **C++:** set `options.test_session_base_sandbox_name` + `options.test_session_expected_base_fingerprint` then `create_test_session`; `seal_sandbox(name, fingerprint)`, `unseal_sandbox(name)`. **MCP:** tools `seal_sandbox`, `unseal_sandbox`; the `create_sandbox` and `create_test_session` tools accept the new fields.
+
 ## Wrapping XCiteDB in a higher-level service
 
 When you build a backend that calls XCiteDB on behalf of users:

package/package.json

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