@finsys/core 2.3.0 → 2.4.0

package/dist/index.d.cts

@@ -469,6 +469,60 @@ declare enum ExtractionFileType {
     Ic = "ic"
 }
 
+/**
+ * IHS application status — canonical source of truth, mirroring finsys-api's
+ * `IHS_STATUS` enum and `allowedIhsStatus` list in src/utils/appHelper.ts.
+ *
+ * finsys-api originates these values (it writes them to the `ihs.status`
+ * column). Consumer apps (finhub-adonisjs, finsys-client) read them off the
+ * wire and use them for validation and display.
+ *
+ * Lender rejection is not represented by a distinct status: when a lender
+ * rejects an application, finsys-api transitions the record back to
+ * `APPLICATION_FINALIZED` from `LENDER_EVALUATION`.
+ */
+declare enum IhsStatus {
+    CreatingApplication = "CREATING_APPLICATION",
+    ApplicationFinalized = "APPLICATION_FINALIZED",
+    LenderEvaluation = "LENDER_EVALUATION",
+    Approved = "APPROVED",
+    LouDelivered = "LOU_DELIVERED",
+    AwaitingDisbursement = "AWAITING_DISBURSEMENT",
+    Disbursement = "DISBURSEMENT",
+    Declined = "DECLINED",
+    Expired = "EXPIRED",
+    Canceled = "CANCELED"
+}
+/**
+ * All valid IHS status values, in display order (earliest lifecycle stage
+ * first, terminal states last).
+ */
+declare const IHS_VALID_STATUSES: readonly IhsStatus[];
+/**
+ * Terminal statuses — the application lifecycle has completed and no further
+ * transitions are expected. Useful for suppressing action UI (e.g. re-extract,
+ * status update controls) on the application detail view.
+ */
+declare const IHS_TERMINAL_STATUSES: readonly IhsStatus[];
+/**
+ * Failure statuses — a subset of terminal statuses that represent an
+ * unsuccessful outcome. Useful for badge colour / messaging.
+ */
+declare const IHS_FAILURE_STATUSES: readonly IhsStatus[];
+/**
+ * Type guard: narrows an unknown value to `IhsStatus` iff it is one of the
+ * canonical status strings.
+ */
+declare function isValidIhsStatus(status: unknown): status is IhsStatus;
+/**
+ * Type guard: terminal (no further transitions expected).
+ */
+declare function isTerminalIhsStatus(status: unknown): status is IhsStatus;
+/**
+ * Type guard: terminal and unsuccessful.
+ */
+declare function isFailureIhsStatus(status: unknown): status is IhsStatus;
+
 declare enum DocExtractionStatus {
     NotUploaded = "not_uploaded",
     Uploaded = "uploaded",
@@ -504,6 +558,11 @@ interface ExtractionStatusResult {
 /**
  * Determines per-document extraction status from IHS record data.
  *
+ * For multi-file document types (bank statements, financial statements, EPF,
+ * payslips) the result contains one entry per uploaded file, indexed in the
+ * same order as the files appear in the IHS record's aggregate array.
+ * For single-file types (SSM, Form 9, IC) there is one entry.
+ *
  * @param ihsRecord - The IHS application record (any shape satisfying Record<string, unknown>)
  * @param jobRecords - Extraction job records for this IHS. Pass the array (even if empty)
  *   when job records were fetched. Omit or pass undefined when job records are unavailable;
@@ -511,4 +570,4 @@ interface ExtractionStatusResult {
  */
 declare function resolveExtractionStatus(ihsRecord: Record<string, unknown>, jobRecords?: ExtractionJobRecord[]): ExtractionStatusResult;
 
-export { BASE_FIELD_SPECS, BasicFormField, type Category, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, type IhsDetailCategory, type IhsFieldDetail, IhsValueFormat, type PageConfig, type RHFSchemaOutput, type RHFStep, type ResolvedField, Role, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type UnifiedFormConfig, type Validator, applyDynamicTitles, buildFileFieldTables, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { BASE_FIELD_SPECS, BasicFormField, type Category, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, 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 PageConfig, type RHFSchemaOutput, type RHFStep, type ResolvedField, Role, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type UnifiedFormConfig, type Validator, applyDynamicTitles, buildFileFieldTables, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.d.ts

@@ -469,6 +469,60 @@ declare enum ExtractionFileType {
     Ic = "ic"
 }
 
+/**
+ * IHS application status — canonical source of truth, mirroring finsys-api's
+ * `IHS_STATUS` enum and `allowedIhsStatus` list in src/utils/appHelper.ts.
+ *
+ * finsys-api originates these values (it writes them to the `ihs.status`
+ * column). Consumer apps (finhub-adonisjs, finsys-client) read them off the
+ * wire and use them for validation and display.
+ *
+ * Lender rejection is not represented by a distinct status: when a lender
+ * rejects an application, finsys-api transitions the record back to
+ * `APPLICATION_FINALIZED` from `LENDER_EVALUATION`.
+ */
+declare enum IhsStatus {
+    CreatingApplication = "CREATING_APPLICATION",
+    ApplicationFinalized = "APPLICATION_FINALIZED",
+    LenderEvaluation = "LENDER_EVALUATION",
+    Approved = "APPROVED",
+    LouDelivered = "LOU_DELIVERED",
+    AwaitingDisbursement = "AWAITING_DISBURSEMENT",
+    Disbursement = "DISBURSEMENT",
+    Declined = "DECLINED",
+    Expired = "EXPIRED",
+    Canceled = "CANCELED"
+}
+/**
+ * All valid IHS status values, in display order (earliest lifecycle stage
+ * first, terminal states last).
+ */
+declare const IHS_VALID_STATUSES: readonly IhsStatus[];
+/**
+ * Terminal statuses — the application lifecycle has completed and no further
+ * transitions are expected. Useful for suppressing action UI (e.g. re-extract,
+ * status update controls) on the application detail view.
+ */
+declare const IHS_TERMINAL_STATUSES: readonly IhsStatus[];
+/**
+ * Failure statuses — a subset of terminal statuses that represent an
+ * unsuccessful outcome. Useful for badge colour / messaging.
+ */
+declare const IHS_FAILURE_STATUSES: readonly IhsStatus[];
+/**
+ * Type guard: narrows an unknown value to `IhsStatus` iff it is one of the
+ * canonical status strings.
+ */
+declare function isValidIhsStatus(status: unknown): status is IhsStatus;
+/**
+ * Type guard: terminal (no further transitions expected).
+ */
+declare function isTerminalIhsStatus(status: unknown): status is IhsStatus;
+/**
+ * Type guard: terminal and unsuccessful.
+ */
+declare function isFailureIhsStatus(status: unknown): status is IhsStatus;
+
 declare enum DocExtractionStatus {
     NotUploaded = "not_uploaded",
     Uploaded = "uploaded",
@@ -504,6 +558,11 @@ interface ExtractionStatusResult {
 /**
  * Determines per-document extraction status from IHS record data.
  *
+ * For multi-file document types (bank statements, financial statements, EPF,
+ * payslips) the result contains one entry per uploaded file, indexed in the
+ * same order as the files appear in the IHS record's aggregate array.
+ * For single-file types (SSM, Form 9, IC) there is one entry.
+ *
  * @param ihsRecord - The IHS application record (any shape satisfying Record<string, unknown>)
  * @param jobRecords - Extraction job records for this IHS. Pass the array (even if empty)
  *   when job records were fetched. Omit or pass undefined when job records are unavailable;
@@ -511,4 +570,4 @@ interface ExtractionStatusResult {
  */
 declare function resolveExtractionStatus(ihsRecord: Record<string, unknown>, jobRecords?: ExtractionJobRecord[]): ExtractionStatusResult;
 
-export { BASE_FIELD_SPECS, BasicFormField, type Category, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldReference, FieldType, type FileFieldTableData, type FileFieldTableItem, FileFieldTableType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, type IhsDetailCategory, type IhsFieldDetail, IhsValueFormat, type PageConfig, type RHFSchemaOutput, type RHFStep, type ResolvedField, Role, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type UnifiedFormConfig, type Validator, applyDynamicTitles, buildFileFieldTables, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };
+export { BASE_FIELD_SPECS, BasicFormField, type Category, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DocExtractionResult, DocExtractionStatus, type DropdownOption, type EditorValidator, ExtractionFileType, type ExtractionJobRecord, ExtractionJobStatus, type ExtractionStatusResult, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, 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 PageConfig, type RHFSchemaOutput, type RHFStep, type ResolvedField, Role, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type UnifiedFormConfig, type Validator, applyDynamicTitles, buildFileFieldTables, evaluateExpression, extractTimePeriods, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecMap, getBaseFieldSpecs, getCategoryName, getDisplayName, getDisplayNames, getGroupDisplayNames, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupColumnsByTimePeriod, groupDetailsByCategory, groupFieldsByCategory, groupFieldsByPattern, isFailureIhsStatus, isTerminalIhsStatus, isValidIhsStatus, processIhsDetails, resolveExtractionStatus, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };

package/dist/index.js

@@ -9495,9 +9495,12 @@ function processIhsDetails(ihsData) {
   const specs = getBaseFieldSpecs();
   const fileColumnSet = /* @__PURE__ */ new Set();
   for (const field of specs) {
-    if (field.type === "file" && field.ihs_column_names) {
-      for (const col of field.ihs_column_names) {
-        fileColumnSet.add(col);
+    if (field.type === "file") {
+      if (field.name) fileColumnSet.add(field.name);
+      if (field.ihs_column_names) {
+        for (const col of field.ihs_column_names) {
+          fileColumnSet.add(col);
+        }
       }
     }
   }
@@ -9570,6 +9573,53 @@ var ExtractionFileType = /* @__PURE__ */ ((ExtractionFileType2) => {
   return ExtractionFileType2;
 })(ExtractionFileType || {});
 
+// src/ihs-status.ts
+var IhsStatus = /* @__PURE__ */ ((IhsStatus2) => {
+  IhsStatus2["CreatingApplication"] = "CREATING_APPLICATION";
+  IhsStatus2["ApplicationFinalized"] = "APPLICATION_FINALIZED";
+  IhsStatus2["LenderEvaluation"] = "LENDER_EVALUATION";
+  IhsStatus2["Approved"] = "APPROVED";
+  IhsStatus2["LouDelivered"] = "LOU_DELIVERED";
+  IhsStatus2["AwaitingDisbursement"] = "AWAITING_DISBURSEMENT";
+  IhsStatus2["Disbursement"] = "DISBURSEMENT";
+  IhsStatus2["Declined"] = "DECLINED";
+  IhsStatus2["Expired"] = "EXPIRED";
+  IhsStatus2["Canceled"] = "CANCELED";
+  return IhsStatus2;
+})(IhsStatus || {});
+var IHS_VALID_STATUSES = [
+  "CREATING_APPLICATION" /* CreatingApplication */,
+  "APPLICATION_FINALIZED" /* ApplicationFinalized */,
+  "LENDER_EVALUATION" /* LenderEvaluation */,
+  "APPROVED" /* Approved */,
+  "LOU_DELIVERED" /* LouDelivered */,
+  "AWAITING_DISBURSEMENT" /* AwaitingDisbursement */,
+  "DISBURSEMENT" /* Disbursement */,
+  "DECLINED" /* Declined */,
+  "EXPIRED" /* Expired */,
+  "CANCELED" /* Canceled */
+];
+var IHS_TERMINAL_STATUSES = [
+  "DISBURSEMENT" /* Disbursement */,
+  "DECLINED" /* Declined */,
+  "EXPIRED" /* Expired */,
+  "CANCELED" /* Canceled */
+];
+var IHS_FAILURE_STATUSES = [
+  "DECLINED" /* Declined */,
+  "EXPIRED" /* Expired */,
+  "CANCELED" /* Canceled */
+];
+function isValidIhsStatus(status) {
+  return typeof status === "string" && IHS_VALID_STATUSES.includes(status);
+}
+function isTerminalIhsStatus(status) {
+  return typeof status === "string" && IHS_TERMINAL_STATUSES.includes(status);
+}
+function isFailureIhsStatus(status) {
+  return typeof status === "string" && IHS_FAILURE_STATUSES.includes(status);
+}
+
 // src/extraction-status.ts
 var DocExtractionStatus = /* @__PURE__ */ ((DocExtractionStatus2) => {
   DocExtractionStatus2["NotUploaded"] = "not_uploaded";
@@ -9599,59 +9649,45 @@ function isPopulated(value) {
   if (value === "Not Specified") return false;
   return true;
 }
-function hasUploadedFile(fields, ihsRecord) {
-  return fields.some((field) => {
-    if (!field.name) return false;
-    return isPopulated(ihsRecord[field.name]);
-  });
-}
-function getExtractionColumns(fields) {
-  const columns = [];
-  for (const field of fields) {
-    if (field.ihs_column_names) {
-      columns.push(...field.ihs_column_names);
+function countUploadedFiles(ihsRecord, aggregateKey) {
+  const raw = ihsRecord[aggregateKey];
+  if (!raw) return 0;
+  if (typeof raw === "string") {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed.length;
+    } catch {
+      return 1;
     }
   }
-  return columns;
+  if (Array.isArray(raw)) return raw.length;
+  return 1;
 }
 function getPopulatedColumns(columns, ihsRecord) {
   return columns.filter((col) => isPopulated(ihsRecord[col]));
 }
-function resolveExtractionStatus(ihsRecord, jobRecords) {
-  const documents = [];
-  for (const fileType of Object.values(ExtractionFileType)) {
-    const groupName = FILE_TYPE_TO_GROUP[fileType];
-    const fields = _grouped[groupName] ?? [];
-    const displayName = _groupDisplayNames[groupName] ?? fileType;
-    const uploaded = fields.length > 0 && hasUploadedFile(fields, ihsRecord);
-    const allColumns = getExtractionColumns(fields);
-    const populated = getPopulatedColumns(allColumns, ihsRecord);
-    const hasExtractedData = populated.length > 0;
-    let status;
-    let errorMessage;
-    if (!uploaded) {
-      status = "not_uploaded" /* NotUploaded */;
-    } else if (jobRecords) {
-      const job = jobRecords.find((j) => j.fileType === fileType);
-      if (job) {
-        if (job.status === "queued" /* Queued */) {
-          status = "queued" /* Queued */;
-        } else if (job.status === "processing" /* Processing */) {
-          status = "processing" /* Processing */;
-        } else if (job.status === "failed" /* Failed */) {
-          if (hasExtractedData) {
-            status = "extracted" /* Extracted */;
-            errorMessage = job.errorMessage;
-          } else {
-            status = "failed" /* Failed */;
-            errorMessage = job.errorMessage;
-          }
-        } else if (job.status === "succeeded" /* Succeeded */ || hasExtractedData) {
+function resolveDocStatus(columns, ihsRecord, uploaded, jobRecord, hasJobRecords) {
+  const populated = getPopulatedColumns(columns, ihsRecord);
+  const hasExtractedData = populated.length > 0;
+  let status;
+  let errorMessage;
+  if (!uploaded) {
+    status = "not_uploaded" /* NotUploaded */;
+  } else if (hasJobRecords) {
+    if (jobRecord) {
+      if (jobRecord.status === "queued" /* Queued */) {
+        status = "queued" /* Queued */;
+      } else if (jobRecord.status === "processing" /* Processing */) {
+        status = "processing" /* Processing */;
+      } else if (jobRecord.status === "failed" /* Failed */) {
+        if (hasExtractedData) {
           status = "extracted" /* Extracted */;
+          errorMessage = jobRecord.errorMessage;
         } else {
-          status = "uploaded" /* Uploaded */;
+          status = "failed" /* Failed */;
+          errorMessage = jobRecord.errorMessage;
         }
-      } else if (hasExtractedData) {
+      } else if (jobRecord.status === "succeeded" /* Succeeded */ || hasExtractedData) {
         status = "extracted" /* Extracted */;
       } else {
         status = "uploaded" /* Uploaded */;
@@ -9659,16 +9695,68 @@ function resolveExtractionStatus(ihsRecord, jobRecords) {
     } else if (hasExtractedData) {
       status = "extracted" /* Extracted */;
     } else {
-      status = "unknown" /* Unknown */;
+      status = "uploaded" /* Uploaded */;
+    }
+  } else if (hasExtractedData) {
+    status = "extracted" /* Extracted */;
+  } else {
+    status = "unknown" /* Unknown */;
+  }
+  return { status, errorMessage };
+}
+function resolveExtractionStatus(ihsRecord, jobRecords) {
+  const documents = [];
+  const hasJobRecords = jobRecords !== void 0;
+  for (const fileType of Object.values(ExtractionFileType)) {
+    const groupName = FILE_TYPE_TO_GROUP[fileType];
+    const fields = _grouped[groupName] ?? [];
+    const displayName = _groupDisplayNames[groupName] ?? fileType;
+    const uploadedCount = countUploadedFiles(ihsRecord, fileType);
+    const isUploaded = uploadedCount > 0 || fields.some((f) => f.name && isPopulated(ihsRecord[f.name]));
+    const matchingJobs = jobRecords?.filter((j) => j.fileType === fileType) ?? [];
+    if (fields.length <= 1) {
+      const field = fields[0];
+      const columns = field?.ihs_column_names ?? [];
+      const populated = getPopulatedColumns(columns, ihsRecord);
+      const { status, errorMessage } = resolveDocStatus(
+        columns,
+        ihsRecord,
+        isUploaded,
+        matchingJobs[0],
+        hasJobRecords
+      );
+      documents.push({
+        fileType,
+        status,
+        displayName,
+        populatedColumns: populated,
+        totalColumns: columns.length,
+        errorMessage
+      });
+    } else {
+      const count = Math.max(uploadedCount, 1);
+      for (let idx = 0; idx < count; idx++) {
+        const field = fields[idx];
+        const columns = field?.ihs_column_names ?? [];
+        const populated = getPopulatedColumns(columns, ihsRecord);
+        const fileUploaded = idx < uploadedCount;
+        const { status, errorMessage } = resolveDocStatus(
+          columns,
+          ihsRecord,
+          fileUploaded,
+          matchingJobs[idx],
+          hasJobRecords
+        );
+        documents.push({
+          fileType,
+          status,
+          displayName,
+          populatedColumns: populated,
+          totalColumns: columns.length,
+          errorMessage
+        });
+      }
     }
-    documents.push({
-      fileType,
-      status,
-      displayName,
-      populatedColumns: populated,
-      totalColumns: allColumns.length,
-      errorMessage
-    });
   }
   const summary = documents.reduce(
     (acc, d) => {
@@ -9697,6 +9785,10 @@ export {
   FormFieldCategory,
   FormFieldValidator,
   FormSpec,
+  IHS_FAILURE_STATUSES,
+  IHS_TERMINAL_STATUSES,
+  IHS_VALID_STATUSES,
+  IhsStatus,
   IhsValueFormat,
   Role,
   applyDynamicTitles,
@@ -9721,6 +9813,9 @@ export {
   groupDetailsByCategory,
   groupFieldsByCategory,
   groupFieldsByPattern,
+  isFailureIhsStatus,
+  isTerminalIhsStatus,
+  isValidIhsStatus,
   processIhsDetails,
   resolveExtractionStatus,
   resolvePageFields,