Designing APIs for Alternative Credit Scoring

// extract.mjs: Queries API, transforms metrics to canonical fields
const API_URL = process.env.TELCO_UPSTREAM_URL ?? "http://api-internal.telco:4100";
const API_KEY = process.env.TELCO_API_TOKEN ?? "prod-key-token";

const adapter = {
  id: "telco-carrier-adapter-v1",
  category: "telco-carrier",
  version: 1,
  produces: [
    "tenureMonths",
    "onTimePaymentRatio24m",
    "lateDays24m",
    "suspensionsCount24m",
    "arpu",
    "handsetFinancingActive",
    "handsetFinancingDelinquent"
  ],

  async fetch(identity) {
    if (!identity?.ic || !identity?.fullName) {
      throw new Error("Missing candidate identification details: ic/fullName");
    }
    const res = await fetch(`${API_URL}/v1/subscribers/lookup`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        "x-api-key": API_KEY
      },
      body: JSON.stringify({ ic: identity.ic, fullName: identity.fullName })
    });
    
    if (!res.ok) {
      throw new Error(`Telco lookup connection error: HTTP ${res.status}`);
    }
    return res.json();
  },

  async extract(raw) {
    const since = new Date(raw.subscriberSince);
    const now = new Date();
    const tenureMonths = Math.max(0, (now.getFullYear() - since.getFullYear()) * 12 + (now.getMonth() - since.getMonth()));
    
    const history = raw.paymentHistory ?? {};
    const onTime = Number(history.billsPaidOnTime ?? 0);
    const late = Number(history.billsPaidLate ?? 0);
    const unpaid = Number(history.billsUnpaid ?? 0);
    const total = onTime + late + unpaid;
    const onTimeRatio = total > 0 ? Number((onTime / total).toFixed(4)) : 0;
    
    // Assume an average of 15 late days per late bill instance
    const lateDays = late * 15;
    const suspensions = Number(history.suspensions ?? (unpaid > 0 ? 1 : 0));
    const handsetActive = Boolean(raw.handsetFinancing?.active ?? false);
    const handsetDelinquent = Boolean(raw.handsetFinancing?.delinquent ?? false);

    return [{
      instanceKey: "default",
      observedAt: new Date().toISOString(),
      values: {
        tenureMonths: tenureMonths,
        onTimePaymentRatio24m: onTimeRatio,
        lateDays24m: lateDays,
        suspensionsCount24m: suspensions,
        arpu: Number(raw.averageMonthlyArpuMyr ?? 0),
        handsetFinancingActive: handsetActive,
        handsetFinancingDelinquent: handsetDelinquent
      }
    }];
  }
};

export default adapter;

// test.mjs: Standard offline verification test block
import { runFixtures } from "@finsys/adapter-toolkit";
import adapter from "./extract.mjs";

const fixtures = [
  {
    name: "strong-subscriber",
    identity: { ihsId: 1, ic: "850101015432", fullName: "Aiman bin Hassan" },
    expected: [
      {
        instanceKey: "default",
        values: {
          onTimePaymentRatio24m: 1.0,
          suspensionsCount24m: 0
        }
      }
    ]
  }
];

const results = await runFixtures(adapter, fixtures);
console.log(results);
if (results.some(r => !r.ok)) {
  console.error("❌ Offline verification suite failed");
  process.exit(1);
} else {
  console.log("✅ All integration fixtures passed successfully");
}