@qaecy/cue-sdk 0.0.50 → 0.0.53

package/index.d.ts

@@ -8,6 +8,7 @@ export { CueSignUp, CueRequestError } from './lib/signup';
 export type { OrgSignUpPayload, OrgSignUpPlan } from './lib/signup';
 export { CueApi } from './lib/api';
 export { CueIndexApi } from './lib/index-api';
+export type { MigrateAllProgress, MigrateAllResult } from './lib/index-api';
 export { CueMcp } from './lib/mcp';
 export type { McpCallOptions } from './lib/mcp';
 export type { IndexSearchRequest, IndexItem, IndexSearchResponse, IndexFilterOption, IndexAppliedFilters, AvailableFiltersResponse, SearchFilter, DocumentFilterOption, AvailableDocumentFilters, } from './lib/models';
@@ -23,6 +24,7 @@ export { CueProjectDocuments } from './lib/documents';
 export { CueProjectView } from './lib/project-view';
 export type { CueProjectViewOptions } from './lib/project-view';
 export { CueProjects } from './lib/project';
+export type { ProjectUpdate } from './lib/project';
 export { CueProfile } from './lib/profile';
 export { CueAdmin } from './lib/admin';
 export type { AdminOrgSearchResult, AdminUserSearchResult, AdminProjectSearchResult, AdminUserOrgSummary, AdminUserProjectSummary, AdminUserDetail, AdminDeletedUserOrgRef, AdminDeletedUserProjectRef, AdminDeletedUserSummary, AdminRestoreUserResult, } from './lib/models';
@@ -34,20 +36,24 @@ export { CueCache } from './lib/cache';
 export type { QueryCacheEntry } from './lib/cache';
 export { CueCurrency, SUPPORTED_CURRENCIES, BASE_CURRENCY } from './lib/currency';
 export type { SupportedCurrency, CurrencyRates } from './lib/currency';
-export type { CueSdkConfig, SsoProvider, PasswordCredentials, SearchRequest, SearchResponse, SearchSource, SearchOptions, ProjectData, ProjectSettings, QleverStats, CreateProjectOptions, SyncOptions, SyncResult, SyncPreview, ScanOutputRecord, UnitCreditMap, UnitsConsumedDto, OrgCreditsDto, OrgPlanSummary, MonthlyConsumptionDto, ProjectConsumptionReportDto, OrgConsumptionReportDto, FileTypeConsumptionDto, FileTypeBreakdownDto, RouteTrafficDto, DayTrafficDto, MonthTrafficDto, TrafficReportDto, ViewUsageDto, DayUsageDto, MonthUsageDto, UsageReportDto, OrganizationData, OrgMember, ProfileSSOAccount, APIKeyInfo, APIKeyDoc, ProjectDoc, OrganizationDoc, UserDoc, UserSettings, CustomAppRecord, CustomAppWithHtml, CreateCustomAppOptions, UpdateCustomAppOptions, RDFWritingDoc, ProcessingStatus, ProcessingStage, DocumentProcessingStage, DocumentProgress, ProjectProcessingSummary, MyProcessingStatus, DocumentReprocessJob, ReprocessJobStatus, ViewDefinition, QueryCache, LangMap, CategoryDef, RelationshipDef, EntityCoreData, EntityRelationship, EntityRelationships, MapGeometry, EntityDetailedData, ProjectEntitiesData, SummaryGraphData, DocumentInfo, DocumentSummary, ProjectDocumentsData, } from './lib/models';
+export type { CueSdkConfig, SsoProvider, PasswordCredentials, SearchRequest, SearchResponse, SearchSource, SearchOptions, ProjectData, ProjectSettings, QleverStats, CreateProjectOptions, SyncOptions, SyncResult, SyncPreview, ScanOutputRecord, UnitCreditMap, UnitsConsumedDto, OrgCreditsDto, OrgPlanSummary, MonthlyConsumptionDto, ProjectConsumptionReportDto, OrgConsumptionReportDto, FileTypeConsumptionDto, FileTypeBreakdownDto, RouteTrafficDto, DayTrafficDto, MonthTrafficDto, TrafficReportDto, ViewUsageDto, DayUsageDto, MonthUsageDto, UsageReportDto, OrganizationData, OrgMember, ProfileSSOAccount, APIKeyInfo, APIKeyDoc, ProjectDoc, OrganizationDoc, UserDoc, UserSettings, CustomAppRecord, CustomAppWithHtml, CreateCustomAppOptions, UpdateCustomAppOptions, RDFWritingDoc, ProcessingStatus, ProcessingStage, DocumentProcessingStage, DocumentProgress, ProjectProcessingSummary, MyProcessingStatus, DocumentReprocessJob, ReprocessJobStatus, ViewDefinition, QueryCache, LangMap, CategoryDef, RelationshipDef, EntityCoreData, EntityRelationship, EntityRelationships, MapGeometry, EntityDetailedData, ProjectEntitiesData, SummaryGraphData, PrototypeCategoryCount, PrototypeSummary, PrototypeProperty, PrototypeInstance, EntityAtExpressId, EntityModelLocation, ModelExpressIds, PrototypeCategoryExpressIds, DocumentInfo, DocumentSummary, ProjectDocumentsData, } from './lib/models';
 export type { AuthStateListener, Unsubscribe } from './lib/auth';
 export { CueTables } from './lib/tables';
 export type { ProjectTable } from './lib/tables';
 export { CueExtraction } from './lib/extraction';
 export type { ExtractionRequest, ExtractionResponse } from './lib/extraction';
 export { CueLlmTools } from './lib/llm-tools';
