@qaecy/cue-sdk 0.0.30 → 0.0.31

package/index.d.ts

@@ -19,9 +19,11 @@ export { CueSignal, cueComputed, staleWhileRevalidate } from './lib/signal';
 export type { ReadonlySignal } from './lib/signal';
 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 { 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, LangMap, 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';
 export { CueExtraction } from './lib/extraction';
 export type { ExtractionRequest, ExtractionResponse } from './lib/extraction';
+export { CueContexts } from './lib/contexts';
+export type { ContextDoc, ContextItem } from './lib/models';

package/index.js

@@ -1,24 +1,25 @@
-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";
+import { C as s, a as u, b as C, c as t, d as i, e as o, f as c, g as r, h as n, i as l, j as P, k as j, l as m, m as S, n as g, o as h, p, q as E, R, r as f, s as d, t as x } from "./cue-VOCN5IEZ.js";
 export {
   s as Cue,
   u as CueApi,
   C as CueAuth,
   t as CueCache,
-  i as CueExtraction,
+  i as CueContexts,
+  o as CueExtraction,
   c as CueGis,
-  o as CuePrivileges,
-  r as CueProfile,
+  r as CuePrivileges,
+  n as CueProfile,
   l as CueProjectDocuments,
-  n as CueProjectEntities,
-  P as CueProjectSchema,
-  j as CueProjectView,
-  m as CueProjects,
-  S as CueSignal,
-  g as CueStorage,
-  h as CueSyncApi,
-  p as CueTables,
-  E as REQUIRED_ROLES,
-  R as configureScanWasm,
-  f as cueComputed,
-  d as staleWhileRevalidate
+  P as CueProjectEntities,
+  j as CueProjectSchema,
+  m as CueProjectView,
+  S as CueProjects,
+  g as CueSignal,
+  h as CueStorage,
+  p as CueSyncApi,
+  E as CueTables,
+  R as REQUIRED_ROLES,
+  f as configureScanWasm,
+  d as cueComputed,
+  x as staleWhileRevalidate
 };

package/lib/api.d.ts

@@ -4,6 +4,7 @@ import { CueProjects } from './project';
 import { CueSyncApi } from './sync';
 import { CueTables } from './tables';
 import { CueExtraction } from './extraction';
+import { CueContexts } from './contexts';
 export declare class CueApi {
     private readonly _auth;
     private readonly _gatewayUrl;
@@ -12,6 +13,8 @@ export declare class CueApi {
     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;
     /** 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. */

package/lib/contexts.d.ts

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

@@ -170,6 +170,13 @@ export declare class CueProjectEntities {
     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;

package/lib/models.d.ts

@@ -60,6 +60,26 @@ export interface SearchResponse {
     sources: SearchSource[];
     rankedSources: SearchSource[];
 }
+export interface ContextItem {
+    id: string;
+    type: string;
+    relevance: number;
+    info: Record<string, unknown>;
+    sub_items: ContextItem[];
+}
+export interface ContextDoc {
+    id: string;
+    total: number;
+    operation: {
+        type: string;
+    };
+    input: string;
+    items: ContextItem[];
+    within: string[];
+    meta: {
+        time_created: string;
+    };
+}
 export interface ProjectSettings {
     views?: Array<{
         id: string;
@@ -285,12 +305,35 @@ export interface QueryCache {
     get(key: string): Promise<unknown | undefined>;
     set(key: string, data: unknown): Promise<void>;
 }
+/**
+ * A multilingual string keyed by BCP-47 language tag. The special `default`
+ * key always resolves to the English value (or, when no English value exists,
+ * to the untagged/first available value).
+ */
+export type LangMap = {
+    [lang: string]: string;
+};
 /** A taxonomy node (content category or entity category) from the triplestore. */
 export interface CategoryDef {
     iri: string;
+    /**
+     * Label resolved for the currently active language (falls back to `default`
+     * / English). This is a computed convenience view of {@link CategoryDef.labels}.
+     */
     label: string;
+    /**
+     * Definition resolved for the currently active language (falls back to
+     * `default` / English). Computed view of {@link CategoryDef.definitions}.
+     */
+    definition?: string;
+    /** Full set of labels keyed by language tag (plus a `default` key). */
+    labels: LangMap;
+    /** Full set of definitions keyed by language tag (plus a `default` key). */
+    definitions?: LangMap;
     /** IRI of the parent category (skos:broader), if any. */
     parent?: string;
+    /** Whether this category is marked as deprecated in the triplestore. */
+    deprecated?: boolean;
 }
 /**
  * A relationship type discovered in the triplestore via `qcy:relatedEntity` property scan.

package/lib/schema.d.ts

@@ -5,8 +5,10 @@ import { CategoryDef, QueryCache, RelationshipDef } from './models';
  * Holds the schema for a single project: available content categories,
  * entity categories, and entity relationship types.
  *
- * Data is fetched lazily on construction and cached per language so that
- * switching back to a previously loaded language is instant.
+ * The full schema is fetched **once** (a single SPARQL query covering all three
+ * collections) and cached. Labels and definitions are retained for every
+ * available language as {@link LangMap}s; switching language is therefore a
+ * cheap, client-side re-projection with no extra network round-trip.
  *
  * ### Reactive paradigm
  * All three collections are exposed as `ReadonlySignal<T>`. Framework adapters
@@ -21,8 +23,8 @@ import { CategoryDef, QueryCache, RelationshipDef } from './models';
  * ```ts
  * const schema = new CueProjectSchema(cue.api, projectId, 'en');
  * schema.availableContentCategories.get(); // CategoryDef[]
- * schema.setLanguage('da');                // loads from cache or re-fetches
- * await schema.refresh();                  // force re-fetch current language
+ * schema.setLanguage('da');                // re-projects cached data instantly
+ * await schema.refresh();                  // force re-fetch
  * ```
  */
 export declare class CueProjectSchema {
@@ -30,8 +32,10 @@ export declare class CueProjectSchema {
     private readonly _projectId;
     private readonly _queryCache?;
     private readonly _graphType?;
-    private readonly _cache;
+    private _snapshot?;
+    private _inflight?;
     private _currentLang;
+    private readonly _verbose;
     private readonly _contentCategories;
     private readonly _entityCategories;
     private readonly _relationships;
@@ -46,26 +50,36 @@ export declare class CueProjectSchema {
      * 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);
+    constructor(_api: CueApi, _projectId: string, language: string, _queryCache?: QueryCache | undefined, _graphType?: string | undefined, verbose?: boolean);
     /** Returns the currently active language. */
     get language(): string;
     /**
-     * Switch the active language. If the data for this language has already been
-     * fetched it is applied immediately from cache; otherwise a new SPARQL fetch
-     * is triggered.
+     * Switch the active language. Re-projects the already-fetched schema for the
+     * new language without re-querying; only triggers a fetch if nothing has been
+     * loaded yet.
      */
     setLanguage(lang: string): void;
     /**
-     * Force a re-fetch for the current language, bypassing the cache.
+     * Force a re-fetch of the schema, bypassing the cache.
      * Useful when the triplestore data has changed.
      */
     refresh(): Promise<void>;
     private _load;
+    /**
+     * Fetches the schema once. On QLever the pre-computed `schemas` materialized
+     * view is tried first; if it yields no rows we warn and fall back to the live
+     * schema query.
+     */
+    private _fetchSnapshot;
     private _apply;
-    private _fetchCategories;
-    private _buildCategoriesQuery;
-    private _runCategoriesQuery;
-    private _fetchRelationships;
-    private _buildRelationshipsQuery;
-    private _runRelationshipsQuery;
+    /** Projects a language-independent {@link SchemaNode} into a {@link CategoryDef}. */
+    private _toDef;
+    /**
+     * Single query covering content categories, entity categories and entity
+     * relationship types. Labels/definitions are returned untouched (with their
+     * language tags) so they can be grouped into {@link LangMap}s client-side.
+     */
+    private _buildSchemaQuery;
+    /** Runs a schema query and groups the flat rows into a {@link SchemaSnapshot}. */
+    private _runSchemaQuery;
 }

package/lib/storage.d.ts

@@ -1,30 +1,41 @@
-import { CueBlobStorage } from 'js-databases';
+import { CueAuth } from './auth';
 export type StorageBucket = 'raw' | 'processed';
 /**
- * Provides document download URL resolution against the Cue Firebase Storage buckets.
+ * Provides document download URL resolution proxied through the Cue gateway.
+ *
+ * The returned URLs require an `Authorization: Bearer {token}` header — use
+ * `cue.api.getAuthHeaders()` or `cue.auth.authenticatedFetch()` to fetch them.
+ * For use in `<img src>` / `<video src>`, convert to a blob URL first:
+ * ```ts
+ * const response = await cue.auth.authenticatedFetch(url);
+ * const objectUrl = URL.createObjectURL(await response.blob());
+ * ```
  *
  * @example
  * ```ts
- * const url = await cue.storage.getDownloadUrl('my-project', 'abc123', '.pdf');
+ * const url = cue.storage.getDownloadUrl('my-project', 'abc123', '.pdf');
+ * const res  = await cue.auth.authenticatedFetch(url);
  * ```
  */
 export declare class CueStorage {
-    private readonly _blob;
-    constructor(_blob: CueBlobStorage);
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
     /**
-     * Returns a Firebase authenticated download URL for a document stored in Cue.
+     * Returns a gateway download URL for a document stored in Cue.
      *
      * The storage path is `{projectId}/{uuid}{suffix}`, e.g. `my-project/abc-123.pdf`.
+     * The returned URL must be fetched with an Authorization header.
      *
      * @param projectId - The Cue project (space) ID.
      * @param uuid - The document UUID.
      * @param suffix - File suffix including the leading dot, e.g. `'.pdf'`, `'.ifc'`.
      * @param bucket - `'raw'` (default, original uploads) or `'processed'` (derived artefacts).
      */
-    getDownloadUrl(projectId: string, uuid: string, suffix: string, bucket?: StorageBucket): Promise<string>;
+    getDownloadUrl(projectId: string, uuid: string, suffix: string, bucket?: StorageBucket): string;
     /**
-     * Returns a Firebase authenticated download URL for an alternative representation
-     * using its full `qcy:remoteRelativePath` stored in the processed bucket.
+     * Returns a gateway download URL for an alternative representation using its
+     * full `qcy:remoteRelativePath` stored in the processed bucket.
      *
      * Use this instead of `getDownloadUrl` when the document info was obtained via
      * `fetchAlternativeRepresentations` and carries a `remoteRelativePath`.
@@ -32,5 +43,10 @@ export declare class CueStorage {
      * @param remoteRelativePath - The full path in the processed bucket,
      *   e.g. `{projectId}/fragments/{uuid}.fragments`.
      */
-    getAltRepDownloadUrl(remoteRelativePath: string): Promise<string>;
+    getAltRepDownloadUrl(remoteRelativePath: string): string;
+    /**
+     * Fetch a file through the gateway and return it as a Blob.
+     * Convenience wrapper around `getDownloadUrl` + `authenticatedFetch`.
+     */
+    downloadBlob(projectId: string, uuid: string, suffix: string, bucket?: StorageBucket): Promise<Blob>;
 }

package/node.js

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

package/package.json

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

package/variables.d.ts

@@ -14,6 +14,7 @@ export declare const GCP_REGION = "europe-west6";
 export declare const COLLECTION_API_KEYS = "apiKeys";
 export declare const COLLECTION_ORGANIZATIONS = "organizations";
 export declare const COLLECTION_PROJECTS = "projects";
+export declare const BUCKET_SESSIONS = "sessions_eu_west6";
 export declare const BUCKET_CHAT_SESSIONS = "spaces_chats_eu_west6";
 export declare const BUCKET_RAW = "spaces_raw_eu_west6";
 export declare const BUCKET_PROCESSED = "spaces_processed_eu_west6";
@@ -36,6 +37,9 @@ 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 ENDPOINT_STORAGE_SESSIONS = "/storage/sessions";
+export declare const ENDPOINT_STORAGE_RAW = "/storage/raw";
+export declare const ENDPOINT_STORAGE_PROCESSED = "/storage/processed";
 export declare const MICROSOFT_PROVIDER_ID = "microsoft.com";
 export declare const SUPERADMIN_ROLE = "superadmin";
 /**