@qaecy/cue-sdk 0.0.32 → 0.0.33

package/lib/api.d.ts

@@ -1,57 +0,0 @@
-import { CueAuth } from './auth';
-import { SearchRequest, SearchResponse, ShaclValidationReport, UnitsConsumedDto } from './models';
-import { CueProjects } from './project';
-import { CueSyncApi } from './sync';
-import { CueTables } from './tables';
-import { CueExtraction } from './extraction';
-import { CueContexts } from './contexts';
-import { CueIndexApi } from './index-api';
-export declare class CueApi {
-    private readonly _auth;
-    private readonly _gatewayUrl;
-    readonly projects: CueProjects;
-    readonly sync?: CueSyncApi | undefined;
-    readonly tables: CueTables;
-    /** Semantic extraction client — call document pages against a SemanticTemplate. */
-    readonly extraction: CueExtraction;
-    /** Session context file client — fetch and decompress context documents. */
-    readonly contexts: CueContexts;
-    /** Direct interface to the Cue Index accessor — search and lookup. */
-    readonly index: CueIndexApi;
-    /** Active language used for language-sensitive SPARQL queries across all project classes. */
-    language: string;
-    /** Updates the active language. All project classes (`CueProjectSchema`, `CueProjectDocuments`, `CueProjectEntities`) read this at query time. */
-    setLanguage(lang: string): void;
-    constructor(_auth: CueAuth, _gatewayUrl: string, projects: CueProjects, sync?: CueSyncApi | undefined);
-    /**
-     * Returns standard authentication headers for the current user.
-     * Useful when calling Cue-backed services directly (e.g. the GIS proxy).
-     */
-    getAuthHeaders(): Promise<Record<string, string>>;
-    /**
-     * Search project documents using natural language.
-     * The user must be authenticated before calling this.
-     */
-    search(request: SearchRequest): Promise<SearchResponse>;
-    /**
-     * Execute a SPARQL query against the project's triplestore.
-     * The user must be authenticated before calling this.
-     */
-    sparql(query: string, projectId: string, graphType?: string): Promise<unknown>;
-    /**
-     * Validate a SHACL shape against the project's triplestore.
-     *
-     * @param shape     - SHACL shapes graph in Turtle syntax.
-     * @param projectId - Project to validate against.
-     * @param options   - `format`: `'json-ld'` (default, structured result) or `'turtle'` (raw string).
-     *                    `verbose`: include server-side timing logs.
-     *
-     * Returns a {@link ShaclValidationReport} for JSON-LD, or a Turtle string.
-     */
-    shacl(shape: string, projectId: string, options?: {
-        format?: 'json-ld' | 'turtle';
-        verbose?: boolean;
-        graphType?: string;
-    }): Promise<ShaclValidationReport | string>;
-    getConsumption(projectId: string): Promise<UnitsConsumedDto>;
-}

package/lib/auth.d.ts

@@ -1,78 +0,0 @@
-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>;
-    /**
-     * 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 in with a Firebase custom token (e.g. minted server-side for MCP/OAuth flows). */
-    signInWithCustomToken(token: string): Promise<User>;
-    /** Sign out the current user */
-    signOut(): Promise<void>;
-    /**
-     * Register a new user by name and email.
-     * The backend validates that the email domain belongs to an existing organisation,
-     * creates the Firebase Auth account, assigns org membership, and dispatches a
-     * "set your password" email to the address provided.
-     * Returns the new user's UID and the organisation name on success.
-     */
-    signUp(name: string, email: string): Promise<{
-        uid: string;
-        orgName: string;
-    }>;
-    /** Currently signed-in user, or null if not authenticated */
-    get currentUser(): User | null;
-    /** Subscribe to authentication state changes. Returns an unsubscribe function. */
-    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

@@ -1,26 +0,0 @@
-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/contexts.d.ts