-export type { GenerateWranglingSchemaRequest, GenerateWranglingSchemaResponse, ExistingCategoryForSuggestion, SuggestEntityCategoryRequest, SuggestEntityCategoryResponse, SuggestEntityCategoryMatch, SuggestEntityCategorySuggestion, ColumnToSuggest, ColumnCategorySuggestionResult, SuggestEntityCategoryBatchRequest, SuggestEntityCategoryBatchResponse, } from './lib/llm-tools';
+export type { GenerateWranglingSchemaRequest, GenerateWranglingSchemaResponse, ExistingCategoryForSuggestion, SuggestEntityCategoryRequest, SuggestEntityCategoryResponse, SuggestEntityCategoryMatch, SuggestEntityCategorySuggestion, ColumnToSuggest, ColumnCategorySuggestionResult, SuggestEntityCategoryBatchRequest, SuggestEntityCategoryBatchResponse, ColumnCounts, ColumnCategoryDecision, SuggestFromColumnsRequest, SuggestFromColumnsResponse, } from './lib/llm-tools';
 export { CueDataSources } from './lib/data-sources';
 export type { DataSourceRecord, XToRdfConfig, RmlXToRdfConfig, GraphXToRdfConfig, TypeMappingConfiguration, UploadDataSourceMode, UploadDataSourceResult, } from './lib/data-sources';
 export { CueGisSources } from './lib/gis-sources';
 export type { GisSourceRecord, GisSourceUploadFormat, GisSourceCrs } from './lib/gis-sources';
 export { CueSemanticTemplate } from './lib/semantic-template';
-export type { MutationResult as SemanticTemplateMutationResult, BatchMutationResult as SemanticTemplateBatchMutationResult, ContentCategoryInput, EntityCategoryInput, EntityRelationshipInput, } from './lib/semantic-template';
+export type { MutationResult as SemanticTemplateMutationResult, BatchMutationResult as SemanticTemplateBatchMutationResult, ContentCategoryInput, EntityCategoryInput, EntityRelationshipInput, SchemaSource, } from './lib/semantic-template';
+export { CueSchemaSuggestion } from './lib/schema-suggestion';
+export { ENDPOINT_SCHEMA_SUGGESTION_FROM_PROSE, ENDPOINT_SCHEMA_SUGGESTION_CATALOGS, } from './lib/schema-suggestion';
+export type { SuggestSchemaFromProseRequest, SuggestSchemaFromProseResponse, SchemaSuggestionUsage, } from './lib/schema-suggestion';
+export * from './lib/project-schema';
 export { CueContexts } from './lib/contexts';
 export type { ContextDoc, ContextItem, McpContext } from './lib/models';
 export { CueAppData } from './lib/app-data';

package/index.js

