Introduce DB-backed Promo Manager; improve SSHV, health checks, and persistence

[gamblecodezcom]

User description

Motivation

• Replace the legacy single-code promo system with a more flexible, DB-backed Promo Manager to support multiple promos, per-promo limits, cooldowns and admin workflows.
• Harden admin shell (/sshv) behavior with better error hints and safer editor save handling so operators get clearer diagnostics in restricted sandboxes.
• Support health checks over TLS when configured and persist promo manager state to disk for reliable restarts.

Description

• Add a promoManagerStore with persistent file data/promo-manager-db.json and helper functions savePromoManagerDb and loadPromoManagerDb and migrate promo logic to DB-backed promos via normalizePromoManagerPromo, evaluatePromoEligibility, listActivePromos, getPromoById, renderPromoForUser, countPromoClaims and related helpers.
• Replace legacy in-memory promoStore/promoCodeStore flows and admin UI paths with a Promo Manager UI and new admin actions (admin_pm_create, admin_pm_edit, admin_pm_pause_toggle, admin_pm_delete, admin_pm_stats, admin_pm_preview, admin_pm_queue) plus admin commands /pmapprove and /pmdeny for claim approval workflows; update user-facing promo commands to use the new manager and persist claims in promoManagerStore.claims.
• Improve /sshv interactions: add buildSshvSandboxRestrictionHint to append helpful messages when filesystem/sandbox errors occur, wrap editor save in try/catch with error logging, and add admin logging for ctrl actions; make the SSHV GC timer ref-able via sshvGcTimer.unref().
• Make health-check handlers TLS-aware via isHealthTlsEnabled() and use http/https clients accordingly; add runtime persistence calls to save the promo manager DB from persistRuntimeState and load it in loadPersistentData.
• Miscellaneous: update .dockerignore and .gitignore to exclude runtime JSON and backups, update .env.example to document WEBAPP_HMAC_KEY, switch several parse modes to Markdown for editor replies, and change many admin labels/menus to reflect Promo Manager.

Testing

• Performed a module startup smoke-load under CI mode with CI=true node -e "require('./index.js')" which completed without uncaught exceptions.
• Exercised the new promo-manager persistence by calling loadPromoManagerDb/savePromoManagerDb paths during startup/persist cycles in automated smoke tests to confirm no file parse errors.

---

Codex Task

---

CodeAnt-AI Description

Introduce DB-backed Promo Manager, admin workflows, and harden SSHV & health checks

What Changed

• Replaced the single in-memory promo/code flow with a persistent, DB-backed Promo Manager: promos and claims are stored on disk, multiple promos can be configured, and active promos are shown in a user-facing Promo Menu.
• Users open a Promo Menu to see only promos they are eligible for; claiming creates a recorded claim that is either auto-approved or submitted for admin review and notification.
• Admins get a new Promo Manager UI and multi-step creation/editing flows, preview and stats views, a pending-claims queue, and simple approve/deny commands (/pmapprove, /pmdeny) to process claims.
• Promo eligibility now enforces new-user vs existing-user rules, wager requirements, per-promo claim limits, and cooldowns; failed eligibility checks are logged for admin inspection.
• Persist promo manager state to data/promo-manager-db.json and include it in runtime persistence and backups.
• Hardened SSHV interactions: safer editor save with error handling and user feedback, added sandbox-restriction hint when filesystem permission errors occur, and admin logging for Ctrl actions.
• Health check requests respect TLS configuration when HTTPS key/cert paths are provided and use the appropriate HTTP/HTTPS client; health checks no longer assume HTTPS.
• Minor user-visible changes: legacy /setpromo and promo broadcast flows are disabled in favor of the new manager; reply formatting for some admin messages changed to Markdown; .env.example clarified HMAC key instructions; runtime JSON files excluded in .dockerignore.

Impact

✅ Clearer promo claims and statuses for users
✅ Fewer lost or untracked promo claims (persistent storage)
✅ Faster admin approvals via explicit approve/deny commands
✅ Clearer SSHV error messages when filesystem/sandbox restrictions occur

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.

Summary by CodeRabbit

Release Notes

• New Features

  • Enhanced promotion management with persistent storage and real-time eligibility tracking
  • Expanded broadcast capabilities with multi-target messaging support
  • Improved health check handling with TLS detection

• Documentation

  • Updated configuration example with security key guidance

• Chores

  • Updated .gitignore to exclude runtime-generated data
  • Added system integrity validation tests

[codeant-ai]

CodeAnt AI is reviewing your PR.

---

Thanks for using CodeAnt! 🎉

We're free for open-source projects. if you're enjoying it, help us grow by sharing.

