@qaecy/cue-sdk 0.0.31 → 0.0.33

package/lib/project.d.ts

@@ -1,45 +0,0 @@
-import { FirebaseApp } from 'firebase/app';
-import { CueAuth } from './auth';
-import { CreateProjectOptions, CueEndpoints, ProjectData } from './models';
-type ProjectRole = 'admin' | 'syncer' | 'member';
-export declare class CueProjects {
-    private readonly _auth;
-    private readonly _db;
-    private readonly _functions;
-    private readonly _gatewayUrl;
-    constructor(_auth: CueAuth, app: FirebaseApp, useEmulator?: boolean, endpoints?: CueEndpoints);
-    private _requireUser;
-    /**
-     * Create a new project. The authenticated user is automatically set as admin, syncer, and member.
-     * Throws if a project with the given ID already exists.
-     */
-    createProject(options: CreateProjectOptions): Promise<ProjectData>;
-    /**
-     * List all projects where the authenticated user appears in the members array.
-     * Access is gated by Firestore rules which check membership.
-     */
-    listProjects(): Promise<ProjectData[]>;
-    /** Fetch a single project by ID. Returns null if not found. */
-    getProject(projectId: string): Promise<ProjectData | null>;
-    /**
-     * Atomically increments `unitsConsumed` on the top-level `clientSync/{projectId}`
-     * document, creating it if it doesn't exist. Intended for pre-flight checks.
-     */
-    incrementUnitsConsumed(projectId: string, units: number, userId: string): Promise<void>;
-    /**
-     * Invite a user to a project by email. Returns the invited user's uid and display name.
-     */
-    inviteUserToProject(email: string, projectId: string, role: ProjectRole): Promise<{
-        uid: string;
-        name?: string;
-    }>;
-    /** Change an existing member's role on a project. */
-    changeUserRoleOnProject(uid: string, projectId: string, role: ProjectRole): Promise<void>;
-    /** Remove a member from a project. */
-    removeUserFromProject(uid: string, projectId: string): Promise<void>;
-    /**
-     * Delete a project by ID. Requires superadmin privileges on the server.
-     */
-    deleteProject(projectId: string): Promise<void>;
-}
-export {};

package/lib/schema.d.ts

@@ -1,85 +0,0 @@
-import { CueApi } from './api';
-import { ReadonlySignal } from './signal';
-import { CategoryDef, QueryCache, RelationshipDef } from './models';
-/**
- * Holds the schema for a single project: available content categories,
- * entity categories, and entity relationship types.
- *
- * 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
- * (e.g. Angular) should bridge these to their own reactive primitives using
- * `subscribe()`.
- *
- * ### Lifecycle
- * One `CueProjectSchema` instance should be created per project. It is owned
- * by the higher-level `CueProjectView` and shares the same `CueApi` instance.
- *
- * @example
- * ```ts
- * const schema = new CueProjectSchema(cue.api, projectId, 'en');
- * schema.availableContentCategories.get(); // CategoryDef[]
- * schema.setLanguage('da');                // re-projects cached data instantly
- * await schema.refresh();                  // force re-fetch
- * ```
- */
-export declare class CueProjectSchema {
-    private readonly _api;
-    private readonly _projectId;
-    private readonly _queryCache?;
-    private readonly _graphType?;
-    private _snapshot?;
-    private _inflight?;
-    private _currentLang;
-    private readonly _verbose;
-    private readonly _contentCategories;
-    private readonly _entityCategories;
-    private readonly _relationships;
-    /** Currently active content categories for the selected language. */
-    readonly availableContentCategories: ReadonlySignal<CategoryDef[]>;
-    /** Currently active entity categories for the selected language. */
-    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, verbose?: boolean);
-    /** Returns the currently active language. */
-    get language(): string;
-    /**
-     * 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 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;
-    /** 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/signal.d.ts

@@ -1,54 +0,0 @@
-import { QueryCache } from './models';
-/** A reactive value that can be read and subscribed to. */
-export interface ReadonlySignal<T> {
-    /** Returns the current value. */
-    get(): T;
-    /**
-     * Register a listener that is called whenever the value changes.
-     * Returns an unsubscribe function.
-     */
-    subscribe(listener: () => void): () => void;
-}
-/** A writable reactive state container. */
-export declare class CueSignal<T> implements ReadonlySignal<T> {
-    private _value;
-    private _listeners;
-    constructor(initial: T);
-    get(): T;
-    set(value: T): void;
-    subscribe(listener: () => void): () => void;
-    /** Returns a read-only view of this signal. */
-    asReadonly(): ReadonlySignal<T>;
-}
-/**
- * Creates a derived read-only signal from one or more source signals.
- * The compute function is evaluated lazily and cached until a dependency changes.
- *
- * @param deps   Source signals to watch.
- * @param compute Function that computes the derived value; must be pure.
- * @returns A `ReadonlySignal` with a `destroy()` method to stop tracking deps.
- */
-export declare function cueComputed<T>(deps: ReadonlySignal<unknown>[], compute: () => T): ReadonlySignal<T> & {
-    destroy(): void;
-};
-/**
- * Stale-while-revalidate helper for SPARQL queries.
- *
- * 1. If `cache` is provided and has a stored result for `cacheKey`, calls
- *    `onData(staleData, true)` immediately (synchronously relative to the await).
- * 2. Fires `fetchFresh()` to get current data from the triplestore.
- * 3. Calls `onData(freshData, false)`.
- * 4. Writes the fresh result to `cache` only if it differs from the stale
- *    result (content-addressed via `contextBasedGuid`).
- * 5. Returns the fresh data.
- *
- * If no `cache` is provided the function simply fetches and calls `onData`
- * once, transparently.
- *
- * @param query      The SPARQL query string — also used as cache key input.
- * @param fetchFresh Function that executes the query and returns the result.
- * @param onData     Called once with stale data (if available) and once with
- *                   fresh data.
- * @param cache      Optional {@link QueryCache} implementation.
- */
-export declare function staleWhileRevalidate<T>(query: string, fetchFresh: () => Promise<T>, onData: (data: T, isStale: boolean) => void, cache?: QueryCache): Promise<T>;

package/lib/storage.d.ts

@@ -1,52 +0,0 @@
-import { CueAuth } from './auth';
-export type StorageBucket = 'raw' | 'processed';
-/**
- * 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 = cue.storage.getDownloadUrl('my-project', 'abc123', '.pdf');
- * const res  = await cue.auth.authenticatedFetch(url);
- * ```
- */
-export declare class CueStorage {
-    private readonly _auth;
-    private readonly _gatewayUrl;
-    constructor(_auth: CueAuth, _gatewayUrl: string);
-    /**
-     * 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): string;
-    /**
-     * 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`.
-     *
-     * @param remoteRelativePath - The full path in the processed bucket,
-     *   e.g. `{projectId}/fragments/{uuid}.fragments`.
-     */
-    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/lib/sync.d.ts

@@ -1,125 +0,0 @@
-import { CueBlobStorage } from 'js-databases';
-import { LocalFile } from 'js-sync-tools';
-import { CueAuth } from './auth';
-import { CueApi } from './api';
-import { CueProjects } from './project';
-import { ScanOutputRecord, SyncOptions, SyncPreview, SyncResult } from './models';
-/**
- * Configure the URL from which the WASM scanner assets are loaded in browser environments.
- * Call this once during app initialisation (e.g. Angular APP_INITIALIZER) before any credit
- * calculations are requested.
- *
- * @param baseUrl - URL prefix for `dir_scanner_wasm_bg.wasm` and `dir_scanner_wasm.mjs`,
- *   e.g. `'/assets/wasm'` or `'https://cdn.example.com/wasm'`.
- */
-export declare function configureScanWasm(baseUrl: string): void;
-export declare class CueSyncApi {
-    private readonly _auth;
-    private readonly _projects;
-    private readonly _blob;
-    private readonly _gatewayUrl;
-    private readonly _graphMap;
-    private _api?;
-    private _pendingItems;
-    private _pendingSpaceId;
-    private _flushTimer;
-    private _legacy;
-    constructor(_auth: CueAuth, _projects: CueProjects, _blob: CueBlobStorage, _gatewayUrl: string);
-    /** @internal Injected by CueApi after construction to avoid circular dependency. */
-    _bindApi(api: CueApi): void;
-    /**
-     * Initialises browser-mode sync for a project space.
-     * - Flushes any metadata items that were queued but not sent in a previous session
-     *   (persisted in `localStorage`).
-     * - Starts the 60-second periodic flush timer.
-     *
-     * Call this once when the file manager component is created (or when the active
-     * project changes) so that interrupted uploads are recovered immediately.
-     */
-    initBrowserSync(spaceId: string): Promise<void>;
-    /**
-     * Pushes filesystem-structure metadata for all provided files directly to the
-     * commands API, without checking what is already on the remote or accounting for
-     * credits.  Use this when you want to force-write metadata for every file in a
-     * local path (e.g. to repair missing graph data after a migration).
-     */
-    pushAllMetadata(localFiles: LocalFile[], options: Pick<SyncOptions, 'spaceId' | 'providerId' | 'verbose' | 'legacy'>): Promise<void>;
-    /**
-     * Flushes any pending file-location metadata from a previously interrupted sync.
-     * Safe to call even when there are no new files to upload (e.g. when the process
-     * died after uploading to blob storage but before the commands-API batch POST).
-     */
-    flushPendingMetadata(spaceId: string, verbose?: boolean, legacy?: boolean): Promise<void>;
-    /**
-     * Returns a preview of what would be synced: cost breakdown for new files only,
-     * units required, and units still available. Use this before calling {@link sync}
-     * to show the user an accurate cost estimate.
-     */
-    previewSync(localFiles: LocalFile[], options: SyncOptions): Promise<SyncPreview>;
-    sync(localFiles: LocalFile[], options: SyncOptions): Promise<SyncResult>;
-    private _getOrCreateGraph;
-    private _listRemoteFiles;
-    private _getGraphFiles;
-    private _initPendingBatch;
-    private _queueFileLocation;
-    /**
-     * Flush all queued file-location items to the commands API in a single batch.
-     * Call this once after a group of `syncBrowserFile` calls completes so that
-     * all items are sent together rather than one POST per file.
-     */
-    drainPending(): Promise<void>;
-    private _drainPending;
-    private _flushBatch;
-    private _postFssBatch;
-    private _stopFlushTimer;
-    /**
-     * Scans `localFiles` and returns a per-extension cost breakdown.
-     *
-     * Each {@link ScanOutputRecord} contains `units` — the billable metric for
-     * that extension (e.g. pages for PDFs, rows for spreadsheets) — which can be
-     * shown to the user before or after calling {@link sync}.
-     */
-    scanCost(localFiles: LocalFile[]): Promise<ScanOutputRecord[]>;
-    /**
-     * Compute the credit cost for a set of local files without uploading anything.
-     * Intended for browser use where the full {@link previewSync} (which requires a
-     * remote file listing) would be too heavy for a quick estimate.
-     *
-     * @param localFiles - Files to analyse.  Each entry must carry `data` when
-     *   called from a browser context.
-     * @param spaceId    - Project/space identifier used to fetch the tier settings.
-     * @returns Per-extension cost breakdown and the number of credits currently
-     *   available in the project.
-     */
-    computeCredits(localFiles: LocalFile[], spaceId: string): Promise<{
-        costRecords: ScanOutputRecord[];
-        creditsToConsume: number;
-        creditsAvailable: number;
-    }>;
-    /**
-     * Upload a single browser-supplied file and write its metadata to the knowledge graph.
-     *
-     * Unlike {@link sync} (which performs a full remote comparison), this method is
-     * designed for the web file-manager flow where the user has already confirmed the
-     * upload via the credit modal.  The file's binary data must be provided in
-     * `file.data`; the `file.fullPath` field is ignored.
-     *
-     * Cancellation is supported via `options.signal`.  Aborting the signal cancels
-     * the Firebase Storage upload; metadata is never written for a cancelled upload.
-     *
-     * @param file    - `LocalFile` with `data` populated (e.g. from `File.arrayBuffer()`).
-     * @param options - Upload options including project/provider/user context and an
-     *   optional `AbortSignal` for cancellation and `onProgress` for tracking.
-     */
-    syncBrowserFile(file: LocalFile, options: {
-        spaceId: string;
-        providerId: string;
-        userId: string;
-        signal?: AbortSignal;
-        onProgress?: (percent: number) => void;
-    }): Promise<void>;
-    getTierNames(): Promise<Record<string, string>>;
-    private _fetchTierNames;
-    private _fetchUnitCreditMap;
-    private _logProgress;
-}

package/lib/tables.d.ts

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

@@ -1,49 +0,0 @@
-/**
- * Default Firebase configuration for the QAECY SDK demo app ("sdk-default").
- * These are safe to use for evaluation and development purposes.
- * For production use, obtain your own configuration from QAECY.
- */
-export declare const DEFAULT_SDK_CONFIG: {
-    readonly apiKey: "AIzaSyAiW42QBx9HS4Khu88pCW7MV66IhBAQul0";
-    readonly appId: "1:151132927589:web:d2ffdb377dfadfd23ab88c";
-    readonly measurementId: "G-YT4PK6HGZD";
-};
-export declare const FIREBASE_PROJECT_ID = "qaecy-mvp-406413";
-export declare const FIREBASE_SENDER_ID = "734737865998";
-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";
-export declare const BUCKET_LOGS = "spaces_logs_eu_west6";
-export declare const BUCKET_PUBLIC = "cue_public_eu_west6";
-export declare const BUCKET_PERSISTENCE = "db_persistence_eu_west6";
-export declare const ENDPOINT_CONSUMPTION = "/data-views/admin/consumption";
-export declare const ENDPOINT_PROFILE_ORGANIZATIONS = "/data-views/admin/profile/organizations";
-export declare const ENDPOINT_PROFILE_API_KEYS = "/data-views/admin/profile/api-keys";
-export declare const ENDPOINT_COMMANDS_PROFILE_API_KEYS = "/commands/admin/profile/api-keys";
-export declare const ENDPOINT_COMMANDS_PROFILE_TERMS = "/commands/admin/profile/terms";
-export declare const ENDPOINT_ORG_MEMBERS: (orgId: string) => string;
-export declare const ENDPOINT_CREATE_PROJECT = "/commands/admin/project";
-export declare const ENDPOINT_DELETE_PROJECT: (projectId: string) => string;
-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 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";
-/**
- * Base URL for all RDF resource IRIs: `https://cue.qaecy.com/r/{projectId}/{entityUUID}`.
- * Entity IRIs are constructed as `${RESOURCE_BASE}${projectId}/${uuid}`.
- */
-export declare const RESOURCE_BASE = "https://cue.qaecy.com/r/";