gift accounts: $5 guest passes with time box, inviter ledger, auto member conversion

Operator feature: a member gives a friend access with $5 of credits, no OC
membership. Cloudron user lands in the guests group (chat + dashboard only),
LiteLLM team capped at GIFT_BUDGET with NO monthly reset, portal row marked
account_type='gift' with gift_expires_at set, gift welcome email, newsletter
subscription, and a gifts ledger recording inviter -> recipient (one gift per
inviter per 30 days, one per recipient ever).

Sweep safety: reconcile_memberships never deactivates a gift for lacking an
OC contribution; reconcile_gift_lifecycles lapses gifts by their own rules
(credits spent out, or the GIFT_DAYS time box) with member-deactivation
semantics. Guests are excluded from Loomio/Matrix invite lists, the reinvite
path, budget notices, the allowance reconciliation and the metrics member
counts.

Conversion: a gift whose OC identity appears under its own email converts
automatically (webhook + sweep + /admin/provision all funnel through
provision_member): group guests->members, cap lifted to allowance + carried
credits, anchor day kept, congrats email, full member onboarding.
/admin/gift-convert links a membership paid under a different OC email
(members.oc_email, matched by the sweep and webhook).

Fixture test: tests/test_gift_lifecycle.py (37 checks, network replaced by
a raising guard).
This commit is contained in:
inference-bot committed 2026-11-08 02:05:37 +00:00
1 parent 73d8c61aa7
commit 6d9074eefe
4 files changed
+1159 -32

No files matched your search

+44
View File
@@ -50,6 +50,50 @@ LibreChat ──→ Member Portal ──→ LiteLLM ──→ backend
| `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`). |
| `GIFT_BUDGET` | Gift-account credit in USD (default `5.0`). |
| `GIFT_DAYS` | Gift-account time box in days from provisioning (default `60`). The sweep deactivates an expired gift even with credits left. |
| `GIFT_PER_INVITER_DAYS` | Rolling window for the one-gift-per-inviter limit (default `30`). |
| `GUESTS_GROUP_ID` | Cloudron group ID for gift accounts. The chat and dashboard apps' access restrictions list BOTH the members and guests groups, so a guest reaches exactly those two apps. |
## Gift accounts
A member can give a friend access to the co-op with $5 of credits — no Open
Collective membership required. `POST /admin/provision-gift` (X-Admin-Token)
with `{"email", "name", "inviter": "<the gifting member's email>"}` runs the
gift pipeline: Cloudron user in the **guests** group, a LiteLLM team capped at
`GIFT_BUDGET` with **no monthly reset** (the cap is the gift's whole life), the
portal row marked `account_type='gift'` with the $5 held as non-expiring
credit, `gift_expires_at` set to now + `GIFT_DAYS`, the gift welcome email
(setup link, what they can use, Become-a-member, newsletter note), and a
**gifts ledger** row (`gifts` table: inviter → recipient, expiry, status) for
the abuse audit. Guards: one gift per inviter per `GIFT_PER_INVITER_DAYS`; one
gift per recipient ever; the inviter must be an active member; an existing
portal row under the recipient address is refused. Guests are subscribed to
the newsletter and invited to NOTHING else (no Loomio, no Matrix).
**Sweep safety.** `reconcile_memberships()` never deactivates a gift for
lacking an OC contribution. A gift lapses only by its own rules, handled by
`reconcile_gift_lifecycles()` inside the sweep: credits spent out (LiteLLM's
cap enforces the limit; the sweep retires the row) or the `GIFT_DAYS` time box.
Deactivation is the same semantics as a member's — guests group → inactive,
budget zeroed, row `active=0`, newsletter unsubscribed — and the account is
KEPT so a returning payer resumes cleanly.
**Guest → member conversion (automatic).** When a gift's OC identity appears as
a live BACKER/ADMIN with the account's own email — via the webhook or the
nightly sweep — `provision_member()` routes the call to
`convert_gift_to_member()`: the Cloudron user moves guests → members, the
LiteLLM cap lifts to the member allowance + credits (unspent gift credit is
carried — it already lives in `credit_balance`), the row becomes a normal
member with the standard `MEMBER_BUDGET`, the anchor day (the gift's start
date) is kept and the reset pinned to it, the congratulations email goes out,
and the normal member onboarding runs (newsletter, Loomio + Matrix syncs,
docs-RAG group, held-credit grants). When the contribution arrives under a
DIFFERENT OC email it cannot auto-match: the operator links it with
`POST /admin/gift-convert` `{"email": "<gift account>", "oc_email": "<the OC
email the contribution is under>"}` — the row records `members.oc_email`, and
the sweep and webhook treat that address as an additional matcher from then on.
## Budget model