@@ -1,17 +0,0 @@
-import { CueAuth } from './auth';
-import { ContextDoc } from './models';
-export declare class CueContexts {
-    private readonly _auth;
-    private readonly _gatewayUrl;
-    constructor(_auth: CueAuth, _gatewayUrl: string);
-    /**
-     * Fetch and decompress a session context document.
-     *
-     * Context files are stored as `sessions_eu_west6/{projectId}/contexts/{contextId}.json.gz`
-     * and served via the gateway at `GET /storage/sessions/{projectId}/contexts/{contextId}.json.gz`.
-     *
-     * @param projectId - The project the context belongs to.
-     * @param contextId - The context document ID (without the `.json.gz` suffix).
-     */
-    getContext(projectId: string, contextId: string): Promise<ContextDoc>;
-}

package/lib/cue-node.d.ts

@@ -1,21 +0,0 @@
-import { CueApi } from './api';
-import { Cue } from './cue';
-import { CueProjects } from './project';
-import { CueSyncApi } from './sync';
-import { CueSdkConfig } from './models';
-/**
- * Node.js entry point for the QAECY SDK.
- * Extends `Cue` with file-sync capabilities that require Node.js APIs.
- *
- * @example
- * const cue = new CueNode({ apiKey: '...', appId: '...', measurementId: '...' });
- * await cue.auth.signInWithApiKey(key);
- * await cue.api.sync.sync(localFiles, { spaceId, providerId, userId });
- */
-export declare class CueNode extends Cue {
-    readonly api: CueApi & {
-        sync: CueSyncApi;
-    };
-    constructor(config: CueSdkConfig);
-    protected _buildApi(projects: CueProjects): CueApi;
-}

package/lib/cue.d.ts

