@qaecy/cue-sdk 0.0.16 → 0.0.18

package/index.d.ts

@@ -1,5 +1,7 @@
 export { Cue } from './lib/cue';
 export { CueGis } from './lib/gis';
+export { CueStorage } from './lib/storage';
+export type { StorageBucket } from './lib/storage';
 export type { GisBBox, GisCategoryDescriptor, GisFeature, GisFeaturesMap, FeatureCategory } from './lib/gis';
 export { CueAuth } from './lib/auth';
 export { CueApi } from './lib/api';

package/index.js

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

package/lib/cue.d.ts

@@ -1,5 +1,7 @@
 import { FirebaseApp } from 'firebase/app';
+import { FirebaseStorage } from 'firebase/storage';
 import { CueAuth } from './auth';
+import { CueStorage } from './storage';
 import { CueApi } from './api';
 import { CueGis } from './gis';
 import { CueProjects } from './project';
@@ -7,6 +9,8 @@ import { CueProfile } from './profile';
 import { CuePrivileges } from './privileges';
 import { CueCache } from './cache';
 import { CueProjectView, CueProjectViewOptions } from './project-view';
+import { CueProjectEntities } from './entities';
+import { CueProjectDocuments } from './documents';
 import { CueEndpoints, CueSdkConfig, QueryCache } from './models';
 /**
  * Main entry point for the QAECY SDK (browser-safe).
@@ -24,10 +28,14 @@ export declare class Cue {
     readonly profile: CueProfile;
     readonly privileges: CuePrivileges;
     readonly cache: CueCache;
+    readonly storage: CueStorage;
     protected readonly _app: FirebaseApp;
     protected readonly _endpoints: CueEndpoints;
     protected readonly _isEmulator: boolean;
+    protected _storageRaw: FirebaseStorage;
+    protected _storageProcessed: FirebaseStorage;
     private _gis;
+    private readonly _projectDocuments;
     /**
      * Reactive GIS service. Lazily constructed on first access.
      *
@@ -79,4 +87,46 @@ export declare class Cue {
     createProjectView(projectId: string, opts: Omit<CueProjectViewOptions, 'queryCache'> & {
         queryCache?: QueryCache;
     }): CueProjectView;
+    /**
+     * Creates a `CueProjectEntities` instance for the given project, with the
+     * SDK query cache wired automatically.
+     *
+     * Prefer this over `new CueProjectEntities(cue.api, projectId)` — it avoids
+     * the manual cache setup and keeps the instance bound to the correct API.
+     *
+     * @example
+     * ```ts
+     * const entities = cue.createProjectEntities('my-project');
+     * entities.requestEntityData(['uuid1']);
+     * const info = entities.entityInfoMap.get()['uuid1'];
+     *
+     * // Promise-based (no signal polling needed):
+     * const graph = await entities.buildSummaryGraph('graph');
+     * ```
+     */
+    createProjectEntities(projectId: string, opts?: {
+        rdfBase?: string;
+        graphType?: string;
+        queryCache?: QueryCache;
+    }): CueProjectEntities;
+    /**
+     * Creates a `CueProjectDocuments` instance for the given project, with the
+     * SDK query cache wired automatically.
+     *
+     * Prefer this over `new CueProjectDocuments(cue.api, projectId)` — it avoids
+     * the manual cache setup and keeps the instance bound to the correct API.
+     *
+     * @example
+     * ```ts
+     * const docs = cue.createProjectDocuments('my-project');
+     * await docs.fetchOverview();
+     * const data = await docs.fetchDocumentData(['uuid1', 'uuid2']);
+     * ```
+     */
+    createProjectDocuments(projectId: string, opts?: {
+        language?: string;
+        rdfBase?: string;
+        graphType?: string;
+        queryCache?: QueryCache;
+    }): CueProjectDocuments;
 }

package/lib/documents.d.ts

@@ -73,11 +73,61 @@ export declare class CueProjectDocuments {
      * 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>;
+    /** 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;

package/lib/storage.d.ts

@@ -0,0 +1,26 @@
+import { FirebaseStorage } from 'firebase/storage';
+export type StorageBucket = 'raw' | 'processed';
+/**
+ * Provides document download URL resolution against the Cue Firebase Storage buckets.
+ *
+ * @example
+ * ```ts
+ * const url = await cue.storage.getDownloadUrl('my-project', 'abc123', '.pdf');
+ * ```
+ */
+export declare class CueStorage {
+    private readonly _storageRaw;
+    private readonly _storageProcessed;
+    constructor(_storageRaw: FirebaseStorage, _storageProcessed: FirebaseStorage);
+    /**
+     * Returns a Firebase authenticated download URL for a document stored in Cue.
+     *
+     * The storage path is `{projectId}/{uuid}{suffix}`, e.g. `my-project/abc-123.pdf`.
+     *
+     * @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>;
+}

package/node.js

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

package/package.json

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