@qaecy/cue-sdk 0.0.33 → 0.0.35

package/lib/privileges.d.ts

@@ -0,0 +1,76 @@
+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];
+/** Role a user can have within an organization. */
+export type UserOrgRole = 'admin' | 'member';
+export interface Privileges {
+    changeContentCategories: boolean;
+    createEntities: boolean;
+    createProject: boolean;
+    createProvider: boolean;
+    deleteDocuments: boolean;
+    deleteProject: boolean;
+    deleteUserFromProject: boolean;
+    downloadDocuments: boolean;
+    editContentCategories: boolean;
+    editPublicReposAvailableToAgent: boolean;
+    editTier: boolean;
+    inviteUserToProject: boolean;
+    rebuildIndex: boolean;
+    refreshStats: boolean;
+    renameDocuments: boolean;
+    uploadDocuments: boolean;
+    viewAdvancedStats: boolean;
+    viewCredits: boolean;
+    viewEntities: boolean;
+}
+/**
+ * Minimum project role required for each privilege.
+ * Note: `createProject` is intentionally absent — it is gated by the
+ * user's organisation role, not their project role.
+ */
+export declare const REQUIRED_ROLES: Record<Exclude<keyof Privileges, 'createProject'>, UserProjectRole>;
+/**
+ * Manages role-based access control for the current user + selected project.
+ *
+ * - Call `setProjectRoles()` whenever the selected project changes.
+ * - Call `setOrgRole()` whenever the selected project's organisation changes.
+ * - Read `privileges` (a `ReadonlySignal<Privileges>`) for reactive access.
+ *
+ * @example
+ * cue.privileges.setProjectRoles(['admin']);
+ * cue.privileges.setOrgRole('admin');
+ * const canUpload = cue.privileges.privileges.get().uploadDocuments; // true
+ * const canCreate = cue.privileges.privileges.get().createProject;  // true
+ */
+export declare class CuePrivileges {
+    private readonly _isSuperAdmin;
+    private readonly _projectRoles;
+    private readonly _orgRole;
+    /**
+     * 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 role within the organisation that owns the selected project.
+     * Pass `null` to clear the organisation role (e.g. when deselecting a project).
+     *
+     * Only organisation admins (and superadmins) may create projects.
+     */
+    setOrgRole(role: UserOrgRole | null): void;
+    /**
+     * 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/processing.d.ts

@@ -0,0 +1,25 @@
+import { CueAuth } from './auth';
+import { ReadonlySignal } from './signal';
+import { ProcessingStatus } from './models';
+export interface ProcessingStatusWatcher {
+    /** Live pipeline status for the watched project; `undefined` until the first message arrives. */
+    status: ReadonlySignal<ProcessingStatus | undefined>;
+    /** Stops the subscription and closes the underlying WebSocket. */
+    close(): void;
+}
+/**
+ * Live pipeline-progress status, pushed by the `accessors-data-views`
+ * processing-status WebSocket. Backs the upload modal and project-settings
+ * "processing" indicators in the portal.
+ */
+export declare class CueProcessingApi {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    /**
+     * Opens a live subscription to a project's pipeline status. Reconnects
+     * automatically (with a fixed delay) if the connection drops, until `close()`
+     * is called.
+     */
+    watchStatus(projectId: string): ProcessingStatusWatcher;
+}

package/lib/profile.d.ts

