@qaecy/cue-sdk 0.0.35 → 0.0.38

package/lib/models.d.ts

@@ -1,4 +1,5 @@
 import { SupportedCurrency } from './currency';
+import { ComparisonResult } from 'js-sync-tools';
 export type CueEnvironment = 'production' | 'emulator';
 export interface CueEndpoints {
     /** API gateway base URL */
@@ -35,6 +36,28 @@ export interface PasswordCredentials {
     email: string;
     password: string;
 }
+/** A supported 3rd-party DMS sync provider (e.g. ThinkProject). */
+export interface DmsProviderInfo {
+    id: string;
+    label: string;
+}
+/** A file found in a 3rd-party DMS, as returned by a preview/dry-run sync. */
+export interface DmsRemoteFile {
+    relativePath: string;
+    size: number;
+    /** Content checksum (e.g. md5), if the provider's listing exposes one. */
+    checksum?: string;
+    /** Opaque id used to fetch this file's bytes when confirming the sync. */
+    externalFileId: string;
+    modifiedAt?: string;
+}
+/** Result of previewing a DMS sync — the delta to show the user for confirmation. */
+export interface DmsSyncPreviewResponse {
+    providerId: string;
+    filesToSync: DmsRemoteFile[];
+    filesAlreadySynced: DmsRemoteFile[];
+    totalRemoteCount: number;
+}
 export interface SearchRequest {
     /** Natural language query or search term */
     term: string;
@@ -105,6 +128,17 @@ export interface ProjectSettings {
     /** Processing tier determining credit costs. Defaults to "l" if not set. */
     tier?: 's' | 'm' | 'l';
 }
+/** One daily snapshot in `QleverStats.history` — a calendar day this index's stats were (re)computed. */
+export interface QleverStatsHistoryEntry {
+    /** UTC calendar day, `YYYY-MM-DD`. */
+    date: string;
+    numDocuments: number | null;
+    numTriples: number | null;
+    numSubjects: number | null;
+    numPredicates: number | null;
+    numObjects: number | null;
+    indexSizeBytes: number | null;
+}
 export interface QleverStats {
     /** ISO timestamp of when this index was first created (init or clone) — null for indexes built before this field existed. */
     created: string | null;
@@ -125,6 +159,8 @@ export interface QleverStats {
     /** Percentage of entity mentions that are resolved: (resolved / total) * 100 */
     resolutionPct: number | null;
     avgEntitiesPerDoc: number | null;
+    /** One entry per calendar day this index's stats were (re)computed, oldest first. Frozen while the index is idled. */
+    history: QleverStatsHistoryEntry[];
 }
 export interface ProjectData {
     id: string;
@@ -138,6 +174,9 @@ export interface ProjectData {
     alternativeIDs: string[];
     projectSettings: ProjectSettings;
     qleverStats?: QleverStats | null;
+    /** Set by a superadmin's soft delete — the project doc, index, and storage remain intact. */
+    deleted?: boolean;
+    deletedAt?: string | null;
 }
 export interface CreateProjectOptions {
     /** The organization this project belongs to */
@@ -157,6 +196,18 @@ export interface CreateProjectOptions {
     /** Processing tier determining credit costs. */
     tier?: 's' | 'm' | 'l';
 }
+export interface ProjectLocation {
+    lat: number;
+    lng: number;
+}
+/**
+ * Portal-only project metadata (currently just an optional map location) —
+ * deliberately kept off `ProjectData`/Firestore, stored as its own small blob
+ * instead (see `CueProjects.getProjectMetadata`/`setProjectMetadata`).
+ */
+export interface ProjectMetadata {
+    location?: ProjectLocation | null;
+}
 export interface SyncProgress {
     percent: number;
     syncCount: number;
@@ -254,6 +305,8 @@ export interface SyncPreview {
     filesToUpload: number;
     /** Total local files scanned */
     totalLocalFiles: number;
+    /** Full local/remote comparison — file lists, path-only mismatches, sync stats */
+    report: ComparisonResult;
 }
 export interface SyncResult {
     /** Number of files successfully synced in this run */
@@ -284,7 +337,153 @@ export interface OrganizationData {
     admins: string[];
     members: string[];
     alternativeIDs: string[];
-    domain: string;
+    domains: string[];
+}
+/** One organisation matched by `CueAdmin.searchOrganizations`. */
+export interface AdminOrgSearchResult {
+    id: string;
+    name: string;
+    created: string | null;
+    adminCount: number;
+    /** Admins and members deduplicated — an admin is also counted as a member. */
+    memberCount: number;
+    planType: 'freemium' | 'custom';
+    planStatus: 'active' | 'pendingPayment' | 'cancelled';
+}
+/** One user matched by `CueAdmin.searchUsers`, or listed by `listSuperadmins`. */
+export interface AdminUserSearchResult {
+    uid: string;
+    name: string;
+    email: string;
+}
+/** One project matched by `CueAdmin.searchProjects`, with its owning org resolved. */
+export interface AdminProjectSearchResult {
+    id: string;
+    name: string;
+    organizationID: string;
+    orgName: string;
+    created: string | null;
+    /** Admins, syncers and members deduplicated. */
+    memberCount: number;
+    /** Set when a superadmin has soft-deleted this project. */
+    deleted: boolean;
+}
+/** An organisation the looked-up user belongs to. */
+export interface AdminUserOrgSummary {
+    id: string;
+    name: string;
+    isAdmin: boolean;
+}
+/** A project the looked-up user belongs to, with the highest role they hold on it. */
+export interface AdminUserProjectSummary {
+    id: string;
+    name: string;
+    organizationID: string;
+    /** Falls back to `organizationID` when the org couldn't be resolved (guest access). */
+    orgName: string;
+    role: 'admin' | 'syncer' | 'member';
+}
+/**
+ * Full profile for one user, from `CueAdmin.getUserDetail`. Auth-record fields
+ * (`disabled`, `created`, `providers`, …) fall back to defaults when the
+ * Firestore user doc has outlived its Firebase Auth user.
+ */
+export interface AdminUserDetail {
+    uid: string;
+    name: string;
+    email: string;
+    isSuperadmin: boolean;
+    disabled: boolean;
+    emailVerified: boolean;
+    created: string | null;
+    lastSignIn: string | null;
+    providers: string[];
+    organizations: AdminUserOrgSummary[];
+    projects: AdminUserProjectSummary[];
+}
+/** An org the deleted user belonged to, captured at delete time — see {@link AdminDeletedUserSummary}. */
+export interface AdminDeletedUserOrgRef {
+    orgId: string;
+    orgName: string;
+    role: 'admin' | 'member';
+}
+/** A project the deleted user belonged to, captured at delete time — see {@link AdminDeletedUserSummary}. */
+export interface AdminDeletedUserProjectRef {
+    projectId: string;
+    projectName: string;
+    organizationID: string;
+    role: 'admin' | 'syncer' | 'member';
+}
+/**
+ * One archived deletion, from `CueAdmin.listDeletedUsers`. `restoredAt` is set
+ * once a superadmin has restored the account — the record is kept either way
+ * as an audit trail.
+ */
+export interface AdminDeletedUserSummary {
+    uid: string;
+    name: string;
+    email: string;
+    isSuperadmin: boolean;
+    deletedAt: string;
+    deletedBy: string;
+    orgs: AdminDeletedUserOrgRef[];
+    projects: AdminDeletedUserProjectRef[];
+    restoredAt?: string;
+    restoredBy?: string;
+}
+/** Result of `CueAdmin.restoreUser` — orgs/projects that no longer exist and so couldn't be re-granted. */
+export interface AdminRestoreUserResult {
+    skippedOrgs: string[];
+    skippedProjects: string[];
+}
+/** Result of `CueAdmin.createOrganization`. */
+export interface AdminOrganization {
+    id: string;
+    name: string;
+    created: string;
+    admins: string[];
+    members: string[];
+    domains: string[];
+}
+/**
+ * One archived org deletion, from `CueAdmin.listDeletedOrganizations`. Unlike a
+ * deleted user, the org doc itself is never removed — it stays in Firestore
+ * flagged `deleted`, with `admins`/`members` intact as the relationship
+ * snapshot a restore re-grants.
+ */
+export interface AdminDeletedOrganizationSummary {
+    id: string;
+    name: string;
+    deletedAt: string;
+    deletedBy: string;
+    /** Members who had no other org membership at delete time, so were soft-deleted along with the org. */
+    cascadeDeletedUserIds: string[];
+    /** Projects under the org that were soft-deleted along with it. */
+    cascadeDeletedProjectIds: string[];
+}
+/** Result of `CueAdmin.restoreOrganization` — ids that couldn't be re-granted (already independently deleted/restored). */
+export interface AdminRestoreOrganizationResult {
+    restoredProjectIds: string[];
+    skippedProjectIds: string[];
+    restoredUserIds: string[];
+    skippedUserIds: string[];
+}
+/** A user with no organisation (`listUsersWithoutOrg`) or no project (`listUsersWithoutProject`) membership. */
+export interface AdminOrphanedUser {
+    uid: string;
+    name: string;
+    email: string;
+}
+/** A project with no members/syncers/admins (`listProjectsWithoutUsers`) or specifically no admin (`listProjectsWithoutAdmins`). */
+export interface AdminOrphanedProject {
+    id: string;
+    name: string;
+    organizationID: string;
+}
+/** An organisation with no members (`listOrgsWithoutUsers`) or specifically no admin (`listOrgsWithoutAdmins`). */
+export interface AdminOrphanedOrganization {
+    id: string;
+    name: string;
 }
 /** Org's current plan — no Stripe ids exposed to the frontend. */
 export interface OrgPlanSummary {
@@ -322,6 +521,62 @@ export interface ProjectConsumptionReportDto {
 export interface OrgConsumptionReportDto {
     projects: ProjectConsumptionReportDto[];
 }
+/** Consumption for one raw-file extension (lowercased, no leading dot; `'unknown'` if a file had none). */
+export interface FileTypeConsumptionDto {
+    unitsConsumed: number;
+    creditsConsumed: number;
+    filesProcessed: number;
+}
+/** Per-file-extension breakdown for one project within a given period — see {@link CueProfile.getProjectFileTypeBreakdown}. */
+export type FileTypeBreakdownDto = Record<string, FileTypeConsumptionDto>;
+/** Requests through one gateway route on one day/month. */
+export interface RouteTrafficDto {
+    route: string;
+    count: number;
+    avgLatencyMs: number;
+    /** Keyed by HTTP status code as a string, e.g. `{ '200': 5120, '404': 3 }`. */
+    statusCounts: Record<string, number>;
+}
+export interface DayTrafficDto {
+    /** `YYYY-MM-DD` (UTC). */
+    day: string;
+    routes: RouteTrafficDto[];
+}
+export interface MonthTrafficDto {
+    /** `YYYY-MM` (UTC). */
+    month: string;
+    routes: RouteTrafficDto[];
+}
+/** Gateway traffic for one project — see {@link CueProfile.getProjectTrafficReport}. */
+export interface TrafficReportDto {
+    days: DayTrafficDto[];
+    /** Rolled-up totals for months entirely outside the day-level retention window. */
+    months: MonthTrafficDto[];
+}
+/** Opens of one portal view on one day/month. */
+export interface ViewUsageDto {
+    /** Route path template, e.g. `projects/:id/files` — never a resolved URL. */
+    view: string;
+    count: number;
+    /** Opens keyed by user id. */
+    byUser: Record<string, number>;
+}
+export interface DayUsageDto {
+    /** `YYYY-MM-DD` (UTC). */
+    day: string;
+    views: ViewUsageDto[];
+}
+export interface MonthUsageDto {
+    /** `YYYY-MM` (UTC). */
+    month: string;
+    views: ViewUsageDto[];
+}
+/** Portal view opens for one project — see {@link CueProfile.getProjectUsageReport}. */
+export interface UsageReportDto {
+    days: DayUsageDto[];
+    /** Rolled-up totals for months entirely outside the day-level retention window. */
+    months: MonthUsageDto[];
+}
 export interface ProfileSSOAccount {
     id: string;
     label: string;
@@ -409,12 +664,105 @@ export interface RDFWritingDoc {
     firstRDFWrite: string;
     lastRDFWrite: string;
 }
-export type ProcessingStage = 'idle' | 'writing' | 'loading' | 'enriching';
+/**
+ * `processing` covers the upload→artifact window: a file has been uploaded and a
+ * processor is working on it, but no `.ttl` exists yet so none of the RDF
+ * write/load/resolution tracking has begun. It is the *lowest*-precedence stage,
+ * so a project already committing RDF never appears to fall back to it.
+ */
+export type ProcessingStage = 'idle' | 'processing' | 'writing' | 'loading' | 'enriching';
+/**
+ * Lifecycle of a single uploaded document.
+ *
+ * - `uploaded`   — in storage, no processor output yet
+ * - `processing` — a processor has emitted artifacts (markdown, images, fragments)
+ * - `extracting` — RDF exists but is not all committed to the ledger
+ * - `stored`     — every `.ttl` produced so far is committed
+ * - `failed`     — processing errored
+ *
+ * `stored` is not strictly final: an enricher producing further RDF later moves
+ * the document back to `extracting`, which is a faithful description of reality
+ * rather than a bug.
+ */
+export type DocumentProcessingStage = 'uploaded' | 'processing' | 'extracting' | 'stored' | 'failed';
+/** Per-document pipeline progress for one uploaded file. */
+export interface DocumentProgress {
+    documentUUID: string;
+    /** Original upload name, e.g. `Rotated_wall.ifc`. */
+    fileName: string;
+    suffix: string;
+    sizeBytes: number;
+    stage: DocumentProcessingStage;
+    uploadedAt: string;
+    updatedAt: string;
+    finishedAt?: string;
+    /**
+     * Services that have produced output for this document, in first-seen order
+     * (e.g. `['processors-bim-files', 'enrichers-semantic-extraction']`). This is
+     * what lets the UI say *which step* a file is on.
+     */
+    contributors: string[];
+    rdfCount: number;
+    rdfStoredCount: number;
+    error?: string;
+}
+/** Counts-only per-project rollup, streamed by {@link CueProcessingApi.watchMyStatus}. */
+export interface ProjectProcessingSummary {
+    projectId: string;
+    stage: ProcessingStage;
+    pendingDocumentCount: number;
+    failedDocumentCount: number;
+    lastActivityAt?: string;
+}
+/**
+ * Cross-project processing rollup for every project the signed-in user belongs
+ * to — backs a global "still working" indicator such as a badge on the header's
+ * project selector, which must keep updating after any per-project view closes.
+ */
+export interface MyProcessingStatus {
+    projects: ProjectProcessingSummary[];
+    /** Sum of `pendingDocumentCount` across `projects`. */
+    totalPendingDocumentCount: number;
+    /**
+     * True when the user belongs to more projects than the server watches on one
+     * connection, so the totals cover only the watched subset. Render the count as
+     * approximate (e.g. `99+`) when set.
+     */
+    truncated?: boolean;
+}
+/** Lifecycle of a superadmin document-reprocess request. */
+export type ReprocessJobStatus = 'queued' | 'purging-rdf' | 'purging-blobs' | 'publishing' | 'succeeded' | 'failed';
+/**
+ * Progress of one document reprocess (`POST /commands/document/:uuid/reprocess`),
+ * pushed on the same socket as the rest of the pipeline status.
+ */
+export interface DocumentReprocessJob {
+    processId: string;
+    /** Project id — named `space_id` to match the pipeline's Firestore convention. */
+    space_id: string;
+    documentUUID: string;
+    requestedBy: string;
+    requestedAt: string;
+    status: ReprocessJobStatus;
+    /** Named graphs that were resolved for the document and retracted. */
+    graphs?: string[];
+    quadsRetracted?: number;
+    blobsDeleted?: number;
+    publishedTopics?: string[];
+    /** Sub-steps requested but not run (e.g. `retrigger` unreachable). */
+    skipped?: string[];
+    error?: string;
+    finishedAt?: string;
+}
 /**
  * Aggregated, per-project pipeline status pushed live by the `accessors-data-views`
  * processing-status WebSocket (see `CueProcessingApi.watchStatus`). Shape mirrors
  * `cue-ui`'s `ProcessingStatus` (views/project-settings/models.ts) so it can be
  * passed straight through to `<cue-project-settings>` / `<cue-portal-upload>`.
+ *
+ * `reprocessJobs` is the one field cue-ui does not mirror — it is only consumed by
+ * cue-portal's resource viewer, and an extra property stays assignable to cue-ui's
+ * narrower interface.
  */
 export interface ProcessingStatus {
     stage: ProcessingStage;
@@ -427,6 +775,27 @@ export interface ProcessingStatus {
     lastResolutionActivityAt?: string;
     enrichmentTotalBatches?: number;
     enrichmentCompletedBatches?: number;
+    /** Canonical-resolver's own per-category dedup progress, separate from mention-resolver's batches above. */
+    canonicalResolutionCategoriesTotal?: number;
+    canonicalResolutionCategoriesCompleted?: number;
+    /** Document reprocess jobs for this project, most recently requested first. */
+    reprocessJobs?: DocumentReprocessJob[];
+    /**
+     * Per-document progress, newest upload first. Bounded server-side, so treat
+     * this as "the recent ones" and rely on the counts below for totals.
+     */
+    documents?: DocumentProgress[];
+    /**
+     * Documents not yet in a terminal stage. Exact even when `documents` was
+     * truncated. Optional because a client may be talking to a data-views
+     * deployment predating per-document tracking, which omits it — treat absent as
+     * "unknown", not zero.
+     */
+    pendingDocumentCount?: number;
+    /** Documents whose processing failed. Exact. Absent on older servers. */
+    failedDocumentCount?: number;
+    /** True when `documents` was capped server-side; the counts stay exact. */
+    documentsTruncated?: boolean;
 }
 export interface ViewDefinition {
     id: string;

package/lib/privileges.d.ts

@@ -16,13 +16,17 @@ export interface Privileges {
     editContentCategories: boolean;
     editPublicReposAvailableToAgent: boolean;
     editTier: boolean;
+    hardDeleteProject: boolean;
     inviteUserToProject: boolean;
     rebuildIndex: boolean;
     refreshStats: boolean;
     renameDocuments: boolean;
+    restoreProject: boolean;
+    softDeleteProject: boolean;
     uploadDocuments: boolean;
     viewAdvancedStats: boolean;
     viewCredits: boolean;
+    viewUsageStats: boolean;
     viewEntities: boolean;
 }
 /**

package/lib/processing.d.ts

@@ -1,16 +1,22 @@
 import { CueAuth } from './auth';
 import { ReadonlySignal } from './signal';
-import { ProcessingStatus } from './models';
+import { MyProcessingStatus, 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;
 }
+export interface MyProcessingStatusWatcher {
+    /** Live cross-project rollup; `undefined` until the first message arrives. */
+    status: ReadonlySignal<MyProcessingStatus | 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.
+ * processing-status WebSockets. Backs the upload modal, the project-settings
+ * "processing" indicators, and the header's cross-project badge.
  */
 export declare class CueProcessingApi {
     private readonly _auth;
@@ -22,4 +28,24 @@ export declare class CueProcessingApi {
      * is called.
      */
     watchStatus(projectId: string): ProcessingStatusWatcher;
+    /**
+     * Opens a live subscription to the signed-in user's cross-project processing
+     * rollup — every project they belong to, as counts.
+     *
+     * Intended to be opened **once at app-shell level** and kept for the session:
+     * it is what lets a header badge keep counting while no project view is open.
+     * Unlike {@link watchStatus} it takes no projectId — the server resolves
+     * memberships from the authenticated identity.
+     *
+     * Membership is resolved at connect time, so a project created or shared with
+     * the user mid-session appears after a reconnect rather than immediately.
+     */
+    watchMyStatus(): MyProcessingStatusWatcher;
+    /**
+     * Shared socket lifecycle: token fetch, connect, JSON parse, auto-reconnect.
+     *
+     * `params` are appended alongside the auth token. The token has to ride in the
+     * query string because browsers cannot set headers on a WebSocket handshake.
+     */
+    private _open;
 }

package/lib/profile.d.ts

@@ -1,6 +1,6 @@
 import { UserInfo } from 'firebase/auth';
 import { FirebaseApp } from 'firebase/app';
-import { APIKeyDoc, APIKeyInfo, OrgConsumptionReportDto, OrgCreditsDto, OrgMember, OrganizationData, ProfileSSOAccount } from './models';
+import { APIKeyDoc, APIKeyInfo, FileTypeBreakdownDto, OrgConsumptionReportDto, OrgCreditsDto, OrgMember, OrganizationData, ProfileSSOAccount, TrafficReportDto, UsageReportDto } from './models';
 import { CueAuth } from './auth';
 import { ReadonlySignal } from './signal';
 export declare class CueProfile {
@@ -50,6 +50,8 @@ export declare class CueProfile {
     })[]>;
     /** Returns all members of the given organisation. Caller must be an org admin or superadmin. */
     getOrgMembers(orgId: string): Promise<OrgMember[]>;
+    /** Returns just the given organisation's admins. Caller must be a member (or admin/superadmin). */
+    getOrgAdmins(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;
@@ -64,16 +66,51 @@ export declare class CueProfile {
      * 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.
+     *
+     * The backend serves this from a short-lived cache, because computing it
+     * scans storage once per project in the org. Pass `{ refresh: true }` when the
+     * figure must be exact — before spending credits, or right after an upload —
+     * and accept that the call then takes as long as the computation does.
      */
-    getOrgCredits(orgId: string): Promise<OrgCreditsDto>;
+    getOrgCredits(orgId: string, opts?: {
+        refresh?: boolean;
+    }): 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>;
+    /**
+     * Per-file-extension credit/unit breakdown for one project within `[from, to)` (UTC ISO 8601,
+     * `to` exclusive) — for a report drill-down (e.g. a monthly/yearly PDF export), not the
+     * regular monthly totals (use {@link getOrgConsumptionReport} for those). The backend
+     * recomputes this on every call by re-scanning the project's raw files — only call it when
+     * the user actually asks for a report, not on every page load. Caller must be an org admin
+     * or superadmin.
+     */
+    getProjectFileTypeBreakdown(orgId: string, projectId: string, from: string, to: string): Promise<FileTypeBreakdownDto>;
+    /**
+     * Gateway traffic for one project within `[from, to)` (UTC `YYYY-MM-DD`, `to`
+     * exclusive). Superadmin-facing; caller must be an org admin or superadmin.
+     *
+     * Reads a stored aggregate rather than recomputing, so it is cheap — but it is
+     * still a round trip per call, so fetch it when the user asks for it, not on
+     * every page load.
+     */
+    getProjectTrafficReport(orgId: string, projectId: string, from?: string, to?: string): Promise<TrafficReportDto>;
+    /**
+     * Portal view opens for one project within `[from, to)` (UTC `YYYY-MM-DD`, `to`
+     * exclusive) — the counterpart to {@link getProjectTrafficReport}, recorded by
+     * the frontend rather than the gateway. Same authorization and cost profile.
+     */
+    getProjectUsageReport(orgId: string, projectId: string, from?: string, to?: string): Promise<UsageReportDto>;
+    /** `?from=…&to=…`, or `''` when unbounded — the backend treats missing bounds as "everything". */
+    private _rangeQuery;
     /** 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>;
+    /** Manual/support credit withdrawal from an organisation's shared pool (e.g. correcting an over-grant). Superadmins only. */
+    withdrawOrgCredits(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
@@ -125,4 +162,18 @@ export declare class CueProfile {
      * force-refreshed token to see the updated value.
      */
     latestTermsAccepted(): Promise<string | null>;
+    /**
+     * Record that the current user has been shown (and dismissed) the usage-analytics
+     * notice. Sets an `analyticsNotice` custom claim on the token — independent of
+     * `terms`, since this is a lightweight acknowledgement, not a blocking agreement.
+     */
+    acceptAnalyticsNotice(version: string): Promise<void>;
+    /**
+     * Returns the analytics-notice version the current user has acknowledged (e.g.
+     * `"v1"`), or `null` if they haven't yet. Reads from the cached ID token — call
+     * after `acceptAnalyticsNotice()` with a force-refreshed token to see the update
+     * within the same session (not required if you just hide the banner locally on
+     * dismiss, since this only needs to be correct on the *next* sign-in).
+     */
+    latestAnalyticsNoticeAccepted(): Promise<string | null>;
 }

package/lib/project.d.ts

@@ -1,12 +1,11 @@
 import { FirebaseApp } from 'firebase/app';
 import { CueAuth } from './auth';
-import { CreateProjectOptions, CueEndpoints, ProjectData } from './models';
+import { CreateProjectOptions, CueEndpoints, ProjectData, ProjectMetadata } 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;
     /**
@@ -38,7 +37,9 @@ export declare class CueProjects {
      */
     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.
+     * Invite a user to a project by email. Returns the invited user's uid.
+     * Throws if no account exists yet for that email — the gateway route supports
+     * a pending-invitation flow for that case, but no client surfaces it yet.
      */
     inviteUserToProject(email: string, projectId: string, role: ProjectRole): Promise<{
         uid: string;
@@ -50,7 +51,23 @@ export declare class CueProjects {
     removeUserFromProject(uid: string, projectId: string): Promise<void>;
     /**
      * Delete a project by ID. Requires superadmin privileges on the server.
+     * Soft delete (default) flags the project as deleted, hiding it from listings
+     * while leaving its data, index, and storage intact. Hard delete permanently
+     * drops the graph index, the Firestore document, and the project's storage.
      */
-    deleteProject(projectId: string): Promise<void>;
+    deleteProject(projectId: string, hard?: boolean): Promise<void>;
+    /**
+     * Restore a soft-deleted project by ID. Requires superadmin privileges on the server.
+     * Resolves with a server-provided status message.
+     */
+    restoreProject(projectId: string): Promise<string>;
+    /**
+     * Reads a project's portal-only metadata (currently just an optional map
+     * location) — kept off `ProjectData` on purpose, see {@link ProjectMetadata}.
+     * Returns `{}` if none has been set yet.
+     */
+    getProjectMetadata(projectId: string): Promise<ProjectMetadata>;
+    /** Sets a project's portal-only metadata. Omit a field to leave it untouched, `null` to clear it. */
+    setProjectMetadata(projectId: string, metadata: ProjectMetadata): Promise<void>;
 }
 export {};

package/lib/usage-stats.d.ts

@@ -0,0 +1,19 @@
+import { CueAuth } from './auth';
+/**
+ * Records portal view-opens for usage reporting (per-user, per-view, per-project) —
+ * fed into the same GCS-aggregate pipeline as gateway traffic tracking, but written
+ * by the frontend directly instead of Kong's `http-log` plugin. See
+ * apps/writers/commands/src/app/admin/usage/usage-ingest.service.ts.
+ */
+export declare class CueUsageStats {
+    private readonly _auth;
+    private readonly _gatewayUrl;
+    constructor(_auth: CueAuth, _gatewayUrl: string);
+    /**
+     * Fire-and-forget: records that the current user opened `view` (a route path
+     * template, e.g. `projects/:id/files` — never a literal resolved URL/resource id),
+     * optionally scoped to `projectId`. Never throws — an analytics call must not
+     * break navigation; failures are only logged.
+     */
+    recordView(view: string, projectId?: string): void;
+}