@finsys/core 2.5.0 → 2.7.0

package/README.md

@@ -1,8 +1,20 @@
 # @finsys/core
 
-Convert unified form configurations into Zod schemas, React Hook Form defaults, and SurveyJS JSON.
+The shared contract layer for the FinSys ecosystem. Two distinct surfaces:
 
-## Features
+1. **Unified form configuration** — generate Zod schemas, React Hook Form defaults, and SurveyJS JSON from a single JSON form spec.
+2. **Source Adapter Framework** — vendor-agnostic contract for ingesting alternative-data sources (telco, payments, bank statements, etc.) into FinSys's canonical credit-signal vocabulary.
+
+## Building a Source Adapter?
+
+Partner-facing integration documentation lives in [`docs/`](./docs/):
+
+- 📖 [**Adapter Authoring Guide**](./docs/adapter-authoring.md) — start here. Walks from "what's an adapter" through "how do I package and deliver one."
+- 📋 [Category Reference](./docs/category-reference.md) — canonical field set per category.
+- 📋 [Manifest Reference](./docs/manifest-reference.md) — every field in `manifest.json`.
+- 🔒 [Security Model](./docs/security-model.md) — sandboxing, secrets, network posture.
+
+## Features (form-config surface)
 
 - **Unified Form Configuration** — Single JSON format for defining form fields and multi-step page layouts
 - **React Hook Form Generator** — Generate Zod schemas, default values, and step configurations from a form config

package/dist/data/adapter-categories.json

@@ -0,0 +1,156 @@
+{
+  "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; ≥0.95 is the clean-history signal."
+        },
+        {
+          "name": "telcoTenureMonths",
+          "type": "number",
+          "unit": "months",
+          "range": [0, 600],
+          "description": "Account age. ≥48 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. ≥3 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, 10000],
+          "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, 100000000],
+          "description": "Mean monthly inbound transaction volume (RM) over the trailing 3 months."
+        },
+        {
+          "name": "paymentsMonthlyVolumeMyrT12",
+          "type": "number",
+          "unit": "MYR",
+          "range": [0, 100000000],
+          "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": [-100000000, 100000000],
+          "description": "Closing balance for the statement period."
+        },
+        {
+          "name": "bankTotalCreditsMyr",
+          "type": "number",
+          "unit": "MYR",
+          "range": [0, 100000000],
+          "description": "Sum of credit transactions during the period."
+        },
+        {
+          "name": "bankTotalDebitsMyr",
+          "type": "number",
+          "unit": "MYR",
+          "range": [0, 100000000],
+          "description": "Sum of debit transactions during the period."
+        },
+        {
+          "name": "bankLargestSingleCreditMyr",
+          "type": "number",
+          "unit": "MYR",
+          "range": [0, 100000000],
+          "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, 1000],
+          "description": "Bounced / returned transactions in the period. Distress signal at counts > 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
         };
       });
     }
@@ -9468,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
@@ -9836,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,
@@ -9858,8 +10111,13 @@ function resolveExtractionStatus(ihsRecord, jobRecords) {
   IhsStatus,
   IhsValueFormat,
   Role,
+  allCategories,
+  applyAggregation,
   applyDynamicTitles,
   buildFileFieldTables,
+  categoryFieldsOf,
+  categoryForField,
+  categorySchemaOf,
   evaluateExpression,
   extractTimePeriods,
   generateRHFSchema,