@@ -0,0 +1,128 @@
+import { UserInfo } from 'firebase/auth';
+import { FirebaseApp } from 'firebase/app';
+import { APIKeyDoc, APIKeyInfo, OrgConsumptionReportDto, OrgCreditsDto, OrgMember, OrganizationData, ProfileSSOAccount } from './models';
+import { CueAuth } from './auth';
+import { ReadonlySignal } from './signal';
+export declare class CueProfile {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    private readonly _functions;
+    private readonly _orgCredits;
+    /**
+     * Reactive view of the last-fetched org credit pool. Updated automatically
+     * by `getOrgCredits()` and by the sync layer after every `previewSync`/
+     * `sync`/`computeCredits` call, so consumers that bind to this signal see
+     * balance changes (e.g. after an upload) without polling or manually
+     * re-fetching. Angular consumers bridge via
+     * `effect(() => sig.set(cue.profile.orgCredits.get()))` + `.subscribe(...)`.
+     */
+    readonly orgCredits: ReadonlySignal<OrgCreditsDto | undefined>;
+    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. */
+    getSignInMethods(): Promise<string[]>;
+    /** Builds a human-readable label from a Firebase UserInfo provider entry. */
+    buildProviderLabel(userInfo: UserInfo): string;
+    /** Returns SSO accounts linked to the current user (excludes password). */
+    getSSOAccounts(): ProfileSSOAccount[];
+    /** Links a Google or Microsoft provider to the current account via popup. Returns the new provider label. */
+    linkProvider(ssoProvider: string): Promise<string>;
+    /** Unlinks a provider from the current account. */
+    unlinkProvider(providerId: string): Promise<void>;
+    /** Changes the password. Reauthenticates first. */
+    updatePassword(currentPassword: string, newPassword: string): Promise<void>;
+    /** Adds (sets) a password for an account that currently only uses SSO. */
+    addPassword(password: string): Promise<void>;
+    /** Requests an e-mail change. Sends a verification e-mail to the new address. */
+    updateEmail(newEmail: string, password: string): Promise<void>;
+    /** Creates a new API key for the current user. */
+    createAPIKey(expiration: string): Promise<APIKeyDoc>;
+    /** Revokes the current user's API key. */
+    revokeAPIKey(): Promise<void>;
+    /** Fetches the current user's existing API key. */
+    requestAPIKey(): Promise<APIKeyInfo>;
+    /** 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[]>;
+    /** Adds a new member to the organisation. Caller must be an org admin or superadmin. */
+    addOrgMember(orgId: string, member: {
+        name: string;
+        email: string;
+        role: 'admin' | 'member';
+    }): Promise<void>;
+    /** Changes an existing member's role within the organisation. Caller must be an org admin or superadmin. */
+    setOrgUserRole(orgId: string, userId: string, role: 'admin' | 'member'): Promise<void>;
+    /** Removes a member from the organisation, optionally also removing them from every project they belong to. Caller must be an org admin or superadmin. */
+    removeOrgMember(orgId: string, userId: string, removeFromProjects: boolean): Promise<void>;
+    /**
+     * Returns the organisation's shared credit pool: `purchased`, `consumed`
+     * (summed across every project the org owns), and `available`. Caller must
+     * be an org admin or superadmin.
+     */
+    getOrgCredits(orgId: string): Promise<OrgCreditsDto>;
+    /**
+     * Per-project, per-month consumption breakdown for the org — for reporting/export, not
+     * the balance itself (use {@link getOrgCredits} for that). Caller must be an org admin
+     * or superadmin.
+     */
+    getOrgConsumptionReport(orgId: string): Promise<OrgConsumptionReportDto>;
+    /** Manual/support credit grant to an organisation's shared pool. Superadmins only — org admins self-serve via `startOrgCheckout`. */
+    topUpOrgCredits(orgId: string, amount: number): Promise<void>;
+    /**
+     * Starts a self-serve Stripe checkout for a one-time credit top-up.
+     * Returns the hosted checkout URL to redirect the user to; credits are
+     * granted by the backend webhook once payment completes.
+     */
+    startOrgCheckout(orgId: string, credits: number): Promise<{
+        url: string;
+    }>;
+    /**
+     * Opens the Stripe Billing Portal for the organisation (update card, view
+     * invoices, cancel the plan). Returns the hosted portal URL. Caller must be
+     * an org admin; requires the org to have a Stripe customer.
+     */
+    startOrgBillingPortal(orgId: string): Promise<{
+        url: string;
+    }>;
+    /**
+     * Change an organisation's plan — freemium → custom (first paid plan), or
+     * re-quote a plan that's still `pendingPayment`. Prices with the same
+     * canonical formula used at signup. Returns a checkout URL for the card
+     * flow (redirect the user there); omitted for the invoice flow or a
+     * freemium change, which apply immediately.
+     *
+     * Orgs with an *active* paid subscription must use
+     * {@link startOrgBillingPortal} instead — this throws if called on one.
+     */
+    changeOrgPlan(orgId: string, plan: {
+        type: 'freemium' | 'custom';
+        monthlySpendChf?: number;
+        paymentMethod?: 'card' | 'invoice';
+    }): Promise<{
+        checkoutUrl?: string;
+    }>;
+    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. Sets a `terms` custom claim on the token. */
+    acceptTerms(version: string): Promise<void>;
+    /**
+     * Returns the terms version the current user has accepted (e.g. `"v1"`),
+     * or `null` if they have not accepted any version yet.
+     * Reads from the cached ID token — call after `acceptTerms()` with a
+     * force-refreshed token to see the updated value.
+     */
+    latestTermsAccepted(): Promise<string | null>;
+}

package/lib/project-view.d.ts

@@ -0,0 +1,112 @@
+import { CueApi } from './api';
+import { CueProjectSchema } from './schema';
+import { CueProjectEntities } from './entities';
+import { CueProjectDocuments } from './documents';
+import { ReadonlySignal } from './signal';
+import { SearchOptions, SearchResponse, CategoryDef, RelationshipDef, EntityDetailedData, EntityRelationships, ProjectEntitiesData, DocumentInfo, ProjectDocumentsData } from './models';
+export interface CueProjectViewOptions {
+    language: string;
+    /** 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;
+    /** Enable verbose debug logging for entity and document fetch stats. */
+    verbose?: boolean;
+}
+/**
+ * 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.
+ *
+ * @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[]>;
+    /**
+     * Resolves when the initial schema load has completed. Await before reading
+     * schema signal values imperatively.
+     */
+    readonly schemaReady: Promise<void>;
+    /** 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, rdfBase, graphType, verbose }: 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

@@ -0,0 +1,56 @@
+import { FirebaseApp } from 'firebase/app';
+import { CueAuth } from './auth';
+import { CreateProjectOptions, CueEndpoints, ProjectData } from './models';
+import { ReadonlySignal } from './signal';
+type ProjectRole = 'admin' | 'syncer' | 'member';
+export declare class CueProjects {
+    private readonly _auth;
+    private readonly _db;
+    private readonly _functions;
+    private readonly _gatewayUrl;
+    private readonly _projects;
+    /**
+     * Live cache of the current user's projects, refreshed on every `listProjects()`
+     * call and patched in place by `getProject()` — lets consumers reflect changes
+     * without every caller having to remember to re-fetch the whole list.
+     */
+    readonly projects: ReadonlySignal<ProjectData[] | undefined>;
+    constructor(_auth: CueAuth, app: FirebaseApp, useEmulator?: boolean, endpoints?: CueEndpoints);
+    /**
+     * 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. */
+    listProjects(): Promise<ProjectData[]>;
+    /** Fetch a single project by ID. Returns null if not found or user lacks access. */
+    getProject(projectId: string): Promise<ProjectData | null>;
+    /**
+     * Merges a freshly-fetched project into the live `projects` signal, replacing
+     * the entry with matching `id`. Skipped if the signal hasn't been populated by
+     * `listProjects()` yet — patching into an unknown/partial list would make a
+     * single project look like the user's entire project set.
+     */
+    private _patchProject;
+    /**
+     * 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

@@ -0,0 +1,84 @@
+import { CueApi } from './api';
+import { ReadonlySignal } from './signal';
+import { CategoryDef, 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 _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, _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

@@ -0,0 +1,38 @@
+/**
+ * Minimal framework-agnostic reactive primitives for the Cue SDK.
+ *
+ * No external dependencies. Angular consumers bridge to Angular signals via
+ * `effect(() => { angularSig.set(sdkSig.get()); sdkSig.subscribe(...) })`.
+ */
+/** 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;
+};

package/lib/signup.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Error thrown by unauthenticated sign-up requests. Carries the HTTP status
+ * and, when the backend provides one, a machine-readable `code`
+ * (e.g. 'emailExists' | 'domainClaimed' | 'domainBlocked').
+ */
+export declare class CueRequestError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+export type OrgSignUpPlan = {
+    type: 'freemium';
+} | {
+    type: 'custom';
+    monthlySpendChf: number;
+    paymentMethod?: 'card' | 'invoice';
+};
+export interface OrgSignUpPayload {
+    /** Display name of the new admin user. */
+    name: string;
+    /** The organization domain is extracted from this address server-side. */
+    email: string;
+    orgName: string;
+    /** When provided, the account is created with this password and no
+     * password-reset email is sent — the admin can sign in immediately. */
+    password?: string;
+    /** Version of the terms accepted client-side — recorded immediately so the
+     * admin isn't asked again on their next sign-in. */
+    termsVersion?: string;
+    plan: OrgSignUpPlan;
+}
+/**
+ * Unauthenticated account-creation calls — create a Firebase user (and,
+ * for `signUpWithOrganization`, a new organisation) before any session
+ * exists. Kept separate from `CueAuth`, which manages an *existing* session
+ * (sign in/out, tokens, superadmin checks).
+ */
+export declare class CueSignUp {
+    private readonly _gatewayUrl;
+    constructor(_gatewayUrl: string);
+    /**
+     * Register a new user by name and email.
+     * The backend validates that the email domain belongs to an existing organisation,
+     * creates the Firebase Auth account, assigns org membership, and — when no
+     * `password` is given — dispatches a "set your password" email to the
+     * address provided. `termsVersion`, when given, is recorded as accepted
+     * immediately so the user isn't asked again on their next sign-in.
+     * Returns the new user's UID and the organisation name on success.
+     */
+    signUp(name: string, email: string, password?: string, termsVersion?: string): Promise<{
+        uid: string;
+        orgName: string;
+    }>;
+    /**
+     * Self-service sign-up that creates a new organisation together with its
+     * first (admin) user — for users whose email domain matches no existing
+     * organisation. The backend records the selected plan, seeds the freemium
+     * credit grant, and dispatches verification + "set your password" emails.
+     * Throws `CueRequestError` with `code` 'emailExists' | 'domainClaimed' |
+     * 'domainBlocked' for the mappable failure modes.
+     */
+    signUpWithOrganization(payload: OrgSignUpPayload): Promise<{
+        uid: string;
+        orgId: string;
+        orgName: string;
+        checkoutUrl?: string;
+    }>;
+    /** Re-send the verification + set-password emails after a sign-up. */
+    resendSignUpEmails(email: string): Promise<{
+        sent: boolean;
+    }>;
+    private _publicPost;
+}

package/lib/storage.d.ts

@@ -0,0 +1,52 @@
+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>;
+}