open invoices are weeks past due_date and nobody chases

"""Report open Stripe invoices that are past their due_date with nothing chasing them.

Read only. One paginated GET and no writes: give this a RESTRICTED key with read
access to Invoices. The repair is printed, never performed, because re-sending an
invoice emails a customer and marking one uncollectible writes off revenue.
"""
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_overdue_invoices")

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

ACTION_DAYS = 30      # earliest past-due subscription action Stripe offers
REMINDER_END_DAYS = 60  # past this, no built-in reminder will ever be sent


def verdict(days_overdue, amount_remaining):
    """Classify one open invoice. Pure, so the boundaries can be tested without a network.

    `days_overdue` is negative while the invoice is still within terms and None
    when it has no due_date at all. Returns (state, detail).
    """
    if not amount_remaining or amount_remaining <= 0:
        return ("nothing_due", "open with amount_remaining 0: no money outstanding")
    if days_overdue is None:
        return ("undated",
                "open with no due_date: it can never be overdue, so no reminder "
                "will ever fire for it")
    if days_overdue < 0:
        return ("current", "due in %.1f day(s)" % -days_overdue)
    if days_overdue < ACTION_DAYS:
        return ("overdue",
                "%.0f day(s) past due; still inside the reminder window" % days_overdue)
    if days_overdue < REMINDER_END_DAYS:
        return ("stale",
                "%.0f day(s) past due; past the point where a subscription action "
                "would have fired had one been configured" % days_overdue)
    return ("abandoned",
            "%.0f day(s) past due; beyond every built-in reminder, so nothing "
            "automated will chase this one again" % days_overdue)


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 open_invoices(session, limit):
    """Page open, manually collected invoices.

    There is no server-side filter for due_date on this endpoint, so the whole set
    comes back and the comparison happens here.
    """
    out = []
    params = {"status": "open", "collection_method": "send_invoice", "limit": 100}
    while True:
        page = get(session, "/invoices", **params)
        data = page.get("data", [])
        out.extend(data)
        if not data or not page.get("has_more") or len(out) >= limit:
            break
        params["starting_after"] = data[-1]["id"]
    return out


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--top", type=int, default=20,
                    help="how many individual invoices to print")
    ap.add_argument("--max-invoices", type=int, default=2000,
                    help="stop paginating after this many open invoices")
    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()
    rows = []
    for inv in open_invoices(s, args.max_invoices):
        due = inv.get("due_date")
        remaining = inv.get("amount_remaining") or 0
        rows.append((
            inv.get("id", "<no id>"),
            verdict(None if due is None else (now - due) / 86400.0, remaining),
            remaining,
            (inv.get("currency") or "").upper(),
        ))

    late = [r for r in rows if r[1][0] in ("overdue", "stale", "abandoned", "undated")]
    if not late:
        log.info("%-12s 0 open invoice(s) past due_date", "clear")
        return 0

    # Biggest balance first: the oldest invoice is rarely the one worth a call.
    late.sort(key=lambda r: r[2], reverse=True)
    outstanding = sum(r[2] for r in late)
    log.warning("%-12s %d unchased invoice(s) worth %d in minor units",
                "receivable", len(late), outstanding)
    for inv_id, (state, detail), amount, currency in late[:args.top]:
        log.warning("  %-12s %s  %d %s  %s", state, inv_id, amount, currency, detail)
    if len(late) > args.top:
        log.warning("  ... and %d more", len(late) - args.top)
    log.warning("  turn the follow-up on first: Dashboard, Settings, Billing, "
                "Invoices, then enable reminder emails and the past-due "
                "subscription action")
    log.warning("  then per invoice: POST %s/invoices/<id>/send to re-send, or "
                "mark_uncollectible on the ones nobody will pay", API)
    return 1


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

/**
 * Report open Stripe invoices past their due_date with nothing chasing them.
 *
 * Read only. One paginated GET and no writes: give this a RESTRICTED key with
 * read access to Invoices. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

const ACTION_DAYS = 30;             // earliest past-due subscription action
export const REMINDER_END_DAYS = 60; // past this, no built-in reminder is sent

/**
 * Classify one open invoice. Pure, so the boundaries can be tested without a network.
 * `daysOverdue` is negative within terms and null when there is no due_date.
 */
