firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

docs: Task #87 - Arbiter 2.1 cancellation & grace period system

Browse Source 
WHAT WAS DONE:
Created comprehensive enhancement plan for Arbiter 2.1 adding subscription cancellation, grace periods, and offboarding automation

CRITICAL SOFT LAUNCH BLOCKER:
We have subscription onboarding (Arbiter 2.0) but NO unsubscribe process.
Cannot launch without defining what happens when someone cancels.

POLICY DECISIONS MADE (March 30, 2026):
1. Discord Role Removal: At end of billing period (user gets what they paid for)
2. Whitelist Grace: 30 days after cancellation (goodwill, might come back)
3. Payment Failure Grace: 7 days with email reminders (industry standard)
4. Chargeback: Immediate removal + flag account (fraud protection)

THIS IS AN ENHANCEMENT, NOT A REWRITE:
- Arbiter 2.0 foundation is solid (2,000 lines)
- Arbiter 2.1 adds ~1,000 lines of new code
- Preserves all existing functionality
- Adds new webhook event handlers
- Adds grace period system
- Adds automated cleanup job

ARCHITECTURE COMPONENTS:

1. DATABASE ENHANCEMENT (2 new tables):
   - subscriptions: Track lifecycle and status
   - grace_periods: Automated cleanup tracking
   - Indexes for performance

2. NEW WEBHOOK HANDLERS (4 functions):
   - handleSubscriptionCancelled() - 30-day whitelist grace
   - handlePaymentFailed() - 7-day grace with reminders
   - handleChargeback() - immediate removal
   - handleSubscriptionExpired() - cleanup

3. SCHEDULED CLEANUP JOB (new file):
   - Runs daily at 4 AM
   - Removes Discord roles (billing period ended)
   - Removes whitelists (30-day grace expired)
   - Sends payment failure reminders (Day 3, Day 6)
   - Converts expired payment failures to cancellations

4. EMAIL TEMPLATES (5 new files):
   - subscription_cancelled.html
   - payment_failed.html
   - payment_failure_reminder_day3.html
   - payment_failure_final_warning.html
   - access_removed_payment_failure.html

5. WHITELIST MANAGER INTEGRATION:
   - New service: whitelistService.js
   - API call to remove from all servers
   - Requires Whitelist Manager API endpoint

GRACE PERIOD FLOWS:

NORMAL CANCELLATION:
1. User cancels → Paymenter webhook
2. Arbiter updates database (status = cancelled)
3. Discord role stays until billing period ends
4. Whitelist stays 30 days after billing end
5. Cleanup job removes role at billing end
6. Cleanup job removes whitelist after 30 days
7. Emails sent at each step

PAYMENT FAILURE:
1. Payment fails → Paymenter webhook
2. Arbiter creates 7-day grace period
3. Email sent immediately ("update payment")
4. Day 3: Reminder email (4 days left)
5. Day 6: Final warning (24 hours)
6. Day 7: Convert to cancellation
7. Follow normal cancellation flow

CHARGEBACK:
1. Chargeback filed → Paymenter webhook
2. IMMEDIATE Discord role removal
3. IMMEDIATE whitelist removal
4. Account flagged (manual review required)
5. Email sent (account suspended)
6. Discord alert to Michael/Meg

TESTING REQUIREMENTS:
- Unit test each handler in isolation
- Integration test full cancellation flow
- Edge case testing (race conditions, API failures)
- Test with real Paymenter subscription

DEPLOYMENT STRATEGY:
Phase 1: Arbiter 2.0 deployment (validate onboarding)
Phase 2: Arbiter 2.1 development (this task)
Phase 3: Staging test (full flow validation)
Phase 4: Production deployment (careful monitoring)

DEPENDENCIES:
- Arbiter 2.0 deployed and validated
- Paymenter webhook event research (verify what events exist)
- Whitelist Manager API endpoint (/api/bulk-remove)

BLOCKS:
- Soft launch (must have cancellation before launching)

RELATED TASKS:
- Task #83: Paymenter → Pterodactyl integration
- Task #7: Whitelist Manager (needs API enhancement)
- Task #86: Whitelist Manager compatibility fix
- Task #2: LuckPerms rank system

GEMINI REVIEW REQUESTED:
Architecture consultation needed before implementation:
1. Grace period architecture sound?
2. Database tables properly designed?
3. Separate cleanup job vs integrated handlers?
4. Chargeback handling appropriate?
5. Edge cases missing?
6. Security concerns?
7. Better Whitelist Manager integration approach?
8. Should grace periods be configurable?

WHY THIS MATTERS:
Cannot soft launch without offboarding flow. Industry standard requires:
- Clear cancellation process
- Grace periods for payment failures
- Fair billing (access through paid period)
- Fraud protection (chargeback handling)

This completes the subscription lifecycle: onboard → maintain → offboard.

FILE: docs/tasks/arbiter-2-1-cancellation-flow/README.md (28,000+ words)

NEXT STEPS:
1. Run by Gemini for architecture review
2. Incorporate feedback
3. Research Paymenter webhook events
4. Build Arbiter 2.1 enhancement
5. Test thoroughly
6. Deploy before soft launch

Signed-off-by: The Versionist (Chronicler #49) <claude@firefrostgaming.com>
This commit is contained in:
Claude (Chronicler #49)
2026-03-30 22:56:43 +00:00
parent 43dcec8bd9
commit 18142bc1d6
1 changed files with 1061 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1061
docs/tasks/arbiter-2-1-cancellation-flow/README.md Normal file
View File

File diff suppressed because it is too large Load Diff