@qaecy/cue-sdk 0.0.5 → 0.0.8

package/lib/models.d.ts

@@ -16,12 +16,12 @@ export interface CueEndpoints {
     firestoreEmulatorPort: number;
 }
 export interface CueSdkConfig {
-    /** Firebase API key for this project */
-    apiKey: string;
-    /** Firebase App ID */
-    appId: string;
-    /** Firebase Measurement ID */
-    measurementId: string;
+    /** Firebase API key for this project. Defaults to the QAECY demo app if omitted. */
+    apiKey?: string;
+    /** Firebase App ID. Defaults to the QAECY demo app if omitted. */
+    appId?: string;
+    /** Firebase Measurement ID. Defaults to the QAECY demo app if omitted. */
+    measurementId?: string;
     /** Target environment. Defaults to 'production'. */
     environment?: CueEnvironment;
     /** Override individual endpoint URLs. Takes precedence over environment. */
@@ -40,6 +40,11 @@ export interface SearchRequest {
     /** Optional category filters */
     categories?: string[];
 }
+/** Options for `CueProjectView.search()`. */
+export interface SearchOptions {
+    /** Optional content category IRI filters. */
+    categories?: string[];
+}
 export interface SearchSource {
     item: string;
     parent: string;
@@ -60,9 +65,11 @@ export interface ProjectSettings {
     }>;
     chatDisabled: boolean;
     graph?: {
-        type: string;
-        uri: string;
+        type: 'qlever' | 'fuseki';
+        uri?: string;
     };
+    /** Processing tier determining credit costs. Defaults to "l" if not set. */
+    tier?: 's' | 'm' | 'l';
 }
 export interface ProjectData {
     id: string;
@@ -84,6 +91,23 @@ export interface CreateProjectOptions {
     name: string;
     /** Explicit project ID. Defaults to a new UUID. */
     id?: string;
+    /** UIDs to set as project admins. Non-superadmin callers are always included automatically. */
+    admins?: string[];
+    /** UIDs to set as project syncers. Non-superadmin callers are always included automatically. */
+    syncers?: string[];
+    /** UIDs to set as project members. Non-superadmin callers are always included automatically. */
+    members?: string[];
+    /** Graph backend type. The service maps this to the configured URI. */
+    graphType?: 'fuseki' | 'qlever';
+    /** Processing tier determining credit costs. */
+    tier?: 's' | 'm' | 'l';
+}
+export interface SyncProgress {
+    percent: number;
+    syncCount: number;
+    totalCount: number;
+    syncSize: number;
+    totalSize: number;
 }
 export interface SyncOptions {
     /** The project/space ID to sync into */
@@ -94,7 +118,16 @@ export interface SyncOptions {
     userId: string;
     /** Enable verbose logging */
     verbose?: boolean;
+    /** Called whenever upload progress changes */
+    onProgress?: (progress: SyncProgress) => void;
+    /** Write RDF as BLOBs to the processed bucket instead of patching the graph directly */
+    legacy?: boolean;
 }
+/**
+ * Credit cost table fetched from the public bucket (`unit-credit.json`).
+ * Maps file extension → tier → credits per unit.
+ */
+export type UnitCreditMap = Partial<Record<'s' | 'm' | 'l', Record<string, number>>>;
 /** Per-extension cost breakdown returned by {@link CueSyncApi.scanCost}. */
 export interface ScanOutputRecord {
     /** File extension (without leading dot), e.g. `"pdf"`, `"ifc"`. */
@@ -109,17 +142,29 @@ export interface ScanOutputRecord {
     units: number;
     /** Total size of files with this extension in megabytes. */
     sizeMb: number;
+    /** Credits to consume for this extension (units × credit-per-unit for the project tier). */
+    credits?: number;
 }
 export interface UnitsConsumedDto {
+    creditsAvailable: number;
+    creditsConsumed: number;
+    filesProcessed: number;
     unitsAvailable: number;
     unitsConsumed: number;
-    filesProcessed: number;
 }
 export interface SyncPreview {
     /** Per-extension cost breakdown for files not yet synced */
     costRecords: ScanOutputRecord[];
+    /** Project tier used for cost calculation */
+    tier: 's' | 'm' | 'l';
+    /** Human-readable tier name from tier-names.json */
+    tierName: string;
     /** Total units required for the new files */
     unitsToConsume: number;
+    /** Total credits to consume (derived from unit-credit.json + project tier) */
+    creditsToConsume: number;
+    /** Credits currently available for this project */
+    creditsAvailable: number;
     /** Units still available for this project */
     unitsAvailable: number;
     /** Number of new files that would be uploaded */
@@ -140,6 +185,23 @@ export interface SyncResult {
     totalSize: number;
     /** Whether any RDF metadata was written */
     rdfWritten: boolean;
+    /** Updated credit balance after sync, fetched from the consumption endpoint */
+    creditsAvailable: number;
+}
+export interface OrgMember {
+    uid: string;
+    name: string;
+    email: string;
+    isAdmin: boolean;
+}
+export interface OrganizationData {
+    id: string;
+    name: string;
+    created: string;
+    admins: string[];
+    members: string[];
+    alternativeIDs: string[];
+    domain: string;
 }
 export interface ProfileSSOAccount {
     id: string;
@@ -154,3 +216,133 @@ export interface APIKeyDoc {
     uid: string;
     expiration: string;
 }
+/** Alias for {@link ProjectData} — the Firestore document shape for a project. */
+export type ProjectDoc = ProjectData;
+/** Alias for {@link OrganizationData} — the Firestore document shape for an org. */
+export type OrganizationDoc = OrganizationData;
+export interface UserDoc {
+    id: string;
+    name: string;
+    email: string;
+    created: string;
+    lastVisit: string;
+    lastVisitProjects?: Record<string, string>;
+    organizations: string[];
+    locale?: string;
+    hasAcceptedTermsAndConditions: boolean;
+}
+export interface RDFWritingDoc {
+    id: string;
+    accumulatedSizeSinceLastIdleEvent: number;
+    accumulatedFilesSinceLastIdleEvent: number;
+    firstRDFWrite: string;
+    lastRDFWrite: string;
+}
+export interface ViewDefinition {
+    id: string;
+    pinned?: boolean;
+}
+/**
+ * Minimal cache interface for SPARQL query results.
+ *
+ * Implement this against any storage backend (Cloud Storage, localStorage,
+ * IndexedDB, in-memory Map) and pass it to the project-view classes to enable
+ * stale-while-revalidate query caching.
+ *
+ * The Angular adapter wires this to `CueCache` from `cue-repos`.
+ */
+export interface QueryCache {
+    get(key: string): Promise<unknown | undefined>;
+    set(key: string, data: unknown): Promise<void>;
+}
+/** A taxonomy node (content category or entity category) from the triplestore. */
+export interface CategoryDef {
+    iri: string;
+    label: string;
+    /** IRI of the parent category (skos:broader), if any. */
+    parent?: string;
+}
+/**
+ * A relationship type discovered in the triplestore via `qcy:relatedEntity` property scan.
+ * The IRI is the property IRI, label is its rdfs:label.
+ */
+export type RelationshipDef = CategoryDef;
+/** Core label + classification data for a single entity. */
+export interface EntityCoreData {
+    value: string;
+    categories: string[];
+    mentionCount?: number;
+}
+/** A single directed relationship edge between two entities. */
+export interface EntityRelationship {
+    /** IRI of the property used (e.g. `qcy:hasContractor`). */
+    relIRI: string;
+    /** Full IRI of the related entity. */
+    nodeIRI: string;
+    /** Label of the related entity. */
+    nodeValue: string;
+    /** Category IRIs of the related entity. */
+    nodeCategories: string[];
+}
+/** Incoming and outgoing relationship edges for one entity. */
+export interface EntityRelationships {
+    incoming: EntityRelationship[];
+    outgoing: EntityRelationship[];
+}
+/** An OSM geometry associated with an entity or related entity. */
+export interface MapGeometry {
+    osmIRI: string;
+    wkt: string;
+}
+/** Fully resolved data for a single entity, merging all lazy-loaded slices. */
+export interface EntityDetailedData extends EntityCoreData {
+    relationshipData?: EntityRelationships;
+    /** UUIDs of documents that reference this entity. */
+    documentRefs?: string[];
+    directMapGeometries?: MapGeometry[];
+    indirectMapGeometries?: Array<{
+        rel: string;
+        entityUUID: string;
+        geometries: MapGeometry[];
+    }>;
+}
+/**
+ * Project-level entity category graph — nodes are category IRIs, edges
+ * represent the `qcy:relatedEntity` connection at the category level.
+ */
+export interface ProjectEntitiesData {
+    entities: Array<{
+        iri: string;
+        size?: number;
+    }>;
+    relations: Array<{
+        sourceID: string;
+        targetID: string;
+    }>;
+}
+/** Core metadata for a single document (FileContent node). */
+export interface DocumentInfo {
+    id: string;
+    contentIRI: string;
+    path: string;
+    suffix: string;
+    size: number;
+    tags: string[];
+    categories: string[];
+    subject?: string;
+    summary?: string;
+    providerId?: string;
+}
+/** Count + total size for a group of documents (e.g. grouped by suffix or category). */
+export interface DocumentSummary {
+    size: number;
+    count: number;
+}
+/** Project-level document overview — fetched once on project init. */
+export interface ProjectDocumentsData {
+    duplicateCount: number;
+    /** File extension → `{ size, count }` */
+    documentsBySuffix: Record<string, DocumentSummary>;
+    /** Content-category IRI → `{ size, count }` */
+    documentsByContentCategory: Record<string, DocumentSummary>;
+}

package/lib/privileges.d.ts

@@ -0,0 +1,53 @@
+import { ReadonlySignal } from './signal';
+/** Roles ordered from highest to lowest privilege. */
+declare const ROLE_HIERARCHY: readonly ["superadmin", "admin", "syncer", "member"];
+export type UserProjectRole = (typeof ROLE_HIERARCHY)[number];
+export interface Privileges {
+    changeContentCategories: boolean;
+    createEntities: boolean;
+    createProvider: boolean;
+    deleteDocuments: boolean;
+    deleteUserFromProject: boolean;
+    downloadDocuments: boolean;
+    editContentCategories: boolean;
+    editPublicReposAvailableToAgent: boolean;
+    editTier: boolean;
+    inviteUserToProject: boolean;
+    renameDocuments: boolean;
+    uploadDocuments: boolean;
+    viewEntities: boolean;
+}
+/** Minimum role required for each privilege. */
+export declare const REQUIRED_ROLES: Record<keyof Privileges, UserProjectRole>;
+/**
+ * Manages role-based access control for the current user + selected project.
+ *
+ * - Call `setProjectRoles()` whenever the selected project changes.
+ * - Read `privileges` (a `ReadonlySignal<Privileges>`) for reactive access.
+ *
+ * @example
+ * cue.privileges.setProjectRoles(['admin']);
+ * const canUpload = cue.privileges.privileges.get().uploadDocuments; // true
+ */
+export declare class CuePrivileges {
+    private readonly _isSuperAdmin;
+    private readonly _projectRoles;
+    /**
+     * Reactive signal — current user's privileges for the selected project.
+     * Recomputes automatically when `setProjectRoles()` is called or when
+     * the `isSuperAdmin` signal changes.
+     */
+    readonly privileges: ReadonlySignal<Privileges>;
+    constructor(_isSuperAdmin: ReadonlySignal<boolean>);
+    /**
+     * Set the user's roles for the currently selected project.
+     *
+     * Roles are expanded along the hierarchy: `admin` automatically includes
+     * `syncer` and `member`; `syncer` includes `member`. Pass an empty array
+     * to reset to the lowest privilege level.
+     */
+    setProjectRoles(roles: UserProjectRole[]): void;
+    private _expand;
+    private _compute;
+}
+export {};

package/lib/profile.d.ts

@@ -1,12 +1,14 @@
 import { UserInfo } from 'firebase/auth';
 import { FirebaseApp } from 'firebase/app';
-import { APIKeyDoc, APIKeyInfo, ProfileSSOAccount } from './models';
+import { APIKeyDoc, APIKeyInfo, OrgMember, OrganizationData, ProfileSSOAccount } from './models';
 import { CueAuth } from './auth';
 export declare class CueProfile {
     private readonly _auth;
-    private readonly _db;
-    private _apiKeyDocRef?;
-    constructor(_auth: CueAuth, app: FirebaseApp, useEmulator: boolean, emulatorHost: string, emulatorPort: number);
+    private readonly _gatewayUrl;
+    private readonly _functions;
+    constructor(_auth: CueAuth, app: FirebaseApp, useEmulator: boolean, _gatewayUrl: string);
+    private _url;
+    private _fetch;
     /** Whether the current user has an active API key. */
     hasAPIKey(): Promise<boolean>;
     /** Returns the sign-in methods registered for the current user's email. */
@@ -31,6 +33,21 @@ export declare class CueProfile {
     revokeAPIKey(): Promise<void>;
     /** Fetches the current user's existing API key. */
     requestAPIKey(): Promise<APIKeyInfo>;
-    private _checkIfUserHasAPIKey;
+    /** Returns organizations the current user is a member of. */
+    listOrganizations(): Promise<(Pick<OrganizationData, 'id' | 'name'> & {
+        isAdmin: boolean;
+    })[]>;
+    /** Returns all members of the given organisation. Caller must be an org admin or superadmin. */
+    getOrgMembers(orgId: string): Promise<OrgMember[]>;
     private _requireUser;
+    /**
+     * Fetch display name and email for a list of user UIDs.
+     * Uses the `getUserInfo` Firebase callable function.
+     */
+    getUserInfo(uids: string[]): Promise<Record<string, {
+        name: string;
+        email: string;
+    }>>;
+    /** Record that the current user has accepted the terms of service. */
+    acceptTerms(): Promise<void>;
 }

package/lib/project-view.d.ts

@@ -0,0 +1,107 @@
+import { CueApi } from './api';
+import { CueProjectSchema } from './schema';
+import { CueProjectEntities } from './entities';
+import { CueProjectDocuments } from './documents';
+import { ReadonlySignal } from './signal';
+import { QueryCache, SearchOptions, SearchResponse, CategoryDef, RelationshipDef, EntityDetailedData, EntityRelationships, ProjectEntitiesData, DocumentInfo, ProjectDocumentsData } from './models';
+export interface CueProjectViewOptions {
+    language: string;
+    queryCache?: QueryCache;
+    /** Override the RDF resource base URL. Defaults to `https://cue.qaecy.com/r/`. */
+    rdfBase?: string;
+    /** Graph engine type from projectSettings.graph.type (e.g. 'qlever' or 'fuseki'). */
+    graphType?: string;
+}
+/**
+ * Framework-agnostic facade over `CueProjectSchema`, `CueProjectEntities`, and
+ * `CueProjectDocuments`. Exposes a flat, ergonomic API for all knowledge-graph
+ * view state needed by the portal.
+ *
+ * Create via `cue.createProjectView()` rather than constructing directly — the
+ * factory wires the active `QueryCache` automatically.
+ *
+ * @example
+ * ```ts
+ * const view = cue.createProjectView('my-project', { language: 'en' });
+ * view.entityInfoMap.subscribe(map => render(map));
+ * view.requestEntityData(['uuid1', 'uuid2']);
+ * ```
+ */
+export declare class CueProjectView {
+    private readonly _api;
+    private readonly _projectId;
+    /** Direct access to the schema data class (available categories / relationships). */
+    readonly schema: CueProjectSchema;
+    /** Direct access to the entity data class. */
+    readonly entities: CueProjectEntities;
+    /** Direct access to the document data class. */
+    readonly documents: CueProjectDocuments;
+    /** Available content category definitions for this project. Auto-fetched on init. */
+    readonly availableContentCategories: ReadonlySignal<CategoryDef[]>;
+    /** Available entity category definitions for this project. Auto-fetched on init. */
+    readonly availableEntityCategories: ReadonlySignal<CategoryDef[]>;
+    /** Available entity relationship types. Auto-fetched on init. */
+    readonly availableEntityRelationships: ReadonlySignal<RelationshipDef[]>;
+    /** Merged per-entity detail map. Populated lazily via `requestEntityData()` etc. */
+    readonly entityInfoMap: ReadonlySignal<Record<string, EntityDetailedData>>;
+    /** Project-level entity co-occurrence graph. Fetched once on init. */
+    readonly entityGraph: ReadonlySignal<ProjectEntitiesData | undefined>;
+    /** Per-document info map. Populated lazily via `requestDocumentData()`. */
+    readonly documentInfoMap: ReadonlySignal<Record<string, DocumentInfo>>;
+    /** Project document overview (counts by suffix and category). Fetched on init. */
+    readonly projectDocumentsData: ReadonlySignal<ProjectDocumentsData | undefined>;
+    private readonly _searchResults;
+    /** The result of the most recent `search()` call. `undefined` before first search. */
+    readonly searchResults: ReadonlySignal<SearchResponse | undefined>;
+    private _destroyed;
+    constructor(_api: CueApi, _projectId: string, { language, queryCache, rdfBase, graphType }: CueProjectViewOptions);
+    /**
+     * Lazily batch-fetch core data (label + categories) for the given entity UUIDs.
+     * Already-fetched UUIDs are skipped. Populates `entityInfoMap`.
+     */
+    requestEntityData(uuids: string[], includeMentionCount?: boolean): void;
+    /**
+     * Lazily fetch OSM location data for the given entity UUIDs.
+     * Already-fetched UUIDs are skipped. Populates `entityInfoMap` geometry fields.
+     */
+    requestEntityLocations(uuids: string[]): Promise<void>;
+    /**
+     * Fetch incoming and outgoing relationships for a single entity IRI.
+     * Result is stored in `entityInfoMap[uuid].relationshipData`.
+     */
+    fetchEntityRelationships(iri: string): Promise<EntityRelationships>;
+    /**
+     * Fetch UUIDs of documents that reference the given entity IRI.
+     * Result is stored in `entityInfoMap[uuid].documentRefs`.
+     */
+    fetchEntityDocuments(iri: string): Promise<string[]>;
+    /** Constructs the full RDF IRI for an entity UUID. */
+    entityIri(uuid: string): string;
+    /**
+     * Lazily batch-fetch document info for the given UUIDs.
+     * Already-fetched UUIDs are skipped. Populates `documentInfoMap`.
+     */
+    requestDocumentData(uuids: string[]): void;
+    /**
+     * Run a natural-language search against the project.
+     * The result is stored in `searchResults` and replaces any previous result.
+     */
+    search(term: string, options?: SearchOptions): Promise<void>;
+    /**
+     * Switch the active language for schema labels and document text fields.
+     * Schema responses are cached per language (instant if previously loaded).
+     * The document info map is cleared and lazily re-populated on next access.
+     */
+    setLanguage(lang: string): void;
+    /**
+     * Reset all entity and document state and re-fetch the project overview.
+     * Prefer creating a fresh `CueProjectView` when switching projects.
+     * Use `reset()` only when the same project's data needs to be invalidated.
+     */
+    reset(): void;
+    /**
+     * Tear down this view instance. Clears all reactive state and blocks further
+     * updates. Call from the Angular adapter's `ngOnDestroy` or equivalent.
+     */
+    destroy(): void;
+}

package/lib/project.d.ts

@@ -1,9 +1,12 @@
 import { FirebaseApp } from 'firebase/app';
 import { CueAuth } from './auth';
 import { CreateProjectOptions, CueEndpoints, ProjectData } from './models';
+type ProjectRole = 'admin' | 'syncer' | 'member';
 export declare class CueProjects {
     private readonly _auth;
     private readonly _db;
+    private readonly _functions;
+    private readonly _gatewayUrl;
     constructor(_auth: CueAuth, app: FirebaseApp, useEmulator?: boolean, endpoints?: CueEndpoints);
     private _requireUser;
     /**
@@ -12,8 +15,8 @@ export declare class CueProjects {
      */
     createProject(options: CreateProjectOptions): Promise<ProjectData>;
     /**
-     * List all projects where the authenticated user appears in the members, syncers, or admins array.
-     * Runs three parallel Firestore queries and deduplicates by project ID.
+     * List all projects where the authenticated user appears in the members array.
+     * Access is gated by Firestore rules which check membership.
      */
     listProjects(): Promise<ProjectData[]>;
     /** Fetch a single project by ID. Returns null if not found. */
@@ -23,4 +26,16 @@ export declare class CueProjects {
      * document, creating it if it doesn't exist. Intended for pre-flight checks.
      */
     incrementUnitsConsumed(projectId: string, units: number, userId: string): Promise<void>;
+    /**
+     * Invite a user to a project by email. Returns the invited user's uid and display name.
+     */
+    inviteUserToProject(email: string, projectId: string, role: ProjectRole): Promise<{
+        uid: string;
+        name?: string;
+    }>;
+    /** Change an existing member's role on a project. */
+    changeUserRoleOnProject(uid: string, projectId: string, role: ProjectRole): Promise<void>;
+    /** Remove a member from a project. */
+    removeUserFromProject(uid: string, projectId: string): Promise<void>;
 }
+export {};

package/lib/schema.d.ts

@@ -0,0 +1,66 @@
+import { CueApi } from './api';
+import { ReadonlySignal } from './signal';
+import { CategoryDef, QueryCache, RelationshipDef } from './models';
+/**
+ * Holds the schema for a single project: available content categories,
+ * entity categories, and entity relationship types.
+ *
+ * Data is fetched lazily on construction and cached per language so that
+ * switching back to a previously loaded language is instant.
+ *
+ * ### Reactive paradigm
+ * All three collections are exposed as `ReadonlySignal<T>`. Framework adapters
+ * (e.g. Angular) should bridge these to their own reactive primitives using
+ * `subscribe()`.
+ *
+ * ### Lifecycle
+ * One `CueProjectSchema` instance should be created per project. It is owned
+ * by the higher-level `CueProjectView` and shares the same `CueApi` instance.
+ *
+ * @example
+ * ```ts
+ * const schema = new CueProjectSchema(cue.api, projectId, 'en');
+ * schema.availableContentCategories.get(); // CategoryDef[]
+ * schema.setLanguage('da');                // loads from cache or re-fetches
+ * await schema.refresh();                  // force re-fetch current language
+ * ```
+ */
+export declare class CueProjectSchema {
+    private readonly _api;
+    private readonly _projectId;
+    private readonly _queryCache?;
+    private readonly _graphType?;
+    private readonly _cache;
+    private readonly _language;
+    private readonly _contentCategories;
+    private readonly _entityCategories;
+    private readonly _relationships;
+    /** Currently active content categories for the selected language. */
+    readonly availableContentCategories: ReadonlySignal<CategoryDef[]>;
+    /** Currently active entity categories for the selected language. */
+    readonly availableEntityCategories: ReadonlySignal<CategoryDef[]>;
+    /** Currently active entity relationship types for the selected language. */
+    readonly availableEntityRelationships: ReadonlySignal<RelationshipDef[]>;
+    constructor(_api: CueApi, _projectId: string, language: string, _queryCache?: QueryCache | undefined, _graphType?: string | undefined);
+    /** Returns the currently active language. */
+    get language(): string;
+    /**
+     * Switch the active language. If the data for this language has already been
+     * fetched it is applied immediately from cache; otherwise a new SPARQL fetch
+     * is triggered.
+     */
+    setLanguage(lang: string): void;
+    /**
+     * Force a re-fetch for the current language, bypassing the cache.
+     * Useful when the triplestore data has changed.
+     */
+    refresh(): Promise<void>;
+    private _load;
+    private _apply;
+    private _fetchCategories;
+    private _buildCategoriesQuery;
+    private _runCategoriesQuery;
+    private _fetchRelationships;
+    private _buildRelationshipsQuery;
+    private _runRelationshipsQuery;
+}

package/lib/signal.d.ts

@@ -0,0 +1,54 @@
+import { QueryCache } from './models';
+/** A reactive value that can be read and subscribed to. */
+export interface ReadonlySignal<T> {
+    /** Returns the current value. */
+    get(): T;
+    /**
+     * Register a listener that is called whenever the value changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener: () => void): () => void;
+}
+/** A writable reactive state container. */
+export declare class CueSignal<T> implements ReadonlySignal<T> {
+    private _value;
+    private _listeners;
+    constructor(initial: T);
+    get(): T;
+    set(value: T): void;
+    subscribe(listener: () => void): () => void;
+    /** Returns a read-only view of this signal. */
+    asReadonly(): ReadonlySignal<T>;
+}
+/**
+ * Creates a derived read-only signal from one or more source signals.
+ * The compute function is evaluated lazily and cached until a dependency changes.
+ *
+ * @param deps   Source signals to watch.
+ * @param compute Function that computes the derived value; must be pure.
+ * @returns A `ReadonlySignal` with a `destroy()` method to stop tracking deps.
+ */
+export declare function cueComputed<T>(deps: ReadonlySignal<unknown>[], compute: () => T): ReadonlySignal<T> & {
+    destroy(): void;
+};
+/**
+ * Stale-while-revalidate helper for SPARQL queries.
+ *
+ * 1. If `cache` is provided and has a stored result for `cacheKey`, calls
+ *    `onData(staleData, true)` immediately (synchronously relative to the await).
+ * 2. Fires `fetchFresh()` to get current data from the triplestore.
+ * 3. Calls `onData(freshData, false)`.
+ * 4. Writes the fresh result to `cache` only if it differs from the stale
+ *    result (content-addressed via `contextBasedGuid`).
+ * 5. Returns the fresh data.
+ *
+ * If no `cache` is provided the function simply fetches and calls `onData`
+ * once, transparently.
+ *
+ * @param query      The SPARQL query string — also used as cache key input.
+ * @param fetchFresh Function that executes the query and returns the result.
+ * @param onData     Called once with stale data (if available) and once with
+ *                   fresh data.
+ * @param cache      Optional {@link QueryCache} implementation.
+ */
+export declare function staleWhileRevalidate<T>(query: string, fetchFresh: () => Promise<T>, onData: (data: T, isStale: boolean) => void, cache?: QueryCache): Promise<T>;