@qaecy/cue-sdk 0.0.5 → 0.0.8

package/index.d.ts

@@ -1,7 +1,19 @@
 export { Cue } from './lib/cue';
 export { CueAuth } from './lib/auth';
 export { CueApi } from './lib/api';
+export { CueSyncApi, configureScanWasm } from './lib/sync';
+export { CueProjectSchema } from './lib/schema';
+export { CueProjectEntities } from './lib/entities';
+export { CueProjectDocuments } from './lib/documents';
+export { CueProjectView } from './lib/project-view';
+export type { CueProjectViewOptions } from './lib/project-view';
 export { CueProjects } from './lib/project';
 export { CueProfile } from './lib/profile';
-export type { CueSdkConfig, SsoProvider, PasswordCredentials, SearchRequest, SearchResponse, SearchSource, ProjectData, ProjectSettings, CreateProjectOptions, SyncOptions, SyncResult, SyncPreview, ScanOutputRecord, UnitsConsumedDto, ProfileSSOAccount, APIKeyInfo, APIKeyDoc, } from './lib/models';
+export { CuePrivileges, REQUIRED_ROLES } from './lib/privileges';
+export type { UserProjectRole, Privileges } from './lib/privileges';
+export { CueSignal, cueComputed, staleWhileRevalidate } from './lib/signal';
+export type { ReadonlySignal } from './lib/signal';
+export { CueCache } from './lib/cache';
+export type { QueryCacheEntry } from './lib/cache';
+export type { CueSdkConfig, SsoProvider, PasswordCredentials, SearchRequest, SearchResponse, SearchSource, SearchOptions, ProjectData, ProjectSettings, CreateProjectOptions, SyncOptions, SyncResult, SyncPreview, ScanOutputRecord, UnitsConsumedDto, OrganizationData, OrgMember, ProfileSSOAccount, APIKeyInfo, APIKeyDoc, ProjectDoc, OrganizationDoc, UserDoc, RDFWritingDoc, ViewDefinition, QueryCache, CategoryDef, RelationshipDef, EntityCoreData, EntityRelationship, EntityRelationships, MapGeometry, EntityDetailedData, ProjectEntitiesData, DocumentInfo, DocumentSummary, ProjectDocumentsData, } from './lib/models';
 export type { AuthStateListener, Unsubscribe } from './lib/auth';

package/index.js

@@ -1,8 +1,20 @@
-import { C as s, a as u, b as C, c as o, d as r } from "./cue-y-t8nSnt.js";
+import { C as s, a as u, b as C, c, d as i, e as t, f as o, g as r, h as l, i as n, j as P, k as j, l as m, R as h, m as R, n as S, s as f } from "./cue-BIvMahsX.js";
 export {
   s as Cue,
   u as CueApi,
   C as CueAuth,
-  o as CueProfile,
-  r as CueProjects
+  c as CueCache,
+  i as CuePrivileges,
+  t as CueProfile,
+  o as CueProjectDocuments,
+  r as CueProjectEntities,
+  l as CueProjectSchema,
+  n as CueProjectView,
+  P as CueProjects,
+  j as CueSignal,
+  m as CueSyncApi,
+  h as REQUIRED_ROLES,
+  R as configureScanWasm,
+  S as cueComputed,
+  f as staleWhileRevalidate
 };

package/lib/api.d.ts

@@ -8,7 +8,6 @@ export declare class CueApi {
     readonly projects: CueProjects;
     readonly sync?: CueSyncApi | undefined;
     constructor(_auth: CueAuth, _gatewayUrl: string, projects: CueProjects, sync?: CueSyncApi | undefined);
-    private _authHeaders;
     /**
      * Returns standard authentication headers for the current user.
      * Useful when calling Cue-backed services directly (e.g. the GIS proxy).
@@ -23,6 +22,6 @@ export declare class CueApi {
      * Execute a SPARQL query against the project's triplestore.
      * The user must be authenticated before calling this.
      */
-    sparql(query: string, projectId: string): Promise<unknown>;
+    sparql(query: string, projectId: string, graphType?: string): Promise<unknown>;
     getConsumption(projectId: string): Promise<UnitsConsumedDto>;
 }

package/lib/auth.d.ts

@@ -1,18 +1,52 @@
 import { Auth, User } from 'firebase/auth';
 import { FirebaseApp } from 'firebase/app';
 import { CueEndpoints, PasswordCredentials, SsoProvider } from './models';
+import { ReadonlySignal } from './signal';
 export type AuthStateListener = (user: User | null) => void;
 export type Unsubscribe = () => void;
 export declare class CueAuth {
     private readonly _auth;
     private readonly _endpoints;
+    private readonly _userSignal;
+    private readonly _tokenSignal;
+    private readonly _isSuperAdminSignal;
+    private readonly _userIdsSignal;
+    private readonly _stopTokenListener;
+    /** Reactive auth state — emits the signed-in `User`, or `null` when signed out. */
+    readonly user: ReadonlySignal<User | null>;
+    /** Reactive Firebase ID token — refreshes automatically; `null` when signed out. */
+    readonly token: ReadonlySignal<string | null>;
+    /** `true` when the current user has the `superadmin` custom claim. */
+    readonly isSuperAdmin: ReadonlySignal<boolean>;
+    /** All unique UIDs for the current user (Firebase UID + linked provider UIDs). */
+    readonly userIds: ReadonlySignal<string[]>;
     constructor(app: FirebaseApp, useEmulator: boolean | undefined, endpoints: CueEndpoints);
+    /** Stop all internal Firebase listeners. Call when the `Cue` instance is no longer needed. */
+    destroy(): void;
     /** Sign in with Google or Microsoft via browser popup */
     signIn(provider: SsoProvider): Promise<User>;
     /** Sign in with email and password */
     signIn(provider: 'password', credentials: PasswordCredentials): Promise<User>;
-    /** Sign in with a Cue API key */
-    signInWithApiKey(cueApiKey: string, projectId: string): Promise<User>;
+    /**
+     * Initiate a redirect-based sign-in (mobile / iframe contexts where popups
+     * are blocked). Call `checkRedirectResult()` on the next page load to
+     * retrieve the result.
+     */
+    signInWithRedirect(provider: SsoProvider): Promise<void>;
+    /**
+     * Retrieve the result of a redirect sign-in. Returns the signed-in `User`
+     * or `null` if there is no pending redirect result.
+     * Call this once on app startup before showing a sign-in UI.
+     */
+    checkRedirectResult(): Promise<User | null>;
+    /**
+     * One-shot async check — returns `true` if the current user has the
+     * `superadmin` custom claim. For reactive use, read `cue.auth.isSuperAdmin`
+     * (the signal) instead.
+     */
+    checkSuperAdmin(): Promise<boolean>;
+    /** Sign in with a Cue API key. `projectId` is optional — omit it when no project context is available (e.g. admin flows). */
+    signInWithApiKey(cueApiKey: string, projectId?: string): Promise<User>;
     /** Sign out the current user */
     signOut(): Promise<void>;
     /** Currently signed-in user, or null if not authenticated */
@@ -21,6 +55,11 @@ export declare class CueAuth {
     onAuthStateChanged(listener: AuthStateListener): Unsubscribe;
     /** Get the Firebase ID token for the current user, or null if not authenticated */
     getToken(forceRefresh?: boolean): Promise<string | null>;
+    /**
+     * Executes a fetch with a Bearer token. On a 401 response the token is
+     * force-refreshed and the request is retried once before throwing.
+     */
+    authenticatedFetch(url: string, init?: RequestInit): Promise<Response>;
     /** Raw Firebase Auth instance, for advanced use cases */
     get firebaseAuth(): Auth;
 }

package/lib/cache.d.ts

@@ -0,0 +1,26 @@
+import { FirebaseStorage } from 'firebase/storage';
+/** Shape stored by the query cache. */
+export interface QueryCacheEntry {
+    query: string;
+    results: unknown;
+}
+/**
+ * Gzip-compressed JSON cache backed by the `persistence` Cloud Storage bucket.
+ *
+ * Path conventions:
+ * - Query results:      `portal/projects/{pid}/queries/{id}.json.gz`
+ * - Agent sessions:     `portal/projects/{pid}/agent/{id}.json.gz`
+ * - User-project data:  `portal/projects/{pid}/users/{uid}/{id}.json.gz`
+ */
+export declare class CueCache {
+    private readonly _storage;
+    constructor(_storage: FirebaseStorage);
+    getQueryCache(projectId: string, id: string): Promise<QueryCacheEntry | undefined>;
+    setQueryCache(projectId: string, id: string, payload: QueryCacheEntry): Promise<void>;
+    getAgentSessionCache(projectId: string, id: string): Promise<object | undefined>;
+    setAgentSessionCache(projectId: string, id: string, payload: object): Promise<void>;
+    getUserProjectCache(projectId: string, userId: string, id: string): Promise<object | undefined>;
+    setUserProjectCache(projectId: string, userId: string, id: string, payload: object): Promise<void>;
+    private _get;
+    private _set;
+}

package/lib/cue.d.ts

@@ -3,7 +3,10 @@ import { CueAuth } from './auth';
 import { CueApi } from './api';
 import { CueProjects } from './project';
 import { CueProfile } from './profile';
-import { CueEndpoints, CueSdkConfig } from './models';
+import { CuePrivileges } from './privileges';
+import { CueCache } from './cache';
+import { CueProjectView, CueProjectViewOptions } from './project-view';
+import { CueEndpoints, CueSdkConfig, QueryCache } from './models';
 /**
  * Main entry point for the QAECY SDK (browser-safe).
  * For Node.js use with file-sync capabilities, use `CueNode` from `js-cue-sdk/node`.
@@ -16,13 +19,50 @@ import { CueEndpoints, CueSdkConfig } from './models';
 export declare class Cue {
     readonly auth: CueAuth;
     readonly api: CueApi;
+    readonly projects: CueProjects;
     readonly profile: CueProfile;
+    readonly privileges: CuePrivileges;
+    readonly cache: CueCache;
     protected readonly _app: FirebaseApp;
     protected readonly _endpoints: CueEndpoints;
     protected readonly _isEmulator: boolean;
-    constructor(config: CueSdkConfig);
+    constructor(config?: CueSdkConfig);
+    /**
+     * Create a `Cue` instance from an already-initialized Firebase app.
+     *
+     * Use this when the host application (e.g. cue-portal via `CueFirebase`) has
+     * already called `initializeApp()`. Reusing the same `FirebaseApp` means the
+     * SDK shares the same auth state and Firestore instance — no second login is
+     * needed and `getToken()` returns the portal user's token directly.
+     *
+     * Emulator connections are skipped because the host app already set them up.
+     *
+     * @example
+     * // In an Angular service after CueFirebase is ready:
+     * const cue = Cue.fromApp(CueFirebase.getInstance().app!, {
+     *   environment: 'emulator',
+     * });
+     */
+    static fromApp(app: FirebaseApp, config?: Omit<CueSdkConfig, 'apiKey' | 'appId' | 'measurementId'>): Cue;
     /** Override in subclasses to provide a custom CueApi (e.g. with sync). */
     protected _buildApi(projects: CueProjects): CueApi;
     /** Convenience: get the current user's Firebase ID token */
     getToken(forceRefresh?: boolean): Promise<string | null>;
+    /**
+     * Create a `CueProjectView` for the given project, wiring the SDK's query
+     * cache automatically.
+     *
+     * The view auto-fetches the document overview and entity graph on construction
+     * and exposes reactive signals for all project knowledge-graph state.
+     *
+     * @example
+     * ```ts
+     * const view = cue.createProjectView('my-project', { language: 'en' });
+     * view.requestEntityData(['uuid1']);
+     * const info = view.entityInfoMap.get()['uuid1'];
+     * ```
+     */
+    createProjectView(projectId: string, opts: Omit<CueProjectViewOptions, 'queryCache'> & {
+        queryCache?: QueryCache;
+    }): CueProjectView;
 }

