the platform collects zero application fees on its charges

"""Report destination charges that carry no application fee.

Read only. Paginated GETs and no writes: give this a RESTRICTED key with read
access to Charges, Application fees and Balance transactions. 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 time

import requests

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

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

DAY = 86400


def classify(fee_count, dest_total, dest_with_fee, dest_implicit):
    """Sort a platform's fee collection over one window. Pure, so the states can
    be tested without a network.

    `fee_count` is how many ApplicationFee objects exist in the window.
    `dest_total` is how many charges had transfer_data.destination set,
    `dest_with_fee` how many of those carried application_fee_amount, and
    `dest_implicit` how many instead under-transferred with transfer_data.amount,
    which keeps money on the platform without ever creating a fee object.

    Returns (state, detail).
    """
    counts = (fee_count, dest_total, dest_with_fee, dest_implicit)
    if any(not isinstance(c, int) or c < 0 for c in counts):
        return ("unknown", "counts must be non-negative integers: %r" % (counts,))
    if dest_with_fee + dest_implicit > dest_total:
        return ("unknown",
                "%d charges with a fee and %d implicit against only %d destination "
                "charges: the counts do not agree"
                % (dest_with_fee, dest_implicit, dest_total))

    if dest_total == 0:
        return ("idle",
                "no destination charges in the window, so there is nothing here "
                "that could carry an application fee")

    if fee_count == 0 and dest_implicit and not dest_with_fee:
        return ("invisible",
                "%d of %d destination charge(s) keep money on the platform via "
                "transfer_data[amount] and no ApplicationFee object exists: the "
                "revenue is real but every fee report will read zero"
                % (dest_implicit, dest_total))

    if fee_count == 0:
        return ("zero",
                "%d destination charge(s), none with application_fee_amount: the "
                "full amount went to the connected account every time"
                % dest_total)

    missing = dest_total - dest_with_fee - dest_implicit
    if missing > 0:
        return ("partial",
                "%d of %d destination charge(s) carry no fee at all: one code path "
                "that creates charges is not passing application_fee_amount"
                % (missing, dest_total))

    if dest_implicit:
        return ("mixed",
                "%d charge(s) take the fee explicitly and %d take it implicitly "
                "through transfer_data[amount]: the implicit ones never appear in "
                "/v1/application_fees" % (dest_with_fee, dest_implicit))

    return ("collecting",
            "%d destination charge(s), %d with application_fee_amount"
            % (dest_total, dest_with_fee))


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 count_pages(session, path, since, cap, on_item=None):
    """Paginate a created[gte] list, optionally inspecting each item."""
    seen = 0
    params = {"limit": 100, "created[gte]": since}
    while True:
        page = get(session, path, **params)
        data = page.get("data", [])
        for item in data:
            seen += 1
            if on_item:
                on_item(item)
        if not data or not page.get("has_more") or seen >= cap:
            return seen
        params["starting_after"] = data[-1]["id"]


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

    since = int(time.time()) - args.days * DAY

    fee_count = count_pages(s, "/application_fees", since, 5000)

    tally = {"dest": 0, "fee": 0, "implicit": 0}
    destinations = set()

    def inspect(charge):
        transfer = charge.get("transfer_data") or {}
        dest = transfer.get("destination")
        if not dest:
            return
        tally["dest"] += 1
        destinations.add(dest if isinstance(dest, str) else dest.get("id", "?"))
        if charge.get("application_fee_amount") is not None:
            tally["fee"] += 1
        elif (transfer.get("amount") is not None
              and transfer["amount"] < (charge.get("amount") or 0)):
            tally["implicit"] += 1

    count_pages(s, "/charges", since, args.max_charges, inspect)

    state, detail = classify(fee_count, tally["dest"], tally["fee"],
                             tally["implicit"])
    (log.info if state in ("collecting", "idle") else log.warning)(
        "%-11s %s", state, detail)
    log.info("%d application fee object(s) in the window", fee_count)

    # The fee list and the application_fee balance transactions should agree.
    # Fees that exist as objects but never as balance transactions were
    # collected and then refunded, which is a different problem from this one.
    bt_page = get(s, "/balance_transactions", limit=100, type="application_fee",
                  **{"created[gte]": since})
    if fee_count and not bt_page.get("data"):
        log.warning("fee objects exist but no application_fee balance transaction "
                    "in the window: the fees were taken and refunded back out")

    if state in ("zero", "invisible", "partial", "mixed"):
        log.warning("  repair: pass application_fee_amount in minor units on every "
                    "call that creates a charge with transfer_data[destination], "
                    "including subscriptions and invoices.")
        log.warning("  check first, on each destination: GET %s/accounts/{id} and "
                    "confirm capabilities.transfers is active, because a fee on an "
                    "account without it fails the whole charge.", API)
        log.warning("  %d destination account(s) seen in this window", len(destinations))
        return 1
    return 1 if state == "unknown" else 0


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

/**
 * Report destination charges that carry no application fee.
 *
 * Read only. Paginated GETs and no writes: give this a RESTRICTED key with read
 * access to Charges, Application fees and Balance transactions. The repair is
 * printed, never performed.
 */
const API = 'https://api.stripe.com/v1';
const DAY = 86400;

/**
 * Sort a platform's fee collection over one window. Pure, so the states can be
 * tested without a network. Returns [state, detail].
 */
export function classify(feeCount, destTotal, destWithFee, destImplicit) {
  const counts = [feeCount, destTotal, destWithFee, destImplicit];
  if (counts.some((c) => !Number.isInteger(c) || c < 0)) {
    return ['unknown',
      `counts must be non-negative integers: ${JSON.stringify(counts)}`];
  }
  if (destWithFee + destImplicit > destTotal) {
    return ['unknown',
      `${destWithFee} charges with a fee and ${destImplicit} implicit against ` +
      `only ${destTotal} destination charges: the counts do not agree`];
  }

  if (destTotal === 0) {
    return ['idle',
      'no destination charges in the window, so there is nothing here that ' +
      'could carry an application fee'];
  }

  if (feeCount === 0 && destImplicit && !destWithFee) {
    return ['invisible',
      `${destImplicit} of ${destTotal} destination charge(s) keep money on the ` +
      'platform via transfer_data[amount] and no ApplicationFee object exists: ' +
      'the revenue is real but every fee report will read zero'];
  }

  if (feeCount === 0) {
    return ['zero',
      `${destTotal} destination charge(s), none with application_fee_amount: ` +
      'the full amount went to the connected account every time'];
  }

  const missing = destTotal - destWithFee - destImplicit;
  if (missing > 0) {
    return ['partial',
      `${missing} of ${destTotal} destination charge(s) carry no fee at all: ` +
      'one code path that creates charges is not passing application_fee_amount'];
  }

  if (destImplicit) {
    return ['mixed',
      `${destWithFee} charge(s) take the fee explicitly and ${destImplicit} take ` +
      'it implicitly through transfer_data[amount]: the implicit ones never ' +
      'appear in /v1/application_fees'];
  }

  return ['collecting',
    `${destTotal} destination charge(s), ${destWithFee} with application_fee_amount`];
}

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 countPages(key, path, since, cap = 5000, onItem = null) {
  let seen = 0;
  const params = { limit: 100, 'created[gte]': since };
  for (;;) {
    const page = await get(key, path, params);
    const data = page.data ?? [];
    for (const item of data) {
      seen += 1;
      if (onItem) onItem(item);
    }
    if (data.length === 0 || !page.has_more || seen >= cap) return seen;
    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 days = Number(process.env.WINDOW_DAYS ?? 30);
  const since = Math.floor(Date.now() / 1000) - days * DAY;

  const feeCount = await countPages(key, '/application_fees', since);

  const tally = { dest: 0, fee: 0, implicit: 0 };
  const destinations = new Set();

  await countPages(key, '/charges', since, 5000, (charge) => {
    const transfer = charge.transfer_data ?? {};
    const dest = transfer.destination;
    if (!dest) return;
    tally.dest += 1;
    destinations.add(typeof dest === 'string' ? dest : (dest.id ?? '?'));
    if (charge.application_fee_amount !== null
        && charge.application_fee_amount !== undefined) {
      tally.fee += 1;
    } else if (transfer.amount !== null && transfer.amount !== undefined
               && transfer.amount < (charge.amount ?? 0)) {
      tally.implicit += 1;
    }
  });

  const [state, detail] = classify(feeCount, tally.dest, tally.fee, tally.implicit);
  const line = `${state.padEnd(11)} ${detail}`;
  if (state === 'collecting' || state === 'idle') console.log(line);
  else console.warn(line);
  console.log(`${feeCount} application fee object(s) in the window`);

  // Fees that exist as objects but never as balance transactions were collected
  // and then refunded, which is a different problem from this one.
  const btPage = await get(key, '/balance_transactions',
    { limit: 100, type: 'application_fee', 'created[gte]': since });
  if (feeCount && (btPage.data ?? []).length === 0) {
    console.warn('fee objects exist but no application_fee balance transaction in ' +
                 'the window: the fees were taken and refunded back out');
  }

  if (['zero', 'invisible', 'partial', 'mixed'].includes(state)) {
    console.warn('  repair: pass application_fee_amount in minor units on every ' +
                 'call that creates a charge with transfer_data[destination], ' +
                 'including subscriptions and invoices.');
    console.warn(`  check first, on each destination: GET ${API}/accounts/{id} and ` +
                 'confirm capabilities.transfers is active, because a fee on an ' +
                 'account without it fails the whole charge.');
    console.warn(`  ${destinations.size} destination account(s) seen in this window`);
    process.exitCode = 1;
  } else if (state === 'unknown') {
    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_application_fees import classify


def test_no_destination_charges_is_not_a_finding():
    state, _ = classify(0, 0, 0, 0)
    assert state == "idle"


def test_destination_charges_with_no_fees_anywhere():
    state, detail = classify(0, 480, 0, 0)
    assert state == "zero"
    assert "480" in detail


def test_under_transferring_is_revenue_that_no_report_shows():
    # The platform is keeping the difference, so the money is right and every
    # fee report is wrong. Telling someone to "add the fee" here is a mistake.
    state, detail = classify(0, 480, 0, 480)
    assert state == "invisible"
    assert "transfer_data[amount]" in detail


def test_one_code_path_missing_the_parameter():
    state, detail = classify(360, 480, 360, 0)
    assert state == "partial"
    assert "120 of 480" in detail


def test_counts_that_do_not_add_up_are_not_reported_as_healthy():
    state, _ = classify(10, 5, 4, 3)
    assert state == "unknown"

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { classify } from './stripe-application-fees.mjs';

test('no destination charges is not a finding', () => {
  assert.equal(classify(0, 0, 0, 0)[0], 'idle');
});

test('destination charges with no fees anywhere', () => {
  const [state, detail] = classify(0, 480, 0, 0);
  assert.equal(state, 'zero');
  assert.match(detail, /480/);
});

test('under transferring is revenue that no report shows', () => {
  const [state, detail] = classify(0, 480, 0, 480);
  assert.equal(state, 'invisible');
  assert.match(detail, /transfer_data\[amount\]/);
});

test('one code path missing the parameter', () => {
  const [state, detail] = classify(360, 480, 360, 0);
  assert.equal(state, 'partial');
  assert.match(detail, /120 of 480/);
});

test('counts that do not add up are not reported as healthy', () => {
  assert.equal(classify(10, 5, 4, 3)[0], 'unknown');
});