Designing APIs for Business Verification Scoring

// extract.mjs: Queries API, transforms metrics to canonical fields
const API_URL = process.env.FAKE_SOCIAL_API_URL ?? "http://fake-social-api:4400";
const API_KEY = process.env.FAKE_SOCIAL_API_KEY ?? "demo-key";

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

const adapter = {
  id: "social-media-adapter-v1",
  category: "social-media",
  version: 1,
  produces: [
    "accountTenureMonths",
    "followerCount",
    "engagementRate90d",
    "postingConsistency12m",
    "verifiedBusinessAccount",
    "customerRatingAvg",
    "negativeSentimentRatio90d",
    "accountFlags24m"
  ],

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

  async extract(raw) {
    const profile = raw.profile ?? {};
    const posting = raw.posting12m ?? {};
    const sentiment = raw.sentiment90d ?? {};

    return [{
      instanceKey: "default",
      observedAt: new Date().toISOString(),
      values: {
        accountTenureMonths: Number(profile.accountAgeMonths ?? 0),
        followerCount: Number(profile.followers ?? 0),
        engagementRate90d: round4(Number(raw.engagement90d?.engagementRate ?? 0)),
        postingConsistency12m: clamp01(ratio(Number(posting.activeMonths ?? 0), 12)),
        verifiedBusinessAccount: Boolean(profile.verified),
        customerRatingAvg: round4(Number(raw.reviews?.avgRating ?? 0)),
        negativeSentimentRatio90d: ratio(
          Number(sentiment.negativeMentions ?? 0),
          Number(sentiment.totalMentions ?? 0)
        ),
        accountFlags24m: Number(raw.flags24m?.count ?? 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-social",
    identity: { ihsId: 1, ic: "850101015432", fullName: "Aiman bin Hassan" },
    expected: [
      {
        instanceKey: "default",
        values: {
          followerCount: 18500,
          verifiedBusinessAccount: true
        }
      }
    ]
  }
];

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