From 8af8e39c0b0803550460b951f341e407148eb210 Mon Sep 17 00:00:00 2001 From: Inferencebot Date: Sun, 8 Nov 2026 02:34:13 +0000 Subject: [PATCH] README: document the gift self-cancel flow and GUESTS_ENDED_GROUP_ID --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index bb3f354..29a4ecc 100644 --- a/README.md +++ b/README.md @@ -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_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_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 @@ -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 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:` 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 a live BACKER/ADMIN with the account's own email — via the webhook or the nightly sweep — `provision_member()` routes the call to