docs(invitations): module README — referral substrate + reward architectures (#5 prep)#3837
Conversation
|
Warning Review limit reached
More reviews will be available in 56 minutes and 19 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more credits in the billing tab to continue. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the 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 include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
WalkthroughAdds comprehensive invitations module documentation: API routes, Invitation model, two-step claim/finalize signup flow, referral substrate (server-set user.referredBy and invitation.accepted event), two reward architectures (event-driven with idempotency + reconciliation, or compute-on-read), pre-shipping gates, and Vue UI surfaces. ChangesInvitations Module Documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@modules/invitations/README.md`:
- Around line 96-98: The README is ambiguous about which DB index is required:
clarify that the query shown (InvitationRepository.countAccepted({ invitedBy:
userId })) needs an index on invitations.invitedBy, while the referredBy field
lives on the User model and would require a different index for that reward
pattern; update the text to explicitly mention "index invitations.invitedBy"
(and note that rewards keyed off User.referredBy need an index on
users.referredBy) so readers know which collection/field to index.
- Around line 77-81: The reconcile cron described in the README uses the query
"invitations { status:'accepted', invitedBy: {$ne:null} }" which misses
referee-only grants created when invitedBy is null (see cfg.refereeUnits and the
comment about admin-created invites); update the documentation and reconcile
approach to perform two passes: Pass 1 scans for referrer grants using
invitations { status:'accepted', invitedBy: {$ne:null} } to reconcile
referrer-ledger keys, and Pass 2 scans all accepted invitations using
invitations { status:'accepted' } to ensure referee grants (cfg.refereeUnits)
are present, or alternatively describe a single broader query and explain how to
distinguish and back-fill both referrer and referee ledger entries; mention
modules/billing/crons and cfg.refereeUnits so maintainers can find the relevant
code.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: e2a7fbc1-702f-4e28-b935-906d11798b29
📒 Files selected for processing (1)
modules/invitations/README.md
There was a problem hiding this comment.
Pull request overview
Adds module-level documentation for modules/invitations describing the platform invitation flow and the planned referral-reward “seam” (#5 prep), including the two persisted primitives on invite acceptance (user.referredBy + invitation.accepted event) and recommended reward implementation architectures.
Changes:
- Introduces
modules/invitations/README.mdexplaining invitations’ scope (auth-only dependency, org-agnostic) and the referral substrate contract. - Documents two reward architectures (event-driven idempotent grant + reconcile cron vs compute-on-read).
- Captures the pre-shipping gates from #3833 (scoped list, self-referral guard, open-signup behavior, indexing).
… billing.init.js
User feedback: a downstream wiring its own listener in billing.init.js would be
stack-file drift (gate-blocked, ISO-merge-clobbered). Reworked: the standard grant
ships upstream in the stack, gated by config.billing.referral {enabled, referrerUnits,
refereeUnits} (downstream flips config only); custom rewards (cashback/webhooks) live
in a project-only glob-discovered module listening to the same event. billing.init.js
TODO(#5) updated to prescribe exactly that.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #3837 +/- ##
=======================================
Coverage 91.84% 91.84%
=======================================
Files 159 159
Lines 5212 5212
Branches 1659 1659
=======================================
Hits 4787 4787
Misses 337 337
Partials 88 88
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
|
@coderabbitai resolve — all 7 findings addressed in the latest commit. |
|
(ᵔᴥᵔ) ✅ Action performedComments resolved and changes approved. |
User-requested doc (2026-06-11): explains the "Referral rewards — coming soon" seam — the 2 primitives written on accept (
referredBy+ theinvitation.acceptedevent withinvitationIdas idempotency key, referrer AND referee identifiable), the 2 reward architectures (event-driven idempotent grant + reconcile cron for usage-based/cashback economies vs compute-on-read for static boosts), the settings-driven config pattern, the mandatory async-listener self-guard, and the #3833 gates. Docs-only. Part of #3808, preps #5.Summary by CodeRabbit