@qaecy/cue-sdk 0.0.53 → 0.0.55

package/lib/models.d.ts

@@ -1,5 +1,6 @@
 import { SupportedCurrency } from './currency';
 import { ComparisonResult } from '../../sync-tools/src/index';
+import { BlobBucket, BlobDriverKind } from '../../databases/src/index';
 export type CueEnvironment = 'production' | 'emulator';
 export interface CueEndpoints {
     /** API gateway base URL */
@@ -26,6 +27,18 @@ export interface CueSdkConfig {
     endpoints?: Partial<CueEndpoints>;
     /** Enable verbose debug logging for all entity/document store operations. */
     verbose?: boolean;
+    /** How the SDK reaches object storage. Defaults to Firebase Storage for every bucket. */
+    storage?: CueStorageConfig;
+}
+export interface CueStorageConfig {
+    /**
+     * Per-bucket driver. `firebase` (the default) uses Firebase Storage and its
+     * security rules; `gateway` uses the gateway's `/bff/storage` endpoints,
+     * which work on any backend the deployment runs (GCS, MinIO, S3).
+     */
+    drivers?: Partial<Record<BlobBucket, BlobDriverKind>>;
+    /** Firebase Storage bucket names, for buckets on the `firebase` driver. */
+    buckets?: Partial<Record<BlobBucket, string>>;
 }
 export type SsoProvider = 'google' | 'microsoft';
 export interface PasswordCredentials {
@@ -167,7 +180,7 @@ export interface ProjectSettings {
      * Absent means English only, which is what every project resolved to before
      * this field existed.
      *
-     * Read by `writers-commands` (stamped onto `ProjectSchema.languages` on every
+     * Read by `writers-cue-bff` (stamped onto `ProjectSchema.languages` on every
      * schema write), the schema-suggestion endpoint (which languages a proposed
      * term is translated into), and the translation enricher (its targets, minus
      * the pivot).
@@ -244,6 +257,35 @@ export interface ProjectData {
     /** Set by a superadmin's soft delete — the project doc, index, and storage remain intact. */
     deleted?: boolean;
     deletedAt?: string | null;
+    /** Who owned the project when — absent until the first transfer (see `CueAdmin.transferProject`). */
+    ownershipHistory?: ProjectOwnershipPeriod[];
+    /** Orgs that owned the project before; their earlier consumption stays on their balance. */
+    formerOrganizationIDs?: string[];
+}
+/** One stretch of ownership, running from `from` until the next period's `from`. */
+export interface ProjectOwnershipPeriod {
+    organizationID: string;
+    from: string;
+    transferId?: string;
+    transferredBy?: string;
+    /** Credits moved from the previous owner as part of the transfer (0 = none). */
+    creditTransfer?: number;
+}
+/** Body of `CueAdmin.transferProject`. */
+export interface TransferProjectRequest {
+    organizationID: string;
+    /** The owner the caller saw — the server answers 409 if it has changed since. */
+    expectedCurrentOrganizationID: string;
+    /** Credits to move from the current owner to the new one; required, 0 = none. */
+    creditTransfer: number;
+    /** Client-generated UUID. Repeat it to retry a failed credit transfer. */
+    transferId: string;
+}
+/** `creditTransferFailed` means the project moved but its credits did not — retry with the same `transferId`. */
+export interface TransferProjectResult {
+    project: ProjectData;
+    creditTransferFailed: boolean;
+    creditTransferError?: string;
 }
 export interface CreateProjectOptions {
     /** The organization this project belongs to */
@@ -577,6 +619,10 @@ export interface OrgCreditsDto {
     available: number;
     plan: OrgPlanSummary;
 }
+/** An {@link OrgCreditsDto} tagged with the org it was fetched for — what `CueProfile.orgCredits` holds. */
+export interface OrgCredits extends OrgCreditsDto {
+    orgId: string;
+}
 /** Consumption for a single calendar month (`YYYY-MM`, UTC), keyed by the file's own upload time. */
 export interface MonthlyConsumptionDto {
     unitsConsumed: number;
@@ -588,6 +634,12 @@ export interface ProjectConsumptionReportDto {
     name?: string;
     /** Keyed by `YYYY-MM` (UTC). */
     monthly: Record<string, MonthlyConsumptionDto>;
+    /** Set when the org handed the project to another org; `monthly` then covers only its own ownership. */
+    transferredTo?: {
+        organizationID: string;
+        name?: string;
+        at: string;
+    };
 }
 /** Per-project, per-month consumption breakdown for an org — see {@link OrgCreditsDto} for the org-level totals. */
 export interface OrgConsumptionReportDto {
@@ -705,6 +757,8 @@ export interface CustomAppRecord {
     tone: string;
     authorId: string;
     authorName: string;
+    /** Set on a copy made into another organization via `cue.api.apps.copy` — the id of the original. */
+    copiedFrom?: string;
     createdAt: string;
     updatedAt: string;
 }
@@ -737,10 +791,10 @@ export interface RDFWritingDoc {
     lastRDFWrite: string;
 }
 /**
- * `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.
+ * The project's stage, derived from its documents: `processing` while any
+ * document is on its way to `stored`, `enriching` while resolution runs. The
+ * detail is in `documentCounts`. `writing` and `loading` are no longer emitted
+ * by current servers.
  */
 export type ProcessingStage = 'idle' | 'processing' | 'writing' | 'loading' | 'enriching';
 /**
@@ -748,15 +802,17 @@ export type ProcessingStage = 'idle' | 'processing' | 'writing' | 'loading' | 'e
  *
  * - `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
+ * - `extracting` — processing or extraction outstanding, or its RDF not yet bundled
+ * - `stored`     — done through extraction, and every `.ttl` produced so far is bundled
  * - `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.
+ * Partial problems (a page whose extraction failed) do not fail the document;
+ * they are listed in `gaps`. `stored` is not strictly final: RDF arriving later
+ * moves the document back to `extracting` until it is bundled too.
  */
 export type DocumentProcessingStage = 'uploaded' | 'processing' | 'extracting' | 'stored' | 'failed';
+/** How many of a project's documents are in each stage. */
+export type DocumentStageCounts = Record<DocumentProcessingStage, number>;
 /** Per-document pipeline progress for one uploaded file. */
 export interface DocumentProgress {
     documentUUID: string;
@@ -776,12 +832,16 @@ export interface DocumentProgress {
     contributors: string[];
     rdfCount: number;
     rdfStoredCount: number;
+    /** What was missing when the document went ready, e.g. `extraction failed: 2`. */
+    gaps?: string[];
     error?: string;
 }
 /** Counts-only per-project rollup, streamed by {@link CueProcessingApi.watchMyStatus}. */
 export interface ProjectProcessingSummary {
     projectId: string;
     stage: ProcessingStage;
+    /** Absent on older servers. */
+    documentCounts?: DocumentStageCounts;
     pendingDocumentCount: number;
     failedDocumentCount: number;
     lastActivityAt?: string;
@@ -802,10 +862,98 @@ export interface MyProcessingStatus {
      */
     truncated?: boolean;
 }
+/** Options for `CueApi.reprocessDocument` — mirrors the service's `ReprocessDocumentDto`. */
+export interface ReprocessDocumentOptions {
+    removeGraphs?: boolean;
+    removeProcessed?: boolean;
+    /** Publish even when the raw blob carries `skip_processing` (does not clear the flag). */
+    force?: boolean;
+    resetAttempts?: boolean;
+    dryRun?: boolean;
+}
+/** 202 body: the reprocess is running, follow `processId` on the status socket. */
+export interface ReprocessAccepted {
+    processId: string;
+    projectId: string;
+    documentUUID: string;
+    status: string;
+}
+/** 200 body for a `dryRun` request — what a real run would purge. */
+export interface ReprocessPlan {
+    dryRun: true;
+    projectId: string;
+    documentUUID: string;
+    graphs: string[];
+    quads: number;
+    blobs: string[];
+    rawBlobPresent: boolean;
+    /**
+     * Count of this document's mentions already resolved into a canonical entity
+     * elsewhere in the project — purging leaves that entity's link dangling until
+     * the pipeline re-resolves the same text.
+     */
+    resolvedMentionsAtRisk: number;
+}
+export declare const isReprocessPlan: (r: ReprocessAccepted | ReprocessPlan) => r is ReprocessPlan;
+/** One entity mention to create — mirrors the service's `CreateEntityMentionDto`. */
+export interface EntityMentionInput {
+    mention: {
+        iri: string;
+        value: string;
+        entityCategories: string[];
+        description?: string | null;
+        resolvesTo?: string | null;
+        properties?: string[];
+        /** Subjects (e.g. selectors) this mention is made in. */
+        mentions?: string[];
+        relationships?: {
+            predicate: string;
+            objectIri: string;
+        }[];
+    };
+    namedGraph: string;
+    comment?: string;
+}
+/** One entity mention to delete — mirrors the service's `DeleteEntityMentionDto`. */
+export interface EntityMentionDeletion {
+    iri: string;
+    comment?: string;
+}
+/** One selector to create — mirrors the service's `CreateSelectorDto`. */
+export interface SelectorInput {
+    iri: string;
+    type: string;
+    selectorSubjects: string[];
+    selectorObject: string;
+    value: string;
+    namedGraph: string;
+    comment?: string;
+}
+/** Replaces a subject's content categories — mirrors the service's `ChangeObjectIRIRequestDto`. */
+export interface ContentCategoryChange {
+    subject: string;
+    existingValues: string[];
+    newValues: string[];
+    comment?: string;
+}
+/** Outcome of one graph edit — mirrors the service's `MutationResult`. */
+export interface EditResult {
+    message: string;
+    success: boolean;
+    insertCount?: number;
+    iri?: string;
+    errorCode?: string;
+}
+/** Outcome of a batch of graph edits — mirrors the service's `BatchMutationResult`. */
+export interface BatchEditResult {
+    results: EditResult[];
+    successCount: number;
+    failureCount: number;
+}
 /** 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`),
+ * Progress of one document reprocess (`POST /bff/document/:uuid/reprocess`),
  * pushed on the same socket as the rest of the pipeline status.
  */
 export interface DocumentReprocessJob {
@@ -827,7 +975,7 @@ export interface DocumentReprocessJob {
     finishedAt?: string;
 }
 /**
- * Aggregated, per-project pipeline status pushed live by the `accessors-data-views`
+ * Aggregated, per-project pipeline status pushed live by the `writers-cue-bff`
  * 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>`.
@@ -857,9 +1005,11 @@ export interface ProcessingStatus {
      * this as "the recent ones" and rely on the counts below for totals.
      */
     documents?: DocumentProgress[];
+    /** How many documents are in each stage. Exact. Absent on older servers. */
+    documentCounts?: DocumentStageCounts;
     /**
      * Documents not yet in a terminal stage. Exact even when `documents` was
-     * truncated. Optional because a client may be talking to a data-views
+     * truncated. Optional because a client may be talking to a writers-cue-bff
      * deployment predating per-document tracking, which omits it — treat absent as
      * "unknown", not zero.
      */

package/lib/processing.d.ts

@@ -14,7 +14,7 @@ export interface MyProcessingStatusWatcher {
     close(): void;
 }
 /**
- * Live pipeline-progress status, pushed by the `accessors-data-views`
+ * Live pipeline-progress status, pushed by `writers-cue-bff`'s
  * processing-status WebSockets. Backs the upload modal, the project-settings
  * "processing" indicators, and the header's cross-project badge.
  */

package/lib/profile.d.ts

@@ -1,7 +1,8 @@
 import { UserInfo } from 'firebase/auth';
-import { APIKeyDoc, APIKeyInfo, FileTypeBreakdownDto, OrgConsumptionReportDto, OrgCreditsDto, OrgMember, OrganizationData, ProfileSSOAccount, TrafficReportDto, UsageReportDto } from './models';
+import { APIKeyDoc, APIKeyInfo, FileTypeBreakdownDto, OrgConsumptionReportDto, OrgCredits, OrgCreditsDto, OrgMember, OrganizationData, ProfileSSOAccount, TrafficReportDto, UsageReportDto } from './models';
 import { CueAuth } from './auth';
 import { ReadonlySignal } from './signal';
+import { OrgSignUpPlan } from './signup';
 export declare class CueProfile {
     private readonly _auth;
     private readonly _gatewayUrl;
@@ -11,10 +12,12 @@ export declare class CueProfile {
      * 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
+     * re-fetching. The value carries the `orgId` it belongs to: fetches for
+     * different orgs can resolve out of order, so check it against the org on
+     * screen before showing the balance. Angular consumers bridge via
      * `effect(() => sig.set(cue.profile.orgCredits.get()))` + `.subscribe(...)`.
      */
-    readonly orgCredits: ReadonlySignal<OrgCreditsDto | undefined>;
+    readonly orgCredits: ReadonlySignal<OrgCredits | undefined>;
     constructor(_auth: CueAuth, _gatewayUrl: string);
     private _url;
     private _fetch;
@@ -46,6 +49,39 @@ export declare class CueProfile {
     listOrganizations(): Promise<(Pick<OrganizationData, 'id' | 'name'> & {
         isAdmin: boolean;
     })[]>;
+    /**
+     * Creates an organisation with the current user as its admin — for a user
+     * who belongs to none. It claims the user's email domain when that email is
+     * verified, not a free-mail provider and not claimed already; otherwise it is
+     * created without a domain. Throws `CueRequestError` with `code`
+     * 'alreadyInOrganisation' when the user already belongs to one.
+     */
+    createOwnOrganization(orgName: string, plan: OrgSignUpPlan): Promise<{
+        orgId: string;
+        orgName: string;
+        domains: string[];
+        checkoutUrl?: string;
+    }>;
+    /**
+     * Asks to join the organisation owning `domain` (e.g. `qaecy.com`); its
+     * admins get an email. Resolves the same whether or not any organisation
+     * owns the domain, so it can't be used to find out. Throws `CueRequestError`
+     * with `code` 'emailNotVerified' | 'invalidDomain'.
+     */
+    requestToJoinOrganization(domain: string): Promise<void>;
+    /**
+     * Joins the organisation owning the current user's email domain — only once
+     * that email is verified, which is why sign-up itself never joins one. Call
+     * it when a signed-in user has no organisation; `joined` is false when the
+     * email is unverified or no organisation owns the domain.
+     */
+    joinOrganizationByEmailDomain(): Promise<{
+        joined: boolean;
+        orgId?: string;
+        orgName?: string;
+    }>;
+    /** POSTs JSON and surfaces the backend's error `code`, for calls whose failures a UI maps. */
+    private _fetchCoded;
     /** 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). */

package/lib/semantic-template.d.ts

@@ -1,4 +1,4 @@
-import { EntityCategory, ProjectSchema } from '../../models/src/index';
+import { ContentCategory, EntityCategory, ProjectSchema } from '../../models/src/index';
 import { CueAuth } from './auth';
 export interface MutationResult {
     message: string;
@@ -32,6 +32,37 @@ export interface EntityRelationshipInput extends EntityCategoryInput {
     sources: string[];
     targets: string[];
 }
+/** A declared canonical's new value. Changing it changes the canonical's IRI, and everything pointing at it moves too. */
+export interface RenameCanonicalInput {
+    categoryKey: string;
+    canonicalKey: string;
+    newValue: string;
+    /** The schema revision the caller read; a stale one is refused. */
+    revision: number;
+    /** When the new value is already a canonical of the category. Defaults to `merge`. */
+    onCollision?: 'merge' | 'refuse';
+    /** Record the old value as a resolved form of the new canonical. Defaults to `false`. */
+    keepOldAsAlias?: boolean;
+    /** Report what would change and write nothing. */
+    dryRun?: boolean;
+}
+export interface RenameCanonicalResult {
+    oldIri: string;
+    newIri: string;
+    collision: boolean;
+    /** Set when the collision is with another canonical declared in the schema. */
+    collidesWithKey?: string;
+    dryRun: boolean;
+    quads: number;
+    mentions: number;
+    files: number;
+    graphs: number;
+    dataSources: number;
+    /** The saved schema's revision; absent on a dry run. */
+    revision?: number;
+    /** Follow-up steps that failed after the graph moved — running the same rename again finishes them. */
+    warnings: string[];
+}
 /**
  * One project the caller could take an existing schema from — what
  * `listSchemaSources` lists.
@@ -53,7 +84,7 @@ export interface SchemaSource {
     relations: number;
 }
 /**
- * Client for writers-commands' semantic-template CRUD endpoints — persists a
+ * Client for writers-cue-bff's semantic-template CRUD endpoints — persists a
  * project's custom extraction/classification schema (content categories,
  * entity categories, entity relationships) and reloads the project's
  * `databases-cue` schema graph after every mutation.
@@ -114,10 +145,21 @@ export declare class CueSemanticTemplate {
      * starting point — the same list for every caller, nothing project-specific about it.
      */
     getDefaultEntities(projectId: string): Promise<EntityCategory[]>;
+    /**
+     * The QAECY catalogues' content categories — the document types a term can be limited to —
+     * with pinned IRIs stripped, so each is referenced by its bare `key`. The same list for every
+     * caller.
+     */
+    getDefaultContentCategories(projectId: string): Promise<ContentCategory[]>;
     /** Re-pushes the project's currently stored template into its `databases-cue` schema graph, without mutating it. */
     reloadSchema(projectId: string): Promise<MutationResult>;
     private _get;
     private _send;
+    /**
+     * Changes a declared canonical's value. Needs the syncer or admin role. Run it with `dryRun`
+     * first to see what would move and whether the new value collides.
+     */
+    renameCanonical(projectId: string, input: RenameCanonicalInput): Promise<RenameCanonicalResult>;
     private _post;
     private _delete;
     private _errorMessage;

package/lib/signup.d.ts

@@ -39,17 +39,16 @@ 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.
+     * Register a new user by name and email. The account starts without an
+     * organisation and the answer is the same whatever the email's domain; the
+     * user joins the organisation owning that domain once the email is verified
+     * (see `CueProfile.joinOrganizationByEmailDomain`). When no `password` is
+     * given, a "set your password" email is sent. `termsVersion`, when given, is
+     * recorded as accepted immediately so the user isn't asked again on their
+     * next sign-in.
      */
     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

package/lib/usage-stats.d.ts

@@ -3,7 +3,7 @@ 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.
+ * apps/writers/cue-bff/src/app/admin/usage/usage-ingest.service.ts.
  */
 export declare class CueUsageStats {
     private readonly _auth;