@qaecy/cue-sdk 0.0.5 → 0.0.8

package/PORTAL_MIGRATION.md

@@ -0,0 +1,346 @@
+# Cue SDK — Portal Migration
+
+> **Goal:** All server communication in cue-portal flows through `js-cue-sdk`, replacing direct usage of `js-firebase` and `cue-repos`.
+
+---
+
+## Current State
+
+| Layer | Status |
+|-------|--------|
+| **js-cue-sdk** — `Cue`, `CueAuth`, `CueProjects`, `CueProfile`, `CuePrivileges`, `CueCache` | ✅ Active — all major modules built |
+| **js-databases** — `IDocStore`, `FirestoreDocStore`, `CueBlobStorage` | ✅ All repos delegating to these |
+| **cue-repos** (Angular) — now thin adapters over the SDK | ✅ Migrated |
+| **js-firebase** (`CueFirebase`) | Kept — CLI, widget, admin depend on it |
+| **cue-views** (Angular) — SPARQL + entity/doc signals | 🔄 In progress — core data classes built, facade + adapters pending |
+
+**Remaining `js-firebase` imports in the portal:**
+- `libs/ng/cue-repos/src/lib/firebase.service.ts` — intentional (this IS the `CueFirebase` wrapper)
+- `apps/frontend/cue-portal/src/main.ts` — app bootstrap; addressed in Final phase
+
+---
+
+## Remaining Work
+
+### Phase 6 — Knowledge Graph View State (`CueProjectView`)
+
+Full investigation of `cue-views` services completed. The three heaviest SPARQL data classes are already built in `js-cue-sdk`. What remains is a thin facade, the Angular adapter wiring, and gateway API additions for the remaining services.
+
+#### Coverage summary — `cue-views` services vs SDK
+
+| `cue-views` service | SDK status | Owner after migration |
+|---|---|---|
+| `TriplestoreService` | ✅ Replaced by `CueApi.sparql()` | SDK |
+| `AvailableCategoriesService` | ✅ Replaced by `CueProjectSchema` | Angular bridge |
+| `ProjectDocumentsService` | ✅ Replaced by `CueProjectDocuments.fetchOverview()` | Angular bridge |
+| `DocumentInfoService` (SPARQL) | ✅ Replaced by `CueProjectDocuments.requestDocumentData()` | Angular bridge; callbacks stay Angular |
+| `EntityInfoService` (core) | ✅ Replaced by `CueProjectEntities` | Angular bridge |
+| `DocumentDuplicatesService` | ⚠️ Count covered; full path list not yet in SDK | Needs `CueProjectDocuments.fetchDuplicates()` |
+| `DocumentEntitiesService` | ❌ Not covered | Needs new SDK read queries + `CueApi` write methods |
+| `RelatedService` | ❌ Not covered | Needs `CueApi.relatedDocuments()` |
+| `ContentCategoryService` | ❌ Not covered | Needs `CueApi.changeContentCategory()` |
+| `AgentService` | ❌ Not covered | Needs `CueApi.streamPlan()` / `CueApi.streamAct()` |
+| `ResourceService` | ❌ Not covered | Per-document viewer; stays Angular or becomes `CueDocumentResource` |
+| `FileLocationsService` | ❌ Not covered | Low priority; stays Angular or becomes private helper |
+| `FileContentService` | ❌ Not covered | Depends on `FileRepo`; stays Angular-layer |
+| `CueViewsService` | N/A — config/context root | Angular adapter responsibility |
+| `CommandsService` | N/A — thin facade | Angular adapter responsibility |
+
+---
+
+#### Phase 6a — `CueProjectView` facade _(next step)_
+
+Create `libs/js/cue-sdk/src/lib/project-view.ts` — a single class that composes `CueProjectSchema`, `CueProjectEntities`, and `CueProjectDocuments` and adds `search()`.
+
+```ts
+const view = cue.createProjectView(projectId, { language: 'en', queryCache });
+
+// Proxied signals from sub-classes
+view.availableContentCategories   // → schema.availableContentCategories
+view.availableEntityCategories    // → schema.availableEntityCategories
+view.availableEntityRelationships // → schema.availableEntityRelationships
+view.entityInfoMap                // → entities.entityInfoMap
+view.entityGraph                  // → entities.entityGraph
+view.documentInfoMap              // → documents.documentInfoMap
+view.projectDocumentsData         // → documents.projectDocumentsData
+
+// Proxied methods
+view.requestEntityData(ids, includeMentionCount?)
+view.requestEntityLocations(ids)
+view.fetchEntityRelationships(iri)
+view.fetchEntityDocuments(iri)
+view.requestDocumentData(ids)
+
+// New: search
+view.searchResults                // ReadonlySignal<DocumentRef[]>
+view.search(term, options?)       // Calls CueApi.search(), appends to searchResults
+
+// Lifecycle
+view.setLanguage(lang)            // Calls schema.setLanguage(); docs.setLanguage()
+view.destroy()                    // Tears down subscriptions
+```
+
+`Cue` gains a factory method:
+```ts
+cue.createProjectView(projectId: string, opts: { language: string, queryCache?: QueryCache }): CueProjectView
+```
+
+**Files to create/modify:**
+- `libs/js/cue-sdk/src/lib/project-view.ts` — new `CueProjectView` class
+- `libs/js/cue-sdk/src/lib/cue.ts` — add `createProjectView()` method
+- `libs/js/cue-sdk/src/index.ts` — export `CueProjectView` + related types
+
+---
+
+#### Phase 6b — Angular adapters in `cue-views`
+
+Replace the heavy Angular services with thin bridges that subscribe to SDK signals and forward method calls. Each bridge service creates/receives a `CueProjectView` instance from the Angular DI tree.
+
+| Angular service | Migration action |
+|---|---|
+| `AvailableCategoriesService` | Replace with computed signals bridging `view.availableContentCategories` etc. via `toSignal(obs)` or `subscribe()` |
+| `ProjectDocumentsService` | Replace signal with bridge to `view.projectDocumentsData`; call `view.fetchOverview()` on project init |
+| `DocumentInfoService` | Delegate `requestDocumentData()` to `view`; keep `documentListHandlers` callbacks (download, navigate) Angular-side |
+| `EntityInfoService` | Delegate all 4 public methods to `view`; bridge `entityInfoMap` and `entityGraph` signals |
+| `TriplestoreService` | Remove — callers switch to `CueApi.sparql()` directly or via `view` |
+
+The Angular adapter pattern:
+```ts
+// In cue-views Angular service
+readonly entityInfoMap = toSignal(
+  new Observable(obs => this._view.entityInfoMap.subscribe(v => obs.next(v)))
+);
+```
+
+---
+
+#### Phase 6c — Gateway API additions (`CueApi`)
+
+These are needed before the remaining `cue-views` services can be bridged:
+
+| Method | Source service | HTTP call |
+|---|---|---|
+| `CueApi.relatedDocuments(contentUUID, k)` | `RelatedService` | `POST {gatewayURL}/endpoints.relatedDocuments` |
+| `CueApi.changeContentCategory(payload)` | `ContentCategoryService` | `PATCH {gatewayURL}/endpoints.contentCategoryChange` |
+| `CueApi.streamPlan(prompt, cb)` | `AgentService` | Streaming `POST {gatewayURL}/endpoints.agentPlan` via `fetchStream()` |
+| `CueApi.streamAct(plan, cb)` | `AgentService` | Streaming `POST {gatewayURL}/endpoints.agentAct` via `fetchStream()` |
+| `CueApi.saveEntityMentions(payload)` | `DocumentEntitiesService` | `POST/DELETE {gatewayURL}/endpoints.entityMentionBatch` |
+| `CueApi.saveSelectors(payload)` | `DocumentEntitiesService` | `POST {gatewayURL}/endpoints.selectorBatch` |
+
+The `gatewayURL` and project-scoped `Authorization`/`x-project-id` headers are already in `CueApi` — these are additive methods only.
+
+---
+
+#### Phase 6d — SDK data additions
+
+Small additions to existing SDK classes:
+
+- **`CueProjectDocuments.fetchDuplicates()`** — returns `Record<uuid, string[]>` (all file paths per content UUID where count > 1). `DocumentDuplicatesService` currently holds an in-memory project-keyed cache of this.
+- **`CueProjectEntities` — document-entity reads** — fetch all `qcy:mentions` IRIs for a given `contentIRI`, with `qcy:value` and `qcy:hasEntityCategory`. Currently only in `DocumentEntitiesService`.
+- **`CueProjectEntities` or new `CueDocumentResource`** — type detection (`SELECT ?cl WHERE { <iri> a ?cl }`) + file metadata fetch for per-document-viewer panel. Currently in `ResourceService`.
+
+---
+
+#### Phase 6e — `cue-views` cleanup
+
+After 6a–6d, the remaining Angular services that have no SDK equivalent are either:
+- **Kept as-is** (framework-specific): `FileContentService` (depends on `FileRepo`), `ResourceService` viewer composition, `DocumentListHandlers` callbacks
+- **Deleted** once bridge services are verified: `TriplestoreService`, `AvailableCategoriesService`, `ProjectDocumentsService`
+
+---
+
+### Final — Remove `js-firebase` from portal bootstrap
+
+Replace `main.ts` Firebase init + `FirebaseService` with pure SDK init. `cue-repos` services become either collapsed into the SDK or thin DI wrappers with no direct Firebase imports.
+
+---
+
+
+## Verification Plan
+
+After each phase, verify with the following checklist. Run `npx nx build cue-portal` as the baseline — all items below are functional smoke tests.
+
+### ✅ Phase 2–5 (already done — verify these haven't regressed)
+
+| Area | How to verify |
+|------|--------------|
+| **Auth signals** | Sign in; confirm `cue.auth.user.get()` returns the user, `cue.auth.token.get()` returns a JWT, `cue.auth.isSuperAdmin.get()` reflects the claim |
+| **Privileges** | Select a project where the user is `admin`; confirm `cue.privileges.privileges.get().uploadDocuments === true`; `PrivilegesService.privileges()` should match |
+| **Cloud functions** | In Settings → Members: invite a user, change role, remove — all three `CueProjects` callables should fire without error |
+| **Cache (write)** | Run a SPARQL query with caching enabled; confirm a `.json.gz` file appears in the `db_persistence_eu_west6` bucket at `portal/projects/{pid}/queries/{id}.json.gz` |
+| **Cache (read)** | Run the same query again; confirm it loads from cache (no SPARQL call in the network tab) |
+| **Agent session cache** | Run an agent interaction; confirm `portal/projects/{pid}/agent/{id}.json.gz` is written |
+| **Doc types** | `ProjectDoc`, `UserDoc`, `OrganizationDoc`, `RDFWritingDoc`, `ViewDefinition` all importable from `js-cue-sdk` without errors |
+| **`nx graph`** | `cue-repos` should only have one edge to `js-firebase` (via `firebase.service.ts`) |
+
+### 🔲 Phase 6a — `CueProjectView` facade
+
+| Area | How to verify |
+|------|--------------|
+| **Category signals** | Open a project; `view.availableContentCategories.get()` and `view.availableEntityCategories.get()` return non-empty arrays |
+| **Entity graph** | `view.entityGraph.get()` returns the full entity graph after project init |
+| **Entity detail** | Call `view.requestEntityData(['<uuid>'])` then read `view.entityInfoMap.get()['<uuid>']` — `value` and `categories` populated |
+| **Entity relationships** | Call `view.fetchEntityRelationships('<iri>')` and confirm incoming/outgoing edges |
+| **Entity documents** | Call `view.fetchEntityDocuments('<iri>')` and confirm document UUIDs |
+| **Document data** | Call `view.requestDocumentData(['<id>'])` then read `view.documentInfoMap.get()['<id>']` |
+| **Project documents overview** | `view.projectDocumentsData.get()` returns `documentsBySuffix` and `documentsByContentCategory` |
+| **Search** | Call `view.search('test')` and confirm `view.searchResults.get()` accumulates results |
+| **Language change** | Call `view.setLanguage('da')` and confirm category labels switch |
+| **Stale-while-revalidate** | With a warm `QueryCache`, confirm the signal fires twice — first with stale data, then fresh |
+| **Destroy** | Call `view.destroy()` and confirm no further signal updates |
+
+### ✅ Phase 6b — Angular adapters
+
+**Completed.** All 4 `cue-views` services bridged to SDK signals. Build verified (`nx build ng-cue-views` passes). Also fixed a pre-existing ng-packagr `rootDir` issue in `cue-repos` and `cue-views` by overriding `js-cue-sdk` path to dist in `tsconfig.lib.prod.json`.
+
+| Area | Status |
+|------|--------|
+| `CueViewsService` — owns `CueProjectView` signal, effects for project/language change | ✅ |
+| `AvailableCategoriesService` — bridges `view.availableContentCategories/EntityCategories/EntityRelationships` | ✅ |
+| `ProjectDocumentsService` — bridges `view.projectDocumentsData` | ✅ |
+| `DocumentInfoService` — bridges `view.documentInfoMap`; keeps `documentListHandlers` Angular-side | ✅ |
+| `EntityInfoService` — bridges `view.entityInfoMap` + `entityGraph`; delegates all 4 methods to view | ✅ |
+| `cue-repos/tsconfig.lib.prod.json` — path override to dist to fix ng-packagr TS6059 | ✅ |
+| `cue-views/tsconfig.lib.prod.json` — same fix | ✅ |
+
+### 🔲 Phase 6c — Gateway API additions
+
+| Area | How to verify |
+|------|--------------|
+| **Related documents** | Call `cue.api.relatedDocuments(uuid, 10)` from console; confirm response array with `relevance` scores |
+| **Content category change** | Change a document's content category; confirm PATCH fires and SPARQL reflects the update |
+| **Agent plan streaming** | Trigger agent plan build; confirm streaming chunks arrive and plan signal updates incrementally |
+| **Agent act streaming** | Execute a plan; confirm streaming result chunks arrive and final result is saved via `CueCache` |
+
+### 🔲 Phase 6d — SDK data additions
+
+| Area | How to verify |
+|------|--------------|
+| **Duplicate list** | `view.documents.fetchDuplicates()` returns a map of content UUIDs → array of file paths |
+| **Document entity reads** | `view.entities.fetchDocumentMentions(contentIRI)` returns entity IRIs with labels and categories |
+
+### 🔲 Final (portal bootstrap migration — pending)
+
+| Area | How to verify |
+|------|--------------|
+| **`nx graph`** | `cue-portal` has zero edges to `js-firebase` |
+| **Cold load** | Full page refresh — auth state restores, project loads, entities visible |
+| **Emulator** | `nx run cue-portal:serve` with emulator; all Firestore + Storage + Auth calls route correctly |
+
+---
+
+## Architecture Decisions
+
+**`js-firebase` stays** — CLI, widget, and admin depend on it directly and always will. The portal's dependency shrinks to the single `FirebaseService` wrapper.
+
+**`js-databases` as the abstraction boundary** — `IDocStore` and `CueBlobStorage` are Firebase-agnostic. Switching storage provider only requires changing the backing class in `CueFirebase._init()`.
+
+**Vanilla signals in the SDK** — `CueSignal<T>` + `cueComputed()` in `signal.ts`. No external signal library. Angular adapters bridge to Angular signals via `effect(onCleanup => ...)` + `subscribe()`.
+
+**`UploadTask` escape hatch** — `FileRepo.uploadRawFile` still returns a native Firebase `UploadTask` because `cue-views/handlers.service.ts` depends on `task.on('state_changed', ...)` for per-file upload progress. Resolved in Phase 6.
+
+**`CueCache` uses `firebase/storage` directly** — only needs the `persistence` bucket; no need to instantiate all 6 buckets via `CueBlobStorage`.
+
+---
+
+## SDK Module Reference
+
+| Module | Class | Exposed as | Key members |
+|--------|-------|-----------|-------------|
+| `auth.ts` | `CueAuth` | `cue.auth` | `user`, `token`, `isSuperAdmin`, `userIds` (all `ReadonlySignal`); `signIn()`, `signOut()`, `signInWithRedirect()`, `checkRedirectResult()`, `checkSuperAdmin()`, `getToken()`, `authenticatedFetch()` |
+| `privileges.ts` | `CuePrivileges` | `cue.privileges` | `privileges: ReadonlySignal<Privileges>`; `setProjectRoles(roles)` |
+| `project.ts` | `CueProjects` | `cue.projects` | `inviteUserToProject()`, `changeUserRoleOnProject()`, `removeUserFromProject()` |
+| `profile.ts` | `CueProfile` | `cue.profile` | `getUserInfo(uids)`, `acceptTerms()`, API key management |
+| `cache.ts` | `CueCache` | `cue.cache` | `getQueryCache`, `setQueryCache`, `getAgentSessionCache`, `setAgentSessionCache`, `getUserProjectCache`, `setUserProjectCache` |
+| `signal.ts` | `CueSignal<T>` | exported | Writable reactive state; `get()`, `set()`, `subscribe()` |
+| `signal.ts` | `cueComputed()` | exported | Derived read-only signal from deps |
+| `signal.ts` | `staleWhileRevalidate()` | exported | Serve stale cache data first, then revalidate; generic `QueryCache` interface |
+| `api.ts` | `CueApi` | `cue.api` | `search()`, `sparql()`, `sync` (Node only) |
+| `schema.ts` | `CueProjectSchema` | `view.schema` | `availableContentCategories`, `availableEntityCategories`, `availableEntityRelationships` (all `ReadonlySignal`); `setLanguage()`, `refresh()` |
+| `entities.ts` | `CueProjectEntities` | `view.entities` | `entityInfoMap`, `entityGraph` (all `ReadonlySignal`); `requestEntityData()`, `requestEntityLocations()`, `fetchEntityRelationships()`, `fetchEntityDocuments()`, `entityIri()`, `reset()` |
+| `documents.ts` | `CueProjectDocuments` | `view.documents` | `documentInfoMap`, `projectDocumentsData` (all `ReadonlySignal`); `requestDocumentData()`, `fetchOverview()`, `setLanguage()`, `reset()` |
+| `project-view.ts` _(pending)_ | `CueProjectView` | `cue.createProjectView()` | Facade over schema + entities + documents; adds `search()`, `searchResults`, `setLanguage()`, `destroy()` |
+
+---
+
+## Firestore Collections Reference
+
+| Collection | Document type | Owner |
+|-----------|--------------|-------|
+| `projects` | `ProjectDoc` | `ProjectRepo` → `docStore` |
+| `users` | `UserDoc` | `UserRepo` → `docStore` |
+| `organizations` | `OrganizationDoc` | `OrganizationRepo` → `docStore` |
+| `apiKeys` | `APIKeyDoc` | `APIKeysRepo` → `docStore` |
+| `rdfWriting` | `RDFWritingDoc` | `RDFWritingRepo` → `docStore` |
+| `tiers` | `TierDoc` | `FirebaseService` (raw, portal doesn't use) |
+| `userTermsAcceptance` | `{ uid, timestamp }` | `FirebaseService` (raw) |
+| `chatSessions` | `ChatSessionDoc` | `FirebaseService` (raw) |
+
+## Storage Buckets Reference
+
+| Bucket name | Key | Owner |
+|-------------|-----|-------|
+| `cue_raw_eu_west6` | `raw` | `FileRepo` → `blobStore` |
+| `cue_processed_eu_west6` | `processed` | `FileRepo` → `blobStore` |
+| `cue_logs_eu_west6` | `logs` | `FileRepo` → `blobStore` |
+| `cue_public_eu_west6` | `public` | `FileRepo` → `blobStore` |
+| `db_persistence_eu_west6` | `persistence` | `CueCache` (via `firebase/storage` directly) |
+| `cue_chat_sessions_eu_west6` | `chatSessions` | `FileRepo` → `blobStore` |
+
+---
+
+## Completed Work (archive)
+
+### Phase 6 (partial) — Knowledge Graph data classes
+
+| Class | File | Replaces |
+|---|---|---|
+| `CueProjectSchema` | `schema.ts` | `AvailableCategoriesService` |
+| `CueProjectEntities` | `entities.ts` | `EntityInfoService` |
+| `CueProjectDocuments` | `documents.ts` | `ProjectDocumentsService` + `DocumentInfoService` (SPARQL) |
+
+All three classes:
+- Accept `CueApi` + `projectId` — no Angular dependencies
+- Use `CueSignal<T>` / `cueComputed()` — framework-agnostic reactive signals
+- Accept optional `QueryCache` for stale-while-revalidate caching via `staleWhileRevalidate()`
+- Use `js/prefixes` (`qaecyPrefixes`, `prefixCC`) — no inline namespace constants
+- Exported from `libs/js/cue-sdk/src/index.ts`
+
+`staleWhileRevalidate<T>(query, fetchFresh, onData, cache?)` helper added to `signal.ts`:
+- Serves cached (stale) data immediately via `cache.get(key)` then fires `onData(stale, true)`
+- Fetches fresh data, fires `onData(fresh, false)`, writes to cache only if data changed
+- Cache key is `contextBasedGuid(query)` (deterministic UUID v5 hash)
+
+---
+
+### `js-databases` — Provider-agnostic storage layer
+
+- `IDocStore` interface + `FirestoreDocStore` implementation
+- `CueBlobStorage` covers all 6 named buckets and all file operations
+- `CueFirebase` constructs and exposes `docStore` + `blobStore`
+
+### `js-cue-sdk` additions
+
+- **`Cue.fromApp(app, config?)`** — static factory that reuses an existing `FirebaseApp` (portal shares auth session with SDK without a second login)
+- **`CueSignal<T>` + `cueComputed()`** — vanilla framework-agnostic reactive primitives
+- **`CueAuth` signals** — `user`, `token`, `isSuperAdmin`, `userIds` all reactive via `onIdTokenChanged`
+- **`CuePrivileges`** — role expansion (`admin → [admin, syncer, member]`), `REQUIRED_ROLES`, `privileges` signal auto-recomputes when roles or superadmin status changes
+- **`CueProjects`** cloud function wrappers: `inviteUserToProject`, `changeUserRoleOnProject`, `removeUserFromProject`
+- **`CueProfile`** cloud function wrappers: `getUserInfo`, `acceptTerms`
+- **`CueCache`** — gzip cache over `db_persistence_eu_west6`; uses `CompressionStream`/`DecompressionStream` (web standard, no `fflate` in SDK)
+- **Doc types in SDK models** — `ProjectDoc`, `OrganizationDoc`, `UserDoc`, `RDFWritingDoc`, `ViewDefinition` (type aliases/interfaces; classes remain in `js-firebase` for CLI/admin)
+
+### `cue-repos` — Angular adapters
+
+| Service / Repo | Before | After |
+|----------------|--------|-------|
+| All 5 doc repos | Raw `CollectionReference` + `onSnapshot` | `docStore.subscribeToCollection/Doc` |
+| `FileRepo` | Raw `firebase/storage` calls | `blobStore.*` |
+| `CacheRepo` | 200-line `fflate`-based gzip impl | 40-line delegate to `cue.cache` |
+| `PrivilegesService` | Owned all role logic | Thin adapter — syncs from `cue.privileges` signal |
+| `CueSdkService` | — | New: `sdk: Signal<Cue \| undefined>` via `Cue.fromApp()` |
+| `settings.component.ts` | Used `FirebaseService` | Uses `CueSdkService → sdk.projects.*` |
+| `UsersRepo` | Used `FirebaseService.functionGetUserInfo` | Uses `sdk.profile.getUserInfo()` |
+
+Doc type imports in `cue-repos` and portal services moved from `js-firebase` → `js-cue-sdk` (7 files, type-only).
+

package/README.md

@@ -12,9 +12,14 @@ npm install @qaecy/cue-sdk firebase
 
 ## Quick start
 
+### Demo app
 ```typescript
 import { Cue } from '@qaecy/cue-sdk';
 
+// Use default demo app (prints a warning — fine for evaluation)
+const cue = new Cue();
+
+// Or supply your own configuration
 const cue = new Cue({
   apiKey: 'YOUR_FIREBASE_API_KEY',
   appId: 'YOUR_FIREBASE_APP_ID',
@@ -53,9 +58,9 @@ await cue.auth.signOut();
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `apiKey` | `string` | ✅ | Firebase API key |
-| `appId` | `string` | ✅ | Firebase App ID |
-| `measurementId` | `string` | ✅ | Firebase Measurement ID |
+| `apiKey` | `string` | — | Firebase API key (defaults to QAECY demo app) |
+| `appId` | `string` | — | Firebase App ID (defaults to QAECY demo app) |
+| `measurementId` | `string` | — | Firebase Measurement ID (defaults to QAECY demo app) |
 | `environment` | `'production' \| 'emulator'` | — | Target environment (default: `'production'`) |
 | `endpoints` | `Partial<CueEndpoints>` | — | Override individual endpoint URLs (takes precedence over `environment`) |
 
@@ -240,6 +245,48 @@ Access the raw Firebase `Auth` instance for advanced use cases:
 const firebaseAuth = cue.auth.firebaseAuth;
 ```
 
+## E2E tests
+
+The SDK ships integration tests in `e2e/` that run against the local Firebase emulator stack.
+
+### Prerequisites
+
+Start the frontend emulator stack from the `e2e` repo (requires Docker):
+
+```bash
+# From /path/to/e2e
+docker compose up firebase-emulator frontend-seed
+```
+
+This spins up Firebase Auth, Firestore, and Storage emulators and seeds the following password-enabled test accounts:
+
+| Email | Password | Role |
+|-------|----------|------|
+| `front-regular@example.com` | `Test1234!` | member |
+| `front-super@example.com` | `Test1234!` | superadmin |
+
+### Run
+
+```bash
+npx nx run js-cue-sdk:e2e
+```
+
+Or directly with vitest (from `libs/js/cue-sdk/`):
+
+```bash
+npx vitest run --config vitest.e2e.config.mts
+```
+
+### What is tested
+
+| Suite | Tests |
+|-------|-------|
+| `CueAuth — reactive signals` | `user`, `token`, `isSuperAdmin` (false), `checkSuperAdmin()`, `userIds` |
+| `CueProfile — password management` | `getSignInMethods`, `updatePassword` → sign-in with new pw, old pw rejected, restore |
+| `CueAuth — superadmin claim` | `isSuperAdmin` signal (true), `checkSuperAdmin()` (true) |
+
+---
+
 ## License
 
 MIT