@qaecy/cue-sdk 0.0.29 → 0.0.30

package/index.js

@@ -1,4 +1,4 @@
-import { C as s, a as u, b as C, c as t, d as i, e as c, f as o, g as r, h as l, i as n, j as P, k as j, l as m, m as S, n as g, o as h, p, R as E, q as R, r as f, s as d } from "./cue-CnZyGMRG.js";
+import { C as s, a as u, b as C, c as t, d as i, e as c, f as o, g as r, h as l, i as n, j as P, k as j, l as m, m as S, n as g, o as h, p, R as E, q as R, r as f, s as d } from "./cue-DWCLcFvj.js";
 export {
   s as Cue,
   u as CueApi,

package/lib/cue.d.ts

@@ -36,6 +36,7 @@ export declare class Cue {
     protected _storageProcessed: FirebaseStorage;
     private _gis;
     private readonly _projectDocuments;
+    private readonly _verbose;
     /**
      * Reactive GIS service. Lazily constructed on first access.
      *
@@ -108,6 +109,7 @@ export declare class Cue {
         rdfBase?: string;
         graphType?: string;
         queryCache?: QueryCache;
+        verbose?: boolean;
     }): CueProjectEntities;
     /**
      * Creates a `CueProjectDocuments` instance for the given project, with the
@@ -128,5 +130,6 @@ export declare class Cue {
         rdfBase?: string;
         graphType?: string;
         queryCache?: QueryCache;
+        verbose?: boolean;
     }): CueProjectDocuments;
 }

package/lib/documents.d.ts

@@ -38,11 +38,14 @@ export declare class CueProjectDocuments {
     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>>;
@@ -50,7 +53,7 @@ export declare class CueProjectDocuments {
     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);
+    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.
@@ -134,7 +137,10 @@ export declare class CueProjectDocuments {
      * Suffixes are matched case-insensitively and the leading dot is optional
      * (both `'ifc'` and `'.ifc'` are accepted).
      */
-    documentsBySuffix(suffixes: string[], includeMetadata?: false): Promise<string[]>;
+    documentsBySuffix(suffixes: string[], includeMetadata?: false): Promise<Array<{
+        iri: string;
+        uuid: string;
+    }>>;
     documentsBySuffix(suffixes: string[], includeMetadata: true): Promise<Array<{
         iri: string;
         uuid: string;
@@ -149,7 +155,10 @@ export declare class CueProjectDocuments {
      * Resolves matching suffixes from `fileExtensionsInfo` and delegates to
      * `documentsBySuffix`. Accepts the same `includeMetadata` flag.
      */
-    documentsByFileType(fileTypes: FileType[], includeMetadata?: false): Promise<string[]>;
+    documentsByFileType(fileTypes: FileType[], includeMetadata?: false): Promise<Array<{
+        iri: string;
+        uuid: string;
+    }>>;
     documentsByFileType(fileTypes: FileType[], includeMetadata: true): Promise<Array<{
         iri: string;
         uuid: string;
@@ -157,6 +166,25 @@ export declare class CueProjectDocuments {
         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'`).
@@ -164,7 +192,10 @@ export declare class CueProjectDocuments {
      * Resolves matching suffixes from `fileExtensionsInfo` and delegates to
      * `documentsBySuffix`. Accepts the same `includeMetadata` flag.
      */
-    documentsByMime(mimeTypes: string[], includeMetadata?: false): Promise<string[]>;
+    documentsByMime(mimeTypes: string[], includeMetadata?: false): Promise<Array<{
+        iri: string;
+        uuid: string;
+    }>>;
     documentsByMime(mimeTypes: string[], includeMetadata: true): Promise<Array<{
         iri: string;
         uuid: string;
@@ -172,6 +203,9 @@ export declare class CueProjectDocuments {
         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;

package/lib/entities.d.ts

@@ -38,6 +38,7 @@ export declare class CueProjectEntities {
     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;
@@ -46,6 +47,8 @@ export declare class CueProjectEntities {
     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. */
@@ -54,12 +57,15 @@ export declare class CueProjectEntities {
     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);
+    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.
@@ -114,11 +120,15 @@ export declare class CueProjectEntities {
      * - `"qcy:Building"`
      * - `"https://cue.qaecy.com/ontology#Building"`
      *
-     * By default returns only UUIDs (`string[]`) — pass `includeMetadata: true` to
-     * also get `iri`, `value`, and `categories` (all categories, not just the filtered ones).
+     * 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<string[]>;
+    entitiesByCategory(categoryIris: string[], includeMetadata?: false): Promise<Array<{
+        iri: string;
+        uuid: string;
+    }>>;
     entitiesByCategory(categoryIris: string[], includeMetadata: true): Promise<Array<{
         iri: string;
         uuid: string;
@@ -137,6 +147,11 @@ export declare class CueProjectEntities {
      *   - `'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)
@@ -144,14 +159,17 @@ export declare class CueProjectEntities {
      * // 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'): Promise<SummaryGraphData>;
-    buildSummaryGraph(format: 'md'): Promise<string>;
-    buildSummaryGraph(format?: undefined): Promise<unknown>;
+    buildSummaryGraph(format: 'graph', entityIRI?: string): Promise<SummaryGraphData>;
+    buildSummaryGraph(format: 'md', entityIRI?: string): Promise<string>;
+    buildSummaryGraph(format?: undefined, entityIRI?: string): Promise<unknown>;
     private _computeEntityInfoMap;
     private _fetchOutgoingRelationships;
     private _fetchIncomingRelationships;

package/lib/models.d.ts

@@ -26,6 +26,8 @@ export interface CueSdkConfig {
     environment?: CueEnvironment;
     /** Override individual endpoint URLs. Takes precedence over environment. */
     endpoints?: Partial<CueEndpoints>;
+    /** Enable verbose debug logging for all entity/document store operations. */
+    verbose?: boolean;
 }
 export type SsoProvider = 'google' | 'microsoft';
 export interface PasswordCredentials {

package/lib/project-view.d.ts

@@ -11,6 +11,8 @@ export interface CueProjectViewOptions {
     rdfBase?: string;
     /** Graph engine type from projectSettings.graph.type (e.g. 'qlever' or 'fuseki'). */
     graphType?: string;
+    /** Enable verbose debug logging for entity and document fetch stats. */
+    verbose?: boolean;
 }
 /**
  * Framework-agnostic facade over `CueProjectSchema`, `CueProjectEntities`, and
@@ -59,7 +61,7 @@ export declare class CueProjectView {
     /** 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);
+    constructor(_api: CueApi, _projectId: string, { language, queryCache, rdfBase, graphType, verbose }: CueProjectViewOptions);
     /**
      * Lazily batch-fetch core data (label + categories) for the given entity UUIDs.
      * Already-fetched UUIDs are skipped. Populates `entityInfoMap`.

package/node.js

@@ -1,5 +1,5 @@
-import { C as h, B as l, t as _, u as E, v as S, o as m, w as P, a as d } from "./cue-CnZyGMRG.js";
-import { b as j, c as x, d as y, e as I, f as K, g as L, h as v, i as H, j as N, k as O, l as D, m as G, n as W, p as k, R as q, q as Q, r as V, s as z } from "./cue-CnZyGMRG.js";
+import { C as h, B as l, t as _, u as E, v as S, o as m, w as P, a as d } from "./cue-DWCLcFvj.js";
+import { b as j, c as x, d as y, e as I, f as K, g as L, h as v, i as H, j as N, k as O, l as D, m as G, n as W, p as k, R as q, q as Q, r as V, s as z } from "./cue-DWCLcFvj.js";
 import { getStorage as t, connectStorageEmulator as w } from "firebase/storage";
 import "firebase/firestore";
 class A extends h {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qaecy/cue-sdk",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",