@finsys/core 2.7.0 → 3.2.0

package/README.md

@@ -3,7 +3,7 @@
 The shared contract layer for the FinSys ecosystem. Two distinct surfaces:
 
 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.
+2. **Source Adapter Framework** — vendor-agnostic contract for ingesting alternative-data sources (telco, payments, bank statements, social-media presence, etc.) into FinSys's canonical credit-signal vocabulary. Categories are a runtime registry loaded from a single data file (see [Category Reference](./docs/category-reference.md)).
 
 ## Building a Source Adapter?
 

package/dist/data/adapter-categories.json

@@ -4,7 +4,7 @@
     {
       "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": [
         {
@@ -57,7 +57,7 @@
     {
       "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": [
         {
@@ -151,6 +151,239 @@
           "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 — 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, 100000000],
+          "description": "Aggregate audience size across linked public profiles. Coarse reach / scale proxy — 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 — distinguishes an active business from a stale listing."
+        },
+        {
+          "name": "socialVerifiedBusinessAccount",
+          "type": "boolean",
+          "description": "Has at least one platform-verified business / commerce profile. Legitimacy signal — 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–5 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 — closer to formal credit history than most alternative data — 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 — 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 — 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, 1000000000],
+          "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 — one debtor default would materially impair cash flow."
+        },
+        {
+          "name": "tradeReferenceDefaults12m",
+          "type": "number",
+          "unit": "count",
+          "range": [0, 1000],
+          "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, 1000000000],
+          "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 − 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 — 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 — 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, 100000],
+          "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)."
+        }
+      ]
     }
   ]
 }