feat(bot): starboard seeding and one-time first-star dm

[LucasSantana-Dev]

Engagement play: make the starboard discoverable with one click.

What

Two opt-in, per-guild behaviors on StarboardConfig (no guild-specific code — all config):

1. Seed reaction — the bot pre-adds the guild's starboard emoji to messages so members can join with one click. seedReaction (default off) + seedChannelIds (empty = all channels; the starboard channel itself is always excluded).
2. First-star DM — the first time a member ever stars a message, the bot DMs them explaining the highlights channel. firstStarDm (default off) + firstStarDmMessage (per-guild text; default built from the config's emoji/threshold/channel).

Correctness

• The bot's seed never counts: the reaction handler now computes count - (reaction.me ? 1 : 0), so seeding can't inflate the threshold.
• Exactly-once DM: claim = insert into starboard_dm_sents (@@unique([guildId,userId])) — atomic under concurrent reactions; closed DMs are swallowed.
• Seed handler never blocks the message pipeline (always {stop:false}, errors logged).

Changes

Migration starboard_seed_first_star_dm (4 config cols + starboard_dm_sents), starboardSeedHandler in the message pipeline, reaction-handler count fix + DM, StarboardService.tryClaimFirstStarDm, backend config route accepts the new fields.

Tests

6 seed-handler tests (off/all-channels/starboard-exclusion/allow-list/bot-skip/error-path) + 4 reaction tests (seed-exclusion math, threshold with human stars, DM on claim, no-DM on already-claimed). 28 pass; typecheck clean.

Post-deploy: Criativaria config row gets seedReaction=true, firstStarDm=true + PT-BR DM text.

---

Summary by cubic

Adds opt‑in starboard seeding (bot auto‑reacts with the star emoji) and a one‑time first‑star DM to make the highlights channel easier to discover. The bot’s seed never counts toward thresholds, and DMs are sent exactly once per member per guild.

• New Features

  • Seeding: seedReaction (off by default) and seedChannelIds (empty = all; starboard channel always excluded). Implemented via starboardSeedHandler that never blocks the pipeline and logs failures (e.g., bad emoji/permissions).
  • Correct counts: reaction handler subtracts the bot’s own seed (reaction.me) so only human stars count.
  • First‑star DM: firstStarDm + firstStarDmMessage (optional per‑guild text). Exactly once via an atomic claim; DM send failures are ignored. Backend config route now accepts these fields.

• Migration

  • Schema: add seedReaction, seedChannelIds, firstStarDm, firstStarDmMessage to starboard_configs; create starboard_dm_sents with unique (guildId, userId).
  • Post‑deploy: enable per guild as needed (e.g., set seedReaction=true, firstStarDm=true, and supply DM copy).

^{Written for commit f5b1fc9. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Added optional starboard reaction seeding for new messages, with channel allowlisting support.
  • Added an optional one-time DM when a user stars a message for the first time, including a customizable message.

• Bug Fixes

  • Improved star count handling so the bot’s own seeded reaction no longer affects starboard thresholds.
  • Prevented seeding in the starboard channel itself and ensured message processing continues even if starboard lookups fail.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds starboard "seed reaction" and "first-star DM" features: Prisma schema/migration additions for new config fields and a DM-tracking table, a StarboardService method for claiming first-star DMs, backend validation updates, a new message handler seeding reactions, and reaction handler changes excluding seeded reactions from star counts while sending one-time DMs.

Changes

Starboard Seed Reaction and First-Star DM

Layer / File(s)	Summary
Data model: config fields and DM tracking table prisma/schema.prisma, prisma/migrations/20260703040000_starboard_seed_first_star_dm/migration.sql	Adds seedReaction, seedChannelIds, firstStarDm, firstStarDmMessage to StarboardConfig and a new StarboardDmSent model/table with unique (guildId, userId) constraint.
StarboardService type and claim method packages/shared/src/services/StarboardService.ts	Extends StarboardConfig/UpsertConfigData types with new fields and adds tryClaimFirstStarDm(guildId, userId) handling Prisma unique-constraint conflicts.
Backend config upsert validation packages/backend/src/routes/starboard.ts	Validates new optional fields in the PATCH starboard config request schema.
New starboardSeedHandler message handler and wiring packages/bot/src/handlers/message/starboardSeedHandler.ts, packages/bot/src/handlers/message/index.ts, packages/bot/src/handlers/messageHandler.ts, packages/bot/src/handlers/message/__tests__/starboardSeedHandler.test.ts	Adds a handler that reacts with the starboard emoji on eligible non-bot messages, registers it in the pipeline, and tests its config/allow-list/error-swallowing behavior.
handleStarboardReaction exclusion and first-star DM packages/bot/src/handlers/reactionHandler.ts, packages/bot/src/handlers/reactionHandler.spec.ts	Exports handleStarboardReaction, excludes bot seed reactions from star counts, adds first-star DM sending via tryClaimFirstStarDm, refactors fetch/error-log code, and adds corresponding tests.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• LucasSantana-Dev/Lucky#314: Both PRs modify starboard reaction handling in packages/bot/src/handlers/reactionHandler.ts, with this PR extending the earlier starboard posting logic.

Suggested labels: enhancement

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: starboard seeding and one-time first-star DMs.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/starboard-seed-first-star-dm

---

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

[github-actions]

Failed to generate code suggestions for PR

[github-actions]

	Warnings
⚠️	User-facing change without a CHANGELOG.md update. Add a line under ## [Unreleased] if this should appear in release notes. (Or apply the skip-changelog label if this PR does not affect end users.)

Generated by 🚫 dangerJS against f5b1fc9

[cubic-dev-ai]

1 issue found across 10 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

packages/shared/src/services/StarboardService.ts (1)

95-98: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

deleteConfig doesn't clean up starboard_dm_sents for the guild.

The new StarboardDmSent table stores per-user Discord IDs keyed by guildId with no relation to StarboardConfig and no other deletion path. When a guild removes its starboard config, these claim rows are orphaned and retained indefinitely.

🗑️ Suggested fix

     /** Deletes starboard configuration for a guild. */
     async deleteConfig(guildId: string): Promise<void> {
-        await prisma.starboardConfig.deleteMany({ where: { guildId } })
+        await prisma.$transaction([
+            prisma.starboardConfig.deleteMany({ where: { guildId } }),
+            prisma.starboardDmSent.deleteMany({ where: { guildId } }),
+        ])
     }

🤖 Prompt for 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.

In `@packages/shared/src/services/StarboardService.ts` around lines 95 - 98, The
`StarboardService.deleteConfig` cleanup only removes `starboardConfig` rows,
leaving `StarboardDmSent` records orphaned for the same guild. Update
`deleteConfig(guildId)` to also delete from the `starboardDmSent` table using
the same `guildId`, alongside the existing `prisma.starboardConfig.deleteMany`
call. Keep the cleanup in this service method so removing a guild’s starboard
config clears all guild-scoped starboard state.

🧹 Nitpick comments (4)

packages/shared/src/services/StarboardService.ts (1)

75-93: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Use Prisma.PrismaClientKnownRequestError here instead of casting the error.
That keeps the P2002 branch type-safe and matches the Prisma pattern used elsewhere in packages/shared.

🤖 Prompt for 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.

In `@packages/shared/src/services/StarboardService.ts` around lines 75 - 93, The
tryClaimFirstStarDm method in StarboardService is handling Prisma
unique-constraint errors by casting the caught error, which is not type-safe.
Update the catch block to use Prisma.PrismaClientKnownRequestError for the P2002
check, following the same Prisma error-handling pattern used elsewhere in
packages/shared, and keep the existing true/false behavior unchanged.

Source: Linters/SAST tools

packages/bot/src/handlers/message/__tests__/starboardSeedHandler.test.ts (1)

64-69: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a test for allow-list including the starboard channel.

Current tests don't verify that the starboard-channel exclusion wins even when seedChannelIds explicitly includes config.channelId. This is the key safety invariant preventing recursive seeding on highlight posts — worth locking in with a test.

✅ Suggested additional test

     it('never seeds the starboard channel itself', async () => {
         ;(starboardService.getConfig as jest.Mock).mockResolvedValue(baseConfig)
         const { message, react } = makeMessage('starboard-chan')
         await starboardSeedHandler.handle(message, context)
         expect(react).not.toHaveBeenCalled()
     })
+
+    it('never seeds the starboard channel even when it is in the allow-list', async () => {
+        ;(starboardService.getConfig as jest.Mock).mockResolvedValue({
+            ...baseConfig,
+            seedChannelIds: ['starboard-chan'],
+        })
+        const { message, react } = makeMessage('starboard-chan')
+        await starboardSeedHandler.handle(message, context)
+        expect(react).not.toHaveBeenCalled()
+    })

🤖 Prompt for 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.

In `@packages/bot/src/handlers/message/__tests__/starboardSeedHandler.test.ts`
around lines 64 - 69, Add a test in starboardSeedHandler.test.ts to verify that
the starboard channel is still excluded even when seedChannelIds explicitly
contains config.channelId. Use starboardSeedHandler.handle with a message
created by makeMessage for the starboard channel and a mocked
starboardService.getConfig returning a config whose seedChannelIds includes the
starboard channel, then assert react is not called. This should lock in the
exclusion behavior alongside the existing never seeds the starboard channel
itself case.

packages/bot/src/handlers/message/starboardSeedHandler.ts (1)

37-43: 🚀 Performance & Scalability | 🔵 Trivial

Consider rate-limit/backoff exposure from reacting on every message.

The handler reacts with config.emoji on every non-bot message in allow-listed (or all) channels with no throttling. In high-traffic channels this could burn through Discord's per-channel reaction rate limits quickly, and failures are silently swallowed via .catch(() => undefined), hiding systemic misconfiguration (e.g., missing Add Reactions permission).

🤖 Prompt for 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.

In `@packages/bot/src/handlers/message/starboardSeedHandler.ts` around lines 37 -
43, The starboard seeding flow in starboardSeedHandler’s message reaction path
currently adds config.emoji to every eligible message with no throttling and
hides all failures, which can trigger rate limits and mask permission/config
issues. Update the handler to gate reactions with a simple backoff or
per-channel throttle before calling message.react, and change the catch handling
so unexpected reaction failures are logged or surfaced with enough context
instead of being silently ignored.

packages/bot/src/handlers/reactionHandler.spec.ts (1)

468-568: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for the partial-message fetch path and self-star/DM interaction.

Two newly introduced branches in handleStarboardReaction aren't exercised here:

1. reaction.message.partial === true, requiring reaction.message.fetch() before the self-star guard.
2. Self-star with selfStar: false should return before tryClaimFirstStarDm is ever called (guard runs before the DM block).

Both are meaningful correctness fixes worth locking in with tests.

✅ Suggested additional tests

+        it('fetches a partial message before the self-star guard', async () => {
+            const { user, reaction, client } = starSetup({ count: 1, me: false })
+            const fetchedMsg = { ...reaction.message, author: { id: 'author-1' } }
+            ;(reaction.message as any).partial = true
+            ;(reaction.message as any).fetch = jest.fn().mockResolvedValue(fetchedMsg)
+            await handleStarboardReaction(reaction, user, client)
+            expect((reaction.message as any).fetch).toHaveBeenCalled()
+        })
+
+        it('does not claim the first-star DM on a disallowed self-star', async () => {
+            const { user, reaction, client } = starSetup({ count: 1, me: false })
+            ;(reaction.message as any).author.id = 'u1' // same as reactor
+            await handleStarboardReaction(reaction, user, client)
+            expect(starboardService.tryClaimFirstStarDm).not.toHaveBeenCalled()
+        })

🤖 Prompt for 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.

In `@packages/bot/src/handlers/reactionHandler.spec.ts` around lines 468 - 568,
Add tests in reactionHandler.spec.ts to cover the new branches in
handleStarboardReaction: one where reaction.message.partial is true and the
handler must call reaction.message.fetch() before continuing, and another where
the reacting user is the message author with selfStar disabled so the function
returns before any tryClaimFirstStarDm call. Use the existing
handleStarboardReaction helper setup and the reaction/message mocks to verify
fetch order and that the DM claim is never attempted in the self-star case.

🤖 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.

Outside diff comments:
In `@packages/shared/src/services/StarboardService.ts`:
- Around line 95-98: The `StarboardService.deleteConfig` cleanup only removes
`starboardConfig` rows, leaving `StarboardDmSent` records orphaned for the same
guild. Update `deleteConfig(guildId)` to also delete from the `starboardDmSent`
table using the same `guildId`, alongside the existing
`prisma.starboardConfig.deleteMany` call. Keep the cleanup in this service
method so removing a guild’s starboard config clears all guild-scoped starboard
state.

---

Nitpick comments:
In `@packages/bot/src/handlers/message/__tests__/starboardSeedHandler.test.ts`:
- Around line 64-69: Add a test in starboardSeedHandler.test.ts to verify that
the starboard channel is still excluded even when seedChannelIds explicitly
contains config.channelId. Use starboardSeedHandler.handle with a message
created by makeMessage for the starboard channel and a mocked
starboardService.getConfig returning a config whose seedChannelIds includes the
starboard channel, then assert react is not called. This should lock in the
exclusion behavior alongside the existing never seeds the starboard channel
itself case.

In `@packages/bot/src/handlers/message/starboardSeedHandler.ts`:
- Around line 37-43: The starboard seeding flow in starboardSeedHandler’s
message reaction path currently adds config.emoji to every eligible message with
no throttling and hides all failures, which can trigger rate limits and mask
permission/config issues. Update the handler to gate reactions with a simple
backoff or per-channel throttle before calling message.react, and change the
catch handling so unexpected reaction failures are logged or surfaced with
enough context instead of being silently ignored.

In `@packages/bot/src/handlers/reactionHandler.spec.ts`:
- Around line 468-568: Add tests in reactionHandler.spec.ts to cover the new
branches in handleStarboardReaction: one where reaction.message.partial is true
and the handler must call reaction.message.fetch() before continuing, and
another where the reacting user is the message author with selfStar disabled so
the function returns before any tryClaimFirstStarDm call. Use the existing
handleStarboardReaction helper setup and the reaction/message mocks to verify
fetch order and that the DM claim is never attempted in the self-star case.

In `@packages/shared/src/services/StarboardService.ts`:
- Around line 75-93: The tryClaimFirstStarDm method in StarboardService is
handling Prisma unique-constraint errors by casting the caught error, which is
not type-safe. Update the catch block to use
Prisma.PrismaClientKnownRequestError for the P2002 check, following the same
Prisma error-handling pattern used elsewhere in packages/shared, and keep the
existing true/false behavior unchanged.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 6aa8212f-abf8-44cb-8017-407fb6fd95db

📥 Commits

Reviewing files that changed from the base of the PR and between 9ce631b and 0b74fb9.

📒 Files selected for processing (10)

• packages/backend/src/routes/starboard.ts
• packages/bot/src/handlers/message/__tests__/starboardSeedHandler.test.ts
• packages/bot/src/handlers/message/index.ts
• packages/bot/src/handlers/message/starboardSeedHandler.ts
• packages/bot/src/handlers/messageHandler.ts
• packages/bot/src/handlers/reactionHandler.spec.ts
• packages/bot/src/handlers/reactionHandler.ts
• packages/shared/src/services/StarboardService.ts
• prisma/migrations/20260703040000_starboard_seed_first_star_dm/migration.sql
• prisma/schema.prisma

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

<sub>Requires human review: Database migration, new database table, schema changes, new core business logic for starboard seeding and DM notifications, and modifications to the reaction handler's count logic. High-impact changes requiring human review.

Re-trigger cubic</sub>

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
81.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud