save_default_payment_method off orphans the card after payment

"""Report Stripe subscriptions that will have nothing to charge at renewal.

Read only. One paginated GET per status, no writes: give this a RESTRICTED key
with read access to Subscriptions and Customers. 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_save_default_pm")

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

FAILED_STATUSES = ("past_due", "unpaid")


def verdict(subscription):
    """Classify one subscription. Pure, so the rules can be tested without a network.

    Returns (state, detail). The subscription's `customer` must be expanded; when
    it is only an id there is no way to know whether a customer-level default
    exists, and guessing either way is worse than saying so.
    """
    settings = subscription.get("payment_settings") or {}
    save = settings.get("save_default_payment_method")

    # Absent is the same as "off": Stripe omits the field when it was never set,
    # which is how almost every affected subscription actually looks.
    if save not in (None, "off", "on_subscription"):
        return ("unknown", "unrecognised save_default_payment_method %r" % (save,))
    if save == "on_subscription":
        return ("on", "the card that pays an invoice becomes the subscription default")

    if subscription.get("default_payment_method"):
        return ("saved", "the flag is off, but a default is already set on the "
                         "subscription")

    customer = subscription.get("customer")
    if not isinstance(customer, dict):
        return ("unknown",
                "customer is not expanded, so the fallback default cannot be read; "
                "re-read with expand[]=data.customer")

    invoice_settings = customer.get("invoice_settings") or {}
    if invoice_settings.get("default_payment_method"):
        return ("fallback",
                "nothing on the subscription; renewals fall back to the customer "
                "default. Working, and one refactor away from not working.")

    if subscription.get("status") in FAILED_STATUSES:
        return ("failing",
                "status %s with no payment method on the subscription and none on "
                "the customer. The renewal has already failed."
                % subscription.get("status"))

    return ("stranded",
            "no payment method on the subscription and none on the customer. The "
            "next renewal has nothing to charge.")


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 page_all(session, path, limit, **params):
    seen = 0
    params = dict(params, limit=100)
    while True:
        page = get(session, path, **params)
        data = page.get("data", [])
        for obj in data:
            yield obj
            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("--max-subscriptions", type=int, default=5000,
                    help="stop paginating each status after this many subscriptions")
    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 = {}
    flagged = []
    total = 0
    for status in ("active",) + FAILED_STATUSES:
        for sub in page_all(s, "/subscriptions", args.max_subscriptions,
                            status=status, **{"expand[]": "data.customer"}):
            total += 1
            state, detail = verdict(sub)
            counts[state] = counts.get(state, 0) + 1
            if state in ("stranded", "failing", "unknown"):
                flagged.append((state, sub["id"], detail))

    if not total:
        log.info("no subscriptions for this key's mode")
        return 0

    for state, sub_id, detail in flagged[:25]:
        log.warning("%-9s %s  %s", state, sub_id, detail)
        log.warning("  repair: POST %s/subscriptions/%s "
                    "-d \"payment_settings[save_default_payment_method]=on_subscription\"",
                    API, sub_id)

    bad = counts.get("stranded", 0) + counts.get("failing", 0)
    if counts.get("fallback"):
        log.info("%d subscription(s) rely on the customer default; they work until "
                 "the signup flow stops writing it", counts["fallback"])
    log.info("%d subscription(s), %d stranded, %d already failing",
             total, counts.get("stranded", 0), counts.get("failing", 0))
    if not bad:
        return 0
    log.warning("set it at creation so this stops recurring:")
    log.warning("  POST %s/subscriptions "
                "-d \"payment_settings[save_default_payment_method]=on_subscription\"",
                API)
    return 1


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

/**
 * Report Stripe subscriptions that will have nothing to charge at renewal.
 *
 * Read only. One paginated GET per status, no writes: give this a RESTRICTED key
 * with read access to Subscriptions and Customers. The repair is printed, never
 * performed.
 */
const API = 'https://api.stripe.com/v1';

export const FAILED_STATUSES = ['past_due', 'unpaid'];

/**
 * Classify one subscription. Pure, so the rules can be tested without a network.
 *
 * The subscription's `customer` must be expanded; when it is only an id there is
 * no way to know whether a customer-level default exists, and guessing either way
 * is worse than saying so.
 */
export function verdict(subscription) {
  const settings = subscription.payment_settings ?? {};
  const save = settings.save_default_payment_method;

  // Absent is the same as 'off': Stripe omits the field when it was never set,
  // which is how almost every affected subscription actually looks.
  if (save !== undefined && save !== null && save !== 'off' && save !== 'on_subscription') {
    return ['unknown', `unrecognised save_default_payment_method ${JSON.stringify(save)}`];
  }
  if (save === 'on_subscription') {
    return ['on', 'the card that pays an invoice becomes the subscription default'];
  }

  if (subscription.default_payment_method) {
    return ['saved', 'the flag is off, but a default is already set on the subscription'];
  }

  const customer = subscription.customer;
  if (!customer || typeof customer !== 'object') {
    return ['unknown',
      'customer is not expanded, so the fallback default cannot be read; ' +
      're-read with expand[]=data.customer'];
  }

  if (customer.invoice_settings?.default_payment_method) {
    return ['fallback',
      'nothing on the subscription; renewals fall back to the customer default. ' +
      'Working, and one refactor away from not working.'];
  }

  if (FAILED_STATUSES.includes(subscription.status)) {
    return ['failing',
      `status ${subscription.status} with no payment method on the subscription ` +
      'and none on the customer. The renewal has already failed.'];
  }

  return ['stranded',
    'no payment method on the subscription and none on the customer. The next ' +
    'renewal has nothing to charge.'];
}

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

async function* pageAll(key, path, limit, params = {}) {
  let seen = 0;
  const p = { ...params, limit: 100 };
  for (;;) {
    const page = await get(key, path, p);
    const data = page.data ?? [];
    for (const obj of data) { yield obj; seen += 1; }
    if (data.length === 0 || !page.has_more || seen >= limit) break;
    p.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();
  const flagged = [];
  let total = 0;
  for (const status of ['active', ...FAILED_STATUSES]) {
    for await (const sub of pageAll(key, '/subscriptions', 5000,
      { status, 'expand[]': 'data.customer' })) {
      total += 1;
      const [state, detail] = verdict(sub);
      counts.set(state, (counts.get(state) ?? 0) + 1);
      if (state === 'stranded' || state === 'failing' || state === 'unknown') {
        flagged.push([state, sub.id, detail]);
      }
    }
  }

  if (!total) {
    console.log("no subscriptions for this key's mode");
    return;
  }

  for (const [state, id, detail] of flagged.slice(0, 25)) {
    console.warn(`${state.padEnd(9)} ${id}  ${detail}`);
    console.warn(`  repair: POST ${API}/subscriptions/${id} ` +
                 '-d "payment_settings[save_default_payment_method]=on_subscription"');
  }

  const stranded = counts.get('stranded') ?? 0;
  const failing = counts.get('failing') ?? 0;
  if (counts.get('fallback')) {
    console.log(`${counts.get('fallback')} subscription(s) rely on the customer ` +
                'default; they work until the signup flow stops writing it');
  }
  console.log(`${total} subscription(s), ${stranded} stranded, ${failing} already failing`);
  if (!(stranded + failing)) return;
  console.warn('set it at creation so this stops recurring:');
  console.warn(`  POST ${API}/subscriptions ` +
               '-d "payment_settings[save_default_payment_method]=on_subscription"');
  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_save_default_pm import verdict


def sub(**over):
    base = {"id": "sub_1", "status": "active", "payment_settings": {},
            "default_payment_method": None,
            "customer": {"id": "cus_1", "invoice_settings": {}}}
    base.update(over)
    return base


def test_an_absent_flag_is_treated_as_off():
    # Stripe omits the field when it was never set. This is the common shape.
    state, _ = verdict(sub(payment_settings={}))
    assert state == "stranded"


def test_an_explicit_off_reaches_the_same_verdict():
    assert verdict(sub(payment_settings={"save_default_payment_method": "off"}))[0] \
        == "stranded"


def test_on_subscription_is_the_fix():
    state, _ = verdict(sub(payment_settings={"save_default_payment_method": "on_subscription"}))
    assert state == "on"


def test_a_subscription_default_makes_the_flag_moot():
    assert verdict(sub(default_payment_method="pm_1"))[0] == "saved"


def test_a_customer_default_is_a_fallback_not_a_fix():
    state, detail = verdict(sub(customer={"id": "cus_1",
                                          "invoice_settings": {"default_payment_method": "pm_2"}}))
    assert state == "fallback"
    assert "refactor" in detail


def test_past_due_with_nothing_to_charge_has_already_failed():
    state, _ = verdict(sub(status="past_due"))
    assert state == "failing"


def test_an_unexpanded_customer_is_not_silently_stranded():
    # A bare id looks exactly like a customer with no default. Say so instead.
    state, detail = verdict(sub(customer="cus_1"))
    assert state == "unknown"
    assert "expand" in detail


def test_an_unrecognised_value_is_not_silently_healthy():
    assert verdict(sub(payment_settings={"save_default_payment_method": "always"}))[0] \
        == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { verdict } from './stripe-save-default-pm.mjs';

function sub(over = {}) {
  return {
    id: 'sub_1',
    status: 'active',
    payment_settings: {},
    default_payment_method: null,
    customer: { id: 'cus_1', invoice_settings: {} },
    ...over,
  };
}

test('an absent flag is treated as off', () => {
  assert.equal(verdict(sub({ payment_settings: {} }))[0], 'stranded');
});

test('an explicit off reaches the same verdict', () => {
  assert.equal(
    verdict(sub({ payment_settings: { save_default_payment_method: 'off' } }))[0],
    'stranded');
});

test('on_subscription is the fix', () => {
  assert.equal(
    verdict(sub({ payment_settings: { save_default_payment_method: 'on_subscription' } }))[0],
    'on');
});

test('a subscription default makes the flag moot', () => {
  assert.equal(verdict(sub({ default_payment_method: 'pm_1' }))[0], 'saved');
});

test('a customer default is a fallback not a fix', () => {
  const [state, detail] = verdict(sub({
    customer: { id: 'cus_1', invoice_settings: { default_payment_method: 'pm_2' } },
  }));
  assert.equal(state, 'fallback');
  assert.match(detail, /refactor/);
});

test('past_due with nothing to charge has already failed', () => {
  assert.equal(verdict(sub({ status: 'past_due' }))[0], 'failing');
});

test('an unexpanded customer is not silently stranded', () => {
  const [state, detail] = verdict(sub({ customer: 'cus_1' }));
  assert.equal(state, 'unknown');
  assert.match(detail, /expand/);
});

test('an unrecognised value is not silently healthy', () => {
  assert.equal(
    verdict(sub({ payment_settings: { save_default_payment_method: 'always' } }))[0],
    'unknown');
});