@@ -1,135 +0,0 @@
-import { FirebaseApp } from 'firebase/app';
-import { FirebaseStorage } from 'firebase/storage';
-import { CueAuth } from './auth';
-import { CueStorage } from './storage';
-import { CueApi } from './api';
-import { CueGis } from './gis';
-import { CueProjects } from './project';
-import { CueProfile } from './profile';
-import { CuePrivileges } from './privileges';
-import { CueCache } from './cache';
-import { CueProjectView, CueProjectViewOptions } from './project-view';
-import { CueProjectEntities } from './entities';
-import { CueProjectDocuments } from './documents';
-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`.
- *
- * @example
- * const cue = new Cue({ apiKey: '...', appId: '...', measurementId: '...' });
- * await cue.auth.signIn('google');
- * const results = await cue.api.search({ term: 'my query', projectId: 'project-id' });
- */
-export declare class Cue {
-    readonly auth: CueAuth;
-    readonly api: CueApi;
-    readonly projects: CueProjects;
-    readonly profile: CueProfile;
-    readonly privileges: CuePrivileges;
-    readonly cache: CueCache;
-    readonly storage: CueStorage;
-    protected readonly _app: FirebaseApp;
-    protected readonly _endpoints: CueEndpoints;
-    protected readonly _isEmulator: boolean;
-    protected _storageRaw: FirebaseStorage;
-    protected _storageProcessed: FirebaseStorage;
-    private _gis;
-    private readonly _projectDocuments;
-    private readonly _verbose;
-    /**
-     * Reactive GIS service. Lazily constructed on first access.
-     *
-     * @example
-     * ```ts
-     * cue.gis.setProjectId('my-project');
-     * cue.gis.onAvailableCategories(cats => ...);
-     * cue.gis.setBbox([west, south, east, north]);
-     * cue.gis.setSelectedCategories(new Set(['cadastre', 'building']));
-     * ```
-     */
-    get gis(): CueGis;
-    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;
-    /**
-     * Creates a `CueProjectEntities` instance for the given project, with the
-     * SDK query cache wired automatically.
-     *
-     * Prefer this over `new CueProjectEntities(cue.api, projectId)` — it avoids
-     * the manual cache setup and keeps the instance bound to the correct API.
-     *
-     * @example
-     * ```ts
-     * const entities = cue.createProjectEntities('my-project');
-     * entities.requestEntityData(['uuid1']);
-     * const info = entities.entityInfoMap.get()['uuid1'];
-     *
-     * // Promise-based (no signal polling needed):
-     * const graph = await entities.buildSummaryGraph('graph');
-     * ```
-     */
-    createProjectEntities(projectId: string, opts?: {
-        rdfBase?: string;
-        graphType?: string;
-        queryCache?: QueryCache;
-        verbose?: boolean;
-    }): CueProjectEntities;
-    /**
-     * Creates a `CueProjectDocuments` instance for the given project, with the
-     * SDK query cache wired automatically.
-     *
-     * Prefer this over `new CueProjectDocuments(cue.api, projectId)` — it avoids
-     * the manual cache setup and keeps the instance bound to the correct API.
-     *
-     * @example
-     * ```ts
-     * const docs = cue.createProjectDocuments('my-project');
-     * await docs.fetchOverview();
-     * const data = await docs.fetchDocumentData(['uuid1', 'uuid2']);
-     * ```
-     */
-    createProjectDocuments(projectId: string, opts?: {
-        language?: string;
-        rdfBase?: string;
-        graphType?: string;
-        queryCache?: QueryCache;
-        verbose?: boolean;
-    }): CueProjectDocuments;
-}

package/lib/documents.d.ts

@@ -1,224 +0,0 @@
-import { CueApi } from './api';
-import { ReadonlySignal } from './signal';
-import { FileType } from 'js/models';
-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?;
-    private readonly _verbose;
-    /** Full RDF base URL for this project, e.g. `https://cue.qaecy.com/r/{pid}/` */
-    readonly baseURL: string;
-    /** Tracks the language for which `_documentInfoMap` is currently populated. */
-    private _currentLang;
-    private readonly _documentInfoMap;
-    /** Cumulative unique document UUIDs ever passed to request methods (survives cache hits). */
-    private readonly _seenIds;
-    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, _verbose?: boolean);
-    /**
-     * 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;
-    /**
-     * Promise-based alternative to {@link requestDocumentData} for non-reactive contexts.
-     *
-     * Resolves with the `DocumentInfo` entries for every requested UUID once the
-     * SPARQL response arrives. UUIDs already present in the cache are returned
-     * immediately without a network request. The result is also written into
-     * `documentInfoMap` so reactive consumers stay in sync.
-     *
-     * UUIDs not found in the triplestore are omitted from the returned map.
-     *
-     * @example
-     * ```ts
-     * const docs = await cueProjectDocs.fetchDocumentData(['uuid1', 'uuid2']);
-     * console.log(docs['uuid1'].subject);
-     * ```
-     */
-    fetchDocumentData(uuids: string[]): Promise<Record<string, DocumentInfo>>;
-    /**
-     * Fetches a lightweight document metadata shape (id/path/suffix/size) for
-     * the given UUIDs and merges the results into `documentInfoMap`.
-     *
-     * This is useful for list/table contexts that do not need language-tagged
-     * fields (`subject`, `summary`) or category/tag enrichment.
-     *
-     * UUIDs already present in `documentInfoMap` are skipped.
-     */
-    fetchDocumentDataSimple(uuids: string[]): Promise<Record<string, DocumentInfo>>;
-    /**
-     * Returns the alternative representations of the given document UUID.
-     *
-     * Alternative representations are derived artefacts stored under
-     * `qcy:alternativeRepresentation` in the triplestore — for example a
-     * `.fragments` BIM tile derived from an `.ifc` source file.
-     *
-     * The returned `DocumentInfo` entries are also merged into
-     * `documentInfoMap` so reactive consumers stay in sync.
-     *
-     * @example
-     * ```ts
-     * const alts = await docs.fetchAlternativeRepresentations('abc-123');
-     * // alts[0].suffix => '.fragments'
-     * ```
-     */
-    fetchAlternativeRepresentations(uuid: string): Promise<DocumentInfo[]>;
-    /**
-     * Returns a single arbitrary file path from the project's triplestore.
-     * Useful for pre-filling path-based query inputs with a realistic example.
-     */
-    randomFilePath(): Promise<string | null>;
-    /**
-     * Fetches all `qcy:FileContent` documents whose file suffix matches one of
-     * the given extensions (e.g. `'.ifc'`, `'.pdf'`).
-     *
-     * By default returns only `{ iri, uuid }` — pass `includeMetadata: true` to
-     * also get `path`, `suffix`, and `size`. Use the default form when you intend
-     * to lazy-load full details via `requestDocumentData`.
-     *
-     * Suffixes are matched case-insensitively and the leading dot is optional
-     * (both `'ifc'` and `'.ifc'` are accepted).
-     */
-    documentsBySuffix(suffixes: string[], includeMetadata?: false): Promise<Array<{
-        iri: string;
-        uuid: string;
-    }>>;
-    documentsBySuffix(suffixes: string[], includeMetadata: true): Promise<Array<{
-        iri: string;
-        uuid: string;
-        path: string;
-        suffix: string;
-        size: number;
-    }>>;
-    /**
-     * Fetches documents whose file suffix maps to one of the given `FileType`
-     * values (e.g. `FileType.BIM`, `FileType.CAD`).
-     *
-     * Resolves matching suffixes from `fileExtensionsInfo` and delegates to
-     * `documentsBySuffix`. Accepts the same `includeMetadata` flag.
-     */
-    documentsByFileType(fileTypes: FileType[], includeMetadata?: false): Promise<Array<{
-        iri: string;
-        uuid: string;
-    }>>;
-    documentsByFileType(fileTypes: FileType[], includeMetadata: true): Promise<Array<{
-        iri: string;
-        uuid: string;
-        path: string;
-        suffix: string;
-        size: number;
-    }>>;
-    /**
-     * Fetches all `qcy:FileContent` documents that carry one of the given
-     * content-category IRIs (e.g. as returned by `projectDocumentsData.documentsByContentCategory`).
-     *
-     * By default returns only `{ iri, uuid }` — pass `includeMetadata: true` to
-     * also get `path`, `suffix`, and `size`. Use the default form when you intend
-     * to lazy-load full details via `requestDocumentData`.
-     */
-    documentsByContentCategory(categoryIRIs: string[], includeMetadata?: false): Promise<Array<{
-        iri: string;
-        uuid: string;
-    }>>;
-    documentsByContentCategory(categoryIRIs: string[], includeMetadata: true): Promise<Array<{
-        iri: string;
-        uuid: string;
-        path: string;
-        suffix: string;
-        size: number;
-    }>>;
-    /**
-     * Fetches documents whose MIME type matches one of the given strings
-     * (e.g. `'application/x-step'`, `'application/pdf'`).
-     *
-     * Resolves matching suffixes from `fileExtensionsInfo` and delegates to
-     * `documentsBySuffix`. Accepts the same `includeMetadata` flag.
-     */
-    documentsByMime(mimeTypes: string[], includeMetadata?: false): Promise<Array<{
-        iri: string;
-        uuid: string;
-    }>>;
-    documentsByMime(mimeTypes: string[], includeMetadata: true): Promise<Array<{
-        iri: string;
-        uuid: string;
-        path: string;
-        suffix: string;
-        size: number;
-    }>>;
-    /** Builds a full resource IRI from a UUID without a SPARQL round-trip. */
-    private _resourceIri;
-    private _log;
-    /** Executes the document-info SPARQL query for the given UUIDs, merges results
-     * into `documentInfoMap`, and returns the newly fetched entries. */
-    private _fetchDocumentInfoBatch;
-    /** Executes a reduced document-info query (id/path/suffix/size only), merges
-     * into `documentInfoMap`, and returns newly fetched entries. */
-    private _fetchSimpleDocumentInfoBatch;
-    private _fetchDocumentsBySuffix;
-    private _buildDocumentsBySuffixQuery;
-    private _runDocumentsBySuffixQuery;
-    private _fetchDocumentsByContentCategory;
-    private _buildDocumentsByContentCategoryQuery;
-    private _runDocumentsByContentCategoryQuery;
-    private _fetchDuplicateCount;
-    private _buildDuplicateCountQuery;
-    private _runDuplicateCountQuery;
-}