diff --git a/README.md b/README.md index 0eafb02..84f043f 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,9 @@ LibreChat ──→ Member Portal ──→ LiteLLM ──→ backend | `LITELLM_MASTER_KEY` | LiteLLM master key | | `OPENCOLLECTIVE_WEBHOOK_SECRET` | Optional webhook signature secret | | `PORTAL_KEK` | **Required.** Base64-encoded 32-byte key-encryption key. Member chat keys (`members.key_token`) are stored AES-256-GCM-encrypted at rest (`enc1:` prefix) and decrypted in memory only when served (dashboard, LibreChat key feed, LiteLLM management). Generate with `python3 -c "import base64,os;print(base64.b64encode(os.urandom(32)).decode())"`. If unset, the portal runs but refuses to encrypt new keys, keeps legacy plaintext, and logs CRITICAL. Rotating it requires re-encrypting every row (decrypt with the old key, encrypt with the new). | +| `ALLOWANCE_POLICY` | `report` (default) \| `on`. `report` computes every allowance decision and changes nothing; `on` performs renewals and sends the one reminder. Deactivation is gated separately by `ALLOWANCE_DEACTIVATE`. | +| `ALLOWANCE_DEACTIVATE` | `off` (default) \| `on`. When `on`, a member who was reminded and is still unpaid after the grace window is moved to the inactive group. **Defaults off so renewals/reminders can run before anyone loses access.** | +| `PAYMENT_GRACE_DAYS` | Days after the single reminder before an unpaid member is deactivated (default `7`). | ## Tier budgets @@ -99,7 +102,8 @@ Three jobs run inside the container via `CloudronManifest.json` → `addons.sche `/admin/sweep` (auth: `X-Admin-Token` = `WEBHOOK_TOKEN`) to reconcile members against the live Open Collective list: provisions missed signups, deactivates lapsed members, syncs Loomio + Matrix. Idempotent; a missed webhook - self-heals within 24 hours. + self-heals within 24 hours. The same sweep also runs the payment-driven + allowance reconciliation (below). - **rag_refresh** (nightly 3:30am) — `rag_refresh.py` pulls this repo's sibling docs from the Gitea raw API (public, no credentials), uploads changed files to Open WebUI (`OWUI_API_KEY`), attaches them to the shared knowledge @@ -119,6 +123,32 @@ Verify after any manifest change: the deploy log must show `setupAddons: ... scheduler ...` listing all three tasks, and each script must succeed when run manually inside the container. +### Allowance renewal (payment-driven, join-day anchored) + +Each member has a monthly allowance (`MEMBER_BUDGET`, currently $15). The +allowance renews on the day of the month the member *joined*, never on the day +Open Collective happened to charge them — OC aligns every member's charge onto +the collective's common billing day, so anchoring to the payment date let an +early charge move the boundary and skip a cycle entirely. The join day is stored +per member (`members.anchor_day`) and the reset is pinned there. + +Whether the allowance renews is decided by asking Open Collective directly, on +the sweep's own schedule (not inferred from webhook delivery): a member with a +live recurring contribution (order status `ACTIVE` or `PROCESSING` — a payment +in flight is not a missed payment) renews; a member with no live recurring +contribution gets **one** reminder email, and is deactivated only after +`PAYMENT_GRACE_DAYS`. One-time payments are not an allowance cycle — they top up +the non-expiring credit balance and are untouched here. There are no annual +contributors (verified 2026-11-04: 104 orders, 87 MONTHLY, 17 ONETIME, zero +annual), so only the monthly case is implemented. + +Every decision (renewed / reminded / deactivated, plus the payment date or its +absence) is written to `allowance_log` and answerable from that record. Run +`POST /admin/allowance?mode=report` (X-Admin-Token) for a no-op report that +changes nothing; `mode=send` performs renewals and sends the reminder and +requires `ALLOWANCE_POLICY=on`. Deactivation additionally requires +`ALLOWANCE_DEACTIVATE=on`. + ### Energy & carbon metrics The daily snapshot also computes energy (Wh) and carbon (gCO₂e) from output tokens, diff --git a/app/main.py b/app/main.py index 4b4e2c9..5bcabfb 100644 --- a/app/main.py +++ b/app/main.py @@ -2472,9 +2472,15 @@ async def opencollective_webhook(request: Request, token: str): except Exception as e: logger.warning("Webhook: failed to provision %s: %s", member["email"], e) try: + # POLICY (2026-11-04): the allowance reset is anchored to the + # member's JOIN day, NOT the payment date. OC aligns charges + # onto a common billing day, so re-anchoring to the charge + # moved a renewal and skipped a cycle. A payment must only + # CONFIRM the cycle, never redefine where it falls. team_id = await litellm_get_or_create_team( member["email"], get_member_balance(member["email"])) - await litellm_pin_reset_date(team_id, next_reset_from_now()) + anchor = await anchor_day_for_member(member["email"], member["slug"]) + await litellm_pin_reset_date(team_id, next_reset_for_anchor_day(anchor)) except Exception as e: logger.warning("Webhook: failed to pin reset date for %s: %s", member["email"], e) @@ -4032,6 +4038,430 @@ async def reconcile_memberships() -> dict: } +# --------------------------------------------------------------------------- # +# Allowance renewal — payment-driven, anchored to the member's JOIN day. # +# --------------------------------------------------------------------------- # +# Policy (operator decision 2026-11-04). Open Collective aligns every member's +# charge onto the collective's common billing day, so anchoring an allowance +# reset to the PAYMENT date lets a charge move the boundary and skip a cycle +# entirely: [redacted member reference] [redacted timeline], +# and our reset rule re-anchored them to a new day with no reset in between. So the +# reset is anchored to the day of the month the member JOINED, and renewal is +# decided by asking Open Collective directly whether a recurring contribution is +# live — on our own schedule, not inferred from webhook delivery. A webhook that +# never arrives then costs a delayed renewal, never a lost month. +# +# Decisions (per member, per cycle): +# renewed — a recurring contribution is live; the allowance reset is pinned +# to the member's next join-day. +# reminded — no live recurring contribution; one reminder email is sent. +# deactivated — reminded on an earlier pass and still unpaid after the grace +# window; the member loses group access but keeps their account. +# Every decision is written to allowance_log with the Open Collective evidence +# (payment date, or its absence) so a dispute is answered from a record. +ALLOWANCE_POLICY = (os.environ.get("ALLOWANCE_POLICY", "report") or "report").strip().lower() +# Deactivation is gated SEPARATELY and defaults OFF, so the renewal/reminder path +# can be exercised before anyone loses access (operator directive 2026-11-04). +ALLOWANCE_DEACTIVATE = (os.environ.get("ALLOWANCE_DEACTIVATE", "off") or "off").strip().lower() +# Days to wait after the single reminder before deactivating a still-unpaid member. +PAYMENT_GRACE_DAYS = float(os.environ.get("PAYMENT_GRACE_DAYS", "7")) + + +def _ensure_allowance_tables(conn) -> None: + conn.execute( + "CREATE TABLE IF NOT EXISTS allowance_log (" + " id INTEGER PRIMARY KEY AUTOINCREMENT," + " email TEXT NOT NULL, cycle TEXT NOT NULL, decision TEXT NOT NULL," + " evidence TEXT, anchor_day INTEGER," + " decided_at TEXT DEFAULT (datetime('now')))" + ) + conn.execute( + "CREATE TABLE IF NOT EXISTS payment_reminders (" + " email TEXT NOT NULL, cycle TEXT NOT NULL, sent_at TEXT NOT NULL," + " PRIMARY KEY (email, cycle))" + ) + cols = {r[1] for r in conn.execute("PRAGMA table_info(members)")} + if "anchor_day" not in cols: + conn.execute("ALTER TABLE members ADD COLUMN anchor_day INTEGER") + conn.commit() + + +def _parse_oc_dt(value): + """Parse an Open Collective ISO timestamp ('…Z') into an aware datetime.""" + if not value: + return None + try: + dt = datetime.fromisoformat(str(value).replace("Z", "+00:00")) + return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc) + except Exception: + return None + + +def _clamp_anchor_day(anchor_day: int) -> int: + """Clamp the anchor day to 28 so short months never skip a renewal.""" + try: + d = int(anchor_day) + except Exception: + return 1 + return min(max(d, 1), 28) + + +def next_reset_for_anchor_day(anchor_day: int, now: datetime | None = None) -> datetime: + """The member's next allowance reset: the next occurrence of their join-day. + + The day-of-month is the member's JOIN day (not their payment date), so an OC + charge landing early cannot move the boundary. Always strictly after `now`. + """ + now = now or datetime.now(timezone.utc) + day = _clamp_anchor_day(anchor_day) + y, m = now.year, now.month + cand = datetime(y, m, day, 0, 0, tzinfo=timezone.utc) + if cand <= now: + y, m = (y + 1, 1) if m == 12 else (y, m + 1) + cand = datetime(y, m, day, 0, 0, tzinfo=timezone.utc) + return cand + + +def cycle_start_for_anchor_day(anchor_day: int, now: datetime | None = None) -> datetime: + """The most recent occurrence of the member's join-day at/before `now`.""" + now = now or datetime.now(timezone.utc) + day = _clamp_anchor_day(anchor_day) + y, m = now.year, now.month + cand = datetime(y, m, day, 0, 0, tzinfo=timezone.utc) + if cand > now: + y, m = (y - 1, 12) if m == 1 else (y, m - 1) + cand = datetime(y, m, day, 0, 0, tzinfo=timezone.utc) + return cand + + + +async def anchor_day_for_member(email: str, slug: str = "") -> int: + """The member's allowance anchor day (the day of month they joined). + + Stored on the members row; derived from the OC join date on first use and + persisted so later decisions are stable. Clamped to 28. + """ + conn = get_db() + row = conn.execute("SELECT anchor_day FROM members WHERE email = ?", (email,)).fetchone() + conn.close() + if row and row[0]: + return _clamp_anchor_day(row[0]) + if slug: + try: + for n in await fetch_all_member_nodes(): + if (n.get("account") or {}).get("slug") == slug: + dt = _parse_oc_dt(n.get("createdAt")) + if dt: + d = _clamp_anchor_day(dt.day) + conn = get_db() + conn.execute("UPDATE members SET anchor_day = ? WHERE email = ?", (d, email)) + conn.commit() + conn.close() + return d + break + except Exception as e: + logger.warning("anchor_day_for_member: OC join-date lookup failed for %s: %s", email, e) + return _clamp_anchor_day(datetime.now(timezone.utc).day) + +async def fetch_member_orders() -> dict[str, list[dict]]: + """Every OC order for the collective, grouped by the payer's slug. + + One query for the whole collective (orders(limit: 200)) rather than a call + per member. Raises on failure so the caller can skip rather than mis-decide. + """ + if not OC_PERSONAL_TOKEN: + raise RuntimeError("OC_PERSONAL_TOKEN not set; cannot fetch orders") + query = ( + '{ collective(slug: "%s") { orders(limit: 200) { totalCount nodes { ' + "frequency status createdAt lastChargedAt nextChargeDate " + "fromAccount { slug } totalAmount { value currency } } } } }" + % 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 fetch failed: HTTP {r.status_code}") + body = r.json() + if body.get("errors"): + raise RuntimeError(f"OC order fetch errors: {str(body['errors'])[:200]}") + orders = (((body.get("data") or {}).get("collective") or {}).get("orders") or {}) + by_slug: dict[str, list[dict]] = {} + for o in orders.get("nodes") or []: + slug = ((o.get("fromAccount") or {}).get("slug") or "").strip() + if slug: + by_slug.setdefault(slug, []).append(o) + return by_slug + + +def _payment_verdict(orders: list[dict], cycle_start: datetime) -> tuple[bool, str]: + """Did this member's recurring contribution pay for the current cycle? + + Returns (paid, evidence). A PROCESSING order counts as PAID (a payment in + flight is not a missed payment). A live ACTIVE recurring contribution is + treated as paid even if its next charge is still ahead — otherwise a member + whose charge falls due tomorrow reads as unpaid on every sweep. + """ + monthly = [o for o in orders if (o.get("frequency") or "").upper() == "MONTHLY"] + if not monthly: + return False, "no recurring (monthly) contribution on Open Collective" + live = [o for o in monthly if (o.get("status") or "").upper() in ("ACTIVE", "PROCESSING")] + if live: + charges = [c for c in (_parse_oc_dt(o.get("lastChargedAt")) for o in live) if c] + last = max(charges).date().isoformat() if charges else "unknown" + return True, f"live recurring contribution (last charged {last})" + charged = [(_parse_oc_dt(o.get("lastChargedAt")), o.get("status")) for o in monthly] + charged = [(c, s) for c, s in charged if c] + if charged: + last_dt, _ = max(charged, key=lambda t: t[0]) + if last_dt >= cycle_start - timedelta(days=7): + return True, f"charged {last_dt.date().isoformat()} within the current cycle" + return False, f"last charge {last_dt.date().isoformat()} is before this cycle" + statuses = ",".join(sorted({(o.get("status") or "?").upper() for o in monthly})) + return False, f"no live recurring contribution (order status: {statuses})" + + +def payment_reminder_email(name: str, contribute_url: str) -> tuple[str, str, str]: + """Build the one-per-cycle 'we haven't seen your contribution' reminder. + + 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 — it names the action, not the plumbing. + """ + subject = "Your Inference Cooperative membership needs attention" + text = ( + f"Hi {name},\n\n" + "Our records at Open Collective don't show a current monthly contribution " + "for your account, so your monthly allowance won't renew.\n\n" + "To keep your access, restart or update your contribution here:\n\n" + f"{contribute_url}\n\n" + "If your payment has already gone through, ignore this — your allowance " + "will renew on its own. If we don't see a contribution after a short grace " + "period, your account stays in place but loses access until your " + "contribution resumes.\n\n" + "Questions? Reply to this email or write to info@inference.coop.\n\n" + "— The Inference Cooperative\n" + ) + html = f""" + + + + + + + +
+ + + + + + + + + + +
+ {PINE_LOGO_SVG} +
+

Your membership needs attention

+

Our records at Open Collective don't show a current monthly contribution for your account, so your monthly allowance won't renew.

+

To keep your access, restart or update your contribution. If your payment has already gone through, ignore this.

+ Update your contribution +

If we don't see a contribution after a short grace period, your account stays in place but loses access until your contribution resumes.

+
+ Questions? Reply to this email or write to info@inference.coop.
+ The Inference Cooperative · inference.coop +
+
+ +""" + return subject, text, html + + +async def reconcile_allowances(send: bool = False) -> dict: + """Decide every active member's allowance renewal from OC payment evidence. + + `send=False` is a REPORT: it computes and records every decision (renew / + remind / deactivate) and changes NOTHING — no resets, no emails, no group + changes. `send=True` performs renewals and sends the single reminder. + Deactivation still additionally requires ALLOWANCE_DEACTIVATE=on. + """ + try: + by_slug = await fetch_member_orders() + except Exception as e: + logger.warning("Allowance reconcile: order fetch failed; skipping (fail-safe): %s", e) + return {"status": "skipped", "reason": "order_fetch_failed", "detail": str(e)[:200]} + + # Join dates from OC (authoritative anchor source) — best-effort. + joined_by_slug: dict[str, str] = {} + try: + for n in await fetch_all_member_nodes(): + acct = n.get("account") or {} + joined_by_slug[acct.get("slug") or ""] = n.get("createdAt") or "" + except Exception as e: + logger.warning("Allowance reconcile: could not read OC join dates (%s); using stored anchor", e) + + conn = get_db() + _ensure_allowance_tables(conn) + cols = {r[1] for r in conn.execute("PRAGMA table_info(members)")} + extra = ", welcome_sent_at" if "welcome_sent_at" in cols else "" + rows = conn.execute( + f"SELECT email, slug, anchor_day, org_slug{extra} FROM members WHERE active = 1" + ).fetchall() + + # The collective's own ADMIN accounts (the co-op) are not members to reconcile. + admin_emails: set[str] = set() + try: + admin_emails = {m["email"] for m in await fetch_members() if m.get("role") == "ADMIN"} + except Exception as e: + logger.warning("Allowance reconcile: could not read ADMIN accounts (%s)", e) + + now = datetime.now(timezone.utc) + contribute = credit_pack_url() + verified = "on" if (send and ALLOWANCE_POLICY == "on") else "report" + decisions: list[dict] = [] + counts = {"renewed": 0, "reminded": 0, "deactivated": 0, + "would_renew": 0, "would_remind": 0, "would_deactivate": 0, "skipped": 0} + + for row in rows: + email = row[0] + slug = row[1] or "" + anchor_day = row[2] + org_slug = row[3] + welcome_sent = row[4] if len(row) > 4 else None + + if email.lower() in MANUAL_MEMBERS: + counts["skipped"] += 1 + continue + if email in admin_emails: + # The co-op's own account — never reconciled against payment. + counts["skipped"] += 1 + continue + if org_slug: + # Dues are paid by an OC Organization; handled by the org branch. + counts["skipped"] += 1 + continue + if not slug: + # No OC slug on file → we cannot check payment. Never punish that. + decisions.append({"email": email, "slug": "", "anchor_day": anchor_day, + "cycle": "", "decision": "skipped", "evidence": "no OC slug on file"}) + counts["skipped"] += 1 + continue + + # Resolve and persist the anchor day (join day). + if not anchor_day: + src = "oc_join_date" if joined_by_slug.get(slug) else ("welcome_sent" if welcome_sent else "today") + dt = _parse_oc_dt(joined_by_slug.get(slug)) or _parse_oc_dt(welcome_sent) or now + anchor_day = _clamp_anchor_day(dt.day) + if send: + conn.execute("UPDATE members SET anchor_day = ? WHERE email = ?", (anchor_day, email)) + conn.commit() + anchor_day = _clamp_anchor_day(anchor_day) + cycle_start = cycle_start_for_anchor_day(anchor_day, now) + cycle_key = cycle_start.date().isoformat() + + orders = by_slug.get(slug, []) + paid, evidence = _payment_verdict(orders, cycle_start) + + if paid: + decision, act = "renewed", "renew" + next_reset = next_reset_for_anchor_day(anchor_day, now) + evidence = f"{evidence}; reset anchored to day {anchor_day} → next reset {next_reset.date().isoformat()}" + counts["renewed" if verified == "on" else "would_renew"] += 1 + if verified == "on": + try: + team_id = await litellm_team_id_for_email(email) + if team_id: + await litellm_pin_reset_date(team_id, next_reset) + except Exception as e: + logger.warning("Allowance renew failed for %s: %s", email, e) + else: + reminded_row = conn.execute( + "SELECT sent_at FROM payment_reminders WHERE email = ? AND cycle = ?", + (email, cycle_key), + ).fetchone() + if not reminded_row: + decision, act = "reminded", "remind" + counts["reminded" if verified == "on" else "would_remind"] += 1 + if verified == "on": + name = slug or "there" + subject, text_body, html_body = payment_reminder_email(name, contribute) + if send_email(email, subject, text_body, html_body): + conn.execute( + "INSERT OR REPLACE INTO payment_reminders (email, cycle, sent_at)" + " VALUES (?, ?, datetime('now'))", + (email, cycle_key), + ) + conn.commit() + else: + decision = "remind_failed" + else: + sent_at = _parse_oc_dt(str(reminded_row[0])) + elapsed = (now - sent_at).days if sent_at else None + if elapsed is not None and elapsed >= PAYMENT_GRACE_DAYS and ALLOWANCE_DEACTIVATE == "on": + decision, act = "deactivated", "deactivate" + counts["deactivated" if verified == "on" else "would_deactivate"] += 1 + if verified == "on": + urow = conn.execute( + "SELECT cloudron_user_id FROM members WHERE email = ?", (email,) + ).fetchone() + if INACTIVE_GROUP_ID and urow and urow[0]: + await cloudron_set_group(urow[0], INACTIVE_GROUP_ID) + deactivate_member(email) + await revoke_member_litellm_access(email) + await listmonk_sync(email, subscribe=False) + evidence = f"{evidence}; reminder sent {reminded_row[0][:10]}, grace {int(PAYMENT_GRACE_DAYS)}d elapsed" + else: + decision, act = "in_grace", "wait" + evidence = (f"{evidence}; reminder sent " + + (str(reminded_row[0])[:10] if reminded_row[0] else "?") + + f" (grace {int(PAYMENT_GRACE_DAYS)}d)") + + conn.execute( + "INSERT INTO allowance_log (email, cycle, decision, evidence, anchor_day)" + " VALUES (?, ?, ?, ?, ?)", + (email, cycle_key, f"{decision}", evidence, anchor_day), + ) + conn.commit() + decisions.append({"email": email, "slug": slug, "anchor_day": anchor_day, + "cycle": cycle_key, "decision": decision, "evidence": evidence}) + + conn.close() + return { + "mode": ALLOWANCE_POLICY, + "verified": verified, + "deactivation_enabled": ALLOWANCE_DEACTIVATE == "on", + "considered": len(rows), + "counts": counts, + "decisions": decisions, + } + + +@app.post("/admin/allowance") +@limiter.limit("10/minute") +async def admin_allowance(request: Request, mode: str = "report"): + """Reconcile member allowances against Open Collective payments. + + `mode=report` (default) changes nothing. `mode=send` performs renewals and + sends the single reminder, and requires ALLOWANCE_POLICY=on on the app. + Deactivation is separately gated by ALLOWANCE_DEACTIVATE=on. + """ + _verify_admin_token(request) + if mode == "send": + if ALLOWANCE_POLICY != "on": + return {"refused": f"ALLOWANCE_POLICY is '{ALLOWANCE_POLICY}', not 'on' — " + "nothing sent; set it on the portal app first"} + return await reconcile_allowances(send=True) + return await reconcile_allowances(send=False) + + @app.post("/admin/sweep") @limiter.limit("20/minute") async def admin_sweep(request: Request): @@ -4052,6 +4482,14 @@ async def admin_sweep(request: Request): except Exception as exc: # noqa: BLE001 result["budget_notices"] = {"error": str(exc)[:200]} + # Payment-driven allowance renewal (join-day anchored). Rides the same sweep. + # REPORT-ONLY unless ALLOWANCE_POLICY=on; deactivation additionally needs + # ALLOWANCE_DEACTIVATE=on. Wrapped so it can never break reconciliation. + try: + result["allowances"] = await reconcile_allowances(send=(ALLOWANCE_POLICY == "on")) + except Exception as exc: # noqa: BLE001 + result["allowances"] = {"error": str(exc)[:200]} + return result