Designing APIs for B2B Alternative Credit Scoring

// extract.mjs: Queries API, transforms metrics to canonical fields
const API_URL = process.env.FAKE_TRADE_CREDIT_API_URL ?? "http://fake-trade-credit-api:4300";
const API_KEY = process.env.FAKE_TRADE_CREDIT_API_KEY ?? "demo-key";

const round4 = (n) => Number(n.toFixed(4));
const ratio = (num, den) => (den > 0 ? round4(num / den) : 0);

const adapter = {
  id: "trade-credit-adapter-v1",
  category: "trade-credit",
  version: 1,
  produces: [
    "arDaysSalesOutstanding",
    "apDaysPayableOutstanding",
    "arTotalOutstanding",
    "arCurrentRatio",
    "arOverdue90PlusRatio",
    "debtorConcentrationTop5Ratio",
    "tradeReferenceDefaults12m",
    "accountingRevenue12m",
    "grossMarginPct",
    "cashConversionCycleDays"
  ],

  async fetch(identity) {
    if (!identity?.ic || !identity?.fullName) {
      throw new Error("fake-trade-credit-v1: identity.ic and identity.fullName are required");
    }
    const res = await fetch(`${API_URL}/v1/accounts/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(`fake-trade-credit-v1 fetch failed: HTTP ${res.status}`);
    }
    return res.json();
  },

  async extract(raw) {
    const ar = raw.accountsReceivable ?? {};
    const aging = ar.aging ?? {};
    const total = Number(ar.totalMyr ?? 0);
    const pnl = raw.incomeStatement12m ?? {};
    const revenue = Number(pnl.revenueMyr ?? 0);
    const cogs = Number(pnl.cogsMyr ?? 0);

    return [{
      instanceKey: "default",
      observedAt: new Date().toISOString(),
      values: {
        arDaysSalesOutstanding: Number(raw.metrics?.daysSalesOutstanding ?? 0),
        apDaysPayableOutstanding: Number(raw.accountsPayable?.avgDaysOutstanding ?? 0),
        arTotalOutstanding: total,
        arCurrentRatio: ratio(Number(aging.current ?? 0), total),
        arOverdue90PlusRatio: ratio(Number(aging.d90plus ?? 0), total),
        debtorConcentrationTop5Ratio: round4(Number(ar.top5DebtorShareRatio ?? 0)),
        tradeReferenceDefaults12m: Number(raw.tradeReferences?.defaults12m ?? 0),
        accountingRevenue12m: revenue,
        grossMarginPct: ratio(revenue - cogs, revenue),
        cashConversionCycleDays: Number(raw.metrics?.cashConversionCycleDays ?? 0)
      }
    }];
  }
};

export default adapter;

// test.mjs: Offline verification tests
import { runFixtures } from "@finsys/adapter-toolkit";
import adapter from "./extract.mjs";

const fixtures = [
  {
    name: "aiman-hassan-ledger",
    identity: { ihsId: 1, ic: "850101015432", fullName: "Aiman bin Hassan" },
    expected: [
      {
        instanceKey: "default",
        values: {
          arDaysSalesOutstanding: 28,
          accountingRevenue12m: 2400000
        }
      }
    ]
  }
];

const results = await runFixtures(adapter, fixtures);
console.log(results);
if (results.some(r => !r.ok)) {
  console.error("❌ Trade Credit tests failed");
  process.exit(1);
} else {
  console.log("✅ Trade Credit validation tests passed!");
}