@finsys/core 3.2.0 → 3.4.0

package/dist/index.d.cts

@@ -405,6 +405,27 @@ declare enum FileFieldTableType {
     TIME_SERIES = "timeSeries",
     KEY_VALUE = "keyValue"
 }
+/**
+ * Per-field extraction provenance (SYS-2737/SYS-2741). The single canonical
+ * envelope — finsys-api writes it (ihs_field_metadata), finsys-core surfaces it
+ * onto detail cells, both consumers render it. Vocabulary mirrors adapter_runs
+ * (SYS-2441) so FinXtract + adapter provenance converge at SYS-2499 Phase 5.
+ *
+ *   source      — who produced the value, e.g. "finxtract:ssm"
+ *   confidence  — normalized 0..1; null when derived/computed (no score)
+ *   observedAt  — ISO wall-clock of the extraction run
+ *   sourceRunId — the extraction run/job id that wrote it
+ *   origin      — "extracted" (a real {value,confidence} leaf) vs "derived"
+ *                 (computed / no-confidence path). A "derived" field must render
+ *                 as "no confidence available", never a fabricated low score.
+ */
+interface IhsFieldProvenance {
+    source: string;
+    confidence: number | null;
+    observedAt: string;
+    sourceRunId: string | null;
+    origin: 'extracted' | 'derived';
+}
 interface FileFieldTableItem {
     displayName: string;
     timePeriods: string[];
@@ -412,6 +433,14 @@ interface FileFieldTableItem {
     formattedData: Record<string, string>;
     type: FileFieldTableType;
     isNumeric: boolean;
+    /**
+     * SYS-2741: per-cell extraction provenance, keyed exactly like `data` (period
+     * key for TIME_SERIES, `'value'` for KEY_VALUE). `confidence` carries only
+     * scored (origin 'extracted') cells so a numeric dot never renders for a
+     * derived value; `provenance` carries the full envelope for every known cell.
+     */
+    confidence?: Record<string, number>;
+    provenance?: Record<string, IhsFieldProvenance>;
 }
 interface FileFieldTableData {
     name: string;
@@ -420,6 +449,69 @@ interface FileFieldTableData {
     items: FileFieldTableItem[];
     hasData: boolean;
 }
+/**
+ * Per-document File metadata attached by finsys-api `getIhsDetailsById` as the
+ * `documentMetadata` sibling map (SYS-2765), keyed by the document's raw stored
+ * path. The single source for the documents table's Type / Size / Uploaded
+ * columns — the IHS doc fields themselves carry only the path.
+ */
+interface DocumentFileMetadata {
+    fileName: string | null;
+    fileType: string | null;
+    fileSize: number | null;
+    createdAt: string | null;
+}
+/**
+ * Intrinsic, data-derived capability eligibility for a document row. Reflects
+ * ONLY what the IHS payload implies (doc type + a resolvable file); the consumer
+ * ANDs in its own runtime gates (readOnly, allowReupload, and — for viewJson —
+ * whether extraction has actually completed) before showing a control.
+ */
+interface DocumentRowCapabilities {
+    /** A downloadable original exists (a resolvable documentId). */
+    download: boolean;
+    /** The doc type produces extracted JSON (consumer still gates on "Extracted"). */
+    viewJson: boolean;
+    /** The doc type can be re-extracted. */
+    reExtract: boolean;
+    /** The doc type accepts a replacement upload (finsys-api /ihs/client/update/document). */
+    reUpload: boolean;
+}
+/**
+ * One uploaded document, presentation-agnostic — built by `buildDocumentRows`
+ * from the IHS payload + its `documentMetadata` map. Rendered identically by
+ * FinHub (React) and finsys-client (Edge). Live extraction status + confidence
+ * are NOT payload-derived; the consumer overlays them by matching
+ * `(docType, timePeriod)`.
+ */
+interface DocumentRow {
+    /** IHS field key, e.g. 'bankStatements'. */
+    docType: string;
+    /** Human label for the doc-type group, e.g. 'Bank Statements'. */
+    label: string;
+    /** 0-based position within the docType group. */
+    index: number;
+    /** Best display name (resolved file name, or a label + period/index fallback). */
+    displayName: string;
+    /** Id for the download link; null when no file path is resolvable. */
+    documentId: string | null;
+    /** Raw stored path — the join key back to `documentMetadata`. */
+    path: string | null;
+    /** Extraction time-period token: 'T{month|year}' or 'ALL'. */
+    timePeriod: string;
+    /** Human period label ('Jan 2026' / 'Year 2024') or null. */
+    periodLabel: string | null;
+    /** Resolved file name; null when the stored name looks like an opaque id. */
+    fileName: string | null;
+    /** File type label (extension → MIME subtype, upper-cased) or null. */
+    fileType: string | null;
+    /** File size in bytes, or null when unknown. */
+    fileSize: number | null;
+    /** ISO upload timestamp (File.createdAt) or null. */
+    uploadedAt: string | null;
+    /** Intrinsic capability eligibility (consumer overlays its runtime gates). */
+    capabilities: DocumentRowCapabilities;
+}
 
 /** Returns the full display name registry (extraction column → human label). */
 declare function getDisplayNames(): Record<string, string>;
@@ -430,7 +522,43 @@ declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string,
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
 /** Returns human-friendly display names for field groups. */
 declare function getGroupDisplayNames(): Record<string, string>;
-declare function buildFileFieldTables(ihsData: Record<string, unknown>): Record<string, FileFieldTableData>;
+declare function buildFileFieldTables(ihsData: Record<string, unknown>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
+/** IHS doc-field key → human label (the fields that become document sections). */
+declare function getDocDisplayNames(): Record<string, string>;
+/** Doc types eligible for extraction (re-extract / view-JSON). */
+declare function getExtractableDocTypes(): Set<string>;
+/** Doc types eligible for a replacement upload. */
+declare function getReuploadableDocTypes(): Set<string>;
+interface ParsedDocFile {
+    path?: string;
+    fileName?: string;
+    documentId?: string;
+    fileSize?: number | string;
+    fileType?: string;
+    createdAt?: string;
+    month?: number;
+    year?: number;
+}
+/**
+ * Parse one IHS doc field into file entries. Handles the shapes the field takes:
+ * a JSON-array string (bank/financial/…, possibly inline-enriched like
+ * supplementaryDoc), an already-parsed array, or a bare URL string (ssm/form9/ic).
+ */
+declare function parseFileField(value: unknown): ParsedDocFile[];
+/**
+ * Build the presentation-agnostic document rows for an IHS. Reads the doc fields
+ * named in DOC_DISPLAY_NAMES + the `documentMetadata` sibling map (SYS-2765) and
+ * emits a flat DocumentRow[] (all sections, in DOC_DISPLAY_NAMES order). Metadata
+ * is taken inline off the entry first (supplementaryDoc is enriched inline), then
+ * from `documentMetadata[path]`.
+ */
+declare function buildDocumentRows(ihsData: Record<string, unknown>): DocumentRow[];
+/** Type column: the resolved type label, or em-dash. */
+declare function formatDocumentType(row: Pick<DocumentRow, 'fileType'>): string;
+/** Size column: human bytes (B / KB / MB), or em-dash when unknown. */
+declare function formatDocumentSize(bytes: number | null | undefined): string;
+/** Uploaded column: the upload date, else the period label, else em-dash. */
+declare function formatDocumentUploaded(row: Pick<DocumentRow, 'uploadedAt' | 'periodLabel'>): string;
 declare function processIhsDetails(ihsData: Record<string, unknown>): IhsFieldDetail[];
 declare function groupDetailsByCategory(details: IhsFieldDetail[]): IhsDetailCategory[];
 
@@ -1220,4 +1348,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildDocumentRows, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.d.ts

@@ -405,6 +405,27 @@ declare enum FileFieldTableType {
     TIME_SERIES = "timeSeries",
     KEY_VALUE = "keyValue"
 }
+/**
+ * Per-field extraction provenance (SYS-2737/SYS-2741). The single canonical
+ * envelope — finsys-api writes it (ihs_field_metadata), finsys-core surfaces it
+ * onto detail cells, both consumers render it. Vocabulary mirrors adapter_runs
+ * (SYS-2441) so FinXtract + adapter provenance converge at SYS-2499 Phase 5.
+ *
+ *   source      — who produced the value, e.g. "finxtract:ssm"
+ *   confidence  — normalized 0..1; null when derived/computed (no score)
+ *   observedAt  — ISO wall-clock of the extraction run
+ *   sourceRunId — the extraction run/job id that wrote it
+ *   origin      — "extracted" (a real {value,confidence} leaf) vs "derived"
+ *                 (computed / no-confidence path). A "derived" field must render
+ *                 as "no confidence available", never a fabricated low score.
+ */
+interface IhsFieldProvenance {
+    source: string;
+    confidence: number | null;
+    observedAt: string;
+    sourceRunId: string | null;
+    origin: 'extracted' | 'derived';
+}
 interface FileFieldTableItem {
     displayName: string;
     timePeriods: string[];
@@ -412,6 +433,14 @@ interface FileFieldTableItem {
     formattedData: Record<string, string>;
     type: FileFieldTableType;
     isNumeric: boolean;
+    /**
+     * SYS-2741: per-cell extraction provenance, keyed exactly like `data` (period
+     * key for TIME_SERIES, `'value'` for KEY_VALUE). `confidence` carries only
+     * scored (origin 'extracted') cells so a numeric dot never renders for a
+     * derived value; `provenance` carries the full envelope for every known cell.
+     */
+    confidence?: Record<string, number>;
+    provenance?: Record<string, IhsFieldProvenance>;
 }
 interface FileFieldTableData {
     name: string;
@@ -420,6 +449,69 @@ interface FileFieldTableData {
     items: FileFieldTableItem[];
     hasData: boolean;
 }
+/**
+ * Per-document File metadata attached by finsys-api `getIhsDetailsById` as the
+ * `documentMetadata` sibling map (SYS-2765), keyed by the document's raw stored
+ * path. The single source for the documents table's Type / Size / Uploaded
+ * columns — the IHS doc fields themselves carry only the path.
+ */
+interface DocumentFileMetadata {
+    fileName: string | null;
+    fileType: string | null;
+    fileSize: number | null;
+    createdAt: string | null;
+}
+/**
+ * Intrinsic, data-derived capability eligibility for a document row. Reflects
+ * ONLY what the IHS payload implies (doc type + a resolvable file); the consumer
+ * ANDs in its own runtime gates (readOnly, allowReupload, and — for viewJson —
+ * whether extraction has actually completed) before showing a control.
+ */
+interface DocumentRowCapabilities {
+    /** A downloadable original exists (a resolvable documentId). */
+    download: boolean;
+    /** The doc type produces extracted JSON (consumer still gates on "Extracted"). */
+    viewJson: boolean;
+    /** The doc type can be re-extracted. */
+    reExtract: boolean;
+    /** The doc type accepts a replacement upload (finsys-api /ihs/client/update/document). */
+    reUpload: boolean;
+}
+/**
+ * One uploaded document, presentation-agnostic — built by `buildDocumentRows`
+ * from the IHS payload + its `documentMetadata` map. Rendered identically by
+ * FinHub (React) and finsys-client (Edge). Live extraction status + confidence
+ * are NOT payload-derived; the consumer overlays them by matching
+ * `(docType, timePeriod)`.
+ */
+interface DocumentRow {
+    /** IHS field key, e.g. 'bankStatements'. */
+    docType: string;
+    /** Human label for the doc-type group, e.g. 'Bank Statements'. */
+    label: string;
+    /** 0-based position within the docType group. */
+    index: number;
+    /** Best display name (resolved file name, or a label + period/index fallback). */
+    displayName: string;
+    /** Id for the download link; null when no file path is resolvable. */
+    documentId: string | null;
+    /** Raw stored path — the join key back to `documentMetadata`. */
+    path: string | null;
+    /** Extraction time-period token: 'T{month|year}' or 'ALL'. */
+    timePeriod: string;
+    /** Human period label ('Jan 2026' / 'Year 2024') or null. */
+    periodLabel: string | null;
+    /** Resolved file name; null when the stored name looks like an opaque id. */
+    fileName: string | null;
+    /** File type label (extension → MIME subtype, upper-cased) or null. */
+    fileType: string | null;
+    /** File size in bytes, or null when unknown. */
+    fileSize: number | null;
+    /** ISO upload timestamp (File.createdAt) or null. */
+    uploadedAt: string | null;
+    /** Intrinsic capability eligibility (consumer overlays its runtime gates). */
+    capabilities: DocumentRowCapabilities;
+}
 
 /** Returns the full display name registry (extraction column → human label). */
 declare function getDisplayNames(): Record<string, string>;
@@ -430,7 +522,43 @@ declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string,
 declare function groupFieldsByPattern(fields: FieldData[]): Record<string, FieldData[]>;
 /** Returns human-friendly display names for field groups. */
 declare function getGroupDisplayNames(): Record<string, string>;
-declare function buildFileFieldTables(ihsData: Record<string, unknown>): Record<string, FileFieldTableData>;
+declare function buildFileFieldTables(ihsData: Record<string, unknown>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
+/** IHS doc-field key → human label (the fields that become document sections). */
+declare function getDocDisplayNames(): Record<string, string>;
+/** Doc types eligible for extraction (re-extract / view-JSON). */
+declare function getExtractableDocTypes(): Set<string>;
+/** Doc types eligible for a replacement upload. */
+declare function getReuploadableDocTypes(): Set<string>;
+interface ParsedDocFile {
+    path?: string;
+    fileName?: string;
+    documentId?: string;
+    fileSize?: number | string;
+    fileType?: string;
+    createdAt?: string;
+    month?: number;
+    year?: number;
+}
+/**
+ * Parse one IHS doc field into file entries. Handles the shapes the field takes:
+ * a JSON-array string (bank/financial/…, possibly inline-enriched like
+ * supplementaryDoc), an already-parsed array, or a bare URL string (ssm/form9/ic).
+ */
+declare function parseFileField(value: unknown): ParsedDocFile[];
+/**
+ * Build the presentation-agnostic document rows for an IHS. Reads the doc fields
+ * named in DOC_DISPLAY_NAMES + the `documentMetadata` sibling map (SYS-2765) and
+ * emits a flat DocumentRow[] (all sections, in DOC_DISPLAY_NAMES order). Metadata
+ * is taken inline off the entry first (supplementaryDoc is enriched inline), then
+ * from `documentMetadata[path]`.
+ */
+declare function buildDocumentRows(ihsData: Record<string, unknown>): DocumentRow[];
+/** Type column: the resolved type label, or em-dash. */
+declare function formatDocumentType(row: Pick<DocumentRow, 'fileType'>): string;
+/** Size column: human bytes (B / KB / MB), or em-dash when unknown. */
+declare function formatDocumentSize(bytes: number | null | undefined): string;
+/** Uploaded column: the upload date, else the period label, else em-dash. */
+declare function formatDocumentUploaded(row: Pick<DocumentRow, 'uploadedAt' | 'periodLabel'>): string;
 declare function processIhsDetails(ihsData: Record<string, unknown>): IhsFieldDetail[];
 declare function groupDetailsByCategory(details: IhsFieldDetail[]): IhsDetailCategory[];
 
@@ -1220,4 +1348,4 @@ interface FieldMapEntry {
     readonly transform?: "identity" | "pct_to_ratio01" | "to_boolean" | "to_integer";
 }
 
-export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { ADAPTER_CATEGORY_IDS, ALL_AGGREGATION_OPS, type AdapterCategory, AdapterError, type AdapterErrorReason, type AdapterExtraction, type AdapterManifest, type AggregationOp, type ApplicantIdentity, BASE_FIELD_SPECS, BasicFormField, type CanonicalFieldName, type CanonicalFieldSpec, type CanonicalFieldValue, type CanonicalFieldValues, type Category, type CategorySchema, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DeclarativeImplementation, type DocExtractionResult, DocExtractionStatus, type DocumentFileMetadata, type DocumentRow, type DocumentRowCapabilities, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldMapEntry, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, IHS_FAILURE_STATUSES, IHS_TERMINAL_STATUSES, IHS_VALID_STATUSES, type IhsDetailCategory, type IhsFieldDetail, type IhsFieldProvenance, IhsStatus, IhsValueFormat, type InstanceValue, type PageConfig, type RHFSchemaOutput, type RHFStep, type RawPayload, type ResolvedField, Role, type SourceAdapter, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type TypescriptImplementation, type UnifiedFormConfig, type Validator, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, buildDocumentRows, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.js

@@ -9365,7 +9365,7 @@ function formatValue(value, numeric) {
   }
   return String(value);
 }
-function buildTableForGroup(groupName, fields, ihsData) {
+function buildTableForGroup(groupName, fields, ihsData, fieldProvenance) {
   const allColumns = [];
   for (const field of fields) {
     if (field.ihs_column_names) {
@@ -9384,11 +9384,20 @@ function buildTableForGroup(groupName, fields, ihsData) {
       const numeric = isNumericField(baseName);
       const data = {};
       const formattedData = {};
+      const confidence = {};
+      const provenance = {};
       for (const period of periods) {
         const colName = periodMap[period];
         const value = colName ? ihsData[colName] ?? null : null;
         data[period] = value;
         formattedData[period] = formatValue(value, numeric);
+        const prov = colName ? fieldProvenance?.[colName] : void 0;
+        if (prov) {
+          provenance[period] = prov;
+          if (prov.origin === "extracted" && typeof prov.confidence === "number" && !Number.isNaN(prov.confidence)) {
+            confidence[period] = prov.confidence;
+          }
+        }
       }
       items.push({
         displayName: getDisplayName(baseName),
@@ -9396,7 +9405,9 @@ function buildTableForGroup(groupName, fields, ihsData) {
         data,
         formattedData,
         type: tableType,
-        isNumeric: numeric
+        isNumeric: numeric,
+        ...Object.keys(confidence).length ? { confidence } : {},
+        ...Object.keys(provenance).length ? { provenance } : {}
       });
     }
     const hasData = items.some(
@@ -9408,13 +9419,16 @@ function buildTableForGroup(groupName, fields, ihsData) {
     for (const colName of allColumns) {
       const value = ihsData[colName] ?? null;
       const numeric = isNumericField(colName);
+      const prov = fieldProvenance?.[colName];
       items.push({
         displayName: getDisplayName(colName),
         timePeriods: [],
         data: { value },
         formattedData: { value: formatValue(value, numeric) },
         type: tableType,
-        isNumeric: numeric
+        isNumeric: numeric,
+        ...prov && prov.origin === "extracted" && typeof prov.confidence === "number" && !Number.isNaN(prov.confidence) ? { confidence: { value: prov.confidence } } : {},
+        ...prov ? { provenance: { value: prov } } : {}
       });
     }
     const hasData = items.some((item) => {
@@ -9424,19 +9438,160 @@ function buildTableForGroup(groupName, fields, ihsData) {
     return { name: groupName, displayName: groupDisplayName, type: tableType, items, hasData };
   }
 }
-function buildFileFieldTables(ihsData) {
+function buildFileFieldTables(ihsData, fieldProvenance) {
   const specs = getBaseFieldSpecs();
   const fileFields = specs.filter((f) => f.type === "file" && f.ihs_column_names?.length);
   const grouped = groupFieldsByPattern(fileFields);
   const tables = {};
   for (const [groupName, fields] of Object.entries(grouped)) {
-    const table = buildTableForGroup(groupName, fields, ihsData);
+    const table = buildTableForGroup(groupName, fields, ihsData, fieldProvenance);
     if (table && table.hasData) {
       tables[groupName] = table;
     }
   }
   return tables;
 }
+var DOC_DISPLAY_NAMES = {
+  bankStatements: "Bank Statements",
+  financialStatements: "Financial Statements",
+  form9: "Form 9",
+  epfStatements: "EPF Statements",
+  payslips: "Payslips",
+  ssm: "SSM Company Profile",
+  ic: "Identity Card",
+  ssm_registration_documents: "Form 9",
+  ic_documents: "Identity Documents (Supplementary)",
+  consentForm: "Consent Form",
+  supplementaryDoc: "Supplementary Documents",
+  coreIncomeDoc: "Core Income Document",
+  incomeSupportingDoc: "Income Supporting Document",
+  incomeEPF_iakaun: "EPF i-Akaun",
+  photocopyRegistrationCard: "Registration Card",
+  bankStatementOrSavingPassbook: "Bank Passbook",
+  tnbBills: "TNB Bills"
+};
+var EXTRACTABLE_DOC_TYPES = /* @__PURE__ */ new Set([
+  "bankStatements",
+  "financialStatements",
+  "form9",
+  "epfStatements",
+  "payslips",
+  "ssm",
+  "ic",
+  "ssm_registration_documents",
+  "ic_documents"
+]);
+var REUPLOADABLE_DOC_TYPES = /* @__PURE__ */ new Set(["bankStatements", "financialStatements"]);
+function getDocDisplayNames() {
+  return DOC_DISPLAY_NAMES;
+}
+function getExtractableDocTypes() {
+  return EXTRACTABLE_DOC_TYPES;
+}
+function getReuploadableDocTypes() {
+  return REUPLOADABLE_DOC_TYPES;
+}
+function isProbablyId(str) {
+  if (!str) return false;
+  const clean = str.split(".")[0];
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(clean)) return true;
+  if (/^[0-9a-f]{32,128}$/i.test(clean)) return true;
+  return false;
+}
+function parseFileField(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return Array.isArray(parsed) ? parsed : [];
+    } catch {
+      if (value.startsWith("http")) {
+        return [{ path: value, documentId: value.split("/").pop() || void 0 }];
+      }
+      return [];
+    }
+  }
+  return [];
+}
+function toBytes(value) {
+  if (typeof value === "number") return Number.isNaN(value) ? null : value;
+  if (typeof value === "string") {
+    const n = parseInt(value, 10);
+    return Number.isNaN(n) ? null : n;
+  }
+  return null;
+}
+function buildDocumentRows(ihsData) {
+  const metaMap = ihsData.documentMetadata ?? {};
+  const rows = [];
+  for (const docType of Object.keys(DOC_DISPLAY_NAMES)) {
+    const files = parseFileField(ihsData[docType]);
+    if (files.length === 0) continue;
+    const label = DOC_DISPLAY_NAMES[docType];
+    const extractable = EXTRACTABLE_DOC_TYPES.has(docType);
+    const reUploadable = extractable && REUPLOADABLE_DOC_TYPES.has(docType);
+    files.forEach((file, index) => {
+      const path = file.path ?? null;
+      const meta = path ? metaMap[path] : void 0;
+      const documentId = file.documentId || (path ? path.split("/").pop() || null : null);
+      const timePeriod = file.month ? `T${file.month}` : file.year ? `T${file.year}` : "ALL";
+      const rawName = file.fileName ?? meta?.fileName ?? void 0;
+      const fileName = rawName && !isProbablyId(rawName) ? rawName : null;
+      const rawExt = (rawName ?? "").split(".").pop();
+      const ext = rawExt && rawExt.length <= 5 && !isProbablyId(rawExt) ? rawExt.toUpperCase() : null;
+      const mime = file.fileType ?? meta?.fileType;
+      const fileType = ext || (mime?.split("/").pop()?.toUpperCase() ?? null);
+      const fileSize = toBytes(file.fileSize) ?? meta?.fileSize ?? null;
+      const uploadedAt = file.createdAt ?? meta?.createdAt ?? null;
+      const periodLabel = file.month && file.year ? new Date(file.year, file.month - 1).toLocaleDateString("en-MY", {
+        year: "numeric",
+        month: "short"
+      }) : file.year ? `Year ${file.year}` : null;
+      const displayName = fileName || (periodLabel ? `${label} \u2014 ${periodLabel}` : files.length > 1 ? `${label} ${index + 1}` : label);
+      rows.push({
+        docType,
+        label,
+        index,
+        displayName,
+        documentId,
+        path,
+        timePeriod,
+        periodLabel,
+        fileName,
+        fileType,
+        fileSize,
+        uploadedAt,
+        capabilities: {
+          download: !!documentId,
+          viewJson: extractable,
+          reExtract: extractable,
+          reUpload: reUploadable
+        }
+      });
+    });
+  }
+  return rows;
+}
+var EM_DASH = "\u2014";
+function formatDocumentType(row) {
+  return row.fileType ?? EM_DASH;
+}
+function formatDocumentSize(bytes) {
+  if (!bytes || Number.isNaN(bytes)) return EM_DASH;
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatDocumentUploaded(row) {
+  if (row.uploadedAt) {
+    const d = new Date(row.uploadedAt);
+    if (!Number.isNaN(d.getTime())) {
+      return d.toLocaleDateString("en-MY", { year: "numeric", month: "short", day: "numeric" });
+    }
+  }
+  return row.periodLabel ?? EM_DASH;
+}
 function isFileOrFinancialColumn(fieldName, fileColumnSet) {
   return fileColumnSet.has(fieldName) || fieldName.startsWith("financials") || fieldName.startsWith("bank_statement");
 }
@@ -10359,12 +10514,16 @@ export {
   applyAggregation,
   applyDynamicTitles,
   assertAdapterCategory,
+  buildDocumentRows,
   buildFileFieldTables,
   categoryFieldsOf,
   categoryForField,
   categorySchemaOf,
   evaluateExpression,
   extractTimePeriods,
+  formatDocumentSize,
+  formatDocumentType,
+  formatDocumentUploaded,
   generateRHFSchema,
   generateSurveyJson,
   getBaseCategories,
@@ -10374,9 +10533,12 @@ export {
   getCategoryName,
   getDisplayName,
   getDisplayNames,
+  getDocDisplayNames,
+  getExtractableDocTypes,
   getGroupDisplayNames,
   getPastMonthLabel,
   getPastYearLabel,
+  getReuploadableDocTypes,
   getStepDefaultValues,
   getStepSchema,
   groupColumnsByTimePeriod,
@@ -10387,6 +10549,7 @@ export {
   isFailureIhsStatus,
   isTerminalIhsStatus,
   isValidIhsStatus,
+  parseFileField,
   processIhsDetails,
   resolveExtractionStatus,
   resolvePageFields,