customers have no address, so tax and SCA exemptions fail

"""Report Stripe customers whose address cannot satisfy Tax, AVS or SCA.

Read only. Paginated GETs and one search, no writes: give this a RESTRICTED key
with read access to Customers, Subscriptions and Invoices. 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_customer_address")

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

WIDESPREAD = 0.25   # share of incomplete addresses that means the collection path is wrong


def address_state(customer):
    """Classify one customer's address. Pure, so it can be tested without a network.

    Returns one of "missing", "no_country", "no_postal_code" or "complete".

    Stripe returns `address` either as null or as an object whose fields are
    individually null. An object with nothing in it is an absent address, not a
    partial one, and collapsing the two hides the customers who look filled in on
    the Dashboard but resolve to no location at all.
    """
    addr = customer.get("address")
    if not isinstance(addr, dict):
        return "missing"
    if not any(v for v in addr.values()):
        return "missing"
    if not addr.get("country"):
        return "no_country"
    if not addr.get("postal_code"):
        return "no_postal_code"
    return "complete"


def verdict(total, incomplete, subscribed_incomplete, tax_failures):
    """Roll the counts up into one state. Pure.

    Ordered deliberately: an invoice that has already refused to finalize outranks
    any percentage, and a subscribed customer outranks a free-tier one, because
    only the subscribed ones have a finalization due every cycle.
    """
    if not total:
        return ("unknown", "no customers read; check the key and the mode it belongs to")
    if tax_failures:
        return ("failing",
                "%d invoice(s) already refused to finalize with "
                "customer_tax_location_invalid. This is not a risk, it is unsent "
                "revenue." % tax_failures)
    if subscribed_incomplete:
        return ("billing",
                "%d subscribed customer(s) have an incomplete address. Each renewal "
                "is a finalization that can fail." % subscribed_incomplete)
    share = incomplete / float(total)
    if share >= WIDESPREAD:
        return ("widespread",
                "%d of %d customer(s), %.0f%%, have an incomplete address. At that "
                "share the collection path is wrong, not the data." % (
                    incomplete, total, share * 100))
    if incomplete:
        return ("residue",
                "%d of %d customer(s) have an incomplete address. Backfill them and "
                "close the collection hole." % (incomplete, total))
    return ("clear", "%d customer(s), 0 with an incomplete address" % total)


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):
    """Yield every object from a paginated list endpoint, up to `limit`."""
    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 tax_failure_count(session):
    """Count invoices that failed to finalize on the customer's location.

    Search is a separate index and is not enabled on every account, so a failure
    here is reported and treated as no evidence rather than as zero evidence.
    """
    try:
        page = get(session, "/invoices/search",
                   query="last_finalization_error_code:'customer_tax_location_invalid'",
                   limit=100)
    except requests.HTTPError as exc:
        log.info("invoice search unavailable (%s); skipping the confirmation step", exc)
        return 0
    return len(page.get("data", []))


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--max-customers", type=int, default=5000,
                    help="stop paginating customers 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})

    buckets = {"missing": 0, "no_country": 0, "no_postal_code": 0, "complete": 0}
    examples = {}
    total = 0
    for cus in page_all(s, "/customers", args.max_customers):
        state = address_state(cus)
        buckets[state] += 1
        total += 1
        if state != "complete":
            examples.setdefault(state, cus["id"])

    subscribed_incomplete = 0
    for sub in page_all(s, "/subscriptions", 1000, status="active",
                        **{"expand[]": "data.customer"}):
        cus = sub.get("customer")
        if isinstance(cus, dict) and address_state(cus) != "complete":
            subscribed_incomplete += 1

    incomplete = total - buckets["complete"]
    state, detail = verdict(total, incomplete, subscribed_incomplete,
                            tax_failure_count(s))

    line = "%-11s %s" % (state, detail)
    if state in ("clear", "unknown"):
        log.info(line)
        return 0

    log.warning(line)
    log.warning("  %d absent, %d without a country, %d without a postal code",
                buckets["missing"], buckets["no_country"], buckets["no_postal_code"])
    for bucket, cus_id in sorted(examples.items()):
        log.warning("  example %-14s %s", bucket, cus_id)
    log.warning("  repair one customer:")
    log.warning("  POST %s/customers/{id} -d \"address[line1]=...\" "
                "-d \"address[city]=...\" -d \"address[postal_code]=...\" "
                "-d \"address[country]=US\"", API)
    log.warning("  stop creating more: set billing_address_collection=required on "
                "Checkout Sessions, or collect billing details in the Payment Element")
    return 1


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

/**
 * Report Stripe customers whose address cannot satisfy Tax, AVS or SCA.
 *
 * Read only. Paginated GETs and one search, no writes: give this a RESTRICTED
 * key with read access to Customers, Subscriptions and Invoices. The repair is
 * printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

// Share of incomplete addresses that means the collection path is wrong.
export const WIDESPREAD = 0.25;

/**
 * Classify one customer's address. Pure, so it can be tested without a network.
 * Returns 'missing', 'no_country', 'no_postal_code' or 'complete'.
 *
 * Stripe returns `address` either as null or as an object whose fields are
 * individually null. An object with nothing in it is an absent address, not a
 * partial one.
 */
export function addressState(customer) {
  const addr = customer.address;
  if (!addr || typeof addr !== 'object') return 'missing';
  if (!Object.values(addr).some((v) => v)) return 'missing';
  if (!addr.country) return 'no_country';
  if (!addr.postal_code) return 'no_postal_code';
  return 'complete';
}

/**
 * Roll the counts up into one state. Pure.
 * An invoice that has already refused to finalize outranks any percentage.
 */
export function verdict(total, incomplete, subscribedIncomplete, taxFailures) {
  if (!total) {
    return ['unknown', 'no customers read; check the key and the mode it belongs to'];
  }
  if (taxFailures) {
    return ['failing',
      `${taxFailures} invoice(s) already refused to finalize with ` +
      'customer_tax_location_invalid. This is not a risk, it is unsent revenue.'];
  }
  if (subscribedIncomplete) {
    return ['billing',
      `${subscribedIncomplete} subscribed customer(s) have an incomplete address. ` +
      'Each renewal is a finalization that can fail.'];
  }
  const share = incomplete / total;
  if (share >= WIDESPREAD) {
    return ['widespread',
      `${incomplete} of ${total} customer(s), ${Math.round(share * 100)}%, have an ` +
      'incomplete address. At that share the collection path is wrong, not the data.'];
  }
  if (incomplete) {
    return ['residue',
      `${incomplete} of ${total} customer(s) have an incomplete address. Backfill ` +
      'them and close the collection hole.'];
  }
  return ['clear', `${total} customer(s), 0 with an incomplete address`];
}

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 taxFailureCount(key) {
  try {
    const page = await get(key, '/invoices/search', {
      query: "last_finalization_error_code:'customer_tax_location_invalid'",
      limit: 100,
    });
    return (page.data ?? []).length;
  } catch (err) {
    console.log(`invoice search unavailable (${err.message}); skipping the confirmation step`);
    return 0;
  }
}

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 buckets = { missing: 0, no_country: 0, no_postal_code: 0, complete: 0 };
  const examples = new Map();
  let total = 0;
  for await (const cus of pageAll(key, '/customers', 5000)) {
    const state = addressState(cus);
    buckets[state] += 1;
    total += 1;
    if (state !== 'complete' && !examples.has(state)) examples.set(state, cus.id);
  }

  let subscribedIncomplete = 0;
  for await (const sub of pageAll(key, '/subscriptions', 1000,
    { status: 'active', 'expand[]': 'data.customer' })) {
    const cus = sub.customer;
    if (cus && typeof cus === 'object' && addressState(cus) !== 'complete') {
      subscribedIncomplete += 1;
    }
  }

  const incomplete = total - buckets.complete;
  const [state, detail] = verdict(total, incomplete, subscribedIncomplete,
    await taxFailureCount(key));

  const line = `${state.padEnd(11)} ${detail}`;
  if (state === 'clear' || state === 'unknown') { console.log(line); return; }

  console.warn(line);
  console.warn(`  ${buckets.missing} absent, ${buckets.no_country} without a country, ` +
               `${buckets.no_postal_code} without a postal code`);
  for (const [bucket, id] of [...examples].sort()) {
    console.warn(`  example ${bucket.padEnd(14)} ${id}`);
  }
  console.warn('  repair one customer:');
  console.warn(`  POST ${API}/customers/{id} -d "address[line1]=..." ` +
               '-d "address[city]=..." -d "address[postal_code]=..." -d "address[country]=US"');
  console.warn('  stop creating more: set billing_address_collection=required on ' +
               'Checkout Sessions, or collect billing details in the Payment Element');
  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_customer_address import address_state, verdict


def test_absent_address_is_missing():
    assert address_state({"id": "cus_1"}) == "missing"
    assert address_state({"address": None}) == "missing"


def test_address_object_with_every_field_null_is_missing_not_partial():
    # Stripe returns this shape. It renders as an address and resolves to nothing.
    empty = {"line1": None, "line2": None, "city": None,
             "state": None, "postal_code": None, "country": None}
    assert address_state({"address": empty}) == "missing"


def test_street_and_city_without_a_country_still_fails_tax():
    addr = {"line1": "12 Rue de Rivoli", "city": "Paris", "postal_code": "75001"}
    assert address_state({"address": addr}) == "no_country"


def test_country_without_a_postal_code_fails_avs():
    assert address_state({"address": {"country": "US", "city": "Denver"}}) == "no_postal_code"


def test_a_complete_address_is_complete():
    addr = {"line1": "1 Main St", "city": "Denver", "postal_code": "80202", "country": "US"}
    assert address_state({"address": addr}) == "complete"


def test_a_failed_finalization_outranks_any_percentage():
    state, detail = verdict(1000, 1, 0, 3)
    assert state == "failing"
    assert "3" in detail


def test_subscribed_customers_outrank_the_overall_share():
    # 4 of 1000 is a rounding error until you notice all four are billed monthly.
    state, _ = verdict(1000, 4, 4, 0)
    assert state == "billing"


def test_a_quarter_incomplete_is_a_collection_problem():
    assert verdict(1000, 249, 0, 0)[0] == "residue"
    assert verdict(1000, 250, 0, 0)[0] == "widespread"


def test_no_customers_is_not_silently_clear():
    assert verdict(0, 0, 0, 0)[0] == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { addressState, verdict } from './stripe-customer-address.mjs';

test('absent address is missing', () => {
  assert.equal(addressState({ id: 'cus_1' }), 'missing');
  assert.equal(addressState({ address: null }), 'missing');
});

test('address object with every field null is missing not partial', () => {
  const empty = {
    line1: null, line2: null, city: null,
    state: null, postal_code: null, country: null,
  };
  assert.equal(addressState({ address: empty }), 'missing');
});

test('street and city without a country still fails tax', () => {
  const addr = { line1: '12 Rue de Rivoli', city: 'Paris', postal_code: '75001' };
  assert.equal(addressState({ address: addr }), 'no_country');
});

test('country without a postal code fails avs', () => {
  assert.equal(addressState({ address: { country: 'US', city: 'Denver' } }),
    'no_postal_code');
});

test('a complete address is complete', () => {
  const addr = { line1: '1 Main St', city: 'Denver', postal_code: '80202', country: 'US' };
  assert.equal(addressState({ address: addr }), 'complete');
});

test('a failed finalization outranks any percentage', () => {
  const [state, detail] = verdict(1000, 1, 0, 3);
  assert.equal(state, 'failing');
  assert.match(detail, /3/);
});

test('subscribed customers outrank the overall share', () => {
  assert.equal(verdict(1000, 4, 4, 0)[0], 'billing');
});

test('a quarter incomplete is a collection problem', () => {
  assert.equal(verdict(1000, 249, 0, 0)[0], 'residue');
  assert.equal(verdict(1000, 250, 0, 0)[0], 'widespread');
});

test('no customers is not silently clear', () => {
  assert.equal(verdict(0, 0, 0, 0)[0], 'unknown');
});