payout.failed is unsubscribed so failures go unseen for days

"""Report whether payout.failed is subscribed, and whether payouts already failed.

Read only. GETs only, no writes: give this a RESTRICTED key with read access to
Webhook Endpoints, Payouts and Events. 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 requests

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

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

TARGET = "payout.failed"
COMPANION = "payout.paid"


def verdict(subscribed, failed_payouts):
    """Classify payout-failure coverage. Pure, so the rules can be tested.

    `subscribed` is the union of enabled_events across every endpoint;
    `failed_payouts` is how many payouts are already in status failed.
    Returns (state, detail).
    """
    events = set(subscribed or [])
    if "*" in events:
        return ("wildcard",
                "a wildcard subscription covers %s, but it also delivers every "
                "other event type to the same handler." % TARGET)
    if TARGET in events:
        if COMPANION not in events:
            return ("partial",
                    "%s is subscribed but %s is not. Reconciliation cannot tell a "
                    "quiet week from a broken one." % (TARGET, COMPANION))
        return ("covered", "%s is subscribed on at least one endpoint" % TARGET)
    if failed_payouts:
        return ("blind",
                "%d payout(s) already failed and nothing subscribes to %s. The "
                "external account is disabled until the details are updated."
                % (failed_payouts, TARGET))
    return ("unsubscribed",
            "nothing subscribes to %s. No failures in the window yet, so this is "
            "a gap rather than an incident." % TARGET)


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 lacks read access to "
                         + path)
    r.raise_for_status()
    return r.json()


def subscribed_events(endpoints):
    """Union of enabled_events across endpoints. Pure, given the endpoint list."""
    union = set()
    for ep in endpoints:
        union.update(ep.get("enabled_events") or [])
    return union


def failed_payouts(session, limit):
    """Count payouts currently in status failed, and collect their failure codes."""
    codes = {}
    count = 0
    params = {"limit": 100, "status": "failed"}
    while True:
        page = get(session, "/payouts", **params)
        data = page.get("data", [])
        for p in data:
            count += 1
            code = p.get("failure_code") or "unknown"
            codes[code] = codes.get(code, 0) + 1
        if not data or not page.get("has_more") or count >= limit:
            break
        params["starting_after"] = data[-1]["id"]
    return count, codes


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-payouts", type=int, default=500,
                    help="stop counting failed payouts after this many")
    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})

    endpoints = get(s, "/webhook_endpoints", limit=100).get("data", [])
    union = subscribed_events(endpoints)
    count, codes = failed_payouts(s, args.max_payouts)

    state, detail = verdict(union, count)
    line = "%-13s %s" % (state, detail)
    if state == "covered":
        log.info(line)
        return 0

    log.warning(line)
    if codes:
        log.warning("  failure codes seen: %s",
                    ", ".join("%s x%d" % (c, n) for c, n in sorted(codes.items())))
    if state in ("blind", "unsubscribed", "partial"):
        target = endpoints[0]["id"] if endpoints else "<we_id>"
        log.warning("  repair: POST %s/webhook_endpoints/%s "
                    "-d enabled_events[]=%s -d enabled_events[]=%s",
                    API, target, TARGET, COMPANION)
        log.warning("  on Connect, add a connected-accounts destination carrying "
                    "%s and account.external_account.updated", TARGET)
    return 1


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

/**
 * Report whether payout.failed is subscribed, and whether payouts already failed.
 *
 * Read only. GETs only, no writes: give this a RESTRICTED key with read access to
 * Webhook Endpoints, Payouts and Events. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

const TARGET = 'payout.failed';
const COMPANION = 'payout.paid';

/**
 * Classify payout-failure coverage. Pure, so the rules can be tested.
 * `subscribed` is the union of enabled_events across every endpoint.
 */
export function verdict(subscribed, failedPayouts) {
  const events = new Set(subscribed ?? []);
  if (events.has('*')) {
    return ['wildcard',
      `a wildcard subscription covers ${TARGET}, but it also delivers every ` +
      'other event type to the same handler.'];
  }
  if (events.has(TARGET)) {
    if (!events.has(COMPANION)) {
      return ['partial',
        `${TARGET} is subscribed but ${COMPANION} is not. Reconciliation cannot ` +
        'tell a quiet week from a broken one.'];
    }
    return ['covered', `${TARGET} is subscribed on at least one endpoint`];
  }
  if (failedPayouts) {
    return ['blind',
      `${failedPayouts} payout(s) already failed and nothing subscribes to ` +
      `${TARGET}. The external account is disabled until the details are updated.`];
  }
  return ['unsubscribed',
    `nothing subscribes to ${TARGET}. No failures in the window yet, so this is ` +
    'a gap rather than an incident.'];
}

export function subscribedEvents(endpoints) {
  const union = new Set();
  for (const ep of endpoints ?? []) {
    for (const e of ep.enabled_events ?? []) union.add(e);
  }
  return union;
}

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 lacks read access to ${path}`);
  }
  if (!res.ok) throw new Error(`${res.status} from ${url.pathname}`);
  return res.json();
}

export async function failedPayouts(key, limit = 500) {
  const codes = new Map();
  let count = 0;
  const params = { limit: 100, status: 'failed' };
  for (;;) {
    const page = await get(key, '/payouts', params);
    const data = page.data ?? [];
    for (const p of data) {
      count += 1;
      const code = p.failure_code ?? 'unknown';
      codes.set(code, (codes.get(code) ?? 0) + 1);
    }
    if (data.length === 0 || !page.has_more || count >= limit) break;
    params.starting_after = data[data.length - 1].id;
  }
  return { count, codes };
}

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 { data: endpoints = [] } = await get(key, '/webhook_endpoints', { limit: 100 });
  const union = subscribedEvents(endpoints);
  const { count, codes } = await failedPayouts(key);

  const [state, detail] = verdict(union, count);
  const line = `${state.padEnd(13)} ${detail}`;
  if (state === 'covered') { console.log(line); return; }

  console.warn(line);
  if (codes.size > 0) {
    const seen = [...codes.entries()].sort().map(([c, n]) => `${c} x${n}`).join(', ');
    console.warn(`  failure codes seen: ${seen}`);
  }
  const target = endpoints.length > 0 ? endpoints[0].id : '<we_id>';
  console.warn(`  repair: POST ${API}/webhook_endpoints/${target} ` +
               `-d enabled_events[]=${TARGET} -d enabled_events[]=${COMPANION}`);
  console.warn('  on Connect, add a connected-accounts destination carrying ' +
               `${TARGET} and account.external_account.updated`);
  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_payout_events import verdict

BOTH = ["payout.paid", "payout.failed", "payment_intent.succeeded"]


def test_both_payout_events_subscribed_is_covered():
    state, _ = verdict(BOTH, 0)
    assert state == "covered"


def test_missing_subscription_with_failures_is_an_incident():
    state, detail = verdict(["payout.paid"], 3)
    assert state == "blind"
    assert "3 payout(s)" in detail


def test_missing_subscription_with_no_failures_is_only_a_gap():
    # Same configuration, different urgency. Collapsing these two loses the
    # distinction between a ticket and a page.
    state, _ = verdict(["payout.paid"], 0)
    assert state == "unsubscribed"


def test_failure_without_the_success_is_flagged_as_partial():
    state, _ = verdict(["payout.failed"], 0)
    assert state == "partial"


def test_a_wildcard_covers_it_but_is_named_as_such():
    state, detail = verdict(["*"], 0)
    assert state == "wildcard"
    assert "every" in detail

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

const BOTH = ['payout.paid', 'payout.failed', 'payment_intent.succeeded'];

test('both payout events subscribed is covered', () => {
  assert.equal(verdict(BOTH, 0)[0], 'covered');
});

test('missing subscription with failures is an incident', () => {
  const [state, detail] = verdict(['payout.paid'], 3);
  assert.equal(state, 'blind');
  assert.match(detail, /3 payout\(s\)/);
});

test('missing subscription with no failures is only a gap', () => {
  // Same configuration, different urgency.
  assert.equal(verdict(['payout.paid'], 0)[0], 'unsubscribed');
});

test('failure without the success is flagged as partial', () => {
  assert.equal(verdict(['payout.failed'], 0)[0], 'partial');
});

test('a wildcard covers it but is named as such', () => {
  const [state, detail] = verdict(['*'], 0);
  assert.equal(state, 'wildcard');
  assert.match(detail, /every/);
});