a report run fails after the 200 and the CSV never lands

"""Report Stripe report runs that failed, stalled in pending, or never happened.

Read only. Two paginated GETs and no writes: give this a RESTRICTED key with read
access to Reports and Webhook Endpoints. The repair is printed, never performed,
because this script holds a credential to a live payments account.
"""
import argparse
import datetime as dt
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_report_runs")

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

# A run still pending past this is not being worked on. The standard report types
# resolve in seconds; an hour is already several orders of magnitude of slack.
STALL_SECONDS = 3600

FAILURE_EVENT = "reporting.report_run.failed"


def run_state(status, age_seconds, error=None):
    """Classify one report run. Pure, so the pending deadline can be tested offline.

    `age_seconds` is how long ago the run was created. Returns (state, detail).
    """
    if status == "succeeded":
        return ("succeeded", "finished, result file available")
    if status == "failed":
        return ("failed", error or "failed with no error message on the run")
    if status == "pending":
        if age_seconds is not None and age_seconds >= STALL_SECONDS:
            return ("stalled",
                    "pending for %.1f hour(s); nothing is working on it, treat it "
                    "as failed" % (age_seconds / 3600.0))
        return ("running", "pending, still inside the %d second window"
                % STALL_SECONDS)
    return ("unknown", "unrecognised status %r" % (status,))


def verdict(states, missing_days, failure_subscribed):
    """Fold run states, schedule gaps and webhook coverage into one verdict. Pure.

    `states` is the list of per-run states, `missing_days` the expected UTC dates
    with no successful run, `failure_subscribed` whether any endpoint listens for
    reporting.report_run.failed.
    """
    failed = states.count("failed")
    stalled = states.count("stalled")
    if not states:
        return ("silent",
                "no report runs at all in the window; the export never reached "
                "Stripe, so there is nothing here to have failed")
    if failed or stalled:
        return ("failing",
                "%d run(s): %d failed, %d stalled in pending, %d expected day(s) "
                "with no successful run"
                % (len(states), failed, stalled, len(missing_days)))
    if missing_days:
        return ("gaps",
                "%d run(s), none failed, but %d expected day(s) have no successful "
                "run: %s" % (len(states), len(missing_days),
                             ", ".join(missing_days[:5])))
    if not failure_subscribed:
        return ("unwatched",
                "%d run(s), all successful, but nothing subscribes to %s, so the "
                "next failure is silent" % (len(states), FAILURE_EVENT))
    return ("clear",
            "%d run(s), 0 failed, 0 stalled, no missing days, failures subscribed"
            % len(states))


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")
    if r.status_code == 403:
        raise SystemExit("403 from Stripe: the restricted key has no read access to "
                         "this resource")
    r.raise_for_status()
    return r.json()


def page_all(session, path, params, cap=2000):
    """Collect every page, oldest last: Stripe returns these lists newest first."""
    out = []
    params = dict(params)
    while True:
        page = get(session, path, params)
        data = page.get("data", [])
        out.extend(data)
        if not data or not page.get("has_more") or len(out) >= cap:
            return out
        params["starting_after"] = data[-1]["id"]


def expected_days(now, days):
    """UTC dates a nightly export should have covered, excluding today."""
    today = dt.datetime.utcfromtimestamp(now).date()
    return [(today - dt.timedelta(days=n)).isoformat() for n in range(1, days + 1)]


def failure_is_subscribed(endpoints):
    for ep in endpoints:
        if ep.get("status") == "disabled":
            continue
        events = ep.get("enabled_events") or []
        if FAILURE_EVENT in events or "*" in events:
            return True
    return False


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--days", type=int, default=30,
                    help="how far back to read report runs")
    ap.add_argument("--report-type",
                    help="only consider runs of this report type, e.g. balance.summary.1")
    ap.add_argument("--no-daily", action="store_true",
                    help="do not expect one successful run per day")
    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()
    runs = page_all(s, "/reporting/report_runs",
                    {"limit": 100, "created[gte]": int(now - args.days * 86400)})
    if args.report_type:
        runs = [r for r in runs if r.get("report_type") == args.report_type]

    states = []
    succeeded_days = set()
    for r in runs:
        created = r.get("created")
        age = None if created is None else now - created
        state, detail = run_state(r.get("status"), age, r.get("error"))
        states.append(state)
        if state == "succeeded" and r.get("succeeded_at"):
            succeeded_days.add(
                dt.datetime.utcfromtimestamp(r["succeeded_at"]).date().isoformat())
        if state in ("failed", "stalled", "unknown"):
            log.warning("  %-9s %s  %s  %s", state, r.get("id"),
                        r.get("report_type"), detail)

    missing = ([] if args.no_daily
               else [d for d in expected_days(now, args.days) if d not in succeeded_days])

    endpoints = page_all(s, "/webhook_endpoints", {"limit": 100})
    subscribed = failure_is_subscribed(endpoints)

    state, detail = verdict(states, missing, subscribed)
    line = "%-11s %s" % (state, detail)
    if state == "clear":
        log.info(line)
        return 0

    log.warning(line)
    log.warning("  read the reason off the run, then re-issue it:")
    log.warning("  GET %s/reporting/report_runs/<frr_id>   (read .error, .parameters)", API)
    log.warning("  POST %s/reporting/report_runs with the corrected interval, then "
                "poll until status leaves pending", API)
    if not subscribed:
        log.warning("  and subscribe an endpoint so the next one is loud:")
        log.warning("  POST %s/webhook_endpoints/<we_id> "
                    "enabled_events[]=%s enabled_events[]=reporting.report_run.succeeded",
                    API, FAILURE_EVENT)
    return 1


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

/**
 * Report Stripe report runs that failed, stalled in pending, or never happened.
 *
 * Read only. Two paginated GETs and no writes: give this a RESTRICTED key with
 * read access to Reports and Webhook Endpoints. The repair is printed, never
 * performed.
 */
const API = 'https://api.stripe.com/v1';

// A run still pending past this is not being worked on.
export const STALL_SECONDS = 3600;
export const FAILURE_EVENT = 'reporting.report_run.failed';

/**
 * Classify one report run. Pure, so the pending deadline can be tested offline.
 * `ageSeconds` is how long ago the run was created.
 */
export function runState(status, ageSeconds, error = null) {
  if (status === 'succeeded') return ['succeeded', 'finished, result file available'];
  if (status === 'failed') {
    return ['failed', error || 'failed with no error message on the run'];
  }
  if (status === 'pending') {
    if (ageSeconds !== null && ageSeconds !== undefined && ageSeconds >= STALL_SECONDS) {
      return ['stalled',
        `pending for ${(ageSeconds / 3600).toFixed(1)} hour(s); nothing is working ` +
        'on it, treat it as failed'];
    }
    return ['running', `pending, still inside the ${STALL_SECONDS} second window`];
  }
  return ['unknown', `unrecognised status ${JSON.stringify(status)}`];
}

/** Fold run states, schedule gaps and webhook coverage into one verdict. Pure. */
export function verdict(states, missingDays, failureSubscribed) {
  const failed = states.filter((s) => s === 'failed').length;
  const stalled = states.filter((s) => s === 'stalled').length;
  if (states.length === 0) {
    return ['silent',
      'no report runs at all in the window; the export never reached Stripe, so ' +
      'there is nothing here to have failed'];
  }
  if (failed || stalled) {
    return ['failing',
      `${states.length} run(s): ${failed} failed, ${stalled} stalled in pending, ` +
      `${missingDays.length} expected day(s) with no successful run`];
  }
  if (missingDays.length) {
    return ['gaps',
      `${states.length} run(s), none failed, but ${missingDays.length} expected ` +
      `day(s) have no successful run: ${missingDays.slice(0, 5).join(', ')}`];
  }
  if (!failureSubscribed) {
    return ['unwatched',
      `${states.length} run(s), all successful, but nothing subscribes to ` +
      `${FAILURE_EVENT}, so the next failure is silent`];
  }
  return ['clear',
    `${states.length} run(s), 0 failed, 0 stalled, no missing days, failures subscribed`];
}

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.status === 403) {
    throw new Error('403 from Stripe: the restricted key has no read access here');
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

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

const utcDay = (unix) => new Date(unix * 1000).toISOString().slice(0, 10);

export function expectedDays(now, days) {
  const out = [];
  for (let n = 1; n <= days; n += 1) out.push(utcDay(now - n * 86400));
  return out;
}

export function failureIsSubscribed(endpoints) {
  return endpoints.some((ep) => ep.status !== 'disabled'
    && (ep.enabled_events ?? []).some((e) => e === FAILURE_EVENT || e === '*'));
}

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 ?? 30);
  const now = Date.now() / 1000;

  const runs = await pageAll(key, '/reporting/report_runs',
    { limit: 100, 'created[gte]': Math.floor(now - days * 86400) });

  const states = [];
  const succeededDays = new Set();
  for (const r of runs) {
    const age = r.created === undefined ? null : now - r.created;
    const [state, detail] = runState(r.status, age, r.error);
    states.push(state);
    if (state === 'succeeded' && r.succeeded_at) succeededDays.add(utcDay(r.succeeded_at));
    if (['failed', 'stalled', 'unknown'].includes(state)) {
      console.warn(`  ${state.padEnd(9)} ${r.id}  ${r.report_type}  ${detail}`);
    }
  }
  const missing = expectedDays(now, days).filter((d) => !succeededDays.has(d));

  const endpoints = await pageAll(key, '/webhook_endpoints', { limit: 100 });
  const subscribed = failureIsSubscribed(endpoints);

  const [state, detail] = verdict(states, missing, subscribed);
  const line = `${state.padEnd(11)} ${detail}`;
  if (state === 'clear') { console.log(line); return; }

  console.warn(line);
  console.warn('  read the reason off the run, then re-issue it:');
  console.warn(`  GET ${API}/reporting/report_runs/<frr_id>   (read .error, .parameters)`);
  console.warn(`  POST ${API}/reporting/report_runs with the corrected interval, then ` +
               'poll until status leaves pending');
  if (!subscribed) {
    console.warn('  and subscribe an endpoint so the next one is loud:');
    console.warn(`  POST ${API}/webhook_endpoints/<we_id> enabled_events[]=${FAILURE_EVENT}` +
                 ' enabled_events[]=reporting.report_run.succeeded');
  }
  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_report_runs import run_state, verdict


def test_succeeded_run_is_not_flagged():
    state, _ = run_state("succeeded", 120.0)
    assert state == "succeeded"


def test_pending_becomes_stalled_at_the_hour():
    # 59 minutes is still legitimately running; 60 is a run nothing is working on.
    assert run_state("pending", 3599.0)[0] == "running"
    state, detail = run_state("pending", 3600.0)
    assert state == "stalled"
    assert "1.0 hour" in detail


def test_failed_run_without_an_error_string_still_says_something():
    state, detail = run_state("failed", 30.0, None)
    assert state == "failed"
    assert "no error message" in detail


def test_all_successful_but_a_missing_day_is_not_clear():
    state, detail = verdict(["succeeded"] * 29, ["2026-08-14"], True)
    assert state == "gaps"
    assert "2026-08-14" in detail


def test_no_runs_at_all_is_the_loudest_case():
    assert verdict([], [], True)[0] == "silent"
    # Clean runs still are not clear while nothing listens for the failure event.
    assert verdict(["succeeded"], [], False)[0] == "unwatched"
    assert verdict(["succeeded"], [], True)[0] == "clear"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { runState, verdict } from './stripe-report-runs.mjs';

test('succeeded run is not flagged', () => {
  assert.equal(runState('succeeded', 120)[0], 'succeeded');
});

test('pending becomes stalled at the hour', () => {
  assert.equal(runState('pending', 3599)[0], 'running');
  const [state, detail] = runState('pending', 3600);
  assert.equal(state, 'stalled');
  assert.match(detail, /1\.0 hour/);
});

test('failed run without an error string still says something', () => {
  const [state, detail] = runState('failed', 30, null);
  assert.equal(state, 'failed');
  assert.match(detail, /no error message/);
});

test('all successful but a missing day is not clear', () => {
  const [state, detail] = verdict(Array(29).fill('succeeded'), ['2026-08-14'], true);
  assert.equal(state, 'gaps');
  assert.match(detail, /2026-08-14/);
});

test('no runs at all is the loudest case', () => {
  assert.equal(verdict([], [], true)[0], 'silent');
  assert.equal(verdict(['succeeded'], [], false)[0], 'unwatched');
  assert.equal(verdict(['succeeded'], [], true)[0], 'clear');
});