@qaecy/cue-sdk 0.0.14 → 0.0.16

package/index.d.ts

@@ -1,4 +1,6 @@
 export { Cue } from './lib/cue';
+export { CueGis } from './lib/gis';
+export type { GisBBox, GisCategoryDescriptor, GisFeature, GisFeaturesMap, FeatureCategory } from './lib/gis';
 export { CueAuth } from './lib/auth';
 export { CueApi } from './lib/api';
 export { CueSyncApi, configureScanWasm } from './lib/sync';
@@ -17,3 +19,5 @@ export { CueCache } from './lib/cache';
 export type { QueryCacheEntry } from './lib/cache';
 export type { CueSdkConfig, SsoProvider, PasswordCredentials, SearchRequest, SearchResponse, SearchSource, SearchOptions, ProjectData, ProjectSettings, CreateProjectOptions, SyncOptions, SyncResult, SyncPreview, ScanOutputRecord, UnitsConsumedDto, OrganizationData, OrgMember, ProfileSSOAccount, APIKeyInfo, APIKeyDoc, ProjectDoc, OrganizationDoc, UserDoc, RDFWritingDoc, ViewDefinition, QueryCache, CategoryDef, RelationshipDef, EntityCoreData, EntityRelationship, EntityRelationships, MapGeometry, EntityDetailedData, ProjectEntitiesData, DocumentInfo, DocumentSummary, ProjectDocumentsData, } from './lib/models';
 export type { AuthStateListener, Unsubscribe } from './lib/auth';
+export { CueTables } from './lib/tables';
+export type { ProjectTable } from './lib/tables';

package/index.js

@@ -1,20 +1,22 @@
-import { C as s, a as u, b as C, c, d as i, e as t, f as o, g as r, h as l, i as n, j as P, k as j, l as m, R as h, m as R, n as S, s as f } from "./cue-DjbCgB69.js";
+import { C as s, a as u, b as C, c as i, d as c, e as t, f as o, g as r, h as l, i as n, j as P, k as j, l as m, m as h, n as p, R, o as S, p as f, s as g } from "./cue-DiFnK22Q.js";
 export {
   s as Cue,
   u as CueApi,
   C as CueAuth,
-  c as CueCache,
-  i as CuePrivileges,
-  t as CueProfile,
-  o as CueProjectDocuments,
-  r as CueProjectEntities,
-  l as CueProjectSchema,
-  n as CueProjectView,
-  P as CueProjects,
-  j as CueSignal,
-  m as CueSyncApi,
-  h as REQUIRED_ROLES,
-  R as configureScanWasm,
-  S as cueComputed,
-  f as staleWhileRevalidate
+  i as CueCache,
+  c as CueGis,
+  t as CuePrivileges,
+  o as CueProfile,
+  r as CueProjectDocuments,
+  l as CueProjectEntities,
+  n as CueProjectSchema,
+  P as CueProjectView,
+  j as CueProjects,
+  m as CueSignal,
+  h as CueSyncApi,
+  p as CueTables,
+  R as REQUIRED_ROLES,
+  S as configureScanWasm,
+  f as cueComputed,
+  g as staleWhileRevalidate
 };

package/lib/api.d.ts

@@ -1,12 +1,18 @@
 import { CueAuth } from './auth';
-import { SearchRequest, SearchResponse, UnitsConsumedDto } from './models';
+import { SearchRequest, SearchResponse, ShaclValidationReport, UnitsConsumedDto } from './models';
 import { CueProjects } from './project';
 import { CueSyncApi } from './sync';
+import { CueTables } from './tables';
 export declare class CueApi {
     private readonly _auth;
     private readonly _gatewayUrl;
     readonly projects: CueProjects;
     readonly sync?: CueSyncApi | undefined;
+    readonly tables: CueTables;
+    /** 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.
@@ -23,5 +29,20 @@ export declare class CueApi {
      * 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/cue.d.ts

@@ -1,6 +1,7 @@
 import { FirebaseApp } from 'firebase/app';
 import { CueAuth } from './auth';
 import { CueApi } from './api';
+import { CueGis } from './gis';
 import { CueProjects } from './project';
 import { CueProfile } from './profile';
 import { CuePrivileges } from './privileges';
@@ -26,6 +27,19 @@ export declare class Cue {
     protected readonly _app: FirebaseApp;
     protected readonly _endpoints: CueEndpoints;
     protected readonly _isEmulator: boolean;
+    private _gis;
+    /**
+     * 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.

package/lib/documents.d.ts

@@ -39,14 +39,15 @@ export declare class CueProjectDocuments {
     private readonly _graphType?;
     /** Full RDF base URL for this project, e.g. `https://cue.qaecy.com/r/{pid}/` */
     readonly baseURL: string;
-    private _language;
+    /** Tracks the language for which `_documentInfoMap` is currently populated. */
+    private _currentLang;
     private readonly _documentInfoMap;
     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, 
+    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);
     /**
@@ -72,6 +73,11 @@ export declare class CueProjectDocuments {
      * once the SPARQL response arrives.
      */
     requestDocumentData(uuids: string[]): void;
