@qaecy/cue-sdk 0.0.29 → 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-CnZyGMRG.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/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,24 @@ 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>;
+    /**
+     * 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

@@ -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 {
@@ -58,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;
@@ -283,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/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/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-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 { 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.29",
+  "version": "0.0.31",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",