@qaecy/cue-sdk 0.0.33 → 0.0.35

package/index.d.ts

@@ -4,10 +4,16 @@ 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 { CueSignUp, CueRequestError } from './lib/signup';
+export type { OrgSignUpPayload, OrgSignUpPlan } from './lib/signup';
 export { CueApi } from './lib/api';
 export { CueIndexApi } from './lib/index-api';
+export { CueMcp } from './lib/mcp';
+export type { McpCallOptions } from './lib/mcp';
 export type { IndexSearchRequest, IndexItem, IndexSearchResponse, IndexFilterOption, IndexAppliedFilters, AvailableFiltersResponse, SearchFilter, DocumentFilterOption, AvailableDocumentFilters, } from './lib/models';
 export { CueSyncApi, configureScanWasm } from './lib/sync';
+export { CueProcessingApi } from './lib/processing';
+export type { ProcessingStatusWatcher } from './lib/processing';
 export { CueProjectSchema } from './lib/schema';
 export { CueDocumentFilter } from './lib/document-filter';
 export { CueProjectEntities } from './lib/entities';
@@ -18,15 +24,20 @@ export { CueProjects } from './lib/project';
 export { CueProfile } from './lib/profile';
 export { CuePrivileges, REQUIRED_ROLES } from './lib/privileges';
 export type { UserProjectRole, Privileges } from './lib/privileges';
-export { CueSignal, cueComputed, staleWhileRevalidate } from './lib/signal';
+export { CueSignal, cueComputed } 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, LangMap, CategoryDef, RelationshipDef, EntityCoreData, EntityRelationship, EntityRelationships, MapGeometry, EntityDetailedData, ProjectEntitiesData, DocumentInfo, DocumentSummary, ProjectDocumentsData, } from './lib/models';
+export { CueCurrency, SUPPORTED_CURRENCIES, BASE_CURRENCY } from './lib/currency';
+export type { SupportedCurrency, CurrencyRates } from './lib/currency';
+export type { CueSdkConfig, SsoProvider, PasswordCredentials, SearchRequest, SearchResponse, SearchSource, SearchOptions, ProjectData, ProjectSettings, QleverStats, CreateProjectOptions, SyncOptions, SyncResult, SyncPreview, ScanOutputRecord, UnitCreditMap, UnitsConsumedDto, OrgCreditsDto, OrgPlanSummary, MonthlyConsumptionDto, ProjectConsumptionReportDto, OrgConsumptionReportDto, OrganizationData, OrgMember, ProfileSSOAccount, APIKeyInfo, APIKeyDoc, ProjectDoc, OrganizationDoc, UserDoc, UserSettings, CustomAppRecord, CustomAppWithHtml, CreateCustomAppOptions, UpdateCustomAppOptions, RDFWritingDoc, ProcessingStatus, ProcessingStage, ViewDefinition, QueryCache, LangMap, CategoryDef, RelationshipDef, EntityCoreData, EntityRelationship, EntityRelationships, MapGeometry, EntityDetailedData, ProjectEntitiesData, SummaryGraphData, 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';
+export type { ContextDoc, ContextItem, McpContext } from './lib/models';
+export { CueAppData } from './lib/app-data';
+export { CueApps } from './lib/apps';
+export { CueUserSettings } from './lib/user-settings';

package/index.js

@@ -1,27 +1,36 @@
-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 m, k as P, l as j, m as p, n as S, o as g, p as h, q as E, r as R, s as d, R as f, t as x, u as A, v } from "./document-filter-Cmavbe75.js";
+import { B as a, C as u, f as C, A as t, D as r, c as i, v as c, z as o, w as n, m as p, y as E, a as S, g as P, h as R, s as A, k as g, r as m, o as j, n as l, l as D, p as U, q as x, e as f, d as h, t as d, b as y, i as I, x as _, E as b, R as q, S as v, j as w, u as B } from "./document-filter-Dr_-QbaZ.js";
 export {
-  s as Cue,
-  u as CueApi,
-  C as CueAuth,
-  t as CueCache,
-  i as CueContexts,
-  o as CueDocumentFilter,
-  c as CueExtraction,
-  r as CueGis,
-  n as CueIndexApi,
-  l as CuePrivileges,
+  a as BASE_CURRENCY,
+  u as Cue,
+  C as CueApi,
+  t as CueAppData,
+  r as CueApps,
+  i as CueAuth,
+  c as CueCache,
+  o as CueContexts,
+  n as CueCurrency,
+  p as CueDocumentFilter,
+  E as CueExtraction,
+  S as CueGis,
+  P as CueIndexApi,
+  R as CueMcp,
+  A as CuePrivileges,
+  g as CueProcessingApi,
   m as CueProfile,
-  P as CueProjectDocuments,
-  j as CueProjectEntities,
-  p as CueProjectSchema,
-  S as CueProjectView,
-  g as CueProjects,
-  h as CueSignal,
-  E as CueStorage,
-  R as CueSyncApi,
-  d as CueTables,
-  f as REQUIRED_ROLES,
-  x as configureScanWasm,
-  A as cueComputed,
-  v as staleWhileRevalidate
+  j as CueProjectDocuments,
+  l as CueProjectEntities,
+  D as CueProjectSchema,
+  U as CueProjectView,
+  x as CueProjects,
+  f as CueRequestError,
+  h as CueSignUp,
+  d as CueSignal,
+  y as CueStorage,
+  I as CueSyncApi,
+  _ as CueTables,
+  b as CueUserSettings,
+  q as REQUIRED_ROLES,
+  v as SUPPORTED_CURRENCIES,
+  w as configureScanWasm,
+  B as cueComputed
 };