Share on X ·
Reddit ·
LinkedIn

[coderabbitai]

Warning

Rate limit exceeded

@gamblecodezcom has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 26 minutes and 7 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 5c5d9dd and 62ac113.

📒 Files selected for processing (4)

• .env.example
• .gitignore
• index.js
• test/smoke.test.js

📝 Walkthrough

Walkthrough

This PR introduces a database-backed promo management system, replacing ad-hoc in-memory handling with persistent storage via promo-manager-db.json. Configuration files are updated for runtime data persistence, and test coverage is added for callback handler validation.

Changes

Cohort / File(s)	Summary
Configuration & Runtime Setup .env.example, .gitignore	Updated WEBAPP_HMAC_KEY documentation in .env.example and added runtime ignore patterns for generated JSON files and backups in data directory.
DB-Backed Promo Manager index.js	Introduced promo management overhaul: new PROMO_STATUS and PROMO_REQUIREMENT constants; replaced scattered promo fields with consolidated promoManagerStore containing promos, claims, and state. Added persistence layer (loadPromoManagerDb, savePromoManagerDb), eligibility evaluation (evaluatePromoEligibility), and helper APIs (listActivePromos, getPromoById, countPromoClaims, etc.). Expanded admin/user interfaces with new promo management flows, commands, and keyboard options. Enhanced TLS handling and announcement broadcasting.
Test Coverage test/smoke.test.js	Added validation test mapping callback button IDs to action handlers, using pattern-based filtering for dynamic names and filesystem reading of index.js.

Sequence Diagrams

sequenceDiagram
    actor User
    participant PromoMgr as Promo Manager
    participant DB as promo-manager-db.json
    participant Eligibility as Eligibility Check

    User->>PromoMgr: Request active promos
    PromoMgr->>DB: Load promoManagerStore
    DB-->>PromoMgr: Return promos list
    PromoMgr->>Eligibility: evaluatePromoEligibility(user, promo)
    Eligibility-->>PromoMgr: { eligible, reasons }
    alt Eligible
        PromoMgr-->>User: Render promo for user
    else Ineligible
        PromoMgr-->>User: Return eligibility failure reasons
    end

Loading

sequenceDiagram
    actor User
    participant PromoMgr as Promo Manager
    participant Store as promoManagerStore
    participant DB as promo-manager-db.json

    User->>PromoMgr: Claim promo (or auto-approve)
    PromoMgr->>Store: Create claim entry with status
    Store-->>PromoMgr: Claim created
    PromoMgr->>DB: savePromoManagerDb()
    DB-->>PromoMgr: Persisted
    PromoMgr-->>User: Claim confirmed

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• Add admin SSHV console, tips persistence, HTTPS health, admin UX and deployment improvements #79 — Adds runtime ignore patterns to .gitignore and updates .env.example for configuration management alongside this PR's persistence setup.
• Onboarding v4: step‑0 onboarding, referral boost, admin aliases, and JSON runtime + gating #8 — Introduces JSON-backed runtime storage for data, which provides the foundation for this PR's promo-manager-db.json persistence layer.
• Resolve PR #2 review comments: startup, reminders, callbacks, and persistence #3 — Implements DB-backed promo state management and runtime serialization directly aligned with this PR's promo manager refactoring.

Suggested labels

size:XXL

Poem

🐰 A hop through promos, now persistent and true,
DB-backed claims and eligibility rules brew.
From scattered fields to a store unified bright,
The promo manager hops into production light! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 21.95% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and specifically summarizes the main changes: introducing a DB-backed Promo Manager, improving SSHV behavior, enhancing health checks, and refining persistence mechanisms—all directly reflected in the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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.}

[codeant-ai]

Nitpicks 🔍

🔒 No security issues identified

⚡ Recommended areas for review Key/credential patterns Blocking '.pem' and '.key' is appropriate to avoid adding private keys to build contexts, but ensure public key files or intentionally shipped certs are handled explicitly (re-include if required) instead of relying on broad patterns. Runtime data excluded 'data/*.json' and 'data/backups/**' will exclude runtime persistence files (e.g. the new persistent promo DB at data/promo-manager-db.json). Ensure this is intentional: it prevents runtime state leaking into images but also prevents packaging any seed DB files you may want included. Env-file overmatching The patterns '.env*', '.env.*' and related entries are broad and will also ignore environment template/example files (e.g. '.env.example') that you may want to include in build contexts or distribution. Confirm the intent and, if you want to keep example templates in the repo/build, add explicit re-include rules or tighten patterns.

[codeant-ai]

CodeAnt AI finished reviewing your PR.