Build a Real-Time Fraud Scoring API

// src/fraud/signals.ts
import { z } from 'zod';
import { Redis } from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

export const TransactionSignals = z.object({
  // Transaction data
  transactionId: z.string(),
  amount: z.number().positive(),
  currency: z.string(),
  merchantCategory: z.string(),

  // User signals
  userId: z.string(),
  accountAgeDays: z.number().int(),
  totalTransactions: z.number().int(),
  averageTransactionAmount: z.number(),

  // Device signals
  deviceFingerprint: z.string(),
  ipAddress: z.string(),
  userAgent: z.string(),
  isKnownDevice: z.boolean(),
  isVpn: z.boolean(),
  isTor: z.boolean(),

  // Geo signals
  ipCountry: z.string(),
  billingCountry: z.string(),
  shippingCountry: z.string().optional(),
  distanceFromUsualLocationKm: z.number(),

  // Velocity signals
  transactionsLast1h: z.number().int(),
  transactionsLast24h: z.number().int(),
  uniqueCardsLast24h: z.number().int(),
  uniqueMerchantsLast1h: z.number().int(),
  amountLast24h: z.number(),

  // Card signals
  cardBin: z.string(),
  isNewCard: z.boolean(),
  cardCountry: z.string(),
  failedAttemptsLast1h: z.number().int(),
});

export async function collectSignals(tx: {
  transactionId: string;
  userId: string;
  amount: number;
  currency: string;
  merchantCategory: string;
  cardBin: string;
  deviceFingerprint: string;
  ipAddress: string;
  userAgent: string;
  billingCountry: string;
  shippingCountry?: string;
}): Promise<z.infer<typeof TransactionSignals>> {
  const now = Date.now();
  const hourAgo = now - 3600000;
  const dayAgo = now - 86400000;

  // Velocity checks from Redis (O(1) with sorted sets)
  const pipeline = redis.pipeline();
  pipeline.zcount(`fraud:tx:${tx.userId}`, hourAgo, now);
  pipeline.zcount(`fraud:tx:${tx.userId}`, dayAgo, now);
  pipeline.scard(`fraud:cards:${tx.userId}:${Math.floor(now / 86400000)}`);
  pipeline.zcount(`fraud:merchants:${tx.userId}`, hourAgo, now);
  pipeline.get(`fraud:amount:${tx.userId}:day`);
  pipeline.zcount(`fraud:failed:${tx.userId}`, hourAgo, now);
  pipeline.sismember(`fraud:devices:${tx.userId}`, tx.deviceFingerprint);
  pipeline.get(`fraud:avg_amount:${tx.userId}`);
  pipeline.get(`fraud:total_tx:${tx.userId}`);
  pipeline.get(`fraud:account_age:${tx.userId}`);

  const results = await pipeline.exec();

  // Record this transaction
  await redis.pipeline()
    .zadd(`fraud:tx:${tx.userId}`, now.toString(), tx.transactionId)
    .sadd(`fraud:cards:${tx.userId}:${Math.floor(now / 86400000)}`, tx.cardBin)
    .zadd(`fraud:merchants:${tx.userId}`, now.toString(), tx.merchantCategory)
    .incrbyfloat(`fraud:amount:${tx.userId}:day`, tx.amount)
    .expire(`fraud:tx:${tx.userId}`, 86400)
    .expire(`fraud:amount:${tx.userId}:day`, 86400)
    .exec();

  const ipInfo = await getIpInfo(tx.ipAddress);

  return {
    transactionId: tx.transactionId,
    amount: tx.amount,
    currency: tx.currency,
    merchantCategory: tx.merchantCategory,
    userId: tx.userId,
    accountAgeDays: parseInt(results![9]?.[1] as string ?? '0'),
    totalTransactions: parseInt(results![8]?.[1] as string ?? '0'),
    averageTransactionAmount: parseFloat(results![7]?.[1] as string ?? '0'),
    deviceFingerprint: tx.deviceFingerprint,
    ipAddress: tx.ipAddress,
    userAgent: tx.userAgent,
    isKnownDevice: results![6]?.[1] === 1,
    isVpn: ipInfo.isVpn,
    isTor: ipInfo.isTor,
    ipCountry: ipInfo.country,
    billingCountry: tx.billingCountry,
    shippingCountry: tx.shippingCountry,
    distanceFromUsualLocationKm: 0, // calculated from IP geolocation
    transactionsLast1h: results![0]?.[1] as number ?? 0,
    transactionsLast24h: results![1]?.[1] as number ?? 0,
    uniqueCardsLast24h: results![2]?.[1] as number ?? 0,
    uniqueMerchantsLast1h: results![3]?.[1] as number ?? 0,
    amountLast24h: parseFloat(results![4]?.[1] as string ?? '0'),
    cardBin: tx.cardBin,
    isNewCard: true,
    cardCountry: tx.billingCountry,
    failedAttemptsLast1h: results![5]?.[1] as number ?? 0,
  };
}

async function getIpInfo(ip: string): Promise<{ country: string; isVpn: boolean; isTor: boolean }> {
  return { country: 'US', isVpn: false, isTor: false }; // use IP intelligence API
}

// src/fraud/scorer.ts
import type { TransactionSignals } from './signals';

export interface FraudScore {
  score: number;          // 0-100 (0 = safe, 100 = fraud)
  decision: 'approve' | 'review' | 'decline';
  riskFactors: Array<{ factor: string; weight: number; detail: string }>;
  processingMs: number;
}

export function calculateFraudScore(signals: TransactionSignals): FraudScore {
  const start = Date.now();
  const factors: Array<{ factor: string; weight: number; detail: string }> = [];
  let score = 0;

  // New account + high value
  if (signals.accountAgeDays < 7 && signals.amount > 500) {
    const weight = 25;
    score += weight;
    factors.push({ factor: 'new_account_high_value', weight, detail: `${signals.accountAgeDays}d old, $${signals.amount}` });
  }

  // Velocity anomaly
  if (signals.transactionsLast1h > 5) {
    const weight = 20;
    score += weight;
    factors.push({ factor: 'high_velocity', weight, detail: `${signals.transactionsLast1h} tx in 1h` });
  }

  // Amount anomaly (>3x average)
  if (signals.averageTransactionAmount > 0 && signals.amount > signals.averageTransactionAmount * 3) {
    const weight = 15;
    score += weight;
    factors.push({ factor: 'amount_anomaly', weight, detail: `$${signals.amount} vs avg $${signals.averageTransactionAmount.toFixed(0)}` });
  }

  // New device
  if (!signals.isKnownDevice) {
    const weight = 10;
    score += weight;
    factors.push({ factor: 'unknown_device', weight, detail: 'First time seeing this device' });
  }

  // VPN/Tor
  if (signals.isVpn || signals.isTor) {
    const weight = signals.isTor ? 20 : 10;
    score += weight;
    factors.push({ factor: 'anonymized_connection', weight, detail: signals.isTor ? 'Tor network' : 'VPN detected' });
  }

  // Country mismatch
  if (signals.ipCountry !== signals.billingCountry) {
    const weight = 15;
    score += weight;
    factors.push({ factor: 'country_mismatch', weight, detail: `IP: ${signals.ipCountry}, billing: ${signals.billingCountry}` });
  }

  // Card testing pattern (many small amounts)
  if (signals.transactionsLast1h > 3 && signals.amount < 5) {
    const weight = 30;
    score += weight;
    factors.push({ factor: 'card_testing', weight, detail: `${signals.transactionsLast1h} small tx in 1h` });
  }

  // Failed attempts
  if (signals.failedAttemptsLast1h > 2) {
    const weight = 15;
    score += weight;
    factors.push({ factor: 'failed_attempts', weight, detail: `${signals.failedAttemptsLast1h} failures in 1h` });
  }

  score = Math.min(100, score);
  const decision = score >= 70 ? 'decline' : score >= 40 ? 'review' : 'approve';

  return { score, decision, riskFactors: factors, processingMs: Date.now() - start };
}