@finsys/core 3.5.0 → 4.0.0

package/dist/index.d.cts

@@ -519,8 +519,15 @@ declare function getDisplayNames(): Record<string, string>;
 declare function getDisplayName(fieldName: string): string;
 declare function extractTimePeriods(columnNames: string[]): string[];
 declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string, Record<string, string>>;
+/**
+ * Groups fields by their catalog-declared document_group (falling back to
+ * the field's own name for anything untagged). Was a hardcoded, closed
+ * prefix-matching table (FIELD_GROUP_PREFIXES) requiring a code edit for
+ * every new document type; now reads the same document_group tag the
+ * catalog already carries for document-types.ts, so adding a document
+ * type is a catalog-only data change.
+ */
 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>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
 /** IHS doc-field key → human label (the fields that become document sections). */
@@ -583,19 +590,56 @@ declare enum ExtractionJobStatus {
     Failed = "failed"
 }
 /**
- * Document types that go through FinXtract extraction.
- * Values must match the `type` field on finsys-api File entity
- * and the config keys in finXtractApi.api.
+ * Document types that go through FinXtract extraction. Values must match
+ * the `type` field on finsys-api's File entity and the config keys in
+ * finXtractApi.api.
+ *
+ * Was a closed enum (FinancialStatement/BankStatement/Epf/Payslip/Ssm/
+ * Form9/Ic) requiring a core release to add a new document type, even
+ * though nothing outside finsys-api's own request validation actually
+ * needed it to be a closed set (confirmed: zero external consumers
+ * import a specific member by name). Now an open string, matching the
+ * AdapterCategory precedent (SYS-2500) -- the authoritative set of valid
+ * values lives in document-types.ts, derived from the field-spec catalog.
+ * Use isDocumentType()/assertDocumentType() from document-types.ts for
+ * the runtime validation that used to be the enum's job.
  */
-declare enum ExtractionFileType {
-    FinancialStatement = "financialStatements",
-    BankStatement = "bankStatements",
-    Epf = "epfStatements",
-    Payslip = "payslips",
-    Ssm = "ssm",
-    Form9 = "form9",
-    Ic = "ic"
+type ExtractionFileType = string;
+
+type WireFormat = 'path_array' | 'url_string' | 'path_only';
+type TimePeriodUnit = 'month' | 'year';
+interface DocumentTypeGroup {
+    /** Wire/dispatch value, e.g. "bankStatements". */
+    readonly documentType: string;
+    /** Render/table grouping key, e.g. "ssm_documents". Distinct from documentType -- see module doc. */
+    readonly documentGroup: string;
+    /** Human-friendly label, e.g. "Bank Statements". */
+    readonly label: string;
+    /** Reserved for a future borrower-client payload-routing consolidation. Taken from the group's first entry; not enforced consistent across entries (all groups agree today, but a future mixed-format group would silently inherit the first entry's value). */
+    readonly wireFormat?: WireFormat;
+    /**
+     * The catalog's own `type: 'file'` entries belonging to this group, in
+     * catalog order. Each entry may carry its own document_slot/
+     * time_period_unit -- see TaggedFieldData and the module doc.
+     */
+    readonly fields: readonly TaggedFieldData[];
+}
+interface TaggedFieldData extends FieldData {
+    document_type?: string;
+    document_group?: string;
+    document_group_label?: string;
+    wire_format?: WireFormat;
+    /** Which upload position this field represents (1st document, 2nd, etc). See module doc for why this is distinct from a "time period". */
+    document_slot?: number;
+    /** What unit document_slot's number measures for this field. */
+    time_period_unit?: TimePeriodUnit;
 }
+/** Every registered document type, in catalog declaration order. */
+declare function getDocumentTypeGroups(): readonly DocumentTypeGroup[];
+/** True if `id` is a registered document type (the wire/dispatch value). */
+declare function isDocumentType(id: string): boolean;
+/** Returns `id` if it's a registered document type, otherwise throws. */
+declare function assertDocumentType(id: string): string;
 
 /**
  * IHS application status — canonical source of truth, mirroring finsys-api's
@@ -1348,4 +1392,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 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 };
+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 DocumentTypeGroup, type DropdownOption, type EditorValidator, type 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 TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.d.ts

@@ -519,8 +519,15 @@ declare function getDisplayNames(): Record<string, string>;
 declare function getDisplayName(fieldName: string): string;
 declare function extractTimePeriods(columnNames: string[]): string[];
 declare function groupColumnsByTimePeriod(columnNames: string[]): Record<string, Record<string, string>>;
+/**
+ * Groups fields by their catalog-declared document_group (falling back to
+ * the field's own name for anything untagged). Was a hardcoded, closed
+ * prefix-matching table (FIELD_GROUP_PREFIXES) requiring a code edit for
+ * every new document type; now reads the same document_group tag the
+ * catalog already carries for document-types.ts, so adding a document
+ * type is a catalog-only data change.
+ */
 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>, fieldProvenance?: Record<string, IhsFieldProvenance>): Record<string, FileFieldTableData>;
 /** IHS doc-field key → human label (the fields that become document sections). */
@@ -583,19 +590,56 @@ declare enum ExtractionJobStatus {
     Failed = "failed"
 }
 /**
- * Document types that go through FinXtract extraction.
- * Values must match the `type` field on finsys-api File entity
- * and the config keys in finXtractApi.api.
+ * Document types that go through FinXtract extraction. Values must match
+ * the `type` field on finsys-api's File entity and the config keys in
+ * finXtractApi.api.
+ *
+ * Was a closed enum (FinancialStatement/BankStatement/Epf/Payslip/Ssm/
+ * Form9/Ic) requiring a core release to add a new document type, even
+ * though nothing outside finsys-api's own request validation actually
+ * needed it to be a closed set (confirmed: zero external consumers
+ * import a specific member by name). Now an open string, matching the
+ * AdapterCategory precedent (SYS-2500) -- the authoritative set of valid
+ * values lives in document-types.ts, derived from the field-spec catalog.
+ * Use isDocumentType()/assertDocumentType() from document-types.ts for
+ * the runtime validation that used to be the enum's job.
  */
-declare enum ExtractionFileType {
-    FinancialStatement = "financialStatements",
-    BankStatement = "bankStatements",
-    Epf = "epfStatements",
-    Payslip = "payslips",
-    Ssm = "ssm",
-    Form9 = "form9",
-    Ic = "ic"
+type ExtractionFileType = string;
+
+type WireFormat = 'path_array' | 'url_string' | 'path_only';
+type TimePeriodUnit = 'month' | 'year';
+interface DocumentTypeGroup {
+    /** Wire/dispatch value, e.g. "bankStatements". */
+    readonly documentType: string;
+    /** Render/table grouping key, e.g. "ssm_documents". Distinct from documentType -- see module doc. */
+    readonly documentGroup: string;
+    /** Human-friendly label, e.g. "Bank Statements". */
+    readonly label: string;
+    /** Reserved for a future borrower-client payload-routing consolidation. Taken from the group's first entry; not enforced consistent across entries (all groups agree today, but a future mixed-format group would silently inherit the first entry's value). */
+    readonly wireFormat?: WireFormat;
+    /**
+     * The catalog's own `type: 'file'` entries belonging to this group, in
+     * catalog order. Each entry may carry its own document_slot/
+     * time_period_unit -- see TaggedFieldData and the module doc.
+     */
+    readonly fields: readonly TaggedFieldData[];
+}
+interface TaggedFieldData extends FieldData {
+    document_type?: string;
+    document_group?: string;
+    document_group_label?: string;
+    wire_format?: WireFormat;
+    /** Which upload position this field represents (1st document, 2nd, etc). See module doc for why this is distinct from a "time period". */
+    document_slot?: number;
+    /** What unit document_slot's number measures for this field. */
+    time_period_unit?: TimePeriodUnit;
 }
+/** Every registered document type, in catalog declaration order. */
+declare function getDocumentTypeGroups(): readonly DocumentTypeGroup[];
+/** True if `id` is a registered document type (the wire/dispatch value). */
+declare function isDocumentType(id: string): boolean;
+/** Returns `id` if it's a registered document type, otherwise throws. */
+declare function assertDocumentType(id: string): string;
 
 /**
  * IHS application status — canonical source of truth, mirroring finsys-api's
@@ -1348,4 +1392,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 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 };
+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 DocumentTypeGroup, type DropdownOption, type EditorValidator, type 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 TaggedFieldData, type TimePeriodUnit, type TypescriptImplementation, type UnifiedFormConfig, type Validator, type WireFormat, allCategories, applyAggregation, applyDynamicTitles, assertAdapterCategory, assertDocumentType, buildDocumentRows, buildFileFieldTables, categoryFieldsOf, categoryForField, categorySchemaOf, evaluateExpression, extractTimePeriods, formatDocumentSize, formatDocumentType, formatDocumentUploaded, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getDocDisplayNames, getDocumentTypeGroups, getExtractableDocTypes, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getReuploadableDocTypes, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isAdapterCategory, isDocumentType, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, parseFileField, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };