Affiliate Fraud (Click & Lead Inflation)

<script type="module">
  const mod = await import(
    'https://cdn.shieldlabs.ai/snippet.js?publicKey=YOUR_PUBLIC_KEY'
  );
  // The browser does NOT compute the Score, DeviceID, or VisitorID; those
  // arrive by webhook / History API. The first arg is the client IP, not a
  // score. Pass undefined for the userHID slot so the callback fires.
  mod.checkAnonymous(undefined, (ip, requestID) => {
    document.cookie = `shield_rid=${requestID}; max-age=3600; SameSite=Lax`;
    const utm = new URLSearchParams(location.search).get('utm_source') || '';
    document.cookie = `shield_utm=${encodeURIComponent(utm)}; max-age=3600; SameSite=Lax`;
  });
</script>

app.post('/api/conversion', async (req, res) => {
  const { affiliateId, eventType } = req.body;
  const shieldRequestId = req.cookies.shield_rid;

  // Read the score for this visit (waitForScore is the shared webhook-cache
  // helper; it returns the result, History API on a miss).
  const shield = shieldRequestId ? await waitForScore(shieldRequestId, 2000) : null;
  const score = shield?.score ?? 0;        // 0-100, default 0 if not yet in
  const signals = shield?.signals ?? [];   // explainable: [{ name, weight }]

  // Record the conversion with its quality context. Always store, never drop.
  const conversion = await db.conversions.create({
    affiliateId,
    eventType,
    shieldScore: score,
    shieldSignals: signals,
    deviceId: shield?.device_id,
    country: shield?.public_ip?.country,   // public/VPN-side country
    utmSource: req.cookies.shield_utm,       // channel/UTM are client-captured
  });

  // YOUR payout logic. Bands are a guide, the thresholds are yours.
  if (score >= 60) {
    await holdForReview(conversion.id, 'high_risk_visit');          // High: withhold
  } else if (score >= 30) {
    await approveWithClawbackWindow(conversion.id);                 // Medium: delayed
  } else {
    await approvePayout(conversion.id);                            // Clean / Low: pay
  }

  return res.json({ ok: true });
});

app.post('/shieldlabs/webhook', async (req, res) => {
  // Verify the X-Shield-Signature HMAC over the raw body first
  // (see /setup/webhooks), then ack fast.
  const { device_id, request_id } = req.body;
  res.status(200).end();
  if (!device_id) return;

  // Has this exact device already converted for this affiliate recently?
  const key = `affiliate:${affiliateForRequest(request_id)}:device:${device_id}`;
  const firstSeen = await store.setIfAbsent(key, request_id, { ttlSeconds: 86400 });

  if (!firstSeen) {
    // Same device_id, same affiliate, inside the window: a repeat device,
    // not a new visitor. Mark it so payout does not double-count.
    await db.conversions.markRepeatDevice(request_id, device_id);
  }
});

// Daily: summarize each affiliate's last 24h of conversions.
async function rankAffiliates() {
  const affiliates = await db.conversions.groupBy('affiliateId', {
    last24h: true,
    select: {
      total: true,
      avgScore: true,
      mediumOrHigh: { where: { shieldScore: { gte: 30 } } },
      distinctDevices: { distinct: 'deviceId' },
    },
  });

  return affiliates
    .map((a) => ({
      affiliateId: a.affiliateId,
      conversions: a.total,
      avgScore: a.avgScore,                              // average Risk Score
      maskedShare: a.mediumOrHigh / a.total,             // Medium + High share
      deviceInflation: 1 - a.distinctDevices / a.total,  // repeat-device rate
    }))
    .sort((x, y) => y.maskedShare - x.maskedShare);      // worst sources first
}

curl "https://account.shieldlabs.ai/api/v1/history/device_id/5eb7fd5c-1c5e-4a9f-9b21-7d2e8c0a1234?limit=50" \
  -H "Authorization: Bearer sec_your_private_api_key"