guest checkouts finish with customer null and can't be linked

"""Report Stripe Checkout Sessions that completed without a Customer.

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_guests")

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


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

    `email_seen` is how many sessions in the window share this session's
    customer_details.email. A single Session cannot tell you whether its buyer
    has been here before, and that is the fact the whole report turns on.
    Returns (state, detail).
    """
    if session.get("customer"):
        return ("linked", "customer=%s" % (session["customer"],))

    mode = session.get("mode")
    if mode != "payment":
        return ("unknown",
                "mode %r completed with no Customer, which Stripe normally "
                "requires here" % (mode,))

    creation = session.get("customer_creation")
    if creation == "always":
        return ("unknown",
                "customer_creation=always but no Customer is attached; check the "
                "session really completed")

    email = str((session.get("customer_details") or {}).get("email") or "").strip()
    if not email:
        return ("anonymous",
                "no Customer and no customer_details.email: nothing at all to "
                "match this payment to later")
    if email_seen > 1:
        return ("repeat-guest",
                "%s completed %d sessions in this window and was a new stranger "
                "every time" % (email, email_seen))
    return ("guest",
            "customer_creation=%r, so Stripe made no Customer; %s exists only as "
            "a string on the Session" % (creation, email))


def email_of(session):
    """The address a guest session could later be matched on, normalised."""
    return str((session.get("customer_details") or {}).get("email") or "").strip().lower()


def email_counts(sessions):
    """Count how many sessions share each address. Pure, and used before any
    session is classified, because the count is an argument to the classifier."""
    counts = {}
    for s in sessions:
        addr = email_of(s)
        if addr:
            counts[addr] = counts.get(addr, 0) + 1
    return counts


def get(http, path, params=None):
    r = http.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 completed_sessions(http, since, limit):
    """Yield completed Checkout Sessions created since `since`, newest first."""
    seen = 0
    params = {"limit": 100, "status": "complete", "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=90,
                    help="how far back to read completed sessions")
    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 repeat guests 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

    http = requests.Session()
    http.headers.update({"Authorization": "Bearer " + key})

    since = time.time() - args.days * 86400
    sessions = list(completed_sessions(http, since, args.max_sessions))
    if not sessions:
        log.info("no completed Checkout Sessions in the last %d days", args.days)
        return 0

    counts = email_counts(sessions)
    tally = {"linked": 0, "guest": 0, "repeat-guest": 0, "anonymous": 0, "unknown": 0}
    repeats = []
    for s in sessions:
        state, detail = verdict(s, counts.get(email_of(s), 1))
        tally[state] = tally.get(state, 0) + 1
        if state == "repeat-guest" and len(repeats) < args.show:
            repeats.append((s.get("id", "?"), detail))

    log.info("%d session(s): %d linked, %d guest, %d repeat-guest, %d anonymous",
             len(sessions), tally["linked"], tally["guest"],
             tally["repeat-guest"], tally["anonymous"])
    for sid, detail in repeats:
        log.warning("repeat-guest  %s  %s", sid, detail)
    if tally["unknown"]:
        log.warning("%d session(s) in an unexpected state; read them by hand",
                    tally["unknown"])

    unlinked = tally["guest"] + tally["repeat-guest"] + tally["anonymous"]
    if unlinked:
        log.warning("  repair: POST %s/checkout/sessions -d customer_creation=always",
                    API)
        log.warning("          or pass the id you already hold: -d customer=cus_XXX")
        log.warning("  for a Payment Link, set it on the link: POST "
                    "%s/payment_links/plink_XXX -d customer_creation=always", API)
        return 1
    return 0


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

/**
 * Report Stripe Checkout Sessions that completed without a Customer.
 *
 * 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';

/**
 * Classify one completed Checkout Session. Pure, so the rules can be tested
 * offline. `emailSeen` is how many sessions in the window share this session's
 * customer_details.email.
 */
export function verdict(session, emailSeen = 1) {
  if (session.customer) return ['linked', `customer=${session.customer}`];

  const mode = session.mode;
  if (mode !== 'payment') {
    return ['unknown',
      `mode ${JSON.stringify(mode)} completed with no Customer, which Stripe ` +
      'normally requires here'];
  }

  const creation = session.customer_creation;
  if (creation === 'always') {
    return ['unknown',
      'customer_creation=always but no Customer is attached; check the session ' +
      'really completed'];
  }

  const email = String(session.customer_details?.email ?? '').trim();
  if (!email) {
    return ['anonymous',
      'no Customer and no customer_details.email: nothing at all to match this ' +
      'payment to later'];
  }
  if (emailSeen > 1) {
    return ['repeat-guest',
      `${email} completed ${emailSeen} sessions in this window and was a new ` +
      'stranger every time'];
  }
  return ['guest',
    `customer_creation=${JSON.stringify(creation)}, so Stripe made no Customer; ` +
    `${email} exists only as a string on the Session`];
}