package/lib/documents.d.ts

@@ -0,0 +1,84 @@
+import { CueApi } from './api';
+import { ReadonlySignal } from './signal';
+import { DocumentInfo, ProjectDocumentsData, QueryCache } from './models';
+/**
+ * Manages document data for a single project.
+ *
+ * ### Data model
+ * - **`documentInfoMap`** — lazily populated per-document detail signal.
+ *   Call `requestDocumentData(uuids)` to load entries; already-cached UUIDs
+ *   are skipped. Data is merged incrementally.
+ * - **`projectDocumentsData`** — project-level overview (documents grouped by
+ *   suffix and content category, plus duplicate count). Auto-fetched on
+ *   construction via three parallel SPARQL queries that resolve as a single
+ *   atomic update.
+ *
+ * ### Language
+ * `subject` and `summary` fields on documents are language-tagged in the
+ * triplestore. Pass the active language to `requestDocumentData()` and call
+ * `setLanguage()` when it changes (which clears and re-fetches the info map
+ * so labels re-resolve in the new language).
+ *
+ * ### Lifecycle
+ * Call `reset()` when the project changes. The Angular adapter's project-change
+ * effect should call this, followed by `fetchOverview()` once the triplestore
+ * is ready.
+ *
+ * @example
+ * ```ts
+ * const docs = new CueProjectDocuments(cue.api, projectId, 'en');
+ * await docs.fetchOverview();
+ * docs.requestDocumentData(['uuid1', 'uuid2']);
+ * const info = docs.documentInfoMap.get()['uuid1'];
+ * ```
+ */
+export declare class CueProjectDocuments {
+    private readonly _api;
+    private readonly _projectId;
+    private readonly _queryCache?;
+    private readonly _graphType?;
+    /** Full RDF base URL for this project, e.g. `https://cue.qaecy.com/r/{pid}/` */
+    readonly baseURL: string;
+    private _language;
+    private readonly _documentInfoMap;
+    private readonly _projectDocumentsData;
+    /** Lazily populated per-document detail map. */
+    readonly documentInfoMap: ReadonlySignal<Record<string, DocumentInfo>>;
+    /** Project-level document overview (grouped counts + sizes). */
+    readonly projectDocumentsData: ReadonlySignal<ProjectDocumentsData>;
+    constructor(_api: CueApi, _projectId: string, language: string, 
+    /** Override the RDF resource base URL. Defaults to `https://cue.qaecy.com/r/`. */
+    rdfBase?: string, _queryCache?: QueryCache | undefined, _graphType?: string | undefined);
+    /**
+     * Resets all document state. Call when the active project changes.
+     * Follow with `fetchOverview()` once the triplestore is ready.
+     */
+    reset(): void;
+    /**
+     * Updates the active language and clears the document info map so that
+     * language-sensitive fields (subject, summary) are re-fetched on the next
+     * `requestDocumentData()` call.
+     */
+    setLanguage(lang: string): void;
+    /**
+     * Fetches the three-part project overview (by suffix, by content category,
+     * duplicate count) in parallel and writes them as a single atomic update to
+     * `projectDocumentsData`. Safe to call again to refresh.
+     */
+    fetchOverview(): Promise<void>;
+    /**
+     * Lazily batch-fetches core metadata for the given document UUIDs.
+     * Already-cached UUIDs are skipped. Data is merged into `documentInfoMap`
+     * once the SPARQL response arrives.
+     */
+    requestDocumentData(uuids: string[]): void;
+    private _fetchDocumentsBySuffix;
+    private _buildDocumentsBySuffixQuery;
+    private _runDocumentsBySuffixQuery;
+    private _fetchDocumentsByContentCategory;
+    private _buildDocumentsByContentCategoryQuery;
+    private _runDocumentsByContentCategoryQuery;
+    private _fetchDuplicateCount;
+    private _buildDuplicateCountQuery;
+    private _runDuplicateCountQuery;
+}