@@ -1,42 +1,62 @@
-import { B as a, C as u, a as C, b as t, c as i, d as r, e as o, f as c, g as n, h as p, i as S, j as m, k as E, l as A, m as P, n as R, o as l, p as g, q as D, r as j, s as U, t as x, u as d, v as f, w as h, x as I, y as T, z as y, A as G, D as _, E as b, F as q, G as v, H as w, I as B, R as F, S as L, J as N, K as O } from "./document-filter-C9Og2u8R.js";
+import { B as C, C as u, a as i, b as r, c as o, d as t, e as S, f as n, g as c, h as E, i as m, j as p, k as A, l, m as P, n as R, o as _, p as I, q as d, r as g, s as T, t as D, u as O, v as N, w as U, x as G, y as h, z as f, A as j, D as v, E as x, F as M, G as y, H as B, I as F, J as L, K as H, L as b, M as K, N as q, O as w, P as Q, Q as V, R as W, S as X, T as Y, U as k, V as z, W as J, X as Z, Y as $, Z as ee, _ as ae, $ as se, a0 as Ce, a1 as ue, a2 as ie, a3 as re } from "./document-filter-CBrY09DH.js";
+import "uuid";
 export {
-  a as BASE_CURRENCY,
-  u as Cue,
-  C as CueAdmin,
-  t as CueApi,
-  i as CueAppData,
-  r as CueApps,
-  o as CueAuth,
-  c as CueCache,
-  n as CueContexts,
-  p as CueCurrency,
-  S as CueDataSources,
-  m as CueDmsApi,
-  E as CueDocumentFilter,
-  A as CueExtraction,
-  P as CueGis,
-  R as CueGisSources,
-  l as CueIndexApi,
-  g as CueLlmTools,
+  C as BASE_CURRENCY,
+  u as CORE_PREFIXES,
+  i as CanonicalPolicy,
+  r as CatalogKind,
+  o as Cue,
+  t as CueAdmin,
+  S as CueApi,
+  n as CueAppData,
+  c as CueApps,
+  E as CueAuth,
+  m as CueCache,
+  p as CueContexts,
+  A as CueCurrency,
+  l as CueDataSources,
+  P as CueDmsApi,
+  R as CueDocumentFilter,
+  _ as CueExtraction,
+  I as CueGis,
+  d as CueGisSources,
+  g as CueIndexApi,
+  T as CueLlmTools,
   D as CueMcp,
-  j as CuePrivileges,
-  U as CueProcessingApi,
-  x as CueProfile,
-  d as CueProjectDocuments,
-  f as CueProjectEntities,
-  h as CueProjectSchema,
-  I as CueProjectView,
-  T as CueProjects,
-  y as CueRequestError,
-  G as CueSemanticTemplate,
-  _ as CueSignUp,
-  b as CueSignal,
-  q as CueStorage,
-  v as CueSyncApi,
-  w as CueTables,
-  B as CueUserSettings,
-  F as REQUIRED_ROLES,
-  L as SUPPORTED_CURRENCIES,
-  N as configureScanWasm,
-  O as cueComputed
+  O as CuePrivileges,
+  N as CueProcessingApi,
+  U as CueProfile,
+  G as CueProjectDocuments,
+  h as CueProjectEntities,
+  f as CueProjectSchema,
+  j as CueProjectView,
+  v as CueProjects,
+  x as CueRequestError,
+  M as CueSchemaSuggestion,
+  y as CueSemanticTemplate,
+  B as CueSignUp,
+  F as CueSignal,
+  L as CueStorage,
+  H as CueSyncApi,
+  b as CueTables,
+  K as CueUserSettings,
+  q as DEFAULT_SCHEMA_BASE,
+  w as ENDPOINT_SCHEMA_SUGGESTION_CATALOGS,
+  Q as ENDPOINT_SCHEMA_SUGGESTION_FROM_PROSE,
+  V as EmbeddingBasis,
+  W as NumeralRole,
+  X as Provenance,
+  Y as REQUIRED_ROLES,
+  k as ResolutionIdentity,
+  z as SUPPORTED_CURRENCIES,
+  J as SchemaTermKind,
+  Z as configureScanWasm,
+  $ as cueComputed,
+  ee as deriveIri,
+  ae as expandCurie,
+  se as isCurie,
+  Ce as rdfBase,
+  ue as resolveIri,
+  ie as resolveRef,
+  re as schemaGraphIri
 };

package/lib/api.d.ts

@@ -1,4 +1,4 @@
-import { CueBlobStorage } from 'js-databases';
+import { CueBlobStorage } from '../../databases/src/index';
 import { CueAuth } from './auth';
 import { SearchRequest, SearchResponse, ShaclValidationReport, UnitsConsumedDto } from './models';
 import { CueProjects } from './project';
