@finsys/core 4.0.0 → 4.2.0

package/README.md

@@ -23,6 +23,10 @@ Partner-facing integration documentation lives in [`docs/`](./docs/):
 - **Visibility-Aware Validation** — Conditional fields are only validated when visible (`visibleIf` expressions)
 - **TypeScript-First** — Full type exports for all config types and generator outputs
 
+## Prerequisites
+
+This project targets Node 24.16.0 (see [`.nvmrc`](./.nvmrc)) and npm ≥ 12.0.1. After `nvm use`, upgrade npm with `npm install -g npm@12.0.1`.
+
 ## Installation
 
 ```bash

package/dist/index.cjs

@@ -47,6 +47,7 @@ __export(index_exports, {
   FormFieldValidator: () => FormFieldValidator,
   FormSpec: () => FormSpec,
   IHS_FAILURE_STATUSES: () => IHS_FAILURE_STATUSES,
+  IHS_FIELD_ORIGINS: () => IHS_FIELD_ORIGINS,
   IHS_TERMINAL_STATUSES: () => IHS_TERMINAL_STATUSES,
   IHS_VALID_STATUSES: () => IHS_VALID_STATUSES,
   IhsStatus: () => IhsStatus,
@@ -59,6 +60,7 @@ __export(index_exports, {
   assertDocumentType: () => assertDocumentType,
   buildDocumentRows: () => buildDocumentRows,
   buildFileFieldTables: () => buildFileFieldTables,
+  buildFileFieldTablesFromInstances: () => buildFileFieldTablesFromInstances,
   categoryFieldsOf: () => categoryFieldsOf,
   categoryForField: () => categoryForField,
   categorySchemaOf: () => categorySchemaOf,
@@ -85,6 +87,7 @@ __export(index_exports, {
   getReuploadableDocTypes: () => getReuploadableDocTypes,
   getStepDefaultValues: () => getStepDefaultValues,
   getStepSchema: () => getStepSchema,
+  groupColumnsByInstance: () => groupColumnsByInstance,
   groupColumnsByTimePeriod: () => groupColumnsByTimePeriod,
   groupDetailsByCategory: () => groupDetailsByCategory,
   groupFieldsByCategory: () => groupFieldsByCategory,
@@ -93,6 +96,7 @@ __export(index_exports, {
   isDocumentType: () => isDocumentType,
   isFailureIhsStatus: () => isFailureIhsStatus,
   isTerminalIhsStatus: () => isTerminalIhsStatus,
+  isValidIhsFieldOrigin: () => isValidIhsFieldOrigin,
   isValidIhsStatus: () => isValidIhsStatus,
   parseFileField: () => parseFileField,
   processIhsDetails: () => processIhsDetails,
@@ -9306,6 +9310,10 @@ var FileFieldTableType = /* @__PURE__ */ ((FileFieldTableType2) => {
   FileFieldTableType2["KEY_VALUE"] = "keyValue";
   return FileFieldTableType2;
 })(FileFieldTableType || {});
+var IHS_FIELD_ORIGINS = ["extracted", "derived", "manual"];
+function isValidIhsFieldOrigin(origin) {
+  return typeof origin === "string" && IHS_FIELD_ORIGINS.includes(origin);
+}
 
 // src/document-types.ts
 var cached = null;
@@ -9703,6 +9711,124 @@ function buildFileFieldTables(ihsData, fieldProvenance) {
   }
   return tables;
 }
+function instanceColumnLabel(row) {
+  const period = row.timePeriod || row.instanceKey;
+  return row.sourceLabel ? `${period} \xB7 ${row.sourceLabel}` : period;
+}
+function instanceColumnLabels(rows) {
+  const seenCounts = /* @__PURE__ */ new Map();
+  return rows.map((row) => {
+    const raw = instanceColumnLabel(row);
+    const occurrence = (seenCounts.get(raw) ?? 0) + 1;
+    seenCounts.set(raw, occurrence);
+    return occurrence === 1 ? raw : `${raw} (${occurrence})`;
+  });
+}
+function groupColumnsByInstance(baseColumnNames, instanceRows) {
+  const groups = {};
+  for (const baseName of baseColumnNames) {
+    groups[baseName] = {};
+  }
+  if (!instanceRows?.length) return groups;
+  const labels = instanceColumnLabels(instanceRows);
+  instanceRows.forEach((row, i) => {
+    const label = labels[i];
+    for (const baseName of baseColumnNames) {
+      if (Object.prototype.hasOwnProperty.call(row, baseName)) {
+        groups[baseName][label] = row[baseName];
+      }
+    }
+  });
+  return groups;
+}
+function buildInstanceTable(groupName, baseNames, groupDisplayName, instanceRows, fieldProvenance) {
+  const columnGroups = groupColumnsByInstance(baseNames, instanceRows);
+  const instanceLabels = instanceColumnLabels(instanceRows);
+  const items = [];
+  for (const [baseName, labelMap] of Object.entries(columnGroups)) {
+    const hasAny = Object.values(labelMap).some((v) => v !== null && v !== void 0 && v !== "");
+    if (!hasAny) continue;
+    const numeric = isNumericField(baseName);
+    const data = {};
+    const formattedData = {};
+    const confidence = {};
+    const provenance = {};
+    for (const [i, row] of instanceRows.entries()) {
+      const label = instanceLabels[i];
+      const value = labelMap[label] ?? null;
+      data[label] = value;
+      formattedData[label] = formatValue(value, numeric);
+      const legacyKey = row.timePeriod ? `${baseName}${row.timePeriod}` : void 0;
+      const prov = legacyKey ? fieldProvenance?.[legacyKey] : void 0;
+      if (prov) {
+        provenance[label] = prov;
+        if (prov.origin === "extracted" && typeof prov.confidence === "number" && !Number.isNaN(prov.confidence)) {
+          confidence[label] = prov.confidence;
+        }
+      }
+    }
+    items.push({
+      displayName: getDisplayName(baseName),
+      timePeriods: instanceLabels,
+      data,
+      formattedData,
+      type: "timeSeries" /* TIME_SERIES */,
+      isNumeric: numeric,
+      ...Object.keys(confidence).length ? { confidence } : {},
+      ...Object.keys(provenance).length ? { provenance } : {}
+    });
+  }
+  const hasData = items.some(
+    (item) => Object.values(item.data).some((v) => v !== null && v !== void 0 && v !== "")
+  );
+  if (!items.length || !hasData) return null;
+  return {
+    name: groupName,
+    displayName: groupDisplayName,
+    type: "timeSeries" /* TIME_SERIES */,
+    items,
+    hasData
+  };
+}
+function buildFileFieldTablesFromInstances(instancesByCategory = {}, fieldProvenance, categoryOverrides) {
+  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 instanceRows = instancesByCategory[groupName];
+    if (!instanceRows?.length) continue;
+    const baseNames = /* @__PURE__ */ new Set();
+    for (const field of fields) {
+      for (const col of field.ihs_column_names ?? []) {
+        baseNames.add(col.replace(TIME_PERIOD_REGEX, ""));
+      }
+    }
+    const groupDisplayName = getGroupDisplayNames()[groupName] || fields[0]?.displayName || getDisplayName(groupName);
+    const table = buildInstanceTable(
+      groupName,
+      [...baseNames],
+      groupDisplayName,
+      instanceRows,
+      fieldProvenance
+    );
+    if (table) tables[groupName] = table;
+  }
+  for (const [groupName, spec] of Object.entries(categoryOverrides ?? {})) {
+    if (Object.prototype.hasOwnProperty.call(tables, groupName)) continue;
+    const instanceRows = instancesByCategory[groupName];
+    if (!instanceRows?.length) continue;
+    const table = buildInstanceTable(
+      groupName,
+      spec.baseColumnNames,
+      spec.displayName,
+      instanceRows,
+      fieldProvenance
+    );
+    if (table) tables[groupName] = table;
+  }
+  return tables;
+}
 var DOC_DISPLAY_NAMES = {
   bankStatements: "Bank Statements",
   financialStatements: "Financial Statements",
@@ -9955,6 +10081,7 @@ var IhsStatus = /* @__PURE__ */ ((IhsStatus2) => {
   IhsStatus2["CreatingApplication"] = "CREATING_APPLICATION";
   IhsStatus2["ApplicationFinalized"] = "APPLICATION_FINALIZED";
   IhsStatus2["LenderEvaluation"] = "LENDER_EVALUATION";
+  IhsStatus2["EditingApplication"] = "EDITING_APPLICATION";
   IhsStatus2["Approved"] = "APPROVED";
   IhsStatus2["LouDelivered"] = "LOU_DELIVERED";
   IhsStatus2["AwaitingDisbursement"] = "AWAITING_DISBURSEMENT";
@@ -9968,6 +10095,7 @@ var IHS_VALID_STATUSES = [
   "CREATING_APPLICATION" /* CreatingApplication */,
   "APPLICATION_FINALIZED" /* ApplicationFinalized */,
   "LENDER_EVALUATION" /* LenderEvaluation */,
+  "EDITING_APPLICATION" /* EditingApplication */,
   "APPROVED" /* Approved */,
   "LOU_DELIVERED" /* LouDelivered */,
   "AWAITING_DISBURSEMENT" /* AwaitingDisbursement */,
@@ -10734,6 +10862,7 @@ function assertAdapterCategory(id) {
   FormFieldValidator,
   FormSpec,
   IHS_FAILURE_STATUSES,
+  IHS_FIELD_ORIGINS,
   IHS_TERMINAL_STATUSES,
   IHS_VALID_STATUSES,
   IhsStatus,
@@ -10746,6 +10875,7 @@ function assertAdapterCategory(id) {
   assertDocumentType,
   buildDocumentRows,
   buildFileFieldTables,
+  buildFileFieldTablesFromInstances,
   categoryFieldsOf,
   categoryForField,
   categorySchemaOf,
@@ -10772,6 +10902,7 @@ function assertAdapterCategory(id) {
   getReuploadableDocTypes,
   getStepDefaultValues,
   getStepSchema,
+  groupColumnsByInstance,
   groupColumnsByTimePeriod,
   groupDetailsByCategory,
   groupFieldsByCategory,
@@ -10780,6 +10911,7 @@ function assertAdapterCategory(id) {
   isDocumentType,
   isFailureIhsStatus,
   isTerminalIhsStatus,
+  isValidIhsFieldOrigin,
   isValidIhsStatus,
   parseFileField,
   processIhsDetails,