package/lib/entities.d.ts

@@ -0,0 +1,107 @@
+import { CueApi } from './api';
+import { ReadonlySignal } from './signal';
+import { EntityDetailedData, EntityRelationships, ProjectEntitiesData, QueryCache } from './models';
+/**
+ * Manages entity data for a single project.
+ *
+ * ### Data model
+ * - **`entityInfoMap`** — merged per-entity signal. Recomputes reactively as
+ *   any of the five underlying slices (core data, documents, relationships,
+ *   OSM map, OSM WKT) change.
+ * - **`entityGraph`** — project-level category-to-category relationship graph,
+ *   fetched once on construction.
+ *
+ * ### Lazy loading
+ * All public `request*` / `fetch*` methods are no-ops for UUIDs / IRIs already
+ * in the cache. Only the delta is fetched. Data is merged into the
+ * `entityInfoMap` signal incrementally — callers just react to the signal.
+ *
+ * ### Language
+ * Entity labels (`qcy:value`) are not language-tagged in the triplestore, so
+ * entity data itself is language-independent. The `language` parameter is
+ * carried here for future-proofing and forwards to the schema-level queries
+ * where language filtering does apply.
+ *
+ * ### Lifecycle
+ * Call `reset()` when the project changes. The Angular adapter calls this from
+ * the effect that watches `projectId`.
+ *
+ * @example
+ * ```ts
+ * const entities = new CueProjectEntities(cue.api, projectId);
+ * entities.requestEntityData(['uuid1', 'uuid2']);
+ * const info = entities.entityInfoMap.get()['uuid1'];
+ * ```
+ */
+export declare class CueProjectEntities {
+    private readonly _api;
+    private readonly _projectId;
+    private readonly _queryCache?;
+    private readonly _graphType?;
+    /** Full RDF base URL for this project, e.g. `https://cue.qaecy.com/r/{pid}/` */
+    readonly baseURL: string;
+    private readonly _entityDetails;
+    private readonly _entityDocuments;
+    private readonly _entityRelationships;
+    private readonly _entityOSMMap;
+    private readonly _osmWKTMap;
+    private readonly _fetchingOSMIds;
+    private readonly _entityGraph;
+    private readonly _entityInfoMapComputed;
+    /** Merged per-entity detail map. Updated reactively as data arrives. */
+    readonly entityInfoMap: ReadonlySignal<Record<string, EntityDetailedData>>;
+    /** Project-level category graph (fetched once per project). */
+    readonly entityGraph: ReadonlySignal<ProjectEntitiesData | undefined>;
+    constructor(_api: CueApi, _projectId: string, 
+    /** Override the RDF resource base URL. Defaults to `https://cue.qaecy.com/r/`. */
+    rdfBase?: string, _queryCache?: QueryCache | undefined, _graphType?: string | undefined);
+    /**
+     * Constructs the full RDF IRI for the given entity UUID.
+     * Use this to bridge the UUID-based batch APIs and the IRI-based per-entity APIs.
+     */
+    entityIri(uuid: string): string;
+    /**
+     * Resets all entity state and re-fetches the entity graph.
+     * Call when the active project changes.
+     */
+    reset(): void;
+    /**
+     * Lazily batch-fetches core data (label + categories) for the given entity
+     * UUIDs. Already-fetched UUIDs are skipped.
+     *
+     * Data is merged into `entityInfoMap` once the SPARQL response arrives.
+     */
+    requestEntityData(uuids: string[], includeMentionCount?: boolean): void;
+    /**
+     * Lazily fetches OSM location data for the given entity UUIDs.
+     * Already-fetched UUIDs are skipped.
+     *
+     * OSM WKT geometry is fetched in a second pass via a federated SPARQL SERVICE
+     * query and merged into `entityInfoMap` reactively once it arrives.
+     */
+    requestEntityLocations(uuids: string[]): Promise<void>;
+    /**
+     * Fetches incoming and outgoing relationships for a single entity IRI.
+     * Neighbouring entity core data is opportunistically populated into
+     * `entityInfoMap` as a side-effect.
+     *
+     * The result is stored in `entityInfoMap[uuid].relationshipData` and also
+     * returned directly for callers that need an immediate value.
+     */
+    fetchEntityRelationships(iri: string): Promise<EntityRelationships>;
+    /**
+     * Fetches UUIDs of documents that reference the given entity IRI.
+     * Also triggers a core-data fetch for the entity itself if not yet loaded.
+     *
+     * Returns document UUIDs. Full document data will be populated by the
+     * document service (future `CueProjectDocuments`).
+     */
+    fetchEntityDocuments(iri: string): Promise<string[]>;
+    private _computeEntityInfoMap;
+    private _fetchOutgoingRelationships;
+    private _fetchIncomingRelationships;
+    private _fetchEntityGraph;
+    /** Detects new OSM IRIs in the OSM map that don't yet have WKT and fetches them. */
+    private _checkPendingOSMFetches;
+    private _fetchOSMLocations;
+}