@finsys/core 2.4.0 → 2.6.0

package/dist/index.cjs

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ALL_AGGREGATION_OPS: () => ALL_AGGREGATION_OPS,
+  AdapterError: () => AdapterError,
   BASE_FIELD_SPECS: () => BASE_FIELD_SPECS,
   BasicFormField: () => BasicFormField,
   DEFAULT_VALIDATOR_DEFINITIONS: () => DEFAULT_VALIDATOR_DEFINITIONS,
@@ -50,8 +52,13 @@ __export(index_exports, {
   IhsStatus: () => IhsStatus,
   IhsValueFormat: () => IhsValueFormat,
   Role: () => Role,
+  allCategories: () => allCategories,
+  applyAggregation: () => applyAggregation,
   applyDynamicTitles: () => applyDynamicTitles,
   buildFileFieldTables: () => buildFileFieldTables,
+  categoryFieldsOf: () => categoryFieldsOf,
+  categoryForField: () => categoryForField,
+  categorySchemaOf: () => categorySchemaOf,
   evaluateExpression: () => evaluateExpression,
   extractTimePeriods: () => extractTimePeriods,
   generateRHFSchema: () => generateRHFSchema,
@@ -95,7 +102,7 @@ function getPastYearLabel(yearsAgo) {
   const date = /* @__PURE__ */ new Date();
   return (date.getFullYear() - yearsAgo).toString();
 }
-function evaluateExpression(expression, data) {
+function evaluateExpression(expression, data2) {
   if (!expression) return true;
   try {
     let jsExpression = expression.replace(/\{([^}]+)\}/g, (_, key) => {
@@ -119,7 +126,7 @@ function evaluateExpression(expression, data) {
       (_, ref, val) => `!(${ref} || []).includes('${val}')`
     );
     const func = new Function(`return ${jsExpression};`);
-    return !!func.call(data || {});
+    return !!func.call(data2 || {});
   } catch (e) {
     return false;
   }
@@ -265,16 +272,16 @@ function groupFieldsByCategory(fields, categories) {
 // src/rhf-generator.ts
 var import_zod = require("zod");
 function applyVisibilityValidation(baseObject, fields) {
-  return baseObject.superRefine((data, ctx) => {
+  return baseObject.superRefine((data2, ctx) => {
     fields.forEach((field) => {
       const isRequired = field.isRequired !== false && field.required !== false && field.type !== "html";
       if (!isRequired) return;
       let isVisible = field.visible !== false;
       if (isVisible && field.visibleIf) {
-        isVisible = evaluateExpression(field.visibleIf, data);
+        isVisible = evaluateExpression(field.visibleIf, data2);
       }
       if (isVisible) {
-        const value = data[field.name];
+        const value = data2[field.name];
         const isEmpty = value === void 0 || value === null || value === "" || Array.isArray(value) && value.length === 0;
         if (isEmpty) {
           ctx.addIssue({
@@ -735,22 +742,22 @@ var ajv = new Ajv({ allErrors: true, strict: false });
 var addFormatsFn = import_ajv_formats.default.default || import_ajv_formats.default;
 addFormatsFn(ajv);
 ajv.addSchema(unified_form_schema_default, "unified-form.schema.json");
-function validateFormConfig(data) {
+function validateFormConfig(data2) {
   const validate = ajv.getSchema("unified-form.schema.json");
   if (!validate) {
     return { valid: false, message: "Could not load unified form schema" };
   }
-  const valid = validate(data);
+  const valid = validate(data2);
   return {
     valid: !!valid,
     errors: validate.errors || void 0
   };
 }
-function validateFormSpec(data) {
-  return validateFormConfig(data);
+function validateFormSpec(data2) {
+  return validateFormConfig(data2);
 }
-function validatePagesConfig(data) {
-  return validateFormConfig(data);
+function validatePagesConfig(data2) {
+  return validateFormConfig(data2);
 }
 
 // src/form-field-category.ts
@@ -1207,10 +1214,10 @@ var _FormSpec = class _FormSpec {
     if (Array.isArray(jsonData.fields)) {
       fieldObjects = jsonData.fields;
     } else if (typeof jsonData.fields === "object" && jsonData.fields !== null) {
-      fieldObjects = Object.entries(jsonData.fields).map(([name, data]) => {
+      fieldObjects = Object.entries(jsonData.fields).map(([name, data2]) => {
         return {
           name,
-          ...data
+          ...data2
         };
       });
     }
@@ -7974,7 +7981,6 @@ var form_field_base_specs_default = {
       name: "bank_statement_t1",
       displayName: "Bank Statement (Month T-1)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "accountHolderNameT1",
         "statementDateT1",
@@ -7991,7 +7997,6 @@ var form_field_base_specs_default = {
       name: "bank_statement_t2",
       displayName: "Bank Statement (Month T-2)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "accountHolderNameT2",
         "statementDateT2",
@@ -8008,7 +8013,6 @@ var form_field_base_specs_default = {
       name: "bank_statement_t3",
       displayName: "Bank Statement (Month T-3)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "accountHolderNameT3",
         "statementDateT3",
@@ -8025,7 +8029,6 @@ var form_field_base_specs_default = {
       name: "bank_statement_t4",
       displayName: "Bank Statement (Month T-4)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "accountHolderNameT4",
         "statementDateT4",
@@ -8042,7 +8045,6 @@ var form_field_base_specs_default = {
       name: "bank_statement_t5",
       displayName: "Bank Statement (Month T-5)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "accountHolderNameT5",
         "statementDateT5",
@@ -8059,7 +8061,6 @@ var form_field_base_specs_default = {
       name: "bank_statement_t6",
       displayName: "Bank Statement (Month T-6)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "accountHolderNameT6",
         "statementDateT6",
@@ -8076,7 +8077,6 @@ var form_field_base_specs_default = {
       name: "financials",
       displayName: "Audited Financial Statement",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "shareCapital",
         "totalEquityT1",
@@ -8098,7 +8098,6 @@ var form_field_base_specs_default = {
       name: "financials_fincap_t1",
       displayName: "Audited Financial Statement (T-1) (FinCap)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "nonCurrentAssetsSubsidiaryCompaniesT1",
         "nonCurrentAssetsAssociatedCompaniesT1",
@@ -8343,7 +8342,6 @@ var form_field_base_specs_default = {
       name: "financials_fincap_t2",
       displayName: "Audited Financial Statement (T-2) (FinCap)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "nonCurrentAssetsSubsidiaryCompaniesT3",
         "nonCurrentAssetsAssociatedCompaniesT3",
@@ -8470,7 +8468,6 @@ var form_field_base_specs_default = {
       name: "form9",
       displayName: "Form 9 / Section 17 / Form D",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "incorporatedDate",
         "companyName",
@@ -8482,7 +8479,6 @@ var form_field_base_specs_default = {
       name: "ssm",
       displayName: "SSM Company Profile",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "ssmCompanyName",
         "ssmCompanyRegNo",
@@ -8507,7 +8503,6 @@ var form_field_base_specs_default = {
       name: "ic",
       displayName: "Identification Card (Front)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "icNumber",
         "icName",
@@ -8525,7 +8520,6 @@ var form_field_base_specs_default = {
       name: "epf_statement_t1",
       displayName: "Employees' Provident Fund (T-1)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "epfAccountHolderNameT1",
         "epfAccountHolderAddressT1",
@@ -8543,7 +8537,6 @@ var form_field_base_specs_default = {
       name: "epf_statement_t2",
       displayName: "Employees' Provident Fund (T-2)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "epfAccountHolderNameT2",
         "epfAccountHolderAddressT2",
@@ -8561,7 +8554,6 @@ var form_field_base_specs_default = {
       name: "payslip_statement_t1",
       displayName: "Payslip Statement (Month T-1)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "payslipEmployerNameT1",
         "payslipEmployeeNameT1",
@@ -8585,7 +8577,6 @@ var form_field_base_specs_default = {
       name: "payslip_statement_t2",
       displayName: "Payslip Statement (Month T-2)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "payslipEmployerNameT2",
         "payslipEmployeeNameT2",
@@ -8609,7 +8600,6 @@ var form_field_base_specs_default = {
       name: "payslip_statement_t3",
       displayName: "Payslip Statement (Month T-3)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "payslipEmployerNameT3",
         "payslipEmployeeNameT3",
@@ -8633,7 +8623,6 @@ var form_field_base_specs_default = {
       name: "payslip_statement_t4",
       displayName: "Payslip Statement (Month T-4)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "payslipEmployerNameT4",
         "payslipEmployeeNameT4",
@@ -8657,7 +8646,6 @@ var form_field_base_specs_default = {
       name: "payslip_statement_t5",
       displayName: "Payslip Statement (Month T-5)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "payslipEmployerNameT5",
         "payslipEmployeeNameT5",
@@ -8681,7 +8669,6 @@ var form_field_base_specs_default = {
       name: "payslip_statement_t6",
       displayName: "Payslip Statement (Month T-6)",
       type: "file",
-      enableIf: "{formOfDisclosure} contains 'consented'",
       ihs_column_names: [
         "payslipEmployerNameT6",
         "payslipEmployeeNameT6",
@@ -9488,18 +9475,18 @@ function buildTableForGroup(groupName, fields, ihsData) {
     const items = [];
     for (const [baseName, periodMap] of Object.entries(columnGroups)) {
       const numeric = isNumericField(baseName);
-      const data = {};
+      const data2 = {};
       const formattedData = {};
       for (const period of periods) {
         const colName = periodMap[period];
         const value = colName ? ihsData[colName] ?? null : null;
-        data[period] = value;
+        data2[period] = value;
         formattedData[period] = formatValue(value, numeric);
       }
       items.push({
         displayName: getDisplayName(baseName),
         timePeriods: periods,
-        data,
+        data: data2,
         formattedData,
         type: tableType,
         isNumeric: numeric
@@ -9856,8 +9843,254 @@ function resolveExtractionStatus(ihsRecord, jobRecords) {
   );
   return { documents, summary };
 }
+
+// src/adapter.ts
+var AdapterError = class extends Error {
+  constructor(reason, message, cause) {
+    super(message);
+    this.name = "AdapterError";
+    this.reason = reason;
+    this.cause = cause;
+  }
+};
+
+// src/adapter-aggregation.ts
+var ALL_AGGREGATION_OPS = [
+  "sum",
+  "mean",
+  "latest",
+  "max",
+  "count"
+];
+function applyAggregation(op, instances) {
+  if (instances.length === 0) {
+    return op === "count" ? 0 : null;
+  }
+  if (op === "count") {
+    return instances.reduce(
+      (acc, i) => i.value !== null && i.value !== void 0 ? acc + 1 : acc,
+      0
+    );
+  }
+  if (op === "latest") {
+    let pick = instances[0];
+    for (let i = 1; i < instances.length; i++) {
+      if (instances[i].observedAt > pick.observedAt) pick = instances[i];
+    }
+    return pick.value;
+  }
+  const nums = [];
+  for (const i of instances) {
+    if (typeof i.value === "number" && Number.isFinite(i.value)) {
+      nums.push(i.value);
+    } else if (i.value !== null && typeof i.value !== "undefined") {
+      throw new Error(
+        `applyAggregation: '${op}' requires numeric values; got ${typeof i.value}`
+      );
+    }
+  }
+  if (nums.length === 0) return null;
+  switch (op) {
+    case "sum":
+      return nums.reduce((a, b) => a + b, 0);
+    case "mean":
+      return nums.reduce((a, b) => a + b, 0) / nums.length;
+    case "max":
+      return nums.reduce((a, b) => a > b ? a : b);
+  }
+}
+
+// src/data/adapter-categories.json
+var adapter_categories_default = {
+  schemaVersion: "1.0.0",
+  categories: [
+    {
+      id: "telco-carrier",
+      displayName: "Telco Carrier",
+      description: "Mobile carrier bill-payment + account-history signals. Any telco vendor (Celcom, Maxis, DiGi, U-Mobile, etc.) implementing this category produces the same canonical field set.",
+      canonicalTable: "ihs_alt_data_telco",
+      fields: [
+        {
+          name: "telcoOnTimePaymentRatio24m",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of bills paid on time over the last 24 months. Strongest single telco predictor; \u22650.95 is the clean-history signal."
+        },
+        {
+          name: "telcoTenureMonths",
+          type: "number",
+          unit: "months",
+          range: [0, 600],
+          description: "Account age. \u226548 months is the thin-file uplift trigger."
+        },
+        {
+          name: "telcoSuspensionsCount24m",
+          type: "number",
+          unit: "count",
+          range: [0, 100],
+          description: "Non-payment-driven account suspensions in the last 24 months. \u22653 is a strong distress signal."
+        },
+        {
+          name: "telcoLateDays24m",
+          type: "number",
+          unit: "days",
+          range: [0, 800],
+          description: "Cumulative days late across all bills in the trailing 24-month window."
+        },
+        {
+          name: "telcoHandsetFinancingActive",
+          type: "boolean",
+          description: "Has an active handset-EMI account currently. Proxy for financing capacity already extended."
+        },
+        {
+          name: "telcoHandsetFinancingDelinquent",
+          type: "boolean",
+          description: "Recent handset-EMI delinquency in the last 24 months. Distress signal even with otherwise clean bill payment."
+        },
+        {
+          name: "telcoArpuMyr",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e4],
+          description: "Average Revenue Per User (monthly) in Malaysian Ringgit. Coarse spending-capacity proxy."
+        }
+      ]
+    },
+    {
+      id: "payment-network",
+      displayName: "Payment Network",
+      description: "Merchant-side payment-flow signals from POS / gateway networks (iPay88, GHL, etc.). Captures actual transaction velocity rather than self-reported revenue.",
+      canonicalTable: "ihs_alt_data_payments",
+      fields: [
+        {
+          name: "paymentsMonthlyVolumeMyrT3",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e8],
+          description: "Mean monthly inbound transaction volume (RM) over the trailing 3 months."
+        },
+        {
+          name: "paymentsMonthlyVolumeMyrT12",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e8],
+          description: "Mean monthly inbound transaction volume (RM) over the trailing 12 months. Pair with T3 for trend direction."
+        },
+        {
+          name: "paymentsArpuStability12m",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Coefficient-of-variation inverse over monthly ARPU in the trailing 12 months. Closer to 1 = steadier; closer to 0 = volatile."
+        },
+        {
+          name: "paymentsDisputeRate12m",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of transactions disputed or refunded in the trailing 12 months."
+        },
+        {
+          name: "paymentsCustomerConcentrationTop5Pct",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Revenue share from the top-5 recurring customers. Above ~0.7 is concentration risk."
+        },
+        {
+          name: "paymentsActiveTenureMonths",
+          type: "number",
+          unit: "months",
+          range: [0, 600],
+          description: "Months since first transaction on the payment network. Establishment / continuity proxy."
+        }
+      ]
+    },
+    {
+      id: "bank-statement",
+      displayName: "Bank Statement",
+      description: "Per-month bank-statement extractions. Naturally multi-instance: one statement per (account, month). Eval components typically aggregate across instances (sum closing balance, max debit, count of bounced transactions).",
+      canonicalTable: "ihs_alt_data_bank_statements",
+      fields: [
+        {
+          name: "bankStatementMonth",
+          type: "string",
+          description: "Statement period in YYYY-MM format. Used as the instance_key discriminator + by the `latest` aggregation operator."
+        },
+        {
+          name: "bankClosingBalanceMyr",
+          type: "number",
+          unit: "MYR",
+          range: [-1e8, 1e8],
+          description: "Closing balance for the statement period."
+        },
+        {
+          name: "bankTotalCreditsMyr",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e8],
+          description: "Sum of credit transactions during the period."
+        },
+        {
+          name: "bankTotalDebitsMyr",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e8],
+          description: "Sum of debit transactions during the period."
+        },
+        {
+          name: "bankLargestSingleCreditMyr",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e8],
+          description: "Largest single inbound transaction in the period. Useful for spotting one-off injections vs steady revenue."
+        },
+        {
+          name: "bankBouncedTransactionsCount",
+          type: "number",
+          unit: "count",
+          range: [0, 1e3],
+          description: "Bounced / returned transactions in the period. Distress signal at counts > 0."
+        }
+      ]
+    }
+  ]
+};
+
+// src/adapter-categories.ts
+var data = adapter_categories_default;
+function categorySchemaOf(id) {
+  const found = data.categories.find((c) => c.id === id);
+  if (!found) {
+    throw new Error(
+      `Unknown adapter category: ${id}. Available: ${data.categories.map((c) => c.id).join(", ")}`
+    );
+  }
+  return found;
+}
+function categoryFieldsOf(id) {
+  return categorySchemaOf(id).fields.map((f) => f.name);
+}
+function allCategories() {
+  return data.categories;
+}
+var fieldToCategory = (() => {
+  const m = /* @__PURE__ */ new Map();
+  for (const cat of data.categories) {
+    for (const f of cat.fields) {
+      m.set(f.name, cat.id);
+    }
+  }
+  return m;
+})();
+function categoryForField(field) {
+  return fieldToCategory.get(field) ?? null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ALL_AGGREGATION_OPS,
+  AdapterError,
   BASE_FIELD_SPECS,
   BasicFormField,
   DEFAULT_VALIDATOR_DEFINITIONS,
@@ -9878,8 +10111,13 @@ function resolveExtractionStatus(ihsRecord, jobRecords) {
   IhsStatus,
   IhsValueFormat,
   Role,
+  allCategories,
+  applyAggregation,
   applyDynamicTitles,
   buildFileFieldTables,
+  categoryFieldsOf,
+  categoryForField,
+  categorySchemaOf,
   evaluateExpression,
   extractTimePeriods,
   generateRHFSchema,