+    /**
+     * 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>;
     private _fetchDocumentsBySuffix;
     private _buildDocumentsBySuffixQuery;
     private _runDocumentsBySuffixQuery;

package/lib/entities.d.ts

@@ -1,6 +1,6 @@
 import { CueApi } from './api';
 import { ReadonlySignal } from './signal';
-import { EntityDetailedData, EntityRelationships, ProjectEntitiesData, QueryCache } from './models';
+import { EntityDetailedData, EntityRelationships, ProjectEntitiesData, SummaryGraphData, QueryCache } from './models';
 /**
  * Manages entity data for a single project.
  *
@@ -97,6 +97,42 @@ export declare class CueProjectEntities {
      * 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 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
+     *
+     * @example
+     * ```ts
+     * // Structured graph (nodes + edges)
+     * const g = await entities.buildSummaryGraph('graph');
+     * // g.entities  → [{ iri: 'https://…FloorPlanDrawing' }, …]
+     * // g.relations → [{ sourceID, predicate, targetID, weight }, …]
+     *
+     * // 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>;
     private _computeEntityInfoMap;
     private _fetchOutgoingRelationships;
     private _fetchIncomingRelationships;

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/models.d.ts

@@ -152,6 +152,34 @@ export interface UnitsConsumedDto {
     unitsAvailable: number;
     unitsConsumed: number;
 }
+export interface ShaclViolation {
+    '@type': string;
+    'sh:focusNode': {
+        '@id': string;
+    } | {
+        '@value': string;
+    };
+    'sh:resultPath'?: {
+        '@id': string;
+    };
+    'sh:resultSeverity': {
+        '@id': string;
+    };
+    'sh:sourceConstraintComponent': {
+        '@id': string;
+    };
+    'sh:sourceShape'?: {
+        '@id': string;
+    };
+    'sh:resultMessage': string;
+    'sh:value'?: string;
+}
+export interface ShaclValidationReport {
+    '@context': Record<string, string>;
+    '@type': string;
+    'sh:conforms': boolean;
+    'sh:result'?: ShaclViolation[];
+}
 export interface SyncPreview {
     /** Per-extension cost breakdown for files not yet synced */
     costRecords: ScanOutputRecord[];
@@ -320,6 +348,22 @@ export interface ProjectEntitiesData {
         targetID: string;
     }>;
 }
