Add DB-backed Promo Manager: admin UI, eligibility & claim workflow

[gamblecodezcom]

Motivation

• Replace legacy hardcoded / env-driven promo logic with a single admin-managed Promo Manager so all promos are created, edited, and persisted in the DB rather than .env or code.
• Provide a full admin workflow (create/edit/pause/delete/preview/stats/approval) and a user-facing eligibility-aware claim flow that supports auto-approve or admin approval.

Description

• Introduce a persisted Promo Manager store and file data/promo-manager-db.json with promoManagerStore (promos, claims, eligibilityFailures) and helper functions savePromoManagerDb() / loadPromoManagerDb(); wire persistence into persistRuntimeState() and startup loader.
• Add normalized promo model and helpers: normalizePromoManagerPromo, listActivePromos, getPromoById, countPromoClaims, hasRedeemedAnyPromo, getRollingWagerForUser, and evaluatePromoEligibility to evaluate new/existing/wager requirements and cooldowns.
• Replace legacy single-promocode flow with DB-backed flows: user /promo now opens the Promo Menu, menu_claim_bonus lists only promos the user is eligible for, promo preview/claim handlers (promo_open_<id>, promo_claim_<id>) were added, and user claim records are stored in promoManagerStore.claims (auto-approve vs pending_approval).
• Add admin Promo Manager UI and actions: new admin menu item 🎛 Promo Manager and keyboard (adminPromoToolsKeyboard) with actions to open manager, admin_pm_create (9-step guided creation), admin_pm_edit, admin_pm_pause_toggle, admin_pm_delete, admin_pm_stats, admin_pm_preview, and admin_pm_queue (approval queue). Legacy promo code manager and broadcast paths now point admins to the Promo Manager.
• Add admin moderation commands for queued claims: /pmapprove <claim_id> and /pmdeny <claim_id> <reason> which approve/deny pending claims and notify users.
• Keep lightweight legacy placeholders for compatibility (PROMO_AUDIENCE, PROMO_REQUIREMENT_TYPE, promoCodeStore) while removing reliance on PROMO_* env vars for runtime promo behavior; promoStore now only holds bonusRule/bugreports/logs.

Testing

• Ran syntax check with npm run check; it completed successfully after fixes to inserted templates.
• Ran full test suite with npm test (node test files under test/*.test.js); all tests passed (33/33).
• Performed local static validations: code loads promo-manager-db.json on startup, persistence calls added to persistRuntimeState(), and menus/commands wired and exercised by unit tests.

---

Codex Task

Summary by CodeRabbit

• New Features
  • Introduced database-backed promo management system with persistent storage, replacing legacy in-memory configuration
  • Enhanced admin interface with streamlined promo creation and management wizard
  • Added configurable promo statuses and eligibility requirements for flexible campaign targeting
  • Improved promo claim and eligibility workflows with refined admin verification processes

[coderabbitai]

Warning

Rate limit exceeded

@gamblecodezcom has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 21 minutes and 12 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between 78aa4b2 and 58a09f6.

📒 Files selected for processing (1)

• index.js

📝 Walkthrough

Walkthrough

This pull request refactors the promo management system from environment-driven, in-memory defaults to a persistent, database-backed subsystem. It introduces promo status and eligibility constants, adds helper functions for promo operations, restructures admin commands for streamlined management, implements persistent storage via promo-manager-db.json, and reworks eligibility checking and claim workflows.

Changes

Cohort / File(s)

Summary

Promo Management Refactoring index.js

Replaces legacy promoStore with DB-backed promoManagerStore; introduces PROMO_STATUS (ACTIVE/PAUSED/DELETED) and PROMO_REQUIREMENT (NEW_USER_ONLY, EXISTING_USER, EXISTING_USER_WITH_WAGER) constants; adds helper functions (listActivePromos, getPromoById, hasRedeemedAnyPromo, countPromoClaims, renderPromoForUser); refactors promo code storage structure; implements persistent IO via loadPromoManagerDb/savePromoManagerDb; rewrites promo eligibility evaluation and claim workflows with admin verification; restructures admin UI commands from legacy promo tools to new admin_pm_\* command suite for wizard-based promo creation and management.

Sequence Diagram(s)

sequenceDiagram
    actor User
    actor Admin
    participant System as Promo System
    participant DB as promoManagerDb

    Admin->>System: admin_pm_create_name("Bonus Promo")
    Admin->>System: admin_pm_create_requirement(NEW_USER_ONLY)
    Admin->>System: admin_pm_create_claim_limit(100)
    System->>DB: savePromoManagerDb()
    DB-->>System: ✓ Saved
    
    User->>System: getActivePromoCodeForUser()
    System->>System: listActivePromos()
    System->>System: evaluatePromoEligibility(user, promo)
    alt Eligible
        System->>System: renderPromoForUser(promo)
        System-->>User: Promo displayed
    else Ineligible
        System-->>User: Not eligible
    end
    
    User->>System: redeemPromo(promoId)
    System->>System: evaluatePromoEligibility(user, promo)
    alt Verified
        System->>DB: Create claim (promo_id, user_id, status=PENDING)
        DB-->>System: Claim created
        System->>DB: savePromoManagerDb()
        System-->>User: Claim submitted
    else Failed
        System->>DB: Record eligibility failure
        System-->>User: Claim rejected
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Full system upgrade: onboarding, giveaways, admin panel, and JSON storage hardening #7: Implements DB-backed promo persistence with admin management interface and JSON storage, directly related to this architectural refactoring of the promo subsystem.

Suggested labels

size:XL

Poem

🐰 With whiskers twitched and nose held high,
We've swapped the promos to the sky!
No longer ENV's simple song,
But databases where claims belong,
Admin tools now shine so bright—
A promo manager, pure delight! ✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/add-new-admin-promo-manager

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}