radar reviews sit open for days while funds stay at risk

"""Report Stripe Radar reviews left open while the funds behind them are at risk.

Read only. Paginated GETs and nothing else: give this a RESTRICTED key with read
access to Reviews and Charges. The repair is printed, never performed, because
this script holds a credential to a live payments account.
"""
import argparse
import logging
import os
import sys
import time

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("stripe_radar_review_queue")

API = "https://api.stripe.com/v1"

STALE_DAYS = 3     # past this the queue is a backlog, not a queue
LAPSE_DAYS = 7     # an uncaptured authorization is released at this age
MIN_CLOSED = 20    # below this the approval rate is noise
OVERBROAD = 0.95   # approvals at or above this: the rule never changes an outcome
WIDE = 0.80


def verdict(age_days, captured):
    """Classify one open review. Pure, so both deadlines can be tested offline.

    `captured` is the `captured` flag of the review's charge, or None when the
    charge could not be read. Returns (state, detail).
    """
    if age_days < STALE_DAYS:
        return ("open",
                "open for %.1f day(s), still inside the window Stripe asks you to "
                "work" % age_days)
    if captured is False and age_days >= LAPSE_DAYS:
        return ("lapsed",
                "open for %.1f day(s) on an uncaptured authorization: the hold was "
                "released at %d days and approving it now captures nothing"
                % (age_days, LAPSE_DAYS))
    if captured is False:
        return ("expiring",
                "open for %.1f day(s) on an uncaptured authorization, released in "
                "%.1f day(s)" % (age_days, LAPSE_DAYS - age_days))
    if age_days >= LAPSE_DAYS:
        return ("critical",
                "open for %.1f day(s) on a captured charge: the money is with you "
                "and the dispute window is already running" % age_days)
    return ("stale", "open for %.1f day(s) on a captured charge" % age_days)


def rule_health(approved, closed):
    """Judge the review rule from how its reviews were closed. Pure.

    `approved` counts closed_reason == "approved"; `closed` counts every review
    with any closed_reason. Returns (state, detail).
    """
    if closed < MIN_CLOSED:
        return ("insufficient",
                "%d closed review(s) is too few to judge the rule" % closed)
    rate = approved / float(closed)
    if rate >= OVERBROAD:
        return ("overbroad",
                "%.0f%% of closed reviews were approved: the rule flags traffic you "
                "always accept and has never changed an outcome" % (rate * 100))
    if rate >= WIDE:
        return ("wide",
                "%.0f%% approved: add a second predicate before staffing this queue"
                % (rate * 100))
    return ("earning", "%.0f%% approved: the rule is catching real fraud"
            % (rate * 100))


def get(session, path, **params):
    r = session.get(API + path, params=params, timeout=30)
    if r.status_code == 401:
        raise SystemExit("401 from Stripe: the key is wrong, or is for the other mode")
    r.raise_for_status()
    return r.json()


def page(session, path, cap, **params):
    """Collect up to `cap` objects from a list endpoint."""
    out = []
    params = dict(params)
    params["limit"] = 100
    while True:
        p = get(session, path, **params)
        data = p.get("data", [])
        out.extend(data)
        if not data or not p.get("has_more") or len(out) >= cap:
            break
        params["starting_after"] = data[-1]["id"]
    return out


def captured_flag(session, charge_id, cache):
    """Read `captured` off the charge behind a review. None when unreadable."""
    if not charge_id:
        return None
    if charge_id not in cache:
        try:
            cache[charge_id] = get(session, "/charges/" + charge_id).get("captured")
        except requests.HTTPError:
            cache[charge_id] = None
    return cache[charge_id]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=90,
                    help="window for the approval-rate audit")
    ap.add_argument("--max-reviews", type=int, default=2000,
                    help="stop paginating after this many reviews")
    args = ap.parse_args()

    key = os.environ.get("STRIPE_API_KEY")
    if not key:
        log.error("set STRIPE_API_KEY (use a restricted, read-only key)")
        return 2

    s = requests.Session()
    s.headers.update({"Authorization": "Bearer " + key})

    now = time.time()
    since = now - args.days * 86400
    reviews = page(s, "/reviews", args.max_reviews)

    cache = {}
    approved = closed = flagged = 0
    by_reason = {}
    for rev in reviews:
        created = rev.get("created", now)
        if created >= since and rev.get("closed_reason"):
            closed += 1
            if rev["closed_reason"] == "approved":
                approved += 1
        if not rev.get("open"):
            continue
        reason = rev.get("opened_reason") or "unknown"
        by_reason[reason] = by_reason.get(reason, 0) + 1
        age = (now - created) / 86400.0
        state, detail = verdict(age, captured_flag(s, rev.get("charge"), cache))
        if state == "open":
            log.info("%-9s %s  %s", state, rev.get("id"), detail)
            continue
        flagged += 1
        log.warning("%-9s %s  %s", state, rev.get("id"), detail)
        log.warning("    opened by %s, charge %s", reason, rev.get("charge"))

    for reason, n in sorted(by_reason.items()):
        log.info("%d open review(s) opened by %s", n, reason)
    health, detail = rule_health(approved, closed)
    log.info("%-12s %s", health, detail)

    if not flagged and health not in ("overbroad", "wide"):
        log.info("0 open review(s) past %d days", STALE_DAYS)
        return 0

    if flagged:
        log.warning("  work the queue: Dashboard, Radar, Reviews, then Approve, "
                    "Refund, or Refund and report fraud on each one")
        log.warning("  alert instead of polling: subscribe an endpoint to "
                    "review.opened")
    if health in ("overbroad", "wide"):
        log.warning("  narrow the rule in Dashboard, Radar, Rules: add a second "
                    "predicate, for example is_disposable_email alongside the "
                    "card_funding test, or delete the rule outright")
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Report Stripe Radar reviews left open while the funds behind them are at risk.
 *
 * Read only. Paginated GETs and nothing else: give this a RESTRICTED key with
 * read access to Reviews and Charges. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

export const STALE_DAYS = 3;  // past this the queue is a backlog, not a queue
export const LAPSE_DAYS = 7;  // an uncaptured authorization is released at this age
const MIN_CLOSED = 20;
const OVERBROAD = 0.95;
const WIDE = 0.8;

/**
 * Classify one open review. Pure, so both deadlines can be tested offline.
 * `captured` is the charge's captured flag, or null when it could not be read.
 */
export function verdict(ageDays, captured) {
  if (ageDays < STALE_DAYS) {
    return ['open',
      `open for ${ageDays.toFixed(1)} day(s), still inside the window Stripe asks you to work`];
  }
  if (captured === false && ageDays >= LAPSE_DAYS) {
    return ['lapsed',
      `open for ${ageDays.toFixed(1)} day(s) on an uncaptured authorization: the hold ` +
      `was released at ${LAPSE_DAYS} days and approving it now captures nothing`];
  }
  if (captured === false) {
    return ['expiring',
      `open for ${ageDays.toFixed(1)} day(s) on an uncaptured authorization, released ` +
      `in ${(LAPSE_DAYS - ageDays).toFixed(1)} day(s)`];
  }
  if (ageDays >= LAPSE_DAYS) {
    return ['critical',
      `open for ${ageDays.toFixed(1)} day(s) on a captured charge: the money is with ` +
      'you and the dispute window is already running'];
  }
  return ['stale', `open for ${ageDays.toFixed(1)} day(s) on a captured charge`];
}

/** Judge the review rule from how its reviews were closed. Pure. */
export function ruleHealth(approved, closed) {
  if (closed < MIN_CLOSED) {
    return ['insufficient', `${closed} closed review(s) is too few to judge the rule`];
  }
  const rate = approved / closed;
  const pct = Math.round(rate * 100);
  if (rate >= OVERBROAD) {
    return ['overbroad',
      `${pct}% of closed reviews were approved: the rule flags traffic you always ` +
      'accept and has never changed an outcome'];
  }
  if (rate >= WIDE) {
    return ['wide', `${pct}% approved: add a second predicate before staffing this queue`];
  }
  return ['earning', `${pct}% approved: the rule is catching real fraud`];
}

async function get(key, path, params = {}) {
  const url = new URL(API + path);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
  if (res.status === 401) {
    throw new Error('401 from Stripe: the key is wrong, or is for the other mode');
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

async function page(key, path, cap, params = {}) {
  const out = [];
  const q = { ...params, limit: 100 };
  for (;;) {
    const p = await get(key, path, q);
    const data = p.data ?? [];
    out.push(...data);
    if (data.length === 0 || !p.has_more || out.length >= cap) break;
    q.starting_after = data[data.length - 1].id;
  }
  return out;
}

async function capturedFlag(key, chargeId, cache) {
  if (!chargeId) return null;
  if (!(chargeId in cache)) {
    try {
      cache[chargeId] = (await get(key, `/charges/${chargeId}`)).captured ?? null;
    } catch {
      cache[chargeId] = null;
    }
  }
  return cache[chargeId];
}

async function main() {
  const key = process.env.STRIPE_API_KEY;
  if (!key) {
    console.error('set STRIPE_API_KEY (use a restricted, read-only key)');
    process.exitCode = 2;
    return;
  }

  const days = Number(process.env.DAYS ?? 90);
  const now = Date.now() / 1000;
  const since = now - days * 86400;
  const reviews = await page(key, '/reviews', 2000);

  const cache = {};
  const byReason = {};
  let approved = 0;
  let closed = 0;
  let flagged = 0;

  for (const rev of reviews) {
    const created = rev.created ?? now;
    if (created >= since && rev.closed_reason) {
      closed += 1;
      if (rev.closed_reason === 'approved') approved += 1;
    }
    if (!rev.open) continue;
    const reason = rev.opened_reason ?? 'unknown';
    byReason[reason] = (byReason[reason] ?? 0) + 1;
    const age = (now - created) / 86400;
    const [state, detail] = verdict(age, await capturedFlag(key, rev.charge, cache));
    if (state === 'open') {
      console.log(`${state.padEnd(9)} ${rev.id}  ${detail}`);
      continue;
    }
    flagged += 1;
    console.warn(`${state.padEnd(9)} ${rev.id}  ${detail}`);
    console.warn(`    opened by ${reason}, charge ${rev.charge}`);
  }

  for (const [reason, n] of Object.entries(byReason).sort()) {
    console.log(`${n} open review(s) opened by ${reason}`);
  }
  const [health, detail] = ruleHealth(approved, closed);
  console.log(`${health.padEnd(12)} ${detail}`);

  if (!flagged && health !== 'overbroad' && health !== 'wide') {
    console.log(`0 open review(s) past ${STALE_DAYS} days`);
    return;
  }
  if (flagged) {
    console.warn('  work the queue: Dashboard, Radar, Reviews, then Approve, Refund, ' +
                 'or Refund and report fraud on each one');
    console.warn('  alert instead of polling: subscribe an endpoint to review.opened');
  }
  if (health === 'overbroad' || health === 'wide') {
    console.warn('  narrow the rule in Dashboard, Radar, Rules: add a second predicate, ' +
                 'for example is_disposable_email alongside the card_funding test, or ' +
                 'delete the rule outright');
  }
  process.exitCode = 1;
}

// Only run when invoked directly. The test file imports this module, and without
// the guard main() would run there too, fail on the missing key, and set a
// non-zero exit code that fails the whole test file even as every test passes.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from stripe_radar_review_queue import rule_health, verdict


def test_fresh_review_is_just_open():
    state, detail = verdict(1.0, True)
    assert state == "open"
    assert "still inside the window" in detail


def test_three_days_is_the_stale_boundary():
    # Exactly three must already flag. A check that waits until day four has
    # spent nearly half the capture window before saying anything.
    assert verdict(2.9, True)[0] == "open"
    assert verdict(3.0, True)[0] == "stale"


def test_uncaptured_hold_expires_at_seven_days():
    state, detail = verdict(6.9, False)
    assert state == "expiring"
    assert "0.1 day(s)" in detail
    assert verdict(7.0, False)[0] == "lapsed"


def test_captured_charge_past_seven_days_is_critical():
    state, detail = verdict(9.0, True)
    assert state == "critical"
    assert "dispute window" in detail


def test_approval_rate_needs_a_sample_before_it_judges_the_rule():
    assert rule_health(19, 19)[0] == "insufficient"
    assert rule_health(20, 20)[0] == "overbroad"
    assert rule_health(16, 20)[0] == "wide"
    assert rule_health(8, 20)[0] == "earning"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { ruleHealth, verdict } from './stripe-radar-review-queue.mjs';

test('fresh review is just open', () => {
  const [state, detail] = verdict(1.0, true);
  assert.equal(state, 'open');
  assert.ok(detail.includes('still inside the window'));
});

test('three days is the stale boundary', () => {
  assert.equal(verdict(2.9, true)[0], 'open');
  assert.equal(verdict(3.0, true)[0], 'stale');
});

test('uncaptured hold expires at seven days', () => {
  const [state, detail] = verdict(6.9, false);
  assert.equal(state, 'expiring');
  assert.ok(detail.includes('0.1 day(s)'));
  assert.equal(verdict(7.0, false)[0], 'lapsed');
});

test('captured charge past seven days is critical', () => {
  const [state, detail] = verdict(9.0, true);
  assert.equal(state, 'critical');
  assert.ok(detail.includes('dispute window'));
});

test('approval rate needs a sample before it judges the rule', () => {
  assert.equal(ruleHealth(19, 19)[0], 'insufficient');
  assert.equal(ruleHealth(20, 20)[0], 'overbroad');
  assert.equal(ruleHealth(16, 20)[0], 'wide');
  assert.equal(ruleHealth(8, 20)[0], 'earning');
});