@@ -16,7 +16,15 @@ import { CueDmsApi } from './dms';
 import { CueLlmTools } from './llm-tools';
 import { CueDataSources } from './data-sources';
 import { CueGisSources } from './gis-sources';
+import { CueSchemaSuggestion } from './schema-suggestion';
 import { CueSemanticTemplate } from './semantic-template';
+export interface PutAlternativeRepresentationResult {
+    success: boolean;
+    contentIRI: string;
+    remoteRelativePath: string;
+    suffix: string;
+    quads: number;
+}
 export declare class CueApi {
     private readonly _auth;
     private readonly _gatewayUrl;
@@ -51,6 +59,8 @@ export declare class CueApi {
     /** Mutates a project's custom extraction/classification schema (content categories, entity
      *  categories, entity relationships) and reloads its `databases-cue` schema graph. */
     readonly semanticTemplate: CueSemanticTemplate;
+    /** Prose into a proposed `ProjectSchema`, selected from the published term catalogues. */
+    readonly schemaSuggestion: CueSchemaSuggestion;
     /** Active language used for language-sensitive SPARQL queries across all project classes. */
     language: string;
     /** Updates the active language. All project classes (`CueProjectSchema`, `CueProjectDocuments`, `CueProjectEntities`) read this at query time. */
@@ -70,13 +80,20 @@ export declare class CueApi {
      * Execute a SPARQL query against the project's triplestore.
      * The user must be authenticated before calling this.
      *
-     * The gateway resolves which graph backend (qlever, cue, …) actually serves
-     * the query per-project — `graphType` here only needs to distinguish legacy
-     * Fuseki, which lives on its own static Kong route rather than that
-     * per-project routing. Pass it explicitly if the caller already knows;
-     * otherwise it's looked up from the project's own settings.
+     * `graphType` is accepted for call-site compatibility with callers that
+     * still thread a `'fuseki' | 'qlever'` value through from elsewhere in the
+     * SDK (see TODO.md), but it no longer changes anything here: qlever is the
+     * only graph backend left — legacy Fuseki's `/triplestore/*` Kong route is
+     * gone, so routing a `'fuseki'` value to it would just 404.
+     *
+     * `responseMime` picks the result format via the `Accept` header — e.g.
+     * `'application/sparql-results+json'` or `'text/csv'` for SELECT/ASK, or
+     * `'text/turtle'` / `'application/ld+json'` / `'application/n-triples'` for
+     * CONSTRUCT/DESCRIBE. Leave it unset to let the server pick the default for
+     * the query's form (SELECT/ASK → sparql-results+json, CONSTRUCT/DESCRIBE →
+     * n-triples).
      */
-    sparql(query: string, projectId: string, graphType?: 'fuseki' | 'qlever'): Promise<unknown>;
+    sparql(query: string, projectId: string, graphType?: 'fuseki' | 'qlever', responseMime?: string): Promise<unknown>;
     /**
      * Validate a SHACL shape against the project's triplestore.
      *
@@ -90,7 +107,7 @@ export declare class CueApi {
     shacl(shape: string, projectId: string, options?: {
         format?: 'json-ld' | 'turtle';
         verbose?: boolean;
-        graphType?: 'fuseki' | 'qlever';
+        graphType?: 'qlever';
     }): Promise<ShaclValidationReport | string>;
     /**
      * Per-extension credit rates for `tier` (e.g. `{ pdf: 4, ifc: 2, dwg: 2 }`),
@@ -100,4 +117,21 @@ export declare class CueApi {
      */
     getUnitCredits(tier: 's' | 'm' | 'l'): Promise<Record<string, number>>;
     getConsumption(projectId: string): Promise<UnitsConsumedDto>;
+    /**
+     * Attaches `file` to `documentUUID` as a `qcy:alternativeRepresentation` — the same mechanism
+     * `processors-bim`/`processors-cad` use internally (see `alternativeRepresentation()` in
+     * `js/rdf-document-writers`), exposed here for a client that already produced a derivation
+     * itself (e.g. the x-to-rdf tuner's client-side BIM parse producing a model-summary markdown).
+     *
+     * @param location - `'processed'` for a derivation of the source document (lands where a
+     *   processor would have written it, e.g. `{projectId}/md/{documentUUID}.md`); `'raw'` for an
+     *   alternative original companion file.
+     */
+    putAlternativeRepresentation(projectId: string, documentUUID: string, file: Blob, opts: {
+        location: 'raw' | 'processed';
+        suffix: string;
+        fileContentClasses?: string[];
+        processorId?: string;
+        comment?: string;
+    }): Promise<PutAlternativeRepresentationResult>;
 }

package/lib/auth.d.ts

@@ -12,6 +12,7 @@ export declare class CueAuth {
     private readonly _isSuperAdminSignal;
     private readonly _userIdsSignal;
     private readonly _stopTokenListener;
+    private _ssoPending;
     /** Reactive auth state — emits the signed-in `User`, or `null` when signed out. */
     readonly user: ReadonlySignal<User | null>;
     /** Reactive Firebase ID token — refreshes automatically; `null` when signed out. */
@@ -21,6 +22,7 @@ export declare class CueAuth {
     /** All unique UIDs for the current user (Firebase UID + linked provider UIDs). */
     readonly userIds: ReadonlySignal<string[]>;
     constructor(app: FirebaseApp, useEmulator: boolean | undefined, endpoints: CueEndpoints);
+    private _publish;
     /** Stop all internal Firebase listeners. Call when the `Cue` instance is no longer needed. */
     destroy(): void;
     /** Sign in with Google or Microsoft via browser popup */
@@ -39,6 +41,13 @@ export declare class CueAuth {
      * Call this once on app startup before showing a sign-in UI.
      */
     checkRedirectResult(): Promise<User | null>;
+    /**
+     * SSO may sign in to an existing account but never create one. Firebase
+     * creates the account before we can object, so the backend checks it
+     * afterwards and deletes it if it is a fresh sign-up; we sign out and throw.
+     * Fails closed: if the check cannot be made, the session is dropped.
+     */
+    private _confirmSsoSignIn;
     /**
      * One-shot async check — returns `true` if the current user has the
      * `superadmin` custom claim. For reactive use, read `cue.auth.isSuperAdmin`

package/lib/cue.d.ts

@@ -1,6 +1,6 @@
 import { FirebaseApp } from 'firebase/app';
 import { FirebaseStorage } from 'firebase/storage';
-import { CueBlobStorage } from 'js-databases';
+import { CueBlobStorage } from '../../databases/src/index';
 import { CueAuth } from './auth';
 import { CueSignUp } from './signup';
 import { CueStorage } from './storage';

package/lib/data-sources.d.ts

@@ -1,9 +1,19 @@
-import { CueBlobStorage } from 'js-databases';
+import { CueBlobStorage } from '../../databases/src/index';
 import { CueAuth } from './auth';
-export type XToRdfConfig = RmlXToRdfConfig | GraphXToRdfConfig | DecompositionConfig | SheetXToRdfConfig;
+export type XToRdfConfig = RmlXToRdfConfig | GraphXToRdfConfig | DecompositionConfig | SheetXToRdfConfig | RegisterXToRdfConfig | BimXToRdfConfig | FilesXToRdfConfig | TextXToRdfConfig;
 interface XToRdfConfigBase {
     /** Steps run on the transform's output, in order — see `XToRdfPostProcessingStep`. */
     postProcessing?: XToRdfPostProcessingStep[];
+    /** The original source file(s) this mapping was built from, persisted via
+     *  `DataSourceHandlers.uploadSourceFile` — lets the tuner wizard's "Edit mapping" fetch the
+     *  exact file(s) back (`DataSourceHandlers.getSourceFile`) instead of asking the user to
+     *  re-upload before it can resume. Sheet: one entry. Graph: one per loaded `.ttl`. BIM: one
+     *  entry, alongside its own `sourceDocumentUUID` below (kept separate — that one is for the
+     *  document viewer, this one is for wizard resume). */
+    sourceFiles?: {
+        documentUUID: string;
+        fileName: string;
+    }[];
 }
 export interface RmlXToRdfConfig extends XToRdfConfigBase {
     type: 'rml';
@@ -56,6 +66,119 @@ export interface SheetXToRdfConfig extends XToRdfConfigBase {
     type: 'sheet';
     mapping: SheetMappingConfiguration;
 }
+/**
+ * A DMS export / document register: a table whose rows are files and whose every column is a fact
+ * the archive keeps about one — its document type, its status, its revision, who filed it.
+ *
+ * Its own kind rather than a `sheet` mapping with a special column role, because the two ask
+ * different questions of a table. The sheet route asks what things a table names and how they
+ * relate; a register names none, and mapping its columns as entity categories produced terms
+ * standing for nothing. Every column becomes a `qcy:Property` on the row's `qcy:FileLocation`, and
+ * what those properties mean is left to resolution, which can see every source at once.
+ */
+export interface RegisterXToRdfConfig extends XToRdfConfigBase {
+    type: 'register';
+    mapping: RegisterMappingConfiguration;
+}
+/**
+ * The only config whose input is the project's **own** file locations rather than an upload: one
+ * regex per entity category, run over every `qcy:filePath`, linking each file to the canonical
+ * entity its filename encodes. A client numbering standard (`33-ARC-H10-…`) is exactly this.
+ *
+ * Having no uploaded file has two consequences. It is run with `refreshDataSource` rather than
+ * `uploadData`, so re-reading the project after new files arrive costs one call and no
+ * re-authoring. And it attaches to the `qcy:FileLocation` IRIs already in the graph, so unlike the
+ * sheet route it never re-derives one.
+ */
+export interface FilesXToRdfConfig extends XToRdfConfigBase {
+    type: 'files';
+    mappings: FilePathMapping[];
+    /** Restricts which files are scanned, tested against `qcy:filePath`. Absent scans every file. */
+    pathFilter?: string;
+}
+/**
+ * The third source of the same facts: what the documents themselves say.
+ *
+ * Same `mappings` as `files`, pointed at text instead of paths, so one coding scheme produces all
+ * three sources without a pattern being re-authored. Run through `refreshDataSource` like `files`,
+ * for the same reason — its input is the project's own documents, not an upload.
+ *
+ * The matching happens in `enrichers-regex-matcher` and yields `qcy:EntityMention`s, so this is the
+ * one kind with a resolution step: a mention whose value is in the mapping's declared list is
+ * linked to that canonical, and the file the text belongs to gets the same `qcy:about` edge the
+ * other two sources emit — which is what makes the three comparable.
+ */
+export interface TextXToRdfConfig extends XToRdfConfigBase {
+    type: 'text';
+    mappings: FilePathMapping[];
+    /** Search each document's `qcy:textSummary`. Defaults to true — one short string per document,
+     *  and the one that names a project's subjects. */
+    searchSummary?: boolean;
+    /** Search each document's full extracted text. Defaults to false: orders of magnitude more text,
+     *  read from blob storage rather than the graph. */
+    searchTextRaw?: boolean;
+    /** Which extracted-text files body-text search reads, as a regex over their path. Absent means
+     *  the matcher's default (markdown). Only meaningful with `searchTextRaw`. */
+    filePathFilter?: string;
+    /** Caps how many documents are scanned, for trying a scheme out first. Absent scans every one. */
+    limit?: number;
+}
+export interface FilePathMapping {
+    categoryIri: string;
+    /**
+     * Unanchored, with exactly **one** capture group — the group is the field being read, and the
+     * surrounding segments are what stop a stray match elsewhere in the path. Derived by cue-ui's
+     * `codingSchemeToRegex` rather than hand-authored, which is what guarantees both properties and
+     * keeps the pattern valid under RE2 for `regex-matcher` to reuse.
+     */
+    regex: string;
+    /** Captured code (lower-cased) -> the IRI of the canonical entity already declared for it. */
+    iriByValue?: Record<string, string>;
+    /** What to do with a captured code the value list does not have. `'skip'` (the default) records
+     *  nothing — a filename carrying an undeclared code is a finding to show, not a term to invent. */
+    unmatched?: 'skip' | 'mint';
+}
+/**
+ * A BIM model uploaded through the x-to-rdf tuner's client-side IFC parser. Unlike `graph`, there
+ * is no `constructQuery` to run server-side — the parser's own output already IS the canonical
+ * QCY graph (stable IRIs derived from IFC GUIDs), so the backend transform is a passthrough that
+ * mints nothing. `sourceDocumentUUID`/`markdownRemoteRelativePath` are what the document viewer
+ * needs later to render the 3D model + markdown summary alongside this data source's own named
+ * graph — see `CueApi.putAlternativeRepresentation` for how the markdown gets attached.
+ */
+export interface BimXToRdfConfig extends XToRdfConfigBase {
+    type: 'bim';
+    /** The parser knobs the model was parsed with. Not interpreted by the SDK itself, same
+     *  "opaque but structurally mirrored" role `wizardConfig` plays for `graph` configs. */
+    parseSettings?: IfcParseSettings;
+    /** The original `.ifc`, persisted via `CueSyncApi.syncBrowserFile` with `skipProcessing: true`. */
+    sourceDocumentUUID?: string;
+    /** The parser's model-summary markdown, attached to `sourceDocumentUUID` as a
+     *  `qcy:alternativeRepresentation` at `{projectId}/md/{sourceDocumentUUID}.md`. */
+    markdownRemoteRelativePath?: string;
+}
+/** Mirrors cue-ui's tuner-x-to-rdf `IfcParseSettings`. The two prototype fields are optional
+ *  here because data sources saved before they existed carry a `parseSettings` without them;
+ *  cue-ui's panel, which always writes a full object, has them required. */
+export interface IfcParseSettings {
+    enabledParsers: {
+        bot: boolean;
+        products: boolean;
+        properties: boolean;
+        selectors: boolean;
+        polygons: boolean;
+    };
+    buildSummary: boolean;
+    buildDescriptions: boolean;
+    excludedPSets: string[];
+    /** Writes each IFC type object (family type) as a `qcy:EntityPrototype` its occurrences point
+     *  at with `qcy:inheritsFrom`. Absent on data sources saved before prototypes existed, which
+     *  the parser reads as on. */
+    useEntityPrototypes?: boolean;
+    /** Only meaningful with `useEntityPrototypes`. Also moves properties the IFC left on the
+     *  occurrences up onto the prototype when every occurrence of the type shares the value. */
+    hoistSharedProperties?: boolean;
+}
 /**
  * How a spreadsheet's columns become RDF: every column is either ignored, an entity — minted
  * onto the same deterministic-IRI scheme `graph`/`decomposition` use
@@ -70,12 +193,88 @@ export interface SheetMappingConfiguration {
     columnRoles: Record<string, SheetColumnRole>;
     relationMappings: SheetRelationMapping[];
     fileLinkage?: SheetFileLinkage | null;
+    /** Cleaning rules run on every row before mapping, in order. Not opaque to the backend —
+     *  the sheet transform executes these itself (see `apply-wrangling.ts` in
+     *  `rdf-document-writers`), same reasoning as `columnRoles`/`relationMappings` above. */
+    wrangling?: WranglingSettings | null;
 }
+/**
+ * How a document register becomes RDF — mirrors `RegisterMapping` in js/rdf-document-writers,
+ * which documents the triples each field produces. Not opaque to the backend: the register
+ * transform reads it directly.
+ */
+export interface RegisterMappingConfiguration {
+    id?: string;
+    name: string;
+    /** The one column that is not a property: the file's path or name. */
+    filePathColumn: string;
+    /** How that cell finds the `qcy:FileLocation` the project already holds — see
+     *  `SheetFileLinkage.pathMatch`, same meaning. */
+    pathMatch?: 'exact' | 'basename';
+    /** Column -> the `qcy:label` its values are written under. Explicit, so a register re-uploaded
+     *  with an extra column does not start writing properties nobody named. */
+    propertyLabels: Record<string, string>;
+    /** Optional: the schema's regex-bearing entity categories (`qcy-t:regex`), read off the
+     *  file-path cell — same shape and contract as the `files` kind's `FilePathMapping`. */
+    pathPatterns?: FilePathMapping[];
+    /** Cleaning rules run on every row before mapping, in order — same treatment `sheet` gives its
+     *  own. */
+    wrangling?: WranglingSettings | null;
+}
+/** Mirrors cue-ui's `data-wrangling/models.ts` exactly — see that file for the reasoning behind
+ *  each rule type. Kept in structural sync by hand, same convention as `IfcParseSettings` above. */
+export type WranglingRuleType = 'splitCell' | 'formula' | 'setUndefined' | 'parseDate';
+export interface WranglingRuleBase {
+    id: string;
+    type: WranglingRuleType;
+    /** Fields the rule applies to. A rule with no columns is a no-op. */
+    columns: string[];
+    disabled?: boolean;
+}
+export type SplitCellMode = 'expandRows' | 'first' | 'last' | 'join';
+export interface SplitCellRule extends WranglingRuleBase {
+    type: 'splitCell';
+    separator: string;
+    regex?: boolean;
+    trim?: boolean;
+    dropEmpty?: boolean;
+    mode: SplitCellMode;
+    joinSeparator?: string;
+}
+export interface FormulaRule extends WranglingRuleBase {
+    type: 'formula';
+    expression: string;
+}
+export interface SetUndefinedRule extends WranglingRuleBase {
+    type: 'setUndefined';
+    values: string[];
+    caseInsensitive?: boolean;
+}
+export interface ParseDateRule extends WranglingRuleBase {
+    type: 'parseDate';
+    inputFormat?: string;
+}
+export type WranglingRule = SplitCellRule | FormulaRule | SetUndefinedRule | ParseDateRule;
+export interface WranglingSettings {
+    rules: WranglingRule[];
+}
+/**
+ * `pattern` is an optional single-capture regex applied to a cell before lookup, so a cell that
+ * carries its code alongside its meaning (`05-Elektro`) resolves on the code alone.
+ *
+ * `iriByValue` maps the extracted string (lower-cased) to a canonical entity that already exists —
+ * a value declared in the project schema. On a hit the entity is not minted at all: only the
+ * `qcy:about` edge is written, so the schema graph keeps sole ownership of its value, notation and
+ * labels, and a fact read from a spreadsheet and the same fact read from a filename land on one
+ * entity instead of two. On a miss the cell mints as it always has.
+ */
 export type SheetColumnRole = {
     kind: 'unmapped';
 } | {
     kind: 'entity';
     categoryIri: string;
+    pattern?: string;
+    iriByValue?: Record<string, string>;
 } | {
     kind: 'attribute';
     entityColumn: string;
@@ -92,6 +291,16 @@ export interface SheetRelationMapping {
 export interface SheetFileLinkage {
     filePathColumn: string;
     md5Column?: string;
+    /**
+     * How the path cell finds its `qcy:FileLocation`. `'exact'` (the default) matches `qcy:filePath`
+     * verbatim; `'basename'` also accepts a cell holding only the file's name — the shape a DMS
+     * export uses — and refuses a name two files share rather than picking one.
+     *
+     * Either way the location IRI the graph already holds is what the row attaches to, instead of
+     * one re-derived from the cell. The derivation passes no provider id while ingestion passes the
+     * file's own, so a re-derived IRI misses every file that arrived through a connector.
+     */
+    pathMatch?: 'exact' | 'basename';
 }
 /**
  * A step applied to a transform's *output*, after the CONSTRUCT query (or RML mapping) has run.
@@ -218,6 +427,18 @@ export declare class CueDataSources {
      * before the handler even runs, is still thrown from `response.ok` as before).
      */
     uploadData(projectId: string, id: string, files: Blob[], mode: UploadDataSourceMode, onProgress?: (event: DataSourceProgressEvent) => void): Promise<UploadDataSourceResult>;
+    /**
+     * Re-runs a data source that has no uploaded input — today only a `files` config, whose input is
+     * the project's own file locations. This is how "new files have arrived since this ran" is
+     * answered: one call, no re-authoring and nothing to re-upload.
+     *
+     * Always replaces, because re-reading the same input is a recomputation rather than an addition.
+     * Same NDJSON progress stream and same `{added, removed}` result as `uploadData`, so a caller
+     * that already handles an upload handles this with no new branch. Every other config type is
+     * refused — a sheet or RML source has no input without its file, and re-running one with none
+     * would quietly empty its graph.
+     */
+    refreshDataSource(projectId: string, id: string, onProgress?: (event: DataSourceProgressEvent) => void): Promise<UploadDataSourceResult>;
     /**
      * Dry-run: runs `config` against `files` and returns the resulting Turtle,
      * without creating a data source or writing anything to the graph/ledger —

package/lib/documents.d.ts

@@ -1,6 +1,6 @@
 import { CueApi } from './api';
 import { ReadonlySignal } from './signal';
-import { FileType } from 'js/models';
+import { FileType } from '../../models/src/index';
 import { DocumentInfo, ProjectDocumentsData } from './models';
 /**
  * Manages document data for a single project.