README: document the gift self-cancel flow and GUESTS_ENDED_GROUP_ID

This commit is contained in:
inference-bot committed 2026-11-08 02:34:13 +00:00
1 parent 526d98be17
commit 8af8e39c0b
1 file changed
+17
+17
View File
@@ -54,6 +54,7 @@ LibreChat ──→ Member Portal ──→ LiteLLM ──→ backend
| `GIFT_DAYS` | Gift-account time box in days from provisioning (default `60`). The sweep deactivates an expired gift even with credits left. | | `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`). | | `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. | | `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. |
| `GUESTS_ENDED_GROUP_ID` | Cloudron group a SELF-CANCELLED guest's user lands in: out of guests (chat access ends) but still admitted by the dashboard app, so the ended state and Become-a-member stay visible. Unset → the shared inactive group (dashboard access ends too). |
## Gift accounts ## Gift accounts
@@ -79,6 +80,22 @@ Deactivation is the same semantics as a member's — guests group → inactive,
budget zeroed, row `active=0`, newsletter unsubscribed — and the account is budget zeroed, row `active=0`, newsletter unsubscribed — and the account is
KEPT so a returning payer resumes cleanly. KEPT so a returning payer resumes cleanly.
**Self-service cancellation (recipient-initiated).** `POST /broker/cancel-gift`
(dashboard broker identity) ends a gift at the recipient's own request:
deactivation with the same kept-account semantics, the newsletter
unsubscribed, and — the part a lapse does not do — any UNSPENT credit
returned to the co-op as a negative `credit_ledger` row whose reason names
the cancellation and the original gift reference (`gift-return:<email>` is
the dedupe reference, so a repeat cancel can never double-return). The
gifts-ledger row records the full trail: inviter → recipient → 'cancelled
by recipient'. The Cloudron user leaves the guests group for
`GUESTS_ENDED_GROUP_ID` — chat and API access end, while the dashboard app
(which lists that group in its access restriction) still admits them, so
`GET /broker/gift-status` can show the ended state: access ended, data
kept, Become-a-member still one contribution away. A paying member calling
either route gets a 403 — cancelling a membership means ending the Open
Collective contribution, and this endpoint is deliberately gift-only.
**Guest → member conversion (automatic).** When a gift's OC identity appears as **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 a live BACKER/ADMIN with the account's own email — via the webhook or the
nightly sweep — `provision_member()` routes the call to nightly sweep — `provision_member()` routes the call to