@qaecy/cue-sdk 0.0.33 → 0.0.35

package/lib/documents.d.ts

@@ -0,0 +1,223 @@
+import { CueApi } from './api';
+import { ReadonlySignal } from './signal';
+import { FileType } from 'js/models';
+import { DocumentInfo, ProjectDocumentsData } 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 _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, _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;
+}

package/lib/entities.d.ts

@@ -0,0 +1,211 @@
+import { CueApi } from './api';
+import { ReadonlySignal } from './signal';
+import { EntityDetailedData, EntityRelationships, ProjectEntitiesData, SummaryGraphData } 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 _graphType?;
+    private readonly _verbose;
+    /** 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;
+    /** Cumulative unique entity UUIDs ever passed to request methods (survives cache hits). */
+    private readonly _seenIds;
+    private readonly _entityGraph;
+    /**
+     * Memoizes the raw category-summary rows per neighbourhood (keyed by the
+     * expanded `entityIRI`, or `''` for the full graph) so that repeat/concurrent
+     * `buildSummaryGraph` calls for the same neighbourhood — e.g. re-rendering a
+     * view, or requesting both `'graph'` and `'md'` formats — share one fetch
+     * instead of re-querying. Cleared on `reset()`.
+     */
+    private readonly _summaryGraphCache;
+    /**
+     * Memoizes per-category entity counts (project-wide, not neighbourhood-scoped
+     * — unlike `_summaryGraphCache` there's only ever one of these per project).
+     * Cleared on `reset()`.
+     */
+    private _categoryCountsCache;
+    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, _graphType?: string | undefined, _verbose?: boolean);
+    /**
+     * 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;
+    /** @internal Builds a full resource IRI from a UUID without a SPARQL round-trip. */
+    private _resourceIri;
+    private _log;
+    /**
+     * 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[]>;
+    /**
+     * Fetches all `qcy:EntityCategory` IRIs and their preferred labels for this
+     * project. Uses `api.language` (default `'en'`);
+     * falls back to an untagged label when no match is found.
+     */
+    contentCategoriesInProject(orderByOccurences?: boolean): Promise<{
+        iri: string;
+        label: string;
+    }[]>;
+    /**
+     * Fetches all `qcy:CanonicalEntity` instances that belong to at least one of
+     * the given category IRIs.
+     *
+     * Accepts both full HTTP IRIs and prefixed forms, e.g.:
+     * - `"qcy:Building"`
+     * - `"https://cue.qaecy.com/ontology#Building"`
+     *
+     * By default returns `{ iri, uuid }[]` — the IRI is built locally from the
+     * project base URL so no extra data is fetched from the endpoint.
+     * Pass `includeMetadata: true` to also get `value` and `categories`.
+     * Use the default form when you intend to lazy-load details via `requestEntityData`.
+     */
+    entitiesByCategory(categoryIris: string[], includeMetadata?: false): Promise<Array<{
+        iri: string;
+        uuid: string;
+    }>>;
+    entitiesByCategory(categoryIris: string[], includeMetadata: true): Promise<Array<{
+        iri: string;
+        uuid: string;
+        value: string;
+        categories: string[];
+    }>>;
+    /**
+     * Fetches a summary graph of entity category relationships for the project.
+     *
+     * Each row describes how many times entities of `sourceCat` point to
+     * entities of `targetCat` via a given `predicate`, ordered by descending
+     * occurrence count.
+     *
+     * @param format
+     *   - `undefined` — raw SPARQL JSON result
+     *   - `'graph'`   — structured `{ entities, relations }` with predicates and weights
+     *   - `'md'`      — compact aligned text table
+     *
+     * @param entityIRI  Optional category IRI (prefixed, e.g. `qcy:Building`, or
+     *   full, e.g. `https://…Building`). When supplied, only edges where either
+     *   the source or target category equals this IRI are returned — i.e. the
+     *   one-hop neighbourhood of that category.
+     *
+     * @example
+     * ```ts
+     * // Structured graph (nodes + edges)
+     * const g = await entities.buildSummaryGraph('graph');
+     * // g.entities  → [{ iri: 'https://…FloorPlanDrawing' }, …]
+     * // g.relations → [{ sourceID, predicate, targetID, weight }, …]
+     *
+     * // Neighbourhood of a single category (prefixed IRI)
+     * const g2 = await entities.buildSummaryGraph('graph', 'qcy:Building');
+     *
+     * // Markdown table
+     * const md = await entities.buildSummaryGraph('md');
+     * // qcy:FloorPlanDrawing -> qcy:includesBuildingEntity -> qcy:BuildingZone  (5652)
+     * ```
+     */
+    buildSummaryGraph(format: 'graph', entityIRI?: string): Promise<SummaryGraphData>;
+    buildSummaryGraph(format: 'md', entityIRI?: string): Promise<string>;
+    buildSummaryGraph(format?: undefined, entityIRI?: string): Promise<unknown>;
+    /**
+     * Fetches the category-summary rows. On QLever the pre-computed
+     * `entity-summary` materialized view is tried first; if it yields no rows we
+     * warn and fall back to the live aggregation query. Fuseki always uses the
+     * live query.
+     */
+    private _fetchSummaryData;
+    /**
+     * Fetches per-category entity counts (project-wide — there's no neighbourhood
+     * scoping for this one). Cached for the lifetime of this instance since it's
+     * a cheap, single-aggregate view that doesn't vary per `buildSummaryGraph` call.
+     */
+    private _fetchCategoryCounts;
+    /**
+     * Tries the named materialized view first (QLever only); falls back to the
+     * live query if the view yields no rows, or on Fuseki (which has no views).
+     */
+    private _fetchViewBacked;
+    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;
+}

package/lib/extraction.d.ts

@@ -0,0 +1,48 @@
+import { CueAuth } from './auth';
+export declare const ENDPOINT_EXTRACTION = "/semantic-extraction/extract";
+export interface ExtractionRequest {
+    /** PNG (or other image) blob of the document page to extract from. */
+    image: Blob;
+    /** SemanticTemplate JSON object. */
+    template: object;
+    /** Project / space ID used by the extraction service. */
+    projectId: string;
+    /** IRI of the pre-selected content category; omit to let the model classify. */
+    category?: string | null;
+    /** Plain text of the page, used as additional context. */
+    text?: string | null;
+    /** Desired RDF serialisation — defaults to `'json-ld'`. */
+    rdfFormat?: 'json-ld' | 'turtle' | 'ntriples' | 'xml';
+}
+export interface ExtractionResponse {
+    /** Parsed JSON-LD document ready for `cue-rdf-graph`. */
+    jsonld: object;
+}
+/**
+ * Client for the Cue semantic-extraction endpoint.
+ *
+ * Exposed as `cue.api.extraction`.
+ *
+ * @example
+ * ```ts
+ * const result = await cue.api.extraction.extract({
+ *   image: pngBlob,
+ *   template: myTemplate,
+ *   projectId: 'my-project',
+ * });
+ * // result.jsonld is a JSON-LD document for cue-rdf-graph
+ * ```
+ */
+export declare class CueExtraction {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    /**
+     * Run semantic extraction on a document page image.
+     *
+     * Sends a multipart/form-data POST to `/semantic-extraction/extract`.
+     * Always requests JSON-LD so the result can be displayed directly in
+     * `cue-rdf-graph` without any further parsing.
+     */
+    extract(request: ExtractionRequest): Promise<ExtractionResponse>;
+}

package/lib/gis.d.ts

@@ -0,0 +1,89 @@
+import { BBox, FeatureCategory, FeatureCategoryDescriptor, GisFeature } from 'js/cue-gis';
+export type GisBBox = BBox;
+export type { FeatureCategory };
+export type GisCategoryDescriptor = FeatureCategoryDescriptor;
+export type { GisFeature };
+export type GisFeaturesMap = Map<FeatureCategory, GisFeature[]>;
+type Listener<T> = (value: T) => void;
+/**
+ * Reactive GIS service, exposed lazily as `cue.gis`.
+ *
+ * Push-based: consumers set the active bbox and selected categories; results are
+ * delivered via subscription callbacks.  All debouncing and request cancellation
+ * are handled internally.
+ *
+ * @example
+ * ```ts
+ * cue.gis.setProjectId('my-project-id');
+ * cue.gis.onAvailableCategories(cats => console.log(cats));
+ *
+ * // On every map pan/zoom:
+ * cue.gis.setBbox([west, south, east, north]);
+ *
+ * // When the user toggles a category:
+ * cue.gis.setSelectedCategories(new Set(['cadastre', 'building']));
+ *
+ * // Cleanup:
+ * cue.gis.destroy();
+ * ```
+ */
+export declare class CueGis {
+    private readonly _getAuthHeaders;
+    private readonly _gatewayUrl;
+    private _bbox;
+    private _projectId;
+    private _selectedCategories;
+    private _queryToken;
+    private _categoryTokens;
+    private _debounceTimer;
+    private _availableCategories;
+    private _features;
+    private readonly _catListeners;
+    private readonly _featListeners;
+    private readonly _loadListeners;
+    private _gatewayCache;
+    private _gatewayProjectId;
+    /** @internal — construct via `cue.gis`, not directly. */
+    constructor(_getAuthHeaders: () => Promise<Record<string, string>>, _gatewayUrl: string);
+    /**
+     * Update the current map viewport.
+     * Triggers a debounced query for available categories and reloads selected ones.
+     */
+    setBbox(bbox: BBox): void;
+    /**
+     * Set or clear the active project.
+     * Rebuilds the authenticated adapter so subsequent requests carry the new project header.
+     */
+    setProjectId(projectId: string | null): void;
+    /**
+     * Replace the full set of selected categories.
+     * Newly added categories begin loading immediately; removed categories are cleared.
+     */
+    setSelectedCategories(categories: Set<FeatureCategory>): void;
+    /**
+     * Subscribe to available-category updates.
+     * Replays the current value immediately, then fires on every bbox change.
+     * @returns An unsubscribe function.
+     */
+    onAvailableCategories(cb: Listener<GisCategoryDescriptor[]>): () => void;
+    /**
+     * Subscribe to the feature map (category → GisFeature[]).
+     * Replays the current value immediately, then fires whenever features change.
+     * @returns An unsubscribe function.
+     */
+    onFeaturesChange(cb: Listener<GisFeaturesMap>): () => void;
+    /**
+     * Subscribe to the global loading state.
+     * Fires `true` while the category list is being queried, `false` when done.
+     * @returns An unsubscribe function.
+     */
+    onLoadingChange(cb: Listener<boolean>): () => void;
+    /** Cancel all pending requests and clear all listeners. */
+    destroy(): void;
+    private _scheduleDebouncedQuery;
+    private _getGateway;
+    private _queryLayers;
+    private _loadCategory;
+    private _emitFeatures;
+    private _emitLoading;
+}

package/lib/index-api.d.ts

@@ -0,0 +1,39 @@
+import { CueAuth } from './auth';
+import { AvailableFiltersResponse, IndexAppliedFilters, IndexSearchRequest, IndexSearchResponse } from './models';
+export declare class CueIndexApi {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    search(input: string, projectId: string, opts?: Omit<IndexSearchRequest, 'input'>): Promise<IndexSearchResponse>;
+    lookup(input: string, projectId: string, opts?: {
+        aggregate?: boolean;
+    }): Promise<IndexSearchResponse>;
+    /**
+     * Discover which filter options are available in the document set that survives
+     * the provided `applied` filters. Call with no `applied` argument (or an empty
+     * object) to retrieve all options for the project.
+     *
+     * Drives adaptive filter UIs: after the user sets filter N, pass the active
+     * filters to this method and use the response to constrain the options shown
+     * for filter N+1.
+     *
+     * Requires the `/index/available-filters` gateway endpoint.
+     */
+    availableFilters(projectId: string, applied?: IndexAppliedFilters): Promise<AvailableFiltersResponse>;
+    /**
+     * Forces a full binary rebuild of the project's QLever index. Super-admin only
+     * (the gateway/accessor rejects non-superadmin callers). Streams NDJSON
+     * progress lines from the backend; `onProgress` (if given) is called with
+     * each intermediate message. Resolves with the final message once the
+     * rebuild finishes, or rejects if it fails.
+     */
+    rebuild(projectId: string, onProgress?: (message: string) => void): Promise<string>;
+    /**
+     * Forces a full re-scan of every project's QLever stats (materialized views,
+     * index size, cue-meta) and persists the result, bypassing the normal cache
+     * TTL. Super-admin only. This refreshes the shared stats aggregate for ALL
+     * projects, not just the current one — there's no per-project variant since
+     * the aggregate is written as a single file. Resolves with a summary message.
+     */
+    refreshStats(): Promise<string>;
+}

package/lib/mcp.d.ts

@@ -0,0 +1,61 @@
+import { CueAuth } from './auth';
+import { McpContext } from './models';
+/**
+ * Minimal view of an MCP `tools/call` result — only the fields the response
+ * handling reads. Declared locally instead of imported from the SDK on
+ * purpose: the SDK ships its types only behind an `exports` map, which this
+ * project's `moduleResolution: "node"` cannot follow, so the imported result
+ * type collapses to its `unknown` index signature.
+ */
+type McpTextBlock = {
+    type: 'text';
+    text: string;
+};
+interface McpCallResult {
+    content: Array<McpTextBlock | {
+        type: string;
+    }>;
+    structuredContent?: Record<string, unknown> | null;
+    isError?: boolean;
+}
+export interface McpCallOptions {
+    /** Abort signal forwarded to the underlying MCP request. */
+    signal?: AbortSignal;
+}
+/** Flatten any `HeadersInit` (Headers instance, tuples, or record) into a plain record. */
+export declare function toHeaderRecord(init: HeadersInit | undefined): Record<string, string>;
+/** Join every text content block into one string, mirroring the Python probe's `extract_payload`. */
+export declare function extractText(content: McpCallResult['content']): string;
+/**
+ * A data tool that catches an exception returns `{ error }` (see the backend's
+ * `tool_error`) — a soft failure with no `id`, distinct from a real context.
+ */
+export declare function isToolError(payload: unknown): payload is {
+    error: string;
+};
+/**
+ * Resolve a tool result to its payload the same way the Python probe does:
+ * prefer the structured content the tool returned, otherwise fall back to the
+ * text content (parsed as JSON when possible, raw string otherwise).
+ */
+export declare function extractPayload<T>(result: McpCallResult): T;
+/**
+ * Generic caller for the Cue Index MCP *data tools*.
+ *
+ * Speaks the FastMCP streamable-HTTP protocol against the gateway `/mcp` route
+ * (the same protocol the `probe_mcp.py` reference uses via `fastmcp.Client`):
+ * it performs the `initialize` handshake, invokes `tools/call`, and returns the
+ * tool's Context result ({@link McpContext} — `{ id, text }`) proxied through
+ * unchanged, with no endpoint-specific logic or re-templating.
+ *
+ * Type the call per endpoint via the generic parameters, e.g.
+ * `callTool<{ input: string; space_id: string }>('search', { input, space_id })`.
+ * New endpoints need no change to this class.
+ */
+export declare class CueMcp {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    callTool<TParams extends Record<string, unknown> = Record<string, unknown>, TResult = McpContext>(tool: string, params: TParams, options?: McpCallOptions): Promise<TResult>;
+}
+export {};