disputes are hours from due_by with no evidence attached

"""Report Stripe disputes whose response deadline is about to pass.

Read only. One paginated GET and no writes: give this a RESTRICTED key with read
access to Disputes. The response is printed, never submitted, because this script
holds a credential to a live payments account and dispute evidence can be sent
exactly once.
"""
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_dispute_deadlines")

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

CRITICAL_HOURS = 72.0

# Still waiting on you.
OPEN = ("needs_response", "warning_needs_response")
# Answered; the network has it.
IN_REVIEW = ("under_review", "warning_under_review")
# Finished either way.
SETTLED = ("won", "lost", "warning_closed")


def verdict(dispute, now, critical_hours=CRITICAL_HOURS):
    """Classify one dispute. Pure, so the deadline arithmetic can be tested.

    `now` is a unix timestamp. Returns (state, detail).

    The states that matter are `critical` (deadline close, nothing sent) and
    `staged` (deadline close, evidence written but submission_count still 0),
    which is the same loss with the work already paid for.
    """
    status = dispute.get("status")
    ed = dispute.get("evidence_details") or {}

    if status in IN_REVIEW:
        return ("submitted", "evidence is in and the network is reviewing it")
    if status in SETTLED:
        return ("closed", "closed as %s; there is nothing left to send" % status)
    if status not in OPEN:
        return ("unknown", "unrecognised status %r" % (status,))

    due_by = ed.get("due_by")
    staged = bool(ed.get("has_evidence"))
    sent = ed.get("submission_count") or 0

    if ed.get("past_due") or (due_by is not None and due_by <= now):
        return ("forfeited",
                "past due_by while still needing a response. The funds and the "
                "dispute fee are gone, and no evidence will be accepted now.")
    if due_by is None:
        return ("unknown", "open, but with no due_by to measure against")

    hours = (due_by - now) / 3600.0
    if hours <= critical_hours:
        if staged and not sent:
            return ("staged",
                    "%.1f hour(s) left. Evidence is staged but submission_count "
                    "is 0, so none of it has reached the network." % hours)
        return ("critical", "%.1f hour(s) left and nothing attached." % hours)
    if staged and not sent:
        return ("open",
                "%.1f day(s) left; evidence staged, not submitted" % (hours / 24.0))
    return ("open", "%.1f day(s) left to assemble evidence" % (hours / 24.0))


def money(dispute):
    """Amount at risk, in minor units.

    Deliberately not divided by 100: that is wrong for zero-decimal currencies
    like JPY, and a report that quietly reads 100x low on one currency is worse
    than one that makes you read the currency code.
    """
    return "%s %s" % (dispute.get("amount"), (dispute.get("currency") or "?").upper())


def get(session, path, params=None):
    r = session.get(API + path, params=params or {}, 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 disputes(session, limit):
    """Yield disputes, newest first, up to `limit`."""
    seen = 0
    params = {"limit": 100}
    while True:
        page = get(session, "/disputes", params)
        data = page.get("data", [])
        for d in data:
            yield d
            seen += 1
        if not data or not page.get("has_more") or seen >= limit:
            break
        params["starting_after"] = data[-1]["id"]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--hours", type=float, default=CRITICAL_HOURS,
                    help="how close to due_by counts as critical")
    ap.add_argument("--max-disputes", type=int, default=1000,
                    help="stop paginating after this many disputes")
    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()
    seen = urgent = 0
    for d in disputes(s, args.max_disputes):
        seen += 1
        state, detail = verdict(d, now, args.hours)
        if state in ("submitted", "closed", "open"):
            log.info("%-10s %s  %s", state, d.get("id", "?"), detail)
            continue

        urgent += 1
        log.warning("%-10s %s  %s  %s", state, d.get("id", "?"), money(d), detail)
        if state == "unknown":
            continue
        if state == "forfeited":
            log.warning("  nothing to run: the window is closed. Count it with the "
                        "other forfeits and fix the sweep, not this dispute.")
            continue
        log.warning("  repair: POST %s/disputes/%s "
                    "-d 'evidence[product_description]=...' "
                    "-d 'evidence[shipping_tracking_number]=...' "
                    "-d 'evidence[customer_communication]=<file_id>'",
                    API, d["id"])
        log.warning("  evidence submits once, so assemble it all first. "
                    "To concede on purpose: POST %s/disputes/%s/close", API, d["id"])
        if "visa_compelling_evidence_3" in (d.get("enhanced_eligibility_types") or []):
            log.warning("  eligible for Visa Compelling Evidence 3.0: Stripe "
                        "pre-populates most of this from prior transactions")

    log.info("%d dispute(s) read, %d needing a response now", seen, urgent)
    return 1 if urgent else 0


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

/**
 * Report Stripe disputes whose response deadline is about to pass.
 *
 * Read only. One paginated GET and no writes: give this a RESTRICTED key with
 * read access to Disputes. The response is printed, never submitted, because
 * dispute evidence can be sent exactly once.
 */
const API = 'https://api.stripe.com/v1';

export const CRITICAL_HOURS = 72;

const OPEN = ['needs_response', 'warning_needs_response'];
const IN_REVIEW = ['under_review', 'warning_under_review'];
const SETTLED = ['won', 'lost', 'warning_closed'];

/**
 * Classify one dispute. Pure, so the deadline arithmetic can be tested.
 * `now` is a unix timestamp in seconds.
 */
export function verdict(dispute, now, criticalHours = CRITICAL_HOURS) {
  const status = dispute.status;
  const ed = dispute.evidence_details ?? {};

  if (IN_REVIEW.includes(status)) {
    return ['submitted', 'evidence is in and the network is reviewing it'];
  }
  if (SETTLED.includes(status)) {
    return ['closed', `closed as ${status}; there is nothing left to send`];
  }
  if (!OPEN.includes(status)) {
    return ['unknown', `unrecognised status ${JSON.stringify(status)}`];
  }

  const dueBy = ed.due_by;
  const staged = Boolean(ed.has_evidence);
  const sent = ed.submission_count ?? 0;

  if (ed.past_due || (dueBy !== undefined && dueBy !== null && dueBy <= now)) {
    return ['forfeited',
      'past due_by while still needing a response. The funds and the dispute ' +
      'fee are gone, and no evidence will be accepted now.'];
  }
  if (dueBy === undefined || dueBy === null) {
    return ['unknown', 'open, but with no due_by to measure against'];
  }

  const hours = (dueBy - now) / 3600;
  if (hours <= criticalHours) {
    if (staged && !sent) {
      return ['staged',
        `${hours.toFixed(1)} hour(s) left. Evidence is staged but ` +
        'submission_count is 0, so none of it has reached the network.'];
    }
    return ['critical', `${hours.toFixed(1)} hour(s) left and nothing attached.`];
  }
  if (staged && !sent) {
    return ['open', `${(hours / 24).toFixed(1)} day(s) left; evidence staged, not submitted`];
  }
  return ['open', `${(hours / 24).toFixed(1)} day(s) left to assemble evidence`];
}

/**
 * Amount at risk, in minor units. Not divided by 100, which is wrong for
 * zero-decimal currencies such as JPY.
 */
export function money(dispute) {
  return `${dispute.amount} ${(dispute.currency ?? '?').toUpperCase()}`;
}

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();
}

export async function* disputes(key, limit = 1000) {
  let seen = 0;
  const params = { limit: 100 };
  for (;;) {
    const page = await get(key, '/disputes', params);
    const data = page.data ?? [];
    for (const d of data) { yield d; seen += 1; }
    if (data.length === 0 || !page.has_more || seen >= limit) break;
    params.starting_after = data[data.length - 1].id;
  }
}

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 now = Date.now() / 1000;
  let seen = 0;
  let urgent = 0;

  for await (const d of disputes(key)) {
    seen += 1;
    const [state, detail] = verdict(d, now);
    if (state === 'submitted' || state === 'closed' || state === 'open') {
      console.log(`${state.padEnd(10)} ${d.id ?? '?'}  ${detail}`);
      continue;
    }

    urgent += 1;
    console.warn(`${state.padEnd(10)} ${d.id ?? '?'}  ${money(d)}  ${detail}`);
    if (state === 'unknown') continue;
    if (state === 'forfeited') {
      console.warn('  nothing to run: the window is closed. Count it with the ' +
                   'other forfeits and fix the sweep, not this dispute.');
      continue;
    }
    console.warn(`  repair: POST ${API}/disputes/${d.id} ` +
                 `-d 'evidence[product_description]=...' ` +
                 `-d 'evidence[shipping_tracking_number]=...' ` +
                 `-d 'evidence[customer_communication]=<file_id>'`);
    console.warn('  evidence submits once, so assemble it all first. ' +
                 `To concede on purpose: POST ${API}/disputes/${d.id}/close`);
    if ((d.enhanced_eligibility_types ?? []).includes('visa_compelling_evidence_3')) {
      console.warn('  eligible for Visa Compelling Evidence 3.0: Stripe ' +
                   'pre-populates most of this from prior transactions');
    }
  }

  console.log(`${seen} dispute(s) read, ${urgent} needing a response now`);
  process.exitCode = urgent ? 1 : 0;
}

// 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_dispute_deadlines import verdict

NOW = 1_700_000_000


def open_dispute(hours_left, **evidence):
    ev = {"due_by": NOW + int(hours_left * 3600)}
    ev.update(evidence)
    return {"id": "du_1", "status": "needs_response", "evidence_details": ev}


def test_deadline_inside_the_window_with_nothing_attached_is_critical():
    state, detail = verdict(open_dispute(6), NOW)
    assert state == "critical"
    assert "6.0" in detail


def test_seventy_two_hours_is_the_boundary_and_it_is_inclusive():
    # 72 must already fire. Waiting for 71 spends a third of what is left.
    assert verdict(open_dispute(72), NOW)[0] == "critical"
    assert verdict(open_dispute(72.1), NOW)[0] == "open"


def test_staged_evidence_that_was_never_submitted_is_its_own_state():
    state, detail = verdict(
        open_dispute(10, has_evidence=True, submission_count=0), NOW)
    assert state == "staged"
    assert "submission_count" in detail


def test_past_due_while_still_needing_a_response_is_forfeited():
    d = open_dispute(-1, past_due=True)
    state, detail = verdict(d, NOW)
    assert state == "forfeited"
    assert "fee" in detail


def test_under_review_is_answered_and_a_missing_due_by_is_not_silently_open():
    assert verdict({"status": "under_review"}, NOW)[0] == "submitted"
    assert verdict({"status": "needs_response", "evidence_details": {}}, NOW)[0] == "unknown"
    assert verdict({"status": "sleeping"}, NOW)[0] == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-dispute-deadlines.mjs';

const NOW = 1_700_000_000;

function openDispute(hoursLeft, evidence = {}) {
  return {
    id: 'du_1',
    status: 'needs_response',
    evidence_details: { due_by: NOW + Math.round(hoursLeft * 3600), ...evidence },
  };
}

test('deadline inside the window with nothing attached is critical', () => {
  const [state, detail] = verdict(openDispute(6), NOW);
  assert.equal(state, 'critical');
  assert.match(detail, /6\.0 hour/);
});

test('seventy two hours is the boundary and it is inclusive', () => {
  assert.equal(verdict(openDispute(72), NOW)[0], 'critical');
  assert.equal(verdict(openDispute(72.1), NOW)[0], 'open');
});

test('staged evidence that was never submitted is its own state', () => {
  const [state, detail] = verdict(
    openDispute(10, { has_evidence: true, submission_count: 0 }), NOW);
  assert.equal(state, 'staged');
  assert.match(detail, /submission_count/);
});

test('past due while still needing a response is forfeited', () => {
  const [state, detail] = verdict(openDispute(-1, { past_due: true }), NOW);
  assert.equal(state, 'forfeited');
  assert.match(detail, /fee/);
});

test('answered and unreadable disputes are not treated as open', () => {
  assert.equal(verdict({ status: 'under_review' }, NOW)[0], 'submitted');
  assert.equal(
    verdict({ status: 'needs_response', evidence_details: {} }, NOW)[0], 'unknown');
  assert.equal(verdict({ status: 'sleeping' }, NOW)[0], 'unknown');
});