+/**
+ * Structured summary graph returned by `buildSummaryGraph('graph')`.
+ * Nodes are deduplicated category IRIs; edges carry the predicate and
+ * occurrence count from the summary query.
+ */
+export interface SummaryGraphData {
+    entities: Array<{
+        iri: string;
+    }>;
+    relations: Array<{
+        sourceID: string;
+        predicate: string;
+        targetID: string;
+        weight: number;
+    }>;
+}
 /** Core metadata for a single document (FileContent node). */
 export interface DocumentInfo {
     id: string;

package/lib/project-view.d.ts

@@ -42,6 +42,11 @@ export declare class CueProjectView {
     readonly availableEntityCategories: ReadonlySignal<CategoryDef[]>;
     /** Available entity relationship types. Auto-fetched on init. */
     readonly availableEntityRelationships: ReadonlySignal<RelationshipDef[]>;
+    /**
+     * Resolves when the initial schema load has completed. Await before reading
+     * schema signal values imperatively.
+     */
+    readonly schemaReady: Promise<void>;
     /** 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. */

package/lib/schema.d.ts

@@ -31,7 +31,7 @@ export declare class CueProjectSchema {
     private readonly _queryCache?;
     private readonly _graphType?;
     private readonly _cache;
-    private readonly _language;
+    private _currentLang;
     private readonly _contentCategories;
     private readonly _entityCategories;
     private readonly _relationships;
@@ -41,6 +41,11 @@ export declare class CueProjectSchema {
     readonly availableEntityCategories: ReadonlySignal<CategoryDef[]>;
     /** Currently active entity relationship types for the selected language. */
     readonly availableEntityRelationships: ReadonlySignal<RelationshipDef[]>;
+    /**
+     * Resolves when the initial schema load for the constructor language has
+     * completed (or failed). Await this before reading signal values imperatively.
+     */
+    readonly ready: Promise<void>;
     constructor(_api: CueApi, _projectId: string, language: string, _queryCache?: QueryCache | undefined, _graphType?: string | undefined);
     /** Returns the currently active language. */
     get language(): string;

package/lib/tables.d.ts

@@ -0,0 +1,14 @@
+import { CueAuth } from './auth';
+export interface ProjectTable {
+    id: string;
+    title: string;
+    columnDefs: Record<string, unknown>[];
+    rowDef: string;
+}
+export declare class CueTables {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    listTables(projectId: string): Promise<ProjectTable[]>;
+    saveTables(tables: ProjectTable[] | unknown[], projectId: string): Promise<void>;
+}

package/node.js

@@ -1,36 +1,36 @@
-import { C as _, B as E, o as l, p as S, q as m, r as P, t as d, l as U, u as B, a as R } from "./cue-DjbCgB69.js";
-import { b as y, c as I, d as L, e as O, f as x, g as D, h as H, i as N, j as W, k as v, R as k, m as q, n as G, s as Q } from "./cue-DjbCgB69.js";
+import { C as _, B as E, q as l, r as S, t as m, u as P, v as d, m as U, w as B, a as R } from "./cue-DiFnK22Q.js";
+import { b as y, c as I, d as L, e as O, f as v, g as x, h as D, i as H, j as N, k as W, l as G, n as k, R as q, o as Q, p as V, s as z } from "./cue-DiFnK22Q.js";
 import { getStorage as s, connectStorageEmulator as o } from "firebase/storage";
 import "firebase/firestore";
-class w extends _ {
+class f extends _ {
   constructor(t) {
     super(t);
   }
   _buildApi(t) {
-    const p = s(this._app, E), C = s(this._app, l), i = s(this._app, S), g = s(this._app, m), r = s(this._app, P), n = s(this._app, d);
+    const C = s(this._app, E), p = s(this._app, l), i = s(this._app, S), g = s(this._app, m), r = s(this._app, P), n = s(this._app, d);
     if (this._isEmulator) {
       const e = this._endpoints.storageEmulatorHost, a = this._endpoints.storageEmulatorPort;
       o(i, e, a), o(r, e, a), o(n, e, a);
     }
     const h = new B({
-      storageChatSessions: p,
-      storageLogs: C,
+      storageChatSessions: C,
+      storageLogs: p,
       storageRaw: i,
       storagePersistence: g,
       storageProcessed: r,
       storagePublic: n
-    }), c = new U(
+    }), u = new U(
       this.auth,
       t,
       h,
       this._endpoints.gatewayUrl
-    ), u = new R(
+    ), c = new R(
       this.auth,
       this._endpoints.gatewayUrl,
       t,
-      c
+      u
     );
-    return c._bindApi(u), u;
+    return u._bindApi(c), c;
   }
 }
 export {
@@ -38,18 +38,20 @@ export {
   R as CueApi,
   y as CueAuth,
   I as CueCache,
-  w as CueNode,
-  L as CuePrivileges,
-  O as CueProfile,
+  L as CueGis,
+  f as CueNode,
+  O as CuePrivileges,
+  v as CueProfile,
   x as CueProjectDocuments,
   D as CueProjectEntities,
   H as CueProjectSchema,
   N as CueProjectView,
   W as CueProjects,
-  v as CueSignal,
+  G as CueSignal,
   U as CueSyncApi,
-  k as REQUIRED_ROLES,
-  q as configureScanWasm,
-  G as cueComputed,
-  Q as staleWhileRevalidate
+  k as CueTables,
+  q as REQUIRED_ROLES,
+  Q as configureScanWasm,
+  V as cueComputed,
+  z as staleWhileRevalidate
 };

package/package.json

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

package/variables.d.ts

@@ -30,8 +30,10 @@ export declare const ENDPOINT_CREATE_PROJECT = "/commands/admin/project";
 export declare const ENDPOINT_SEARCH = "/assistant/search";
 export declare const ENDPOINT_FUSEKI_QUERY = "/triplestore/query";
 export declare const ENDPOINT_FUSEKI_UPDATE = "/triplestore/update";
+export declare const ENDPOINT_FUSEKI_SHACL = "/triplestore/shacl";
 export declare const ENDPOINT_QLEVER_QUERY = "/qlever-server/qlever/query";
 export declare const ENDPOINT_QLEVER_UPDATE = "/qlever-server/qlever/update";
+export declare const ENDPOINT_QLEVER_SHACL = "/qlever-server/qlever/shacl";
 export declare const ENDPOINT_FSS_BATCH = "/commands/file-system-structure/batch";
 export declare const MICROSOFT_PROVIDER_ID = "microsoft.com";
 export declare const SUPERADMIN_ROLE = "superadmin";