package/lib/api.d.ts

@@ -0,0 +1,79 @@
+import { CueAuth } from './auth';
+import { SearchRequest, SearchResponse, ShaclValidationReport, UnitsConsumedDto } from './models';
+import { CueProjects } from './project';
+import { CueSyncApi } from './sync';
+import { CueTables } from './tables';
+import { CueExtraction } from './extraction';
+import { CueContexts } from './contexts';
+import { CueIndexApi } from './index-api';
+import { CueMcp } from './mcp';
+import { CueAppData } from './app-data';
+import { CueApps } from './apps';
+import { CueUserSettings } from './user-settings';
+import { CueProcessingApi } from './processing';
+export declare class CueApi {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    readonly projects: CueProjects;
+    readonly sync?: CueSyncApi | undefined;
+    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;
+    /** Direct interface to the Cue Index accessor — search and lookup. */
+    readonly index: CueIndexApi;
+    /** Generic caller for Cue Index MCP data-tool endpoints — returns each tool's Context result (`{ id, text }`) proxied as-is. */
+    readonly mcp: CueMcp;
+    /** Per-app, per-user data storage — small JSON blobs namespaced by app UUID. */
+    readonly appData: CueAppData;
+    /** Studio apps saved and shared within an organization (e.g. built with the AI App Builder). */
+    readonly apps: CueApps;
+    /** Global, per-user app settings — one small JSON blob shared across the whole portal (e.g. language). */
+    readonly userSettings: CueUserSettings;
+    /** Live pipeline-progress status for a project (upload → processing → loading → enrichment). */
+    readonly processing: CueProcessingApi;
+    /** 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.
+     * Useful when calling Cue-backed services directly (e.g. the GIS proxy).
+     */
+    getAuthHeaders(): Promise<Record<string, string>>;
+    /**
+     * Search project documents using natural language.
+     * The user must be authenticated before calling this.
+     */
+    search(request: SearchRequest): Promise<SearchResponse>;
+    /**
+     * Execute a SPARQL query against the project's triplestore.
+     * 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>;
+    /**
+     * Per-extension credit rates for `tier` (e.g. `{ pdf: 4, ifc: 2, dwg: 2 }`),
+     * read from the public `unit-credit.json` rate table. Used to show usage
+     * estimates (e.g. the sign-up plan-selection step) without an authenticated
+     * project context.
+     */
+    getUnitCredits(tier: 's' | 'm' | 'l'): Promise<Record<string, number>>;
+    getConsumption(projectId: string): Promise<UnitsConsumedDto>;
+}

package/lib/app-data.d.ts

