a connected account sits with charges_enabled false

"""Report connected accounts that cannot take payments, and say who can fix each.

Read only. One paginated GET and no writes: give this a RESTRICTED key with read
access to Connected accounts. 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_connect_charges_disabled")

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

# Reasons the API cannot clear. An onboarding link sent to one of these produces a
# completed form and no change in status, which reads as a broken link to the
# seller and as a fixed account to whoever sent it.
DASHBOARD_ONLY = ("listed", "under_review", "rejected")

# Stripe is holding the account while it checks something. There is no field to
# collect and nothing for anyone to do.
WAITING = ("requirements.pending_verification",)


def classify(account):
    """Sort one connected account. Pure, so the reason table can be tested.

    Takes an /v1/accounts object. Returns (state, detail). The states exist to
    split the work by who can do it: `blocked` is an email, `rejected` is a human
    in the Dashboard, `waiting` is nobody.
    """
    reqs = account.get("requirements") or {}
    reason = reqs.get("disabled_reason")
    due = [f for f in (reqs.get("currently_due") or []) if f]

    if account.get("charges_enabled"):
        return ("live", "charges_enabled, nothing to chase")

    if not account.get("details_submitted"):
        return ("never-onboarded",
                "details_submitted is false: this account never opened, so it has "
                "not broken. Do not page anyone about it.")

    if reason and (reason in DASHBOARD_ONLY or reason.split(".", 1)[0] == "rejected"):
        return ("rejected",
                "disabled_reason %s: the API cannot clear this. It is resolved from "
                "the Dashboard Connected accounts page, or not at all." % reason)

    if reason in WAITING:
        return ("waiting",
                "disabled_reason %s: Stripe is verifying what it already has. "
                "Collecting more fields does not speed it up." % reason)

    if due:
        return ("blocked",
                "%s, %d field(s) currently due: %s"
                % (reason or "no disabled_reason", len(due), ", ".join(due[:4])))

    if reason:
        return ("blocked",
                "%s with nothing in currently_due: read the per-capability "
                "requirements before collecting anything." % reason)

    return ("unknown",
            "charges_enabled is false with no disabled_reason and no currently_due")


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 accounts(session, cap):
    """Yield connected accounts, paginating until Stripe stops or the cap is hit."""
    seen = 0
    params = {"limit": 100}
    while True:
        page = get(session, "/accounts", **params)
        data = page.get("data", [])
        for acct in data:
            yield acct
            seen += 1
            if seen >= cap:
                return
        if not data or not page.get("has_more"):
            return
        params["starting_after"] = data[-1]["id"]


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-accounts", type=int, default=5000,
                    help="stop paginating after this many accounts")
    ap.add_argument("--quiet-never-onboarded", action="store_true",
                    help="do not list accounts that never finished onboarding")
    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})

    counts = {}
    scanned = 0
    for acct in accounts(s, args.max_accounts):
        scanned += 1
        state, detail = classify(acct)
        counts[state] = counts.get(state, 0) + 1
        if state == "live":
            continue
        if state == "never-onboarded" and args.quiet_never_onboarded:
            continue
        log.warning("%s  %-16s %s", acct.get("id", "acct_?"), state, detail)

    blocked = counts.get("blocked", 0)
    rejected = counts.get("rejected", 0)
    unknown = counts.get("unknown", 0)

    log.info("%d account(s): %d blocked, %d rejected, %d never onboarded",
             scanned, blocked, rejected, counts.get("never-onboarded", 0))

    if blocked:
        log.warning("  repair: read the union of currently_due across every "
                    "capability first:")
        log.warning("  GET %s/accounts/{id}/capabilities", API)
        log.warning("  repair: create an account link for the seller, "
                    "type=account_onboarding, collection_options[fields]=currently_due")
    if rejected:
        log.warning("  repair: Dashboard, Connected accounts, open the account. "
                    "No API call clears a rejected.* or under_review reason.")
    if blocked or rejected or unknown:
        log.warning("  check: an endpoint with connect=true subscribed to "
                    "account.updated turns this into an event instead of a ticket")
    return 1 if (blocked or rejected or unknown) else 0


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

/**
 * Report connected accounts that cannot take payments, and say who can fix each.
 *
 * Read only. One paginated GET and no writes: give this a RESTRICTED key with
 * read access to Connected accounts. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// Reasons the API cannot clear. An onboarding link sent to one of these produces
// a completed form and no change in status.
const DASHBOARD_ONLY = ['listed', 'under_review', 'rejected'];

// Stripe is holding the account while it checks something. Nothing to collect.
const WAITING = ['requirements.pending_verification'];

/**
 * Sort one connected account. Pure, so the reason table can be tested.
 * Returns [state, detail]. The states split the work by who can do it.
 */
export function classify(account) {
  const reqs = account.requirements ?? {};
  const reason = reqs.disabled_reason ?? null;
  const due = (reqs.currently_due ?? []).filter(Boolean);

  if (account.charges_enabled) return ['live', 'charges_enabled, nothing to chase'];

  if (!account.details_submitted) {
    return ['never-onboarded',
      'details_submitted is false: this account never opened, so it has not ' +
      'broken. Do not page anyone about it.'];
  }

  if (reason && (DASHBOARD_ONLY.includes(reason) || reason.split('.')[0] === 'rejected')) {
    return ['rejected',
      `disabled_reason ${reason}: the API cannot clear this. It is resolved from ` +
      'the Dashboard Connected accounts page, or not at all.'];
  }

  if (reason && WAITING.includes(reason)) {
    return ['waiting',
      `disabled_reason ${reason}: Stripe is verifying what it already has. ` +
      'Collecting more fields does not speed it up.'];
  }

  if (due.length) {
    return ['blocked',
      `${reason ?? 'no disabled_reason'}, ${due.length} field(s) currently due: ` +
      due.slice(0, 4).join(', ')];
  }

  if (reason) {
    return ['blocked',
      `${reason} with nothing in currently_due: read the per-capability ` +
      'requirements before collecting anything.'];
  }

  return ['unknown',
    'charges_enabled is false with no disabled_reason and no currently_due'];
}

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* accounts(key, cap = 5000) {
  let seen = 0;
  const params = { limit: 100 };
  for (;;) {
    const page = await get(key, '/accounts', params);
    const data = page.data ?? [];
    for (const acct of data) {
      yield acct;
      seen += 1;
      if (seen >= cap) return;
    }
    if (data.length === 0 || !page.has_more) return;
    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 counts = new Map();
  let scanned = 0;

  for await (const acct of accounts(key)) {
    scanned += 1;
    const [state, detail] = classify(acct);
    counts.set(state, (counts.get(state) ?? 0) + 1);
    if (state === 'live') continue;
    console.warn(`${acct.id ?? 'acct_?'}  ${state.padEnd(16)} ${detail}`);
  }

  const blocked = counts.get('blocked') ?? 0;
  const rejected = counts.get('rejected') ?? 0;
  const unknown = counts.get('unknown') ?? 0;

  console.log(`${scanned} account(s): ${blocked} blocked, ${rejected} rejected, ` +
              `${counts.get('never-onboarded') ?? 0} never onboarded`);

  if (blocked) {
    console.warn('  repair: read the union of currently_due across every capability first:');
    console.warn(`  GET ${API}/accounts/{id}/capabilities`);
    console.warn('  repair: create an account link for the seller, ' +
                 'type=account_onboarding, collection_options[fields]=currently_due');
  }
  if (rejected) {
    console.warn('  repair: Dashboard, Connected accounts, open the account. ' +
                 'No API call clears a rejected.* or under_review reason.');
  }
  if (blocked || rejected || unknown) {
    console.warn('  check: an endpoint with connect=true subscribed to ' +
                 'account.updated turns this into an event instead of a ticket');
    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_connect_charges_disabled import classify


def test_enabled_account_is_live():
    state, _ = classify({"charges_enabled": True, "details_submitted": True})
    assert state == "live"


def test_never_onboarded_is_not_an_incident():
    state, detail = classify({"charges_enabled": False, "details_submitted": False})
    assert state == "never-onboarded"
    assert "never opened" in detail


def test_every_rejected_reason_is_dashboard_only():
    # rejected.* is an open family; matching the prefix rather than a fixed list
    # is the difference between a correct answer and one that ages badly.
    for reason in ("rejected.fraud", "rejected.listed", "rejected.terms_of_service",
                   "rejected.other", "listed", "under_review"):
        state, detail = classify({
            "charges_enabled": False, "details_submitted": True,
            "requirements": {"disabled_reason": reason,
                             "currently_due": ["company.tax_id"]},
        })
        assert state == "rejected", reason
        assert "cannot clear" in detail


def test_past_due_is_blocked_and_names_the_fields():
    state, detail = classify({
        "charges_enabled": False, "details_submitted": True,
        "requirements": {"disabled_reason": "requirements.past_due",
                         "currently_due": ["company.tax_id", "business_profile.url"]},
    })
    assert state == "blocked"
    assert "company.tax_id" in detail


def test_pending_verification_asks_nobody_for_anything():
    state, detail = classify({
        "charges_enabled": False, "details_submitted": True,
        "requirements": {"disabled_reason": "requirements.pending_verification",
                         "currently_due": []},
    })
    assert state == "waiting"
    assert "does not speed it up" in detail


def test_disabled_with_no_explanation_is_not_reported_as_healthy():
    state, _ = classify({"charges_enabled": False, "details_submitted": True,
                         "requirements": {}})
    assert state == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { classify } from './stripe-connect-charges-disabled.mjs';

test('enabled account is live', () => {
  assert.equal(classify({ charges_enabled: true, details_submitted: true })[0], 'live');
});

test('never onboarded is not an incident', () => {
  const [state, detail] = classify({ charges_enabled: false, details_submitted: false });
  assert.equal(state, 'never-onboarded');
  assert.match(detail, /never opened/);
});

test('every rejected reason is dashboard only', () => {
  // rejected.* is an open family; matching the prefix rather than a fixed list is
  // the difference between a correct answer and one that ages badly.
  for (const reason of ['rejected.fraud', 'rejected.listed', 'rejected.terms_of_service',
    'rejected.other', 'listed', 'under_review']) {
    const [state, detail] = classify({
      charges_enabled: false,
      details_submitted: true,
      requirements: { disabled_reason: reason, currently_due: ['company.tax_id'] },
    });
    assert.equal(state, 'rejected', reason);
    assert.match(detail, /cannot clear/);
  }
});

test('past due is blocked and names the fields', () => {
  const [state, detail] = classify({
    charges_enabled: false,
    details_submitted: true,
    requirements: {
      disabled_reason: 'requirements.past_due',
      currently_due: ['company.tax_id', 'business_profile.url'],
    },
  });
  assert.equal(state, 'blocked');
  assert.match(detail, /company\.tax_id/);
});

test('pending verification asks nobody for anything', () => {
  const [state, detail] = classify({
    charges_enabled: false,
    details_submitted: true,
    requirements: {
      disabled_reason: 'requirements.pending_verification',
      currently_due: [],
    },
  });
  assert.equal(state, 'waiting');
  assert.match(detail, /does not speed it up/);
});

test('disabled with no explanation is not reported as healthy', () => {
  assert.equal(
    classify({ charges_enabled: false, details_submitted: true, requirements: {} })[0],
    'unknown');
});