@qaecy/cue-sdk 0.0.6 → 0.0.8

package/lib/privileges.d.ts

@@ -0,0 +1,53 @@
+import { ReadonlySignal } from './signal';
+/** Roles ordered from highest to lowest privilege. */
+declare const ROLE_HIERARCHY: readonly ["superadmin", "admin", "syncer", "member"];
+export type UserProjectRole = (typeof ROLE_HIERARCHY)[number];
+export interface Privileges {
+    changeContentCategories: boolean;
+    createEntities: boolean;
+    createProvider: boolean;
+    deleteDocuments: boolean;
+    deleteUserFromProject: boolean;
+    downloadDocuments: boolean;
+    editContentCategories: boolean;
+    editPublicReposAvailableToAgent: boolean;
+    editTier: boolean;
+    inviteUserToProject: boolean;
+    renameDocuments: boolean;
+    uploadDocuments: boolean;
+    viewEntities: boolean;
+}
+/** Minimum role required for each privilege. */
+export declare const REQUIRED_ROLES: Record<keyof Privileges, UserProjectRole>;
+/**
+ * Manages role-based access control for the current user + selected project.
+ *
+ * - Call `setProjectRoles()` whenever the selected project changes.
+ * - Read `privileges` (a `ReadonlySignal<Privileges>`) for reactive access.
+ *
+ * @example
+ * cue.privileges.setProjectRoles(['admin']);
+ * const canUpload = cue.privileges.privileges.get().uploadDocuments; // true
+ */
+export declare class CuePrivileges {
+    private readonly _isSuperAdmin;
+    private readonly _projectRoles;
+    /**
+     * Reactive signal — current user's privileges for the selected project.
+     * Recomputes automatically when `setProjectRoles()` is called or when
+     * the `isSuperAdmin` signal changes.
+     */
+    readonly privileges: ReadonlySignal<Privileges>;
+    constructor(_isSuperAdmin: ReadonlySignal<boolean>);
+    /**
+     * Set the user's roles for the currently selected project.
+     *
+     * Roles are expanded along the hierarchy: `admin` automatically includes
+     * `syncer` and `member`; `syncer` includes `member`. Pass an empty array
+     * to reset to the lowest privilege level.
+     */
+    setProjectRoles(roles: UserProjectRole[]): void;
+    private _expand;
+    private _compute;
+}
+export {};

package/lib/profile.d.ts

@@ -1,12 +1,14 @@
 import { UserInfo } from 'firebase/auth';
 import { FirebaseApp } from 'firebase/app';
-import { APIKeyDoc, APIKeyInfo, ProfileSSOAccount } from './models';
+import { APIKeyDoc, APIKeyInfo, OrgMember, OrganizationData, ProfileSSOAccount } from './models';
 import { CueAuth } from './auth';
 export declare class CueProfile {
     private readonly _auth;
-    private readonly _db;
-    private _apiKeyDocRef?;
-    constructor(_auth: CueAuth, app: FirebaseApp, useEmulator: boolean, emulatorHost: string, emulatorPort: number);
+    private readonly _gatewayUrl;
+    private readonly _functions;
+    constructor(_auth: CueAuth, app: FirebaseApp, useEmulator: boolean, _gatewayUrl: string);
+    private _url;
+    private _fetch;
     /** Whether the current user has an active API key. */
     hasAPIKey(): Promise<boolean>;
     /** Returns the sign-in methods registered for the current user's email. */
@@ -31,6 +33,21 @@ export declare class CueProfile {
     revokeAPIKey(): Promise<void>;
     /** Fetches the current user's existing API key. */
     requestAPIKey(): Promise<APIKeyInfo>;
-    private _checkIfUserHasAPIKey;
+    /** Returns organizations the current user is a member of. */
+    listOrganizations(): Promise<(Pick<OrganizationData, 'id' | 'name'> & {
+        isAdmin: boolean;
+    })[]>;
+    /** Returns all members of the given organisation. Caller must be an org admin or superadmin. */
+    getOrgMembers(orgId: string): Promise<OrgMember[]>;
     private _requireUser;
+    /**
+     * Fetch display name and email for a list of user UIDs.
+     * Uses the `getUserInfo` Firebase callable function.
+     */
+    getUserInfo(uids: string[]): Promise<Record<string, {
+        name: string;
+        email: string;
+    }>>;
+    /** Record that the current user has accepted the terms of service. */
+    acceptTerms(): Promise<void>;
 }

package/lib/project-view.d.ts

@@ -0,0 +1,107 @@
+import { CueApi } from './api';
+import { CueProjectSchema } from './schema';
+import { CueProjectEntities } from './entities';
+import { CueProjectDocuments } from './documents';
+import { ReadonlySignal } from './signal';
+import { QueryCache, SearchOptions, SearchResponse, CategoryDef, RelationshipDef, EntityDetailedData, EntityRelationships, ProjectEntitiesData, DocumentInfo, ProjectDocumentsData } from './models';
+export interface CueProjectViewOptions {
+    language: string;
+    queryCache?: QueryCache;
+    /** Override the RDF resource base URL. Defaults to `https://cue.qaecy.com/r/`. */
+    rdfBase?: string;
+    /** Graph engine type from projectSettings.graph.type (e.g. 'qlever' or 'fuseki'). */
+    graphType?: string;
+}
+/**
+ * Framework-agnostic facade over `CueProjectSchema`, `CueProjectEntities`, and
+ * `CueProjectDocuments`. Exposes a flat, ergonomic API for all knowledge-graph
+ * view state needed by the portal.
+ *
+ * Create via `cue.createProjectView()` rather than constructing directly — the
+ * factory wires the active `QueryCache` automatically.
+ *
+ * @example
+ * ```ts
+ * const view = cue.createProjectView('my-project', { language: 'en' });
+ * view.entityInfoMap.subscribe(map => render(map));
+ * view.requestEntityData(['uuid1', 'uuid2']);
+ * ```
+ */
+export declare class CueProjectView {
+    private readonly _api;
+    private readonly _projectId;
+    /** Direct access to the schema data class (available categories / relationships). */
+    readonly schema: CueProjectSchema;
+    /** Direct access to the entity data class. */
+    readonly entities: CueProjectEntities;
+    /** Direct access to the document data class. */
+    readonly documents: CueProjectDocuments;
+    /** Available content category definitions for this project. Auto-fetched on init. */
+    readonly availableContentCategories: ReadonlySignal<CategoryDef[]>;
+    /** Available entity category definitions for this project. Auto-fetched on init. */
+    readonly availableEntityCategories: ReadonlySignal<CategoryDef[]>;
+    /** Available entity relationship types. Auto-fetched on init. */
+    readonly availableEntityRelationships: ReadonlySignal<RelationshipDef[]>;
+    /** Merged per-entity detail map. Populated lazily via `requestEntityData()` etc. */
+    readonly entityInfoMap: ReadonlySignal<Record<string, EntityDetailedData>>;
+    /** Project-level entity co-occurrence graph. Fetched once on init. */
+    readonly entityGraph: ReadonlySignal<ProjectEntitiesData | undefined>;
+    /** Per-document info map. Populated lazily via `requestDocumentData()`. */
+    readonly documentInfoMap: ReadonlySignal<Record<string, DocumentInfo>>;
+    /** Project document overview (counts by suffix and category). Fetched on init. */
+    readonly projectDocumentsData: ReadonlySignal<ProjectDocumentsData | undefined>;
+    private readonly _searchResults;
+    /** 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);
+    /**
+     * Lazily batch-fetch core data (label + categories) for the given entity UUIDs.
+     * Already-fetched UUIDs are skipped. Populates `entityInfoMap`.
+     */
+    requestEntityData(uuids: string[], includeMentionCount?: boolean): void;
+    /**
+     * Lazily fetch OSM location data for the given entity UUIDs.
+     * Already-fetched UUIDs are skipped. Populates `entityInfoMap` geometry fields.
+     */
+    requestEntityLocations(uuids: string[]): Promise<void>;
+    /**
+     * Fetch incoming and outgoing relationships for a single entity IRI.
+     * Result is stored in `entityInfoMap[uuid].relationshipData`.
+     */
+    fetchEntityRelationships(iri: string): Promise<EntityRelationships>;
+    /**
+     * Fetch UUIDs of documents that reference the given entity IRI.
+     * Result is stored in `entityInfoMap[uuid].documentRefs`.
+     */
+    fetchEntityDocuments(iri: string): Promise<string[]>;
+    /** Constructs the full RDF IRI for an entity UUID. */
+    entityIri(uuid: string): string;
+    /**
+     * Lazily batch-fetch document info for the given UUIDs.
+     * Already-fetched UUIDs are skipped. Populates `documentInfoMap`.
+     */
+    requestDocumentData(uuids: string[]): void;
+    /**
+     * Run a natural-language search against the project.
+     * The result is stored in `searchResults` and replaces any previous result.
+     */
+    search(term: string, options?: SearchOptions): Promise<void>;
+    /**
+     * Switch the active language for schema labels and document text fields.
+     * Schema responses are cached per language (instant if previously loaded).
+     * The document info map is cleared and lazily re-populated on next access.
+     */
+    setLanguage(lang: string): void;
+    /**
+     * Reset all entity and document state and re-fetch the project overview.
+     * Prefer creating a fresh `CueProjectView` when switching projects.
+     * Use `reset()` only when the same project's data needs to be invalidated.
+     */
+    reset(): void;
+    /**
+     * Tear down this view instance. Clears all reactive state and blocks further
+     * updates. Call from the Angular adapter's `ngOnDestroy` or equivalent.
+     */
+    destroy(): void;
+}

package/lib/project.d.ts

@@ -1,9 +1,12 @@
 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;
     /**
@@ -12,8 +15,8 @@ export declare class CueProjects {
      */
     createProject(options: CreateProjectOptions): Promise<ProjectData>;
     /**
-     * List all projects where the authenticated user appears in the members, syncers, or admins array.
-     * Runs three parallel Firestore queries and deduplicates by project ID.
+     * 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. */
@@ -23,4 +26,16 @@ export declare class CueProjects {
      * 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>;
 }
+export {};

package/lib/schema.d.ts

@@ -0,0 +1,66 @@
+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.
+ *
+ * Data is fetched lazily on construction and cached per language so that
+ * switching back to a previously loaded language is instant.
+ *
+ * ### 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');                // loads from cache or re-fetches
+ * await schema.refresh();                  // force re-fetch current language
+ * ```
+ */
+export declare class CueProjectSchema {
+    private readonly _api;
+    private readonly _projectId;
+    private readonly _queryCache?;
+    private readonly _graphType?;
+    private readonly _cache;
+    private readonly _language;
+    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[]>;
+    constructor(_api: CueApi, _projectId: string, language: string, _queryCache?: QueryCache | undefined, _graphType?: string | undefined);
+    /** 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.
+     */
+    setLanguage(lang: string): void;
+    /**
+     * Force a re-fetch for the current language, bypassing the cache.
+     * Useful when the triplestore data has changed.
+     */
+    refresh(): Promise<void>;
+    private _load;
+    private _apply;
+    private _fetchCategories;
+    private _buildCategoriesQuery;
+    private _runCategoriesQuery;
+    private _fetchRelationships;
+    private _buildRelationshipsQuery;
+    private _runRelationshipsQuery;
+}

package/lib/signal.d.ts

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

@@ -4,6 +4,15 @@ 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;
@@ -14,14 +23,33 @@ export declare class CueSyncApi {
     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;
     /**
-     * Flushes any pending metadata items from a previous interrupted sync.
-     * Safe to call even when there is nothing new to upload.
+     * 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): Promise<void>;
+    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}
@@ -34,6 +62,12 @@ export declare class CueSyncApi {
     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;
@@ -46,6 +80,44 @@ export declare class CueSyncApi {
      * 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>;
     private _fetchTierNames;
     private _fetchUnitCreditMap;
     private _logProgress;