/** The address a guest session could later be matched on, normalised. */
export function emailOf(session) {
  return String(session.customer_details?.email ?? '').trim().toLowerCase();
}

/** Count how many sessions share each address. Pure. */
export function emailCounts(sessions) {
  const counts = new Map();
  for (const s of sessions) {
    const addr = emailOf(s);
    if (addr) counts.set(addr, (counts.get(addr) ?? 0) + 1);
  }
  return counts;
}

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* completedSessions(key, since, limit = 5000) {
  let seen = 0;
  const params = { limit: 100, status: 'complete', '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] ?? 90);
  const sessions = [];
  for await (const s of completedSessions(key, Date.now() / 1000 - days * 86400)) {
    sessions.push(s);
  }
  if (sessions.length === 0) {
    console.log(`no completed Checkout Sessions in the last ${days} days`);
    return;
  }

  const counts = emailCounts(sessions);
  const tally = { linked: 0, guest: 0, 'repeat-guest': 0, anonymous: 0, unknown: 0 };
  const repeats = [];
  for (const s of sessions) {
    const [state, detail] = verdict(s, counts.get(emailOf(s)) ?? 1);
    tally[state] = (tally[state] ?? 0) + 1;
    if (state === 'repeat-guest' && repeats.length < 10) {
      repeats.push([s.id ?? '?', detail]);
    }
  }

  console.log(`${sessions.length} session(s): ${tally.linked} linked, ` +
              `${tally.guest} guest, ${tally['repeat-guest']} repeat-guest, ` +
              `${tally.anonymous} anonymous`);
  for (const [id, detail] of repeats) console.warn(`repeat-guest  ${id}  ${detail}`);
  if (tally.unknown) {
    console.warn(`${tally.unknown} session(s) in an unexpected state; read them by hand`);
  }

  if (tally.guest + tally['repeat-guest'] + tally.anonymous) {
    console.warn(`  repair: POST ${API}/checkout/sessions -d customer_creation=always`);
    console.warn('          or pass the id you already hold: -d customer=cus_XXX');
    console.warn('  for a Payment Link, set it on the link: POST ' +
                 `${API}/payment_links/plink_XXX -d customer_creation=always`);
    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_guests import email_counts, verdict


def make(email=None, **kw):
    s = {"mode": "payment", "customer_creation": "if_required"}
    if email is not None:
        s["customer_details"] = {"email": email}
    s.update(kw)
    return s


def test_a_session_with_a_customer_is_linked():
    state, detail = verdict(make("a@example.com", customer="cus_9"))
    assert state == "linked"
    assert "cus_9" in detail


def test_the_default_flag_produces_a_guest():
    state, detail = verdict(make("a@example.com"))
    assert state == "guest"
    assert "if_required" in detail


def test_the_same_address_twice_is_a_repeat_guest():
    # The point of the note: no single session shows this, only the window does.
    sessions = [make("buyer@example.com"), make("BUYER@example.com")]
    counts = email_counts(sessions)
    state, detail = verdict(sessions[0], counts["buyer@example.com"])
    assert state == "repeat-guest"
    assert "2" in detail


def test_a_guest_with_no_email_is_not_merely_a_guest():
    assert verdict(make())[0] == "anonymous"
    assert verdict(make("   "))[0] == "anonymous"


def test_subscription_mode_and_always_are_not_silently_guests():
    assert verdict(make("a@example.com", mode="subscription"))[0] == "unknown"
    assert verdict(make("a@example.com", customer_creation="always"))[0] == "unknown"

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

const make = (email, extra = {}) => ({
  mode: 'payment',
  customer_creation: 'if_required',
  ...(email === undefined ? {} : { customer_details: { email } }),
  ...extra,
});

test('a session with a customer is linked', () => {
  const [state, detail] = verdict(make('a@example.com', { customer: 'cus_9' }));
  assert.equal(state, 'linked');
  assert.match(detail, /cus_9/);
});

test('the default flag produces a guest', () => {
  const [state, detail] = verdict(make('a@example.com'));
  assert.equal(state, 'guest');
  assert.match(detail, /if_required/);
});

test('the same address twice is a repeat guest', () => {
  const sessions = [make('buyer@example.com'), make('BUYER@example.com')];
  const counts = emailCounts(sessions);
  const [state, detail] = verdict(sessions[0], counts.get('buyer@example.com'));
  assert.equal(state, 'repeat-guest');
  assert.match(detail, /2/);
});

test('a guest with no email is not merely a guest', () => {
  assert.equal(verdict(make())[0], 'anonymous');
  assert.equal(verdict(make('   '))[0], 'anonymous');
});

test('subscription mode and always are not silently guests', () => {
  assert.equal(verdict(make('a@example.com', { mode: 'subscription' }))[0], 'unknown');
  assert.equal(
    verdict(make('a@example.com', { customer_creation: 'always' }))[0], 'unknown');
});