allowances: credit the shortfall when OC's billing day truncates a paid cycle
Open Collective aligns recurring charges onto the collective's common billing day, so a mid-month joiner is charged again before a full month is up: they pay for a full month and receive less than one. Credit the missing ALLOWANCE (the flat MEMBER_BUDGET pro-rated for the days lost, unrounded) as non-expiring credits. - derived from the collective's real per-order charge history, on every sweep; any consecutive pair on the same order < a full month apart is truncated - idempotent on the OC charge reference (dedupe on the charge, not the member) - skips and logs any cycle whose dates cannot be determined - ledger reason names the cycle; the notice is staged and defaults OFF - [redacted member reference]'s remediated charge is excluded by ref Tests: tests/test_allowance_shortfall.py (pure derivation).
This commit is contained in:
1 parent
c468b61d3e
commit
db64dac235
3 files changed
+529
No files matched your search
@@ -149,6 +149,32 @@ changes nothing; `mode=send` performs renewals and sends the reminder and
|
||||
requires `ALLOWANCE_POLICY=on`. Deactivation additionally requires
|
||||
`ALLOWANCE_DEACTIVATE=on`.
|
||||
|
||||
### Allowance shortfall (a paid cycle OC truncated)
|
||||
|
||||
Open Collective aligns every recurring charge onto the collective's common
|
||||
billing day, so a member who joins mid-month is charged again well before a full
|
||||
month has elapsed — they pay for a full month and receive less than one. The
|
||||
co-op's remedy: credit the missing **allowance** (the flat `MEMBER_BUDGET`
|
||||
pro-rated for the days lost, `FULL_PAID_MONTH_DAYS = 30`, unrounded) as
|
||||
non-expiring credits — the same balance that extends the allowance and is spent
|
||||
only after it. It is never a share of what they paid.
|
||||
|
||||
The set is derived FROM DATA, on every sweep (`POST /admin/sweep` calls
|
||||
`reconcile_allowance_shortfalls`, as does `POST /admin/shortfall-credits`):
|
||||
each MONTHLY order's real charge history is read from Open Collective, and any
|
||||
consecutive pair on the SAME order less than a full month apart is a truncated
|
||||
cycle. Two subscriptions a member happens to hold are judged separately; a gap
|
||||
whose dates cannot be determined is skipped and logged. Each credit is keyed to
|
||||
the specific OC charge that caused it (`credit_ledger.reference` = the charge
|
||||
`publicId`), so a re-run credits nothing twice — dedupe is on the charge, not
|
||||
the member — and the ledger `reason` names the cycle so a member's question is
|
||||
answerable from it.
|
||||
|
||||
Member notices ride the same pass, but default OFF
|
||||
(`ALLOWANCE_SHORTFALL_EMAILS=off`); set it to `on` to send the staged notice,
|
||||
at most once per charge (`shortfall_notices`). `mode=report` on
|
||||
`/admin/shortfall-credits` previews the affected set and changes nothing.
|
||||
|
||||
### Energy & carbon metrics
|
||||
|
||||
The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens,
|
||||
|
||||
+387
@@ -4791,6 +4791,383 @@ async def reconcile_allowances(send: bool = False) -> dict:
|
||||
}
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Allowance shortfall — OC's billing-day alignment truncates a paid cycle. #
|
||||
# --------------------------------------------------------------------------- #
|
||||
# Open Collective aligns every recurring charge onto the collective's COMMON
|
||||
# billing day, so a member who joins mid-month is charged again well before a
|
||||
# full month has elapsed: they pay for a full month and receive less than one.
|
||||
# Operator decision (2026-11-04): make the member whole by crediting the missing
|
||||
# ALLOWANCE — the flat MEMBER_BUDGET pro-rated for the days lost — as
|
||||
# non-expiring credits (the same balance that extends the allowance and is spent
|
||||
# only after it). It is NOT a share of what they paid, and it is NOT rounded.
|
||||
#
|
||||
# Scope: EVERY monthly paid cycle shorter than a full month, for any member and
|
||||
# any cycle (not only the first — OC can re-align an existing charge date too).
|
||||
# Derived FROM DATA (each recurring order's real charge history); members are
|
||||
# never asked to claim it. Idempotent: each credit is keyed to the specific OC
|
||||
# charge that caused it, so a re-run credits nothing twice. A charge whose date
|
||||
# cannot be determined is SKIPPED and logged — paying a credit that is not owed
|
||||
# is worse than paying one late.
|
||||
#
|
||||
# Member notices go out automatically (the sweep does both in one pass), but they
|
||||
# default OFF (ALLOWANCE_SHORTFALL_EMAILS=off) so the wording can be reviewed
|
||||
# before any member is written to about billing. Setting it to `on` sends the
|
||||
# staged notice on the next sweep; nothing is re-sent per charge.
|
||||
FULL_PAID_MONTH_DAYS = 30 # the allowance is a flat monthly amount => "a month" = 30 days
|
||||
ALLOWANCE_SHORTFALL_EMAILS = (os.environ.get("ALLOWANCE_SHORTFALL_EMAILS", "off") or "off").strip().lower()
|
||||
|
||||
|
||||
def shortfall_reason(prev: str, cur: str) -> str:
|
||||
"""Human-readable ledger reason — a member's question is answerable from it."""
|
||||
return f"allowance shortfall, truncated paid cycle {prev}→{cur} (OC billing alignment)"
|
||||
|
||||
|
||||
# Members already made whole OUTSIDE this mechanism, keyed by (email, OC charge
|
||||
# reference). [redacted member reference] received a manual allowance reset
|
||||
# on 2026-11-04 for the cycle OC truncated ([redacted timeline]); that
|
||||
# specific charge is excluded so a re-run never credits it again. Later charges
|
||||
# form new cycles and are credited normally.
|
||||
SHORTFALL_REMEDIATED: set[tuple[str, str]] = {
|
||||
("[redacted member reference]", "[redacted member reference]"),
|
||||
}
|
||||
|
||||
|
||||
def _usd(x: float) -> str:
|
||||
"""Format a credit amount for a member without inventing cents (2 -> $2)."""
|
||||
return f"${x:g}"
|
||||
|
||||
|
||||
def _ensure_shortfall_tables(conn) -> None:
|
||||
"""Records which charge-triggered notices have actually been sent.
|
||||
|
||||
Kept apart from the credit ledger on purpose: the ledger answers "what did we
|
||||
credit, and why", this answers "what left the building". A notice is sent at
|
||||
most once per charge reference.
|
||||
"""
|
||||
conn.execute(
|
||||
"CREATE TABLE IF NOT EXISTS shortfall_notices ("
|
||||
" reference TEXT PRIMARY KEY, email TEXT NOT NULL, amount REAL NOT NULL,"
|
||||
" sent_at TEXT NOT NULL DEFAULT (datetime('now')))"
|
||||
)
|
||||
conn.commit()
|
||||
|
||||
|
||||
def credit_reference_exists(reference: str) -> bool:
|
||||
"""Has a credit already been recorded against this OC charge reference?"""
|
||||
conn = get_db()
|
||||
row = conn.execute(
|
||||
"SELECT 1 FROM credit_ledger WHERE reference = ? LIMIT 1", (reference,)
|
||||
).fetchone()
|
||||
conn.close()
|
||||
return bool(row)
|
||||
|
||||
|
||||
def shortfall_notice_sent(reference: str) -> bool:
|
||||
conn = get_db()
|
||||
row = conn.execute(
|
||||
"SELECT 1 FROM shortfall_notices WHERE reference = ? LIMIT 1", (reference,)
|
||||
).fetchone()
|
||||
conn.close()
|
||||
return bool(row)
|
||||
|
||||
|
||||
def mark_shortfall_notice_sent(reference: str, email: str, amount: float) -> None:
|
||||
conn = get_db()
|
||||
_ensure_shortfall_tables(conn)
|
||||
conn.execute(
|
||||
"INSERT OR REPLACE INTO shortfall_notices (reference, email, amount, sent_at)"
|
||||
" VALUES (?, ?, ?, datetime('now'))",
|
||||
(reference, email, amount),
|
||||
)
|
||||
conn.commit()
|
||||
conn.close()
|
||||
|
||||
|
||||
async def fetch_oc_monthly_order_charges() -> list[dict]:
|
||||
"""Every MONTHLY order's real contribution charges — one record per order.
|
||||
|
||||
A record is {"slug", "order_id", "charges": [(datetime, publicId), ...]} from
|
||||
ONE order. Truncation is judged per order: merging the charges of two
|
||||
DIFFERENT subscriptions a member happens to hold invents a short gap that is
|
||||
not a truncated cycle (one member started a second monthly order six days
|
||||
after the first; that is not OC re-aligning a charge). Raises on failure so
|
||||
the caller skips rather than mis-decides. Charges are the CONTRIBUTION
|
||||
amounts INTO the collective (a non-refund CREDIT), one per charge.
|
||||
"""
|
||||
if not OC_PERSONAL_TOKEN:
|
||||
raise RuntimeError("OC_PERSONAL_TOKEN not set; cannot fetch order charges")
|
||||
query = (
|
||||
'{ collective(slug: "%s") { orders(limit: 200) { totalCount nodes { '
|
||||
"id frequency fromAccount { slug } "
|
||||
"transactions { publicId createdAt type kind isRefund } } } } }"
|
||||
% OC_COLLECTIVE_SLUG
|
||||
)
|
||||
async with httpx.AsyncClient(timeout=30.0) as client:
|
||||
r = await client.post(
|
||||
OC_GRAPHQL_URL,
|
||||
headers={"Content-Type": "application/json",
|
||||
"Authorization": f"Bearer {OC_PERSONAL_TOKEN}",
|
||||
"Api-Version": "2022-01-01",
|
||||
"User-Agent": "Mozilla/5.0 (X11; Linux x86_64)"},
|
||||
json={"query": query},
|
||||
)
|
||||
if r.status_code != 200:
|
||||
raise RuntimeError(f"OC order-charge fetch failed: HTTP {r.status_code}")
|
||||
body = r.json()
|
||||
if body.get("errors"):
|
||||
raise RuntimeError(f"OC order-charge fetch errors: {str(body['errors'])[:200]}")
|
||||
nodes = (((body.get("data") or {}).get("collective") or {}).get("orders") or {}).get("nodes") or []
|
||||
out: list[dict] = []
|
||||
for o in nodes:
|
||||
if (o.get("frequency") or "").upper() != "MONTHLY":
|
||||
continue
|
||||
slug = ((o.get("fromAccount") or {}).get("slug") or "").strip()
|
||||
if not slug:
|
||||
continue
|
||||
charges = []
|
||||
for t in o.get("transactions") or []:
|
||||
if t.get("kind") != "CONTRIBUTION" or t.get("isRefund"):
|
||||
continue
|
||||
if (t.get("type") or "").upper() != "CREDIT":
|
||||
continue
|
||||
dt = _parse_oc_dt(t.get("createdAt"))
|
||||
if dt and t.get("publicId"):
|
||||
charges.append((dt, t["publicId"]))
|
||||
charges.sort()
|
||||
if charges:
|
||||
out.append({"slug": slug, "order_id": o.get("id"), "charges": charges})
|
||||
return out
|
||||
|
||||
|
||||
def derive_shortfalls(order_records: list[dict], budget: float | None = None,
|
||||
full_month_days: int = FULL_PAID_MONTH_DAYS) -> list[dict]:
|
||||
"""Pure: truncated paid cycles from per-order monthly charge ladders.
|
||||
|
||||
For each consecutive pair of charges on the SAME order, a gap shorter than a
|
||||
full month means the member paid for a full month and received fewer days of
|
||||
allowance. Credit = budget * days_lost / full_month_days (no rounding). One
|
||||
record per truncated cycle; `reference` is the early charge that truncated it
|
||||
(globally unique, so it is the idempotence key).
|
||||
"""
|
||||
budget = MEMBER_BUDGET if budget is None else budget
|
||||
out: list[dict] = []
|
||||
for rec in order_records:
|
||||
charges = rec.get("charges") or []
|
||||
for i in range(1, len(charges)):
|
||||
prev_dt, _ = charges[i - 1]
|
||||
cur_dt, cur_id = charges[i]
|
||||
gap = (cur_dt - prev_dt).days
|
||||
if gap >= full_month_days:
|
||||
continue
|
||||
lost = full_month_days - gap
|
||||
out.append({
|
||||
"slug": rec.get("slug"), "order_id": rec.get("order_id"),
|
||||
"prev": prev_dt.date().isoformat(), "cur": cur_dt.date().isoformat(),
|
||||
"gap_days": gap, "days_lost": lost,
|
||||
"amount": budget * lost / full_month_days, "reference": cur_id,
|
||||
})
|
||||
return out
|
||||
|
||||
|
||||
def shortfall_email(name: str, amount: float, prev: str, cur: str,
|
||||
gap_days: int, days_lost: int, pack_url: str) -> tuple[str, str, str]:
|
||||
"""Build the shortfall credit notice (subject, text, html).
|
||||
|
||||
Same shell as welcome_email()/budget_notice_email(): cream background, white
|
||||
card, forest-green button, inline pine-tree mark, table-based, no external
|
||||
assets. Plain and direct — says what happened, why, the amount, and how to get
|
||||
more. No filler, no apology theatre.
|
||||
"""
|
||||
subject = "A credit for a short allowance cycle"
|
||||
text = (
|
||||
f"Hi {name},\n\n"
|
||||
"Your Open Collective contribution is charged on the collective's billing "
|
||||
"day, not on the day you joined. That can make a charge arrive less than a "
|
||||
"month after the one before it, so a month you paid for turns out shorter "
|
||||
"than a month of allowance.\n\n"
|
||||
f"That happened on your account: charges on {prev} and {cur} were only "
|
||||
f"{gap_days} days apart, so you paid for a full month and received "
|
||||
f"{days_lost} days less than one.\n\n"
|
||||
f"To make that up, we've added {_usd(amount)} to your account as credits. "
|
||||
"Credits don't expire, and they're used after your monthly allowance.\n\n"
|
||||
"If you'd like to add more, you can buy credit packs here:\n\n"
|
||||
f"{pack_url}\n\n"
|
||||
"Questions? Reply to this email or write to info@inference.coop.\n\n"
|
||||
"— The Inference Cooperative\n"
|
||||
)
|
||||
html = f"""<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head>
|
||||
<body style="margin:0;padding:0;background:#faf8f5;font-family:-apple-system,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;">
|
||||
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#faf8f5;padding:40px 16px;">
|
||||
<tr>
|
||||
<td align="center">
|
||||
<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:520px;">
|
||||
<tr>
|
||||
<td align="center" style="padding-bottom:24px;">
|
||||
{PINE_LOGO_SVG}
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" style="background:#ffffff;border:1px solid #e8e2d8;border-radius:16px;padding:40px 32px;">
|
||||
<h1 style="margin:0 0 12px;font-size:24px;font-weight:700;color:#2d3327;">A credit for a short allowance cycle</h1>
|
||||
<p style="margin:0 0 8px;font-size:16px;color:#6b7a62;line-height:1.5;">Your Open Collective contribution is charged on the collective's billing day, not on the day you joined. That can make a charge arrive less than a month after the one before it, so a month you paid for turns out shorter than a month of allowance.</p>
|
||||
<p style="margin:0 0 20px;font-size:15px;color:#6b7a62;line-height:1.5;">That happened on your account: charges on {prev} and {cur} were only {gap_days} days apart, so you paid for a full month and received {days_lost} days less than one.</p>
|
||||
<p style="margin:0 0 24px;font-size:15px;color:#2d3327;line-height:1.5;"><strong>We've added {_usd(amount)} to your account as credits.</strong> Credits don't expire, and they're used after your monthly allowance.</p>
|
||||
<a href="{pack_url}" style="display:inline-block;background:#5b8c5a;color:#ffffff;text-decoration:none;padding:14px 36px;border-radius:999px;font-size:16px;font-weight:600;">Buy credit packs</a>
|
||||
<p style="margin:28px 0 0;font-size:13px;color:#94a08c;line-height:1.5;">If you'd like to add more, you can buy credit packs at the button above.</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center" style="padding-top:24px;font-size:13px;color:#94a08c;line-height:1.6;">
|
||||
Questions? Reply to this email or write to <a href="mailto:info@inference.coop" style="color:#6b7a62;">info@inference.coop</a>.<br>
|
||||
<span style="color:#2d3327;">The Inference Cooperative</span> · inference.coop
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</body>
|
||||
</html>"""
|
||||
return subject, text, html
|
||||
|
||||
|
||||
async def reconcile_allowance_shortfalls(send: bool = False) -> dict:
|
||||
"""Credit members whose PAID cycle Open Collective's billing-day alignment truncated.
|
||||
|
||||
`send=False` (report) computes the set and changes NOTHING. `send=True`
|
||||
(honoured only when ALLOWANCE_POLICY == "on") applies one credit per truncated
|
||||
charge — idempotent on the charge reference — and, when
|
||||
ALLOWANCE_SHORTFALL_EMAILS == "on", sends the member notice (once per charge).
|
||||
Emails default OFF so the wording is reviewed before any member is written to.
|
||||
"""
|
||||
try:
|
||||
records = await fetch_oc_monthly_order_charges()
|
||||
except Exception as e:
|
||||
logger.warning("Allowance shortfall: charge fetch failed; skipping (fail-safe): %s", e)
|
||||
return {"status": "skipped", "reason": "charge_fetch_failed", "detail": str(e)[:200]}
|
||||
try:
|
||||
index = await fetch_member_index()
|
||||
except Exception as e:
|
||||
logger.warning("Allowance shortfall: member index fetch failed; skipping (fail-safe): %s", e)
|
||||
return {"status": "skipped", "reason": "member_index_failed", "detail": str(e)[:200]}
|
||||
|
||||
cycles = derive_shortfalls(records)
|
||||
|
||||
# slug -> email from the LIVE OC member list; only provisioned, active members
|
||||
# are credited. Orders are matched by the slug resolved from the member's email
|
||||
# (the stored column can hold a stale guest-… slug from first provisioning).
|
||||
slug2email: dict[str, str] = {}
|
||||
for e, rec in index.items():
|
||||
s = rec.get("slug") or ""
|
||||
if s:
|
||||
slug2email.setdefault(s, e)
|
||||
|
||||
conn = get_db()
|
||||
_ensure_shortfall_tables(conn)
|
||||
active = {r[0].strip().lower() for r in conn.execute("SELECT email FROM members WHERE active = 1")}
|
||||
meta = {r[0].strip().lower(): {"slug": r[1], "org_slug": r[2]}
|
||||
for r in conn.execute("SELECT email, slug, org_slug FROM members")}
|
||||
conn.close()
|
||||
|
||||
acting = bool(send and ALLOWANCE_POLICY == "on")
|
||||
mail_on = ALLOWANCE_SHORTFALL_EMAILS == "on"
|
||||
pack_url = credit_pack_url()
|
||||
credited, staged, skipped = [], [], []
|
||||
seen: set[str] = set()
|
||||
|
||||
for c in cycles:
|
||||
if c["reference"] in seen: # a charge truncates exactly one cycle
|
||||
continue
|
||||
email = slug2email.get(c["slug"])
|
||||
if not email:
|
||||
skipped.append({**c, "why": "no Open Collective account email for this charge's slug"})
|
||||
continue
|
||||
if email not in active:
|
||||
skipped.append({**c, "email": email, "why": "not an active portal member"})
|
||||
continue
|
||||
m = meta.get(email) or {}
|
||||
if email in MANUAL_MEMBERS or m.get("org_slug"):
|
||||
skipped.append({**c, "email": email, "why": "exempt member (manual / organization-backed)"})
|
||||
continue
|
||||
rec = index.get(email)
|
||||
if rec and rec.get("role") == "ADMIN":
|
||||
skipped.append({**c, "email": email, "why": "operator account"})
|
||||
continue
|
||||
if (email, c["reference"]) in SHORTFALL_REMEDIATED:
|
||||
skipped.append({**c, "email": email,
|
||||
"why": "already remediated by a manual allowance reset (2026-11-04)"})
|
||||
continue
|
||||
seen.add(c["reference"])
|
||||
|
||||
entry = {**c, "email": email, "name": (m.get("slug") or "there")}
|
||||
already = credit_reference_exists(c["reference"])
|
||||
entry["already_credited"] = already
|
||||
if not already and acting:
|
||||
add_credits(email, c["amount"],
|
||||
reason=shortfall_reason(c["prev"], c["cur"]),
|
||||
reference=c["reference"])
|
||||
try:
|
||||
await sync_team_budget_from_balance(email)
|
||||
except Exception as e: # budget push is best-effort
|
||||
logger.warning("Shortfall: team budget sync failed for %s: %s", email, e)
|
||||
entry["credited"] = True
|
||||
elif not already:
|
||||
entry["credited"] = False # would-credit (report mode / policy off)
|
||||
|
||||
if mail_on and not shortfall_notice_sent(c["reference"]):
|
||||
subject, text_body, html_body = shortfall_email(
|
||||
entry["name"], c["amount"], c["prev"], c["cur"], c["gap_days"],
|
||||
c["days_lost"], pack_url)
|
||||
if send_email(email, subject, text_body, html_body):
|
||||
mark_shortfall_notice_sent(c["reference"], email, c["amount"])
|
||||
entry["notified"] = True
|
||||
else:
|
||||
entry["notified"] = False
|
||||
elif not mail_on:
|
||||
entry["notice"] = "staged (ALLOWANCE_SHORTFALL_EMAILS is off)"
|
||||
|
||||
(credited if entry.get("credited") or entry.get("already_credited") else staged).append(entry)
|
||||
|
||||
newly = sum(e["amount"] for e in credited if e.get("credited"))
|
||||
total = sum(e["amount"] for e in credited)
|
||||
return {
|
||||
"status": "ok",
|
||||
"mode": ALLOWANCE_POLICY,
|
||||
"acting": acting,
|
||||
"emails": ALLOWANCE_SHORTFALL_EMAILS,
|
||||
"full_month_days": FULL_PAID_MONTH_DAYS,
|
||||
"affected": len(credited),
|
||||
"newly_credited": sum(1 for e in credited if e.get("credited")),
|
||||
"already_credited": sum(1 for e in credited if e.get("already_credited")),
|
||||
"new_credit_total": round(newly, 10),
|
||||
"affected_credit_total": round(total, 10),
|
||||
"credits": credited,
|
||||
"would_credit": staged,
|
||||
"skipped": skipped,
|
||||
}
|
||||
|
||||
|
||||
@app.post("/admin/shortfall-credits")
|
||||
@limiter.limit("10/minute")
|
||||
async def admin_shortfall_credits(request: Request, mode: str = "report"):
|
||||
"""Preview (default) or apply allowance-shortfall credits.
|
||||
|
||||
`mode=report` computes the affected set and changes nothing. `mode=send`
|
||||
applies the credits (requires ALLOWANCE_POLICY=on) — idempotent on the OC
|
||||
charge reference, so a second call credits nothing again. Member notices are
|
||||
sent only when ALLOWANCE_SHORTFALL_EMAILS=on.
|
||||
"""
|
||||
_verify_admin_token(request)
|
||||
if mode == "send":
|
||||
if ALLOWANCE_POLICY != "on":
|
||||
return {"refused": f"ALLOWANCE_POLICY is '{ALLOWANCE_POLICY}', not 'on'"}
|
||||
return await reconcile_allowance_shortfalls(send=True)
|
||||
return await reconcile_allowance_shortfalls(send=False)
|
||||
|
||||
|
||||
@app.post("/admin/allowance")
|
||||
@limiter.limit("10/minute")
|
||||
async def admin_allowance(request: Request, mode: str = "report", to: str | None = None):
|
||||
@@ -4846,6 +5223,16 @@ async def admin_sweep(request: Request):
|
||||
except Exception as exc: # noqa: BLE001
|
||||
result["allowances"] = {"error": str(exc)[:200]}
|
||||
|
||||
# Allowance-shortfall credits: OC's billing-day alignment truncates some paid
|
||||
# cycles. Rides the same sweep so a new member is compensated automatically;
|
||||
# credits are idempotent on the OC charge reference. Wrapped so it can never
|
||||
# break reconciliation; notices only go out when ALLOWANCE_SHORTFALL_EMAILS=on.
|
||||
try:
|
||||
result["shortfall_credits"] = await reconcile_allowance_shortfalls(
|
||||
send=(ALLOWANCE_POLICY == "on"))
|
||||
except Exception as exc: # noqa: BLE001
|
||||
result["shortfall_credits"] = {"error": str(exc)[:200]}
|
||||
|
||||
return result
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,116 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Regression tests for the allowance-shortfall derivation (OC billing alignment).
|
||||
|
||||
Runnable:
|
||||
* from the repo root: python3 tests/test_allowance_shortfall.py
|
||||
* inside the portal app: PORTAL_CODE_DIR=/app/code python3 /tmp/test_allowance_shortfall.py
|
||||
(the container has the app's own dependencies; the host usually does not)
|
||||
|
||||
WHY THIS EXISTS
|
||||
The shortfall credit must be derived FROM DATA and must never be paid twice.
|
||||
`derive_shortfalls` is pure (no DB, no network, no clock), so the arithmetic,
|
||||
the per-order boundary, the month-length boundary and the idempotence key are
|
||||
all exercised directly on synthetic charge ladders.
|
||||
|
||||
Covered:
|
||||
- a truncated first cycle -> one credit, pro-rated to the days lost
|
||||
- a gap of exactly a full month -> NOT truncated (boundary)
|
||||
- a gap LONGER than a full month -> NOT truncated (OC deferred a charge)
|
||||
- credits are NEVER rounded -> 4.5 and 1.5 come out exact
|
||||
- two orders are judged separately -> a cross-subscription pair is not
|
||||
mistaken for one truncated cycle
|
||||
- the reference is the EARLY charge -> it is the idempotence key
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
|
||||
# Locate the app package: explicit env, the deployed path, or the repo root.
|
||||
for _cand in (os.environ.get("PORTAL_CODE_DIR"), "/app/code",
|
||||
os.path.dirname(os.path.dirname(os.path.abspath(__file__)))):
|
||||
if _cand and os.path.isfile(os.path.join(_cand, "app", "main.py")):
|
||||
sys.path.insert(0, _cand)
|
||||
break
|
||||
|
||||
from datetime import datetime, timezone # noqa: E402
|
||||
from app.main import ( # noqa: E402
|
||||
derive_shortfalls, shortfall_reason, _usd, SHORTFALL_REMEDIATED,
|
||||
)
|
||||
|
||||
|
||||
def dt(s):
|
||||
return datetime.fromisoformat(s + "T00:00:00+00:00")
|
||||
|
||||
|
||||
failures = 0
|
||||
|
||||
|
||||
def check(name, got, want):
|
||||
global failures
|
||||
ok = got == want
|
||||
if not ok:
|
||||
failures += 1
|
||||
print(f"[{'PASS' if ok else 'FAIL'}] {name}")
|
||||
if not ok:
|
||||
print(f" got {got!r}\n want {want!r}")
|
||||
|
||||
|
||||
# --- one truncated first cycle: joined/charged 11 Sep, re-aligned to 2 Oct (21d)
|
||||
recs = [{"slug": "member-a", "order_id": "or_1",
|
||||
"charges": [(dt("2026-09-11"), "tx_a1"), (dt("2026-10-02"), "tx_a2")]}]
|
||||
got = derive_shortfalls(recs, budget=15.0)
|
||||
check("truncated first cycle -> one credit",
|
||||
[(g["prev"], g["cur"], g["gap_days"], g["days_lost"], g["amount"], g["reference"]) for g in got],
|
||||
[("2026-09-11", "2026-10-02", 21, 9, 4.5, "tx_a2")])
|
||||
|
||||
# --- boundary: a gap of exactly 30 days is a full month -> nothing
|
||||
recs = [{"slug": "member-b", "order_id": "or_2",
|
||||
"charges": [(dt("2026-10-02"), "tx_b1"), (dt("2026-11-01"), "tx_b2")]}]
|
||||
check("gap == full month -> no credit", derive_shortfalls(recs, budget=15.0), [])
|
||||
|
||||
# --- a gap LONGER than a month (OC deferred a charge) -> nothing
|
||||
recs = [{"slug": "member-c", "order_id": "or_3",
|
||||
"charges": [(dt("2026-09-28"), "tx_c1"), (dt("2026-11-02"), "tx_c2")]}]
|
||||
check("gap > full month -> no credit", derive_shortfalls(recs, budget=15.0), [])
|
||||
|
||||
# --- no rounding: 24-day gap -> 6 days lost -> exact 3.0; 27-day -> 1.5
|
||||
recs = [{"slug": "member-d", "order_id": "or_4",
|
||||
"charges": [(dt("2026-10-09"), "tx_d1"), (dt("2026-11-02"), "tx_d2")]}]
|
||||
check("exact pro-rate, no rounding", [g["amount"] for g in derive_shortfalls(recs, 15.0)], [3.0])
|
||||
recs = [{"slug": "member-e", "order_id": "or_5",
|
||||
"charges": [(dt("2026-10-06"), "tx_e1"), (dt("2026-11-02"), "tx_e2")]}]
|
||||
check("half-dollar stays exact", [g["amount"] for g in derive_shortfalls(recs, 15.0)], [1.5])
|
||||
|
||||
# --- per-order boundary: two orders six days apart are NOT one truncated cycle
|
||||
recs = [
|
||||
{"slug": "member-f", "order_id": "or_6a", "charges": [(dt("2026-10-16"), "tx_f1")]},
|
||||
{"slug": "member-f", "order_id": "or_6b", "charges": [(dt("2026-10-22"), "tx_f2")]},
|
||||
]
|
||||
check("two subscriptions are judged separately (no cross-order pair)",
|
||||
derive_shortfalls(recs, budget=15.0), [])
|
||||
|
||||
# --- a later (non-first) cycle can be truncated too
|
||||
recs = [{"slug": "member-g", "order_id": "or_7",
|
||||
"charges": [(dt("2026-09-02"), "tx_g1"), (dt("2026-10-02"), "tx_g2"),
|
||||
(dt("2026-10-20"), "tx_g3")]}]
|
||||
check("a later cycle is caught too",
|
||||
[(g["prev"], g["cur"], g["reference"]) for g in derive_shortfalls(recs, 15.0)],
|
||||
[("2026-10-02", "2026-10-20", "tx_g3")])
|
||||
|
||||
# --- the reference is the EARLY charge (the idempotence key)
|
||||
recs = [{"slug": "member-h", "order_id": "or_8",
|
||||
"charges": [(dt("2026-10-15"), "tx_h1"), (dt("2026-11-02"), "tx_h2")]}]
|
||||
check("reference is the truncating (second) charge",
|
||||
[g["reference"] for g in derive_shortfalls(recs, 15.0)], ["tx_h2"])
|
||||
|
||||
# --- formatting and reason helpers
|
||||
check("_usd keeps exact amounts", [_usd(2.0), _usd(4.5), _usd(1.5)], ["$2", "$4.5", "$1.5"])
|
||||
check("reason names the cycle",
|
||||
shortfall_reason("2026-10-07", "2026-11-02"),
|
||||
"allowance shortfall, truncated paid cycle 2026-10-07→2026-11-02 (OC billing alignment)")
|
||||
|
||||
# --- the manual-remediation exclusion is keyed on (email, charge ref)
|
||||
check("remediated member/charge excluded",
|
||||
("[redacted member reference]", "[redacted member reference]") in SHORTFALL_REMEDIATED, True)
|
||||
|
||||
print(f"\n{'FAILED' if failures else 'OK'} — {failures} failure(s)")
|
||||
sys.exit(1 if failures else 0)
|
||||
Reference in new issue
Block a user