Checkout Sessions carry no ID that maps back to your order

"""Report Stripe Checkout Sessions that carry no identifier of your own.

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

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

DEFAULT_KEYS = ("order_id",)


def verdict(session, expected_keys=DEFAULT_KEYS):
    """Classify one Checkout Session. Pure, so the rules can be tested offline.

    `expected_keys` are the metadata keys your own system reads. Metadata that
    exists but holds none of them is not reconcilable, however full it looks.
    Returns (state, detail).
    """
    ref = str(session.get("client_reference_id") or "").strip()
    meta = session.get("metadata") or {}
    present = [k for k in expected_keys if str(meta.get(k) or "").strip()]

    if ref:
        return ("linked", "client_reference_id=%s" % ref)
    if expected_keys and len(present) == len(expected_keys):
        return ("linked", "metadata carries %s" % ", ".join(present))
    if present:
        missing = [k for k in expected_keys if k not in present]
        return ("partial",
                "metadata has %s but is missing %s"
                % (", ".join(present), ", ".join(missing)))
    if session.get("payment_status") == "paid":
        return ("orphaned",
                "paid, with no client_reference_id and none of %s in metadata: "
                "money that points at nothing" % ", ".join(expected_keys))
    return ("unlinked",
            "no identifier of yours, but payment_status is %r so nothing has "
            "been taken yet" % (session.get("payment_status"),))


def get(session, path, params=None):
    r = session.get(API + path, params=params or {}, 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 sessions(http, since, limit):
    """Yield Checkout Sessions created since `since`, newest first."""
    seen = 0
    params = {"limit": 100, "created[gte]": int(since)}
    while True:
        page = get(http, "/checkout/sessions", params)
        data = page.get("data", [])
        for s in data:
            yield s
            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("--days", type=int, default=30,
                    help="how far back to read sessions")
    ap.add_argument("--keys", default=",".join(DEFAULT_KEYS),
                    help="comma-separated metadata keys your system reads")
    ap.add_argument("--max-sessions", type=int, default=5000,
                    help="stop paginating after this many sessions")
    ap.add_argument("--show", type=int, default=10,
                    help="how many orphaned session ids to print")
    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

    expected = tuple(k.strip() for k in args.keys.split(",") if k.strip())
    http = requests.Session()
    http.headers.update({"Authorization": "Bearer " + key})

    counts = {"linked": 0, "partial": 0, "unlinked": 0, "orphaned": 0}
    worst = []
    total = 0
    for s in sessions(http, time.time() - args.days * 86400, args.max_sessions):
        total += 1
        state, detail = verdict(s, expected)
        counts[state] = counts.get(state, 0) + 1
        if state == "orphaned" and len(worst) < args.show:
            worst.append((s.get("id", "?"), detail))

    log.info("%d session(s): %d linked, %d partial, %d unlinked, %d orphaned",
             total, counts["linked"], counts["partial"], counts["unlinked"],
             counts["orphaned"])
    for sid, detail in worst:
        log.warning("orphaned  %s  %s", sid, detail)

    if counts["orphaned"] or counts["partial"]:
        log.warning("  repair: POST %s/checkout/sessions "
                    "-d client_reference_id=<your_order_id> "
                    "-d 'metadata[order_id]=<your_order_id>'", API)
        log.warning("  for Payment Links, set metadata on the link itself: it is "
                    "copied onto every Session the link creates")
        return 1
    return 0


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

/**
 * Report Stripe Checkout Sessions that carry no identifier of your own.
 *
 * Read only. One paginated GET and no writes: give this a RESTRICTED key with
 * read access to Checkout Sessions. The repair is printed, never performed.
 */
const API = 'https://api.stripe.com/v1';

export const DEFAULT_KEYS = ['order_id'];

/**
 * Classify one Checkout Session. Pure, so the rules can be tested offline.
 * `expectedKeys` are the metadata keys your own system reads.
 */
export function verdict(session, expectedKeys = DEFAULT_KEYS) {
  const ref = String(session.client_reference_id ?? '').trim();
  const meta = session.metadata ?? {};
  const present = expectedKeys.filter((k) => String(meta[k] ?? '').trim());

  if (ref) return ['linked', `client_reference_id=${ref}`];
  if (expectedKeys.length && present.length === expectedKeys.length) {
    return ['linked', `metadata carries ${present.join(', ')}`];
  }
  if (present.length) {
    const missing = expectedKeys.filter((k) => !present.includes(k));
    return ['partial',
      `metadata has ${present.join(', ')} but is missing ${missing.join(', ')}`];
  }
  if (session.payment_status === 'paid') {
    return ['orphaned',
      `paid, with no client_reference_id and none of ${expectedKeys.join(', ')} ` +
      'in metadata: money that points at nothing'];
  }
  return ['unlinked',
    'no identifier of yours, but payment_status is ' +
    `${JSON.stringify(session.payment_status)} so nothing has been taken yet`];
}

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* sessions(key, since, limit = 5000) {
  let seen = 0;
  const params = { limit: 100, 'created[gte]': Math.floor(since) };
  for (;;) {
    const page = await get(key, '/checkout/sessions', params);
    const data = page.data ?? [];
    for (const s of data) { yield s; seen += 1; }
    if (data.length === 0 || !page.has_more || seen >= limit) break;
    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.argv[2] ?? 30);
  const expected = (process.argv[3] ?? DEFAULT_KEYS.join(','))
    .split(',').map((k) => k.trim()).filter(Boolean);

  const counts = { linked: 0, partial: 0, unlinked: 0, orphaned: 0 };
  const worst = [];
  let total = 0;

  for await (const s of sessions(key, Date.now() / 1000 - days * 86400)) {
    total += 1;
    const [state, detail] = verdict(s, expected);
    counts[state] = (counts[state] ?? 0) + 1;
    if (state === 'orphaned' && worst.length < 10) worst.push([s.id ?? '?', detail]);
  }

  console.log(`${total} session(s): ${counts.linked} linked, ${counts.partial} ` +
              `partial, ${counts.unlinked} unlinked, ${counts.orphaned} orphaned`);
  for (const [id, detail] of worst) console.warn(`orphaned  ${id}  ${detail}`);

  if (counts.orphaned || counts.partial) {
    console.warn(`  repair: POST ${API}/checkout/sessions ` +
                 `-d client_reference_id=<your_order_id> ` +
                 `-d 'metadata[order_id]=<your_order_id>'`);
    console.warn('  for Payment Links, set metadata on the link itself: it is ' +
                 'copied onto every Session the link creates');
    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_checkout_reconciliation import verdict


def test_client_reference_id_is_enough_on_its_own():
    state, detail = verdict({"client_reference_id": "ord_918", "payment_status": "paid"})
    assert state == "linked"
    assert "ord_918" in detail


def test_metadata_full_of_someone_elses_keys_is_not_linked():
    # A truthiness check on metadata would call this linked and report nothing.
    state, _ = verdict({"metadata": {"utm_source": "newsletter"},
                        "payment_status": "paid"})
    assert state == "orphaned"


def test_paid_and_unidentified_is_worse_than_abandoned():
    assert verdict({"payment_status": "paid"})[0] == "orphaned"
    assert verdict({"payment_status": "unpaid"})[0] == "unlinked"


def test_some_expected_keys_but_not_all_is_partial():
    state, detail = verdict({"metadata": {"order_id": "42"}, "payment_status": "paid"},
                            ("order_id", "user_id"))
    assert state == "partial"
    assert "user_id" in detail


def test_empty_and_whitespace_references_do_not_count_as_set():
    assert verdict({"client_reference_id": "", "payment_status": "paid"})[0] == "orphaned"
    assert verdict({"client_reference_id": "   ", "payment_status": "paid"})[0] == "orphaned"
    assert verdict({"metadata": {"order_id": " "}, "payment_status": "paid"})[0] == "orphaned"

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

test('client_reference_id is enough on its own', () => {
  const [state, detail] = verdict(
    { client_reference_id: 'ord_918', payment_status: 'paid' });
  assert.equal(state, 'linked');
  assert.match(detail, /ord_918/);
});

test('metadata full of someone elses keys is not linked', () => {
  const [state] = verdict(
    { metadata: { utm_source: 'newsletter' }, payment_status: 'paid' });
  assert.equal(state, 'orphaned');
});

test('paid and unidentified is worse than abandoned', () => {
  assert.equal(verdict({ payment_status: 'paid' })[0], 'orphaned');
  assert.equal(verdict({ payment_status: 'unpaid' })[0], 'unlinked');
});

test('some expected keys but not all is partial', () => {
  const [state, detail] = verdict(
    { metadata: { order_id: '42' }, payment_status: 'paid' },
    ['order_id', 'user_id']);
  assert.equal(state, 'partial');
  assert.match(detail, /user_id/);
});

test('empty and whitespace references do not count as set', () => {
  assert.equal(
    verdict({ client_reference_id: '', payment_status: 'paid' })[0], 'orphaned');
  assert.equal(
    verdict({ client_reference_id: '   ', payment_status: 'paid' })[0], 'orphaned');
  assert.equal(
    verdict({ metadata: { order_id: ' ' }, payment_status: 'paid' })[0], 'orphaned');
});