@finsys/core 2.7.0 → 3.2.0

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ADAPTER_CATEGORY_IDS: () => ADAPTER_CATEGORY_IDS,
   ALL_AGGREGATION_OPS: () => ALL_AGGREGATION_OPS,
   AdapterError: () => AdapterError,
   BASE_FIELD_SPECS: () => BASE_FIELD_SPECS,
@@ -55,6 +56,7 @@ __export(index_exports, {
   allCategories: () => allCategories,
   applyAggregation: () => applyAggregation,
   applyDynamicTitles: () => applyDynamicTitles,
+  assertAdapterCategory: () => assertAdapterCategory,
   buildFileFieldTables: () => buildFileFieldTables,
   categoryFieldsOf: () => categoryFieldsOf,
   categoryForField: () => categoryForField,
@@ -79,6 +81,7 @@ __export(index_exports, {
   groupDetailsByCategory: () => groupDetailsByCategory,
   groupFieldsByCategory: () => groupFieldsByCategory,
   groupFieldsByPattern: () => groupFieldsByPattern,
+  isAdapterCategory: () => isAdapterCategory,
   isFailureIhsStatus: () => isFailureIhsStatus,
   isTerminalIhsStatus: () => isTerminalIhsStatus,
   isValidIhsStatus: () => isValidIhsStatus,
@@ -102,7 +105,7 @@ function getPastYearLabel(yearsAgo) {
   const date = /* @__PURE__ */ new Date();
   return (date.getFullYear() - yearsAgo).toString();
 }
-function evaluateExpression(expression, data2) {
+function evaluateExpression(expression, data) {
   if (!expression) return true;
   try {
     let jsExpression = expression.replace(/\{([^}]+)\}/g, (_, key) => {
@@ -126,7 +129,7 @@ function evaluateExpression(expression, data2) {
       (_, ref, val) => `!(${ref} || []).includes('${val}')`
     );
     const func = new Function(`return ${jsExpression};`);
-    return !!func.call(data2 || {});
+    return !!func.call(data || {});
   } catch (e) {
     return false;
   }
@@ -272,16 +275,16 @@ function groupFieldsByCategory(fields, categories) {
 // src/rhf-generator.ts
 var import_zod = require("zod");
 function applyVisibilityValidation(baseObject, fields) {
-  return baseObject.superRefine((data2, ctx) => {
+  return baseObject.superRefine((data, 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, data2);
+        isVisible = evaluateExpression(field.visibleIf, data);
       }
       if (isVisible) {
-        const value = data2[field.name];
+        const value = data[field.name];
         const isEmpty = value === void 0 || value === null || value === "" || Array.isArray(value) && value.length === 0;
         if (isEmpty) {
           ctx.addIssue({
@@ -742,22 +745,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(data2) {
+function validateFormConfig(data) {
   const validate = ajv.getSchema("unified-form.schema.json");
   if (!validate) {
     return { valid: false, message: "Could not load unified form schema" };
   }
-  const valid = validate(data2);
+  const valid = validate(data);
   return {
     valid: !!valid,
     errors: validate.errors || void 0
   };
 }
-function validateFormSpec(data2) {
-  return validateFormConfig(data2);
+function validateFormSpec(data) {
+  return validateFormConfig(data);
 }
-function validatePagesConfig(data2) {
-  return validateFormConfig(data2);
+function validatePagesConfig(data) {
+  return validateFormConfig(data);
 }
 
 // src/form-field-category.ts
@@ -1214,10 +1217,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, data2]) => {
+      fieldObjects = Object.entries(jsonData.fields).map(([name, data]) => {
         return {
           name,
-          ...data2
+          ...data
         };
       });
     }
@@ -9475,18 +9478,18 @@ function buildTableForGroup(groupName, fields, ihsData) {
     const items = [];
     for (const [baseName, periodMap] of Object.entries(columnGroups)) {
       const numeric = isNumericField(baseName);
-      const data2 = {};
+      const data = {};
       const formattedData = {};
       for (const period of periods) {
         const colName = periodMap[period];
         const value = colName ? ihsData[colName] ?? null : null;
-        data2[period] = value;
+        data[period] = value;
         formattedData[period] = formatValue(value, numeric);
       }
       items.push({
         displayName: getDisplayName(baseName),
         timePeriods: periods,
-        data: data2,
+        data,
         formattedData,
         type: tableType,
         isNumeric: numeric
@@ -9907,7 +9910,7 @@ var adapter_categories_default = {
     {
       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.",
+      description: "Mobile carrier bill-payment + account-history signals. Any mobile carrier implementing this category produces the same canonical field set.",
       canonicalTable: "ihs_alt_data_telco",
       fields: [
         {
@@ -9960,7 +9963,7 @@ var adapter_categories_default = {
     {
       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.",
+      description: "Merchant-side payment-flow signals from POS / payment-gateway networks. Captures actual transaction velocity rather than self-reported revenue.",
       canonicalTable: "ihs_alt_data_payments",
       fields: [
         {
@@ -10054,17 +10057,352 @@ var adapter_categories_default = {
           description: "Bounced / returned transactions in the period. Distress signal at counts > 0."
         }
       ]
+    },
+    {
+      id: "social-media",
+      displayName: "Social Media Presence",
+      description: "Public business-presence signals from social / commerce platforms \u2014 establishment, reach, engagement authenticity, customer reputation, and account standing. Vendor-agnostic: any platform exposing a public business profile maps its data to this canonical field set. Useful as thin-file corroboration of a borrower's operating reality where formal financials are sparse.",
+      canonicalTable: "ihs_alt_data_social_media",
+      fields: [
+        {
+          name: "socialAccountTenureMonths",
+          type: "number",
+          unit: "months",
+          range: [0, 600],
+          description: "Age of the oldest verified public business presence across linked profiles. Establishment / continuity proxy, parallel to telco + payment-network tenure."
+        },
+        {
+          name: "socialFollowerCount",
+          type: "number",
+          unit: "count",
+          range: [0, 1e8],
+          description: "Aggregate audience size across linked public profiles. Coarse reach / scale proxy \u2014 gameable on its own, so read alongside socialEngagementRate90d."
+        },
+        {
+          name: "socialEngagementRate90d",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Mean interactions per impression over the trailing 90 days. Authenticity signal: a large follower count with near-zero engagement indicates a bought or dormant audience."
+        },
+        {
+          name: "socialPostingConsistency12m",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of weeks in the trailing 12 months with at least one public post. Ongoing-operation signal \u2014 distinguishes an active business from a stale listing."
+        },
+        {
+          name: "socialVerifiedBusinessAccount",
+          type: "boolean",
+          description: "Has at least one platform-verified business / commerce profile. Legitimacy signal \u2014 the platform has performed its own business-identity check."
+        },
+        {
+          name: "socialCustomerRatingAvg",
+          type: "number",
+          unit: "rating",
+          range: [0, 5],
+          description: "Mean public customer rating (normalised to a 0\u20135 scale) across review-bearing profiles. Reputation signal; especially predictive for consumer-facing SMEs."
+        },
+        {
+          name: "socialNegativeSentimentRatio90d",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of public mentions / reviews classified as negative over the trailing 90 days. Reputation-risk / distress signal independent of overall rating volume."
+        },
+        {
+          name: "socialAccountFlags24m",
+          type: "number",
+          unit: "count",
+          range: [0, 100],
+          description: "Policy strikes, suspensions, or content takedowns across linked profiles in the last 24 months. Distress signal, parallel to telcoSuspensionsCount24m."
+        }
+      ]
+    },
+    {
+      id: "trade-credit",
+      displayName: "Trade Credit (Accounting)",
+      description: "Accounts-receivable / accounts-payable aging and ledger-derived working-capital signals sourced from a business's accounting / ERP system. Captures how promptly the business collects from its debtors and pays its creditors, the aging profile and concentration of its receivables, and P&L / cash-conversion efficiency. Vendor-agnostic: any accounting or ERP system that exposes an AR/AP aging report plus a P&L summary maps its data to this canonical field set. A direct, high-signal view of trade-obligation behaviour \u2014 closer to formal credit history than most alternative data \u2014 and the anchor for cross-referencing self-reported accounting figures against bank-statement reality.",
+      canonicalTable: "ihs_alt_data_trade_credit",
+      fields: [
+        {
+          name: "arDaysSalesOutstanding",
+          type: "number",
+          unit: "days",
+          range: [0, 400],
+          description: "Days Sales Outstanding \u2014 average days to collect a receivable. The headline collection-efficiency metric; lower is healthier, and a rising DSO is an early liquidity-stress signal."
+        },
+        {
+          name: "apDaysPayableOutstanding",
+          type: "number",
+          unit: "days",
+          range: [0, 400],
+          description: "Days Payable Outstanding \u2014 average days the business takes to pay its suppliers. Context for DSO; a very high DPO can indicate the business is stretching its creditors to fund operations."
+        },
+        {
+          name: "arTotalOutstandingMyr",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e9],
+          description: "Total accounts-receivable balance outstanding (RM). The size of the debtor book the business is carrying."
+        },
+        {
+          name: "arCurrentRatio",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of the receivables book that is current (within payment terms, not yet overdue). Higher is healthier; the complement is the overdue share across all aging buckets."
+        },
+        {
+          name: "arOverdue90PlusRatio",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of the receivables book aged more than 90 days past terms. The key impairment / bad-debt risk signal from the AR aging report; elevated values indicate collection difficulty."
+        },
+        {
+          name: "debtorConcentrationTop5Ratio",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Share of total receivables owed by the top-5 debtors. Above ~0.6 is single-customer concentration risk \u2014 one debtor default would materially impair cash flow."
+        },
+        {
+          name: "tradeReferenceDefaults12m",
+          type: "number",
+          unit: "count",
+          range: [0, 1e3],
+          description: "Count of supplier-reported defaults or dishonoured / returned payments against the business in the trailing 12 months. Direct distress signal, parallel to a bureau default record."
+        },
+        {
+          name: "accountingRevenue12mMyr",
+          type: "number",
+          unit: "MYR",
+          range: [0, 1e9],
+          description: "Trailing-12-month turnover per the general ledger (RM). The cross-reference anchor: comparing this self-reported accounting revenue against payment-network volume and bank-statement inflows surfaces book-vs-reality inconsistencies."
+        },
+        {
+          name: "grossMarginPct",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Gross margin from the P&L (gross profit / revenue). Profitability-quality signal; a thin or declining margin constrains debt-service capacity even at healthy revenue."
+        },
+        {
+          name: "cashConversionCycleDays",
+          type: "number",
+          unit: "days",
+          range: [-200, 600],
+          description: "Cash Conversion Cycle (DSO + days-inventory-outstanding \u2212 DPO). Working-capital efficiency; negative values (collect before paying suppliers) are strongest, very high values indicate cash tied up in operations."
+        }
+      ]
+    },
+    {
+      id: "geolocation",
+      displayName: "Geolocation",
+      description: "Hourly-granularity movement track plus derived mobility signals for an applicant, sourced from any location-capable provider (telco network location, mobile-SDK GPS, GIS / address-verification services). Two instance kinds share this category: point instances (instanceKey 'pt:<ISO-hour>') carry one observed position per hourly bucket, mirroring the bank-statement multi-instance pattern; a single summary instance (instanceKey 'summary') carries adapter-derived behaviour signals \u2014 most importantly work-pattern regularity (sustained weekday dwell at a stable work anchor corroborates income reliability), residential stability, vacation windows, and dwell in operator-flagged hotspot zones. Vendor-agnostic: the source classifies or the adapter infers place labels; no provider-specific semantics leak into the field set. Raw coordinates are sensitive personal data \u2014 product-plane persistence is gated on PDPA consent + CRA Act 710 s25 retention review.",
+      canonicalTable: "ihs_alt_data_geolocation",
+      fields: [
+        {
+          name: "geoLatitude",
+          type: "number",
+          unit: "deg",
+          range: [-90, 90],
+          description: "Observed latitude for this hourly bucket (point instances only)."
+        },
+        {
+          name: "geoLongitude",
+          type: "number",
+          unit: "deg",
+          range: [-180, 180],
+          description: "Observed longitude for this hourly bucket (point instances only)."
+        },
+        {
+          name: "geoAccuracyM",
+          type: "number",
+          unit: "meters",
+          range: [0, 1e5],
+          description: "Source-reported horizontal accuracy radius of the observation. Cell-tower fixes are typically hundreds of meters; GPS fixes tens."
+        },
+        {
+          name: "geoBucket",
+          type: "string",
+          description: "ISO-8601 hour bucket of the observation, e.g. '2026-06-01T08'. Redundant with the instance key (pt:<bucket>) so consumers can query without parsing keys."
+        },
+        {
+          name: "geoPlaceLabel",
+          type: "string",
+          description: "Classified place for the bucket: home | work | commute | leisure | travel | hotspot | other. Classified by the source or inferred by the adapter from anchor dwell."
+        },
+        {
+          name: "geoWorkAttendanceRatio30d",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Fraction of the last 30 weekdays with >= 6 hours of dwell at the inferred work anchor. The income-reliability headline: regular full-time work patterns corroborate declared employment income (summary instance only)."
+        },
+        {
+          name: "geoWorkDailyHoursAvg30d",
+          type: "number",
+          unit: "hours",
+          range: [0, 24],
+          description: "Mean daily hours of work-anchor dwell across the last 30 weekdays (summary instance only)."
+        },
+        {
+          name: "geoLocationStabilityScore",
+          type: "number",
+          unit: "score",
+          range: [0, 1],
+          description: "Residential stability: share of nights spent at the primary home anchor over the observation window. 1 = every night at home (summary instance only)."
+        },
+        {
+          name: "geoCommuteRegularityRatio",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Consistency of the weekday home->work->home rhythm: fraction of weekdays matching the dominant commute pattern within an hour's tolerance (summary instance only)."
+        },
+        {
+          name: "geoVacationDays90d",
+          type: "number",
+          unit: "days",
+          range: [0, 90],
+          description: "Days in the last 90 spent fully away from both home and work anchors (contiguous travel windows; summary instance only)."
+        },
+        {
+          name: "geoHotspotDwellRatio",
+          type: "number",
+          unit: "ratio",
+          range: [0, 1],
+          description: "Share of observed buckets spent inside operator-flagged hotspot zones (known fraud / illicit-activity locations supplied to the adapter). Non-zero values warrant review, not automatic decline (summary instance only)."
+        },
+        {
+          name: "geoPrimaryStateCode",
+          type: "string",
+          description: "Malaysian state / federal-territory code of the primary home anchor, e.g. PNG, KUL, JHR (summary instance only)."
+        },
+        {
+          name: "geoAddressMatchScore",
+          type: "number",
+          unit: "score",
+          range: [0, 1],
+          description: "Agreement between the inferred home anchor and the applicant's registered residential address. 1 = same premises, 0 = different state (summary instance only)."
+        }
+      ]
     }
   ]
 };
 
 // src/adapter-categories.ts
-var data = adapter_categories_default;
+var VALID_FIELD_TYPES = [
+  "number",
+  "boolean",
+  "string"
+];
+function buildCategoryRegistry(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("adapter category data: expected an object");
+  }
+  if (typeof raw.schemaVersion !== "string" || raw.schemaVersion.length === 0) {
+    throw new Error("adapter category data: missing schemaVersion");
+  }
+  if (!Array.isArray(raw.categories) || raw.categories.length === 0) {
+    throw new Error("adapter category data: categories must be a non-empty array");
+  }
+  const byId = /* @__PURE__ */ new Map();
+  const fieldToCategory = /* @__PURE__ */ new Map();
+  const tables = /* @__PURE__ */ new Set();
+  const all = [];
+  for (const cat of raw.categories) {
+    const where = `category "${cat?.id ?? "<unknown>"}"`;
+    if (typeof cat.id !== "string" || cat.id.length === 0) {
+      throw new Error("adapter category data: every category needs a non-empty id");
+    }
+    if (byId.has(cat.id)) {
+      throw new Error(`adapter category data: duplicate category id "${cat.id}"`);
+    }
+    if (typeof cat.displayName !== "string" || cat.displayName.length === 0) {
+      throw new Error(`adapter category data: ${where} needs a non-empty displayName`);
+    }
+    if (typeof cat.description !== "string" || cat.description.length === 0) {
+      throw new Error(`adapter category data: ${where} needs a non-empty description`);
+    }
+    if (typeof cat.canonicalTable !== "string" || !/^ihs_alt_data_/.test(cat.canonicalTable)) {
+      throw new Error(
+        `adapter category data: ${where} canonicalTable must start with "ihs_alt_data_" (got "${cat.canonicalTable}")`
+      );
+    }
+    if (tables.has(cat.canonicalTable)) {
+      throw new Error(
+        `adapter category data: duplicate canonicalTable "${cat.canonicalTable}" (${where})`
+      );
+    }
+    if (!Array.isArray(cat.fields) || cat.fields.length === 0) {
+      throw new Error(`adapter category data: ${where} must declare at least one field`);
+    }
+    const fields = [];
+    for (const f of cat.fields) {
+      if (typeof f.name !== "string" || f.name.length === 0) {
+        throw new Error(`adapter category data: ${where} has a field with no name`);
+      }
+      if (fieldToCategory.has(f.name)) {
+        throw new Error(
+          `adapter category data: canonical field "${f.name}" declared by more than one category (${fieldToCategory.get(f.name)} + ${cat.id}) \u2014 field names must be globally unique`
+        );
+      }
+      if (!VALID_FIELD_TYPES.includes(f.type)) {
+        throw new Error(
+          `adapter category data: field "${f.name}" (${where}) has invalid type "${f.type}"`
+        );
+      }
+      if (typeof f.description !== "string" || f.description.length === 0) {
+        throw new Error(
+          `adapter category data: field "${f.name}" (${where}) needs a non-empty description`
+        );
+      }
+      if (f.range !== void 0) {
+        if (!Array.isArray(f.range) || f.range.length !== 2 || !Number.isFinite(f.range[0]) || !Number.isFinite(f.range[1]) || f.range[0] > f.range[1]) {
+          throw new Error(
+            `adapter category data: field "${f.name}" (${where}) has an invalid range \u2014 expected [lo, hi] with finite lo <= hi`
+          );
+        }
+      }
+      const spec = Object.freeze({
+        name: f.name,
+        type: f.type,
+        ...f.unit !== void 0 ? { unit: f.unit } : {},
+        ...f.range !== void 0 ? { range: Object.freeze([f.range[0], f.range[1]]) } : {},
+        description: f.description
+      });
+      fields.push(spec);
+      fieldToCategory.set(f.name, cat.id);
+    }
+    const schema = Object.freeze({
+      id: cat.id,
+      displayName: cat.displayName,
+      description: cat.description,
+      canonicalTable: cat.canonicalTable,
+      fields: Object.freeze(fields)
+    });
+    byId.set(cat.id, schema);
+    tables.add(cat.canonicalTable);
+    all.push(schema);
+  }
+  return Object.freeze({
+    all: Object.freeze(all),
+    ids: Object.freeze(all.map((c) => c.id)),
+    byId,
+    fieldToCategory
+  });
+}
+var registry = buildCategoryRegistry(adapter_categories_default);
+var ADAPTER_CATEGORY_IDS = registry.ids;
 function categorySchemaOf(id) {
-  const found = data.categories.find((c) => c.id === id);
+  const found = registry.byId.get(id);
   if (!found) {
     throw new Error(
-      `Unknown adapter category: ${id}. Available: ${data.categories.map((c) => c.id).join(", ")}`
+      `Unknown adapter category: ${id}. Available: ${registry.ids.join(", ")}`
     );
   }
   return found;
@@ -10073,22 +10411,25 @@ function categoryFieldsOf(id) {
   return categorySchemaOf(id).fields.map((f) => f.name);
 }
 function allCategories() {
-  return data.categories;
+  return registry.all;
 }
-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;
+  return registry.fieldToCategory.get(field) ?? null;
+}
+function isAdapterCategory(id) {
+  return registry.byId.has(id);
+}
+function assertAdapterCategory(id) {
+  if (!registry.byId.has(id)) {
+    throw new Error(
+      `Unknown adapter category: ${id}. Available: ${registry.ids.join(", ")}`
+    );
+  }
+  return id;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ADAPTER_CATEGORY_IDS,
   ALL_AGGREGATION_OPS,
   AdapterError,
   BASE_FIELD_SPECS,
@@ -10114,6 +10455,7 @@ function categoryForField(field) {
   allCategories,
   applyAggregation,
   applyDynamicTitles,
+  assertAdapterCategory,
   buildFileFieldTables,
   categoryFieldsOf,
   categoryForField,
@@ -10138,6 +10480,7 @@ function categoryForField(field) {
   groupDetailsByCategory,
   groupFieldsByCategory,
   groupFieldsByPattern,
+  isAdapterCategory,
   isFailureIhsStatus,
   isTerminalIhsStatus,
   isValidIhsStatus,