@qaecy/cue-sdk 0.0.32 → 0.0.33

package/lib/entities.d.ts

@@ -1,187 +0,0 @@
-import { CueApi } from './api';
-import { ReadonlySignal } from './signal';
-import { EntityDetailedData, EntityRelationships, ProjectEntitiesData, SummaryGraphData, 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?;
-    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;
-    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, _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;
-    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

@@ -1,48 +0,0 @@
-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

@@ -1,89 +0,0 @@
-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

@@ -1,11 +0,0 @@
-import { CueAuth } from './auth';
-import { 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>;
-}