export function verdict(daysOverdue, amountRemaining) {
  if (!amountRemaining || amountRemaining <= 0) {
    return ['nothing_due', 'open with amount_remaining 0: no money outstanding'];
  }
  if (daysOverdue === null || daysOverdue === undefined) {
    return ['undated',
      'open with no due_date: it can never be overdue, so no reminder will ever fire for it'];
  }
  if (daysOverdue < 0) {
    return ['current', `due in ${(-daysOverdue).toFixed(1)} day(s)`];
  }
  if (daysOverdue < ACTION_DAYS) {
    return ['overdue',
      `${daysOverdue.toFixed(0)} day(s) past due; still inside the reminder window`];
  }
  if (daysOverdue < REMINDER_END_DAYS) {
    return ['stale',
      `${daysOverdue.toFixed(0)} day(s) past due; past the point where a ` +
      'subscription action would have fired had one been configured'];
  }
  return ['abandoned',
    `${daysOverdue.toFixed(0)} day(s) past due; beyond every built-in reminder, ` +
    'so nothing automated will chase this one again'];
}

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 openInvoices(key, limit = 2000) {
  const out = [];
  const params = { status: 'open', collection_method: 'send_invoice', limit: 100 };
  for (;;) {
    const page = await get(key, '/invoices', params);
    const data = page.data ?? [];
    out.push(...data);
    if (data.length === 0 || !page.has_more || out.length >= limit) break;
    params.starting_after = data[data.length - 1].id;
  }
  return out;
}

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;
  const rows = (await openInvoices(key)).map((inv) => {
    const remaining = inv.amount_remaining ?? 0;
    const due = inv.due_date;
    return {
      id: inv.id ?? '<no id>',
      amount: remaining,
      currency: (inv.currency ?? '').toUpperCase(),
      state: verdict(due === null || due === undefined ? null : (now - due) / 86400, remaining),
    };
  });

  const late = rows.filter((r) => ['overdue', 'stale', 'abandoned', 'undated'].includes(r.state[0]));
  if (late.length === 0) {
    console.log(`${'clear'.padEnd(12)} 0 open invoice(s) past due_date`);
    return;
  }

  // Biggest balance first: the oldest invoice is rarely the one worth a call.
  late.sort((a, b) => b.amount - a.amount);
  const outstanding = late.reduce((a, r) => a + r.amount, 0);
  console.warn(`${'receivable'.padEnd(12)} ${late.length} unchased invoice(s) worth ${outstanding} in minor units`);
  for (const r of late.slice(0, 20)) {
    const [state, detail] = r.state;
    console.warn(`  ${state.padEnd(12)} ${r.id}  ${r.amount} ${r.currency}  ${detail}`);
  }
  if (late.length > 20) console.warn(`  ... and ${late.length - 20} more`);
  console.warn('  turn the follow-up on first: Dashboard, Settings, Billing, ' +
               'Invoices, then enable reminder emails and the past-due subscription action');
  console.warn(`  then per invoice: POST ${API}/invoices/<id>/send to re-send, or ` +
               'mark_uncollectible on the ones nobody will pay');
  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_overdue_invoices import verdict


def test_within_terms_is_current():
    state, detail = verdict(-4.0, 25000)
    assert state == "current"
    assert "4.0" in detail


def test_the_due_date_itself_is_already_overdue():
    assert verdict(-0.1, 25000)[0] == "current"
    assert verdict(0.0, 25000)[0] == "overdue"


def test_thirty_and_sixty_days_are_the_two_boundaries():
    assert verdict(29.9, 25000)[0] == "overdue"
    assert verdict(30.0, 25000)[0] == "stale"
    assert verdict(59.9, 25000)[0] == "stale"
    state, detail = verdict(60.0, 25000)
    assert state == "abandoned"
    assert "nothing automated will chase" in detail


def test_no_due_date_is_reported_rather_than_ignored():
    # It can never be overdue, which means no reminder will ever fire. Silence
    # here is how an invoice leaves the receivable report for good.
    state, _ = verdict(None, 25000)
    assert state == "undated"


def test_a_zero_balance_is_not_receivable():
    assert verdict(120.0, 0)[0] == "nothing_due"

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

test('within terms is current', () => {
  const [state, detail] = verdict(-4.0, 25000);
  assert.equal(state, 'current');
  assert.match(detail, /4.0/);
});

test('the due date itself is already overdue', () => {
  assert.equal(verdict(-0.1, 25000)[0], 'current');
  assert.equal(verdict(0.0, 25000)[0], 'overdue');
});

test('thirty and sixty days are the two boundaries', () => {
  assert.equal(verdict(29.9, 25000)[0], 'overdue');
  assert.equal(verdict(30.0, 25000)[0], 'stale');
  assert.equal(verdict(59.9, 25000)[0], 'stale');
  const [state, detail] = verdict(60.0, 25000);
  assert.equal(state, 'abandoned');
  assert.match(detail, /nothing automated will chase/);
});

test('no due date is reported rather than ignored', () => {
  assert.equal(verdict(null, 25000)[0], 'undated');
});

test('a zero balance is not receivable', () => {
  assert.equal(verdict(120.0, 0)[0], 'nothing_due');
});