@@ -0,0 +1,21 @@
+import { CueAuth } from './auth';
+/**
+ * Per-app, per-user data storage. Each app persists its own small JSON blob
+ * (capped at 100KB server-side), keyed by a UUID4 the app hardcodes for
+ * itself — this namespaces the data so no two apps can collide.
+ */
+export declare class CueAppData {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    /**
+     * Fetch this app's persisted data for the current user.
+     * Returns `null` if nothing has been saved yet.
+     */
+    get<T = unknown>(appId: string): Promise<T | null>;
+    /**
+     * Save this app's data for the current user. Overwrites any previous value.
+     * The server rejects payloads larger than 100KB.
+     */
+    set(appId: string, data: unknown): Promise<void>;
+}

package/lib/apps.d.ts

@@ -0,0 +1,24 @@
+import { CueAuth } from './auth';
+import { CreateCustomAppOptions, CustomAppRecord, CustomAppWithHtml, UpdateCustomAppOptions } from './models';
+/**
+ * Studio apps saved and shared within an organization — e.g. apps built with
+ * the AI App Builder. Distinct from `cue.api.appData`: that's a private,
+ * per-user settings blob namespaced by an app's own id; this is the shared
+ * app record itself (name, HTML, author) visible to every member of the app's
+ * organization.
+ */
+export declare class CueApps {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    /** List every custom app shared within the given organization (metadata only, no HTML). */
+    list(organizationId: string): Promise<CustomAppRecord[]>;
+    /** Fetch a single custom app's full record, including its HTML body. */
+    get(id: string): Promise<CustomAppWithHtml>;
+    /** Save a new custom app, shared with every member of `organizationID`. Any org member may create one. */
+    create(options: CreateCustomAppOptions): Promise<CustomAppRecord>;
+    /** Update an existing custom app. Only the original author or an organization admin may do this. */
+    update(id: string, options: UpdateCustomAppOptions): Promise<CustomAppRecord>;
+    /** Delete a custom app. Only the original author or an organization admin may do this. */
+    remove(id: string): Promise<void>;
+}

package/lib/auth.d.ts

@@ -0,0 +1,77 @@
+import { Auth, User } from 'firebase/auth';
+import { FirebaseApp } from 'firebase/app';
+import { CueEndpoints, PasswordCredentials, SsoProvider } from './models';
+import { ReadonlySignal } from './signal';
+export type AuthStateListener = (user: User | null) => void;
+export type Unsubscribe = () => void;
+export declare class CueAuth {
+    private readonly _auth;
+    private readonly _endpoints;
+    private readonly _userSignal;
+    private readonly _tokenSignal;
+    private readonly _isSuperAdminSignal;
+    private readonly _userIdsSignal;
+    private readonly _stopTokenListener;
+    /** Reactive auth state — emits the signed-in `User`, or `null` when signed out. */
+    readonly user: ReadonlySignal<User | null>;
+    /** Reactive Firebase ID token — refreshes automatically; `null` when signed out. */
+    readonly token: ReadonlySignal<string | null>;
+    /** `true` when the current user has the `superadmin` custom claim. */
+    readonly isSuperAdmin: ReadonlySignal<boolean>;
+    /** All unique UIDs for the current user (Firebase UID + linked provider UIDs). */
+    readonly userIds: ReadonlySignal<string[]>;
+    constructor(app: FirebaseApp, useEmulator: boolean | undefined, endpoints: CueEndpoints);
+    /** Stop all internal Firebase listeners. Call when the `Cue` instance is no longer needed. */
+    destroy(): void;
+    /** Sign in with Google or Microsoft via browser popup */
+    signIn(provider: SsoProvider): Promise<User>;
+    /** Sign in with email and password */
+    signIn(provider: 'password', credentials: PasswordCredentials): Promise<User>;
+    /**
+     * Initiate a redirect-based sign-in (mobile / iframe contexts where popups
+     * are blocked). Call `checkRedirectResult()` on the next page load to
+     * retrieve the result.
+     */
+    signInWithRedirect(provider: SsoProvider): Promise<void>;
+    /**
+     * Retrieve the result of a redirect sign-in. Returns the signed-in `User`
+     * or `null` if there is no pending redirect result.
+     * Call this once on app startup before showing a sign-in UI.
+     */
+    checkRedirectResult(): Promise<User | null>;
+    /**
+     * One-shot async check — returns `true` if the current user has the
+     * `superadmin` custom claim. For reactive use, read `cue.auth.isSuperAdmin`
+     * (the signal) instead.
+     */
+    checkSuperAdmin(): Promise<boolean>;
+    /** Sign in with a Cue API key. `projectId` is optional — omit it when no project context is available (e.g. admin flows). */
+    signInWithApiKey(cueApiKey: string, projectId?: string): Promise<User>;
+    /** Sign in with a Firebase custom token (e.g. minted server-side for MCP/OAuth flows). */
+    signInWithCustomToken(token: string): Promise<User>;
+    /**
+     * Mint a short-lived Firebase custom token for the current user, scoped to
+     * the same identity as their existing session. Used to bootstrap a second
+     * `Cue` instance inside a sandboxed, cross-origin context (e.g. an
+     * `srcdoc` iframe hosting AI-generated app HTML) that has no access to the
+     * portal's IndexedDB-persisted session — the sandboxed instance calls
+     * `signInWithCustomToken` with the returned token instead of relying on
+     * restored auth state.
+     */
+    mintAppSessionToken(): Promise<string>;
+    /** Sign out the current user */
+    signOut(): Promise<void>;
+    /** Currently signed-in user, or null if not authenticated */
+    get currentUser(): User | null;
+    /** Subscribe to authentication state changes. Returns an unsubscribe function. */
+    onAuthStateChanged(listener: AuthStateListener): Unsubscribe;
+    /** Get the Firebase ID token for the current user, or null if not authenticated */
+    getToken(forceRefresh?: boolean): Promise<string | null>;
+    /**
+     * Executes a fetch with a Bearer token. On a 401 response the token is
+     * force-refreshed and the request is retried once before throwing.
+     */
+    authenticatedFetch(url: string, init?: RequestInit): Promise<Response>;
+    /** Raw Firebase Auth instance, for advanced use cases */
+    get firebaseAuth(): Auth;
+}

package/lib/cache.d.ts

@@ -0,0 +1,26 @@
+import { FirebaseStorage } from 'firebase/storage';
+/** Shape stored by the query cache. */
+export interface QueryCacheEntry {
+    query: string;
+    results: unknown;
+}
+/**
+ * Gzip-compressed JSON cache backed by the `persistence` Cloud Storage bucket.
+ *
+ * Path conventions:
+ * - Query results:      `portal/projects/{pid}/queries/{id}.json.gz`
+ * - Agent sessions:     `portal/projects/{pid}/agent/{id}.json.gz`
+ * - User-project data:  `portal/projects/{pid}/users/{uid}/{id}.json.gz`
+ */
+export declare class CueCache {
+    private readonly _storage;
+    constructor(_storage: FirebaseStorage);
+    getQueryCache(projectId: string, id: string): Promise<QueryCacheEntry | undefined>;
+    setQueryCache(projectId: string, id: string, payload: QueryCacheEntry): Promise<void>;
+    getAgentSessionCache(projectId: string, id: string): Promise<object | undefined>;
+    setAgentSessionCache(projectId: string, id: string, payload: object): Promise<void>;
+    getUserProjectCache(projectId: string, userId: string, id: string): Promise<object | undefined>;
+    setUserProjectCache(projectId: string, userId: string, id: string, payload: object): Promise<void>;
+    private _get;
+    private _set;
+}

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-node.d.ts

@@ -0,0 +1,19 @@
+import { CueApi } from './api';
+import { Cue } from './cue';
+import { CueSyncApi } from './sync';
+import { CueSdkConfig } from './models';
+/**
+ * Node.js entry point for the QAECY SDK.
+ * Extends `Cue` with file-sync capabilities that require Node.js APIs.
+ *
+ * @example
+ * const cue = new CueNode({ apiKey: '...', appId: '...', measurementId: '...' });
+ * await cue.auth.signInWithApiKey(key);
+ * await cue.api.sync.sync(localFiles, { spaceId, providerId, userId });
+ */
+export declare class CueNode extends Cue {
+    readonly api: CueApi & {
+        sync: CueSyncApi;
+    };
+    constructor(config: CueSdkConfig);
+}

package/lib/cue.d.ts

@@ -0,0 +1,129 @@
+import { FirebaseApp } from 'firebase/app';
+import { FirebaseStorage } from 'firebase/storage';
+import { CueBlobStorage } from 'js-databases';
+import { CueAuth } from './auth';
+import { CueSignUp } from './signup';
+import { CueStorage } from './storage';
+import { CueApi } from './api';
+import { CueGis } from './gis';
+import { CueProjects } from './project';
+import { CueProfile } from './profile';
+import { CuePrivileges } from './privileges';
+import { CueCache } from './cache';
+import { CueCurrency } from './currency';
+import { CueProjectView, CueProjectViewOptions } from './project-view';
+import { CueProjectEntities } from './entities';
+import { CueProjectDocuments } from './documents';
+import { CueEndpoints, CueSdkConfig } from './models';
+/**
+ * Main entry point for the QAECY SDK (browser-safe).
+ * For Node.js use with file-sync capabilities, use `CueNode` from `js-cue-sdk/node`.
+ *
+ * @example
+ * const cue = new Cue({ apiKey: '...', appId: '...', measurementId: '...' });
+ * await cue.auth.signIn('google');
+ * const results = await cue.api.search({ term: 'my query', projectId: 'project-id' });
+ */
+export declare class Cue {
+    readonly auth: CueAuth;
+    readonly signup: CueSignUp;
+    readonly api: CueApi;
+    readonly projects: CueProjects;
+    readonly profile: CueProfile;
+    readonly privileges: CuePrivileges;
+    readonly cache: CueCache;
+    readonly storage: CueStorage;
+    readonly currency: CueCurrency;
+    protected readonly _app: FirebaseApp;
+    protected readonly _endpoints: CueEndpoints;
+    protected readonly _isEmulator: boolean;
+    protected _storageRaw: FirebaseStorage;
+    protected _storageProcessed: FirebaseStorage;
+    private _gis;
+    private readonly _projectDocuments;
+    private readonly _verbose;
+    /**
+     * 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.
+     *
+     * Use this when the host application (e.g. cue-portal via `CueFirebase`) has
+     * already called `initializeApp()`. Reusing the same `FirebaseApp` means the
+     * SDK shares the same auth state and Firestore instance — no second login is
+     * needed and `getToken()` returns the portal user's token directly.
+     *
+     * Emulator connections are skipped because the host app already set them up.
+     *
+     * @example
+     * // In an Angular service after CueFirebase is ready:
+     * const cue = Cue.fromApp(CueFirebase.getInstance().app!, {
+     *   environment: 'emulator',
+     * });
+     */
+    static fromApp(app: FirebaseApp, config?: Omit<CueSdkConfig, 'apiKey' | 'appId' | 'measurementId'>): Cue;
+    protected _buildApi(projects: CueProjects, blob: CueBlobStorage): CueApi;
+    /** Convenience: get the current user's Firebase ID token */
+    getToken(forceRefresh?: boolean): Promise<string | null>;
+    /**
+     * Create a `CueProjectView` for the given project, wiring the SDK's query
+     * cache automatically.
+     *
+     * The view auto-fetches the document overview and entity graph on construction
+     * and exposes reactive signals for all project knowledge-graph state.
+     *
+     * @example
+     * ```ts
+     * const view = cue.createProjectView('my-project', { language: 'en' });
+     * view.requestEntityData(['uuid1']);
+     * const info = view.entityInfoMap.get()['uuid1'];
+     * ```
+     */
+    createProjectView(projectId: string, opts: CueProjectViewOptions): CueProjectView;
+    /**
+     * Creates a `CueProjectEntities` instance for the given project, 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;
+        verbose?: boolean;
+    }): CueProjectEntities;
+    /**
+     * Creates a `CueProjectDocuments` instance for the given project, 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;
+        verbose?: boolean;
+    }): CueProjectDocuments;
+}

package/lib/currency.d.ts

@@ -0,0 +1,34 @@
+export type SupportedCurrency = 'CHF' | 'DKK' | 'EUR';
+export declare const SUPPORTED_CURRENCIES: SupportedCurrency[];
+export declare const BASE_CURRENCY: SupportedCurrency;
+/**
+ * CHF-based exchange rates. `rates[currency]` is "how many units of
+ * `currency` equal 1 CHF" — so `rates.CHF` is always `1`.
+ */
+export interface CurrencyRates {
+    base: 'CHF';
+    rates: Record<SupportedCurrency, number>;
+    fetchedAt: number;
+}
+/**
+ * Live CHF-based exchange rates for DKK/EUR, sourced from the Frankfurter API
+ * (ECB reference rates — the same market rates Google Finance quotes). Used
+ * to convert the CHF-denominated pricing model into a user's preferred
+ * display currency; billing itself always stays in CHF.
+ */
+export declare class CueCurrency {
+    private _cached;
+    private _pending;
+    /**
+     * Fetches the current rates, cached in-memory for one hour. Concurrent
+     * calls share a single in-flight request. If a refetch fails and a
+     * previous rate set is cached, the stale rates are served instead of
+     * throwing — a transient network blip shouldn't break the pricing UI.
+     */
+    getRates(forceRefresh?: boolean): Promise<CurrencyRates>;
+    private _fetchRates;
+    /** Converts an amount in CHF into `currency` using `rates`. */
+    fromBase(amountChf: number, currency: SupportedCurrency, rates: CurrencyRates): number;
+    /** Converts an amount in `currency` back into CHF using `rates`. */
+    toBase(amount: number, currency: SupportedCurrency, rates: CurrencyRates): number;
+}

package/lib/document-filter.d.ts

@@ -0,0 +1,76 @@
+import { CueApi } from './api';
+import { AvailableDocumentFilters, DocumentFilterOption, SearchFilter } from './models';
+/**
+ * Provides document-filter queries for a single project.
+ *
+ * - **{@link availableFilters}** — discovers which mime / content / entity-category
+ *   options exist within the document set that satisfies the currently applied
+ *   filters. Uses a 2-tier strategy to avoid cross-product result blowup:
+ *   1. QLever: 3 parallel single-dimension queries via `document-categories` view
+ *   2. Fallback: 3 parallel live triple-pattern queries
+ * - **{@link doLookup}** — returns UUIDs of documents that satisfy a
+ *   `SearchFilter[]` expression.
+ *
+ * ### Usage
+ * ```ts
+ * const filter = new CueDocumentFilter(cue.api, projectId);
+ * const opts = await filter.availableFilters();          // full option set
+ * const narrowed = await filter.availableFilters({       // adaptive narrowing
+ *   entityCategories: ['https://…/Person'],
+ * });
+ * const ids = await filter.doLookup([
+ *   { type: 'entity', included: ['https://…/Person'], excluded: [] },
+ * ]);
+ * ```
+ */
+export declare class CueDocumentFilter {
+    private readonly _api;
+    private readonly _projectId;
+    private readonly _graphType?;
+    constructor(_api: CueApi, _projectId: string, _graphType?: string | undefined);
+    /**
+     * Returns which mime, content and entity-category options are available among
+     * documents that satisfy `applied`. Pass an empty object (or omit) to get
+     * options across the full project.
+     *
+     * Uses a 2-tier strategy — each tier falls through on error or empty result:
+     * 1. QLever: 3 parallel single-dimension queries via `document-categories` view
+     * 2. Fallback: 3 parallel live triple-pattern queries
+     */
+    availableFilters(applied?: {
+        mimes?: string[];
+        contents?: string[];
+        entityCategories?: string[];
+        entities?: string[];
+    }): Promise<AvailableDocumentFilters>;
+    /**
+     * Lists the *specific* entities (e.g. "John Doe") of a given entity category
+     * (e.g. "Person") that are mentioned by documents satisfying `applied`.
+     *
+     * Each returned option's `iri` is the canonical-entity IRI (suitable for an
+     * `entityInstance` {@link SearchFilter}), and `label` is the entity's
+     * `qcy:value`. Results are narrowed by the currently applied filters so the
+     * list shrinks as other filters are added.
+     */
+    availableEntities(categoryIri: string, applied?: {
+        mimes?: string[];
+        contents?: string[];
+        entityCategories?: string[];
+        entities?: string[];
+    }): Promise<DocumentFilterOption[]>;
+    /**
+     * Returns UUIDs of documents that satisfy all provided filters.
+     *
+     * Filter semantics:
+     * - Multiple filter objects (different types) → AND between types
+     * - Multiple IRIs in `included` for the same type → OR
+     * - `excluded` IRIs → AND NOT
+     */
+    doLookup(filters: SearchFilter[]): Promise<string[]>;
+    /** Single-dimension available-filters query using the dimension-specific views. */
+    private _buildViewDimQuery;
+    /** Single-dimension available-filters query using live triple patterns. */
+    private _buildLiveDimQuery;
+    private _buildViewFilterQuery;
+    private _buildFilterQuery;
+}