feat(bot): add weekly community digest service

[LucasSantana-Dev]

Implements weekly digest feature that posts every Monday 12:00 UTC to the configured digest channel:

Features

• Top-reacted messages: Fetches top 3 messages from forum channel (last 7 days), sorted by reaction count
• Member count delta: Tracks week-over-week community growth via WeeklyDigestSnapshot model
• Upcoming events: Lists guild scheduled events in the next 7 days
• Automatic scheduling: Uses hourly tick pattern to check for Monday 12:00 UTC window

Setup

• Add Prisma model: WeeklyDigestSnapshot for member count tracking
• Create migration: Adds weekly_digest_snapshots table
• Create service: WeeklyDigestService with interval-based scheduling
• Register in initializer: Service started on bot ready, stopped on shutdown

Configuration

The service is enabled via environment variables:

• DIGEST_CHANNEL_ID — where digests are posted
• FORUM_CHANNEL_ID — where top messages are fetched from

If either is unset, the service remains idle.

Error Handling

All digest operations wrapped in try/catch. Failures are logged but non-fatal.
Single-flight mechanism prevents duplicate sends within 30 minutes.

Summary by CodeRabbit

• New Features
  • Added a weekly digest that posts to configured channels with member/community stats, top posts, and upcoming events.
  • The digest avoids duplicate sends by tracking a weekly snapshot of guild member counts.
• Bug Fixes
  • Improved bot startup/shutdown so the weekly digest service starts and stops reliably.
  • Enhanced shutdown resilience so teardown continues even if the weekly digest stop encounters an error.
• Tests
  • Added comprehensive coverage for weekly digest scheduling, sending, cooldown behavior, and shutdown cleanup.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 7ff592a1-6ce1-49e9-b425-2964ef316897

📥 Commits

Reviewing files that changed from the base of the PR and between d51d062 and 774066e.

📒 Files selected for processing (2)

• packages/bot/src/services/WeeklyDigestService.spec.ts
• packages/bot/src/services/WeeklyDigestService.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/bot/src/services/WeeklyDigestService.spec.ts
• packages/bot/src/services/WeeklyDigestService.ts

---

📝 Walkthrough

Walkthrough

Adds weekly digest persistence, scheduling, delivery logic, and bot lifecycle wiring, with tests updated for startup and shutdown coverage.

Changes

Weekly Digest Service

Layer / File(s)	Summary
Snapshot model prisma/schema.prisma, prisma/migrations/20260625100000_add_weekly_digest_snapshot/migration.sql	Adds the WeeklyDigestSnapshot Prisma model and matching table/index migration.
Service scaffold packages/bot/src/services/WeeklyDigestService.ts, tsconfig.json	Introduces weekly digest service helpers, env parsing, singleton export, and removes the tsconfig file globs.
Scheduler lifecycle packages/bot/src/services/WeeklyDigestService.ts	Defines WeeklyDigestService timing, concurrency, and tick scheduling behavior.
Digest assembly packages/bot/src/services/WeeklyDigestService.ts	Resolves channels, reads and writes weekly digest snapshots, gathers forum messages and upcoming events, and builds and sends the digest embed.
Service tests packages/bot/src/services/WeeklyDigestService.spec.ts	Adds lifecycle, timing, delivery, and error-handling coverage for WeeklyDigestService.
Initializer wiring packages/bot/src/bot/start/initializer.ts, packages/bot/src/bot/start/initializer.spec.ts	Starts and stops weeklyDigestService in BotInitializer and updates shutdown coverage for the new teardown path.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WeeklyDigestService
  participant DiscordClient
  participant Prisma
  participant DiscordChannel

  WeeklyDigestService->>DiscordClient: start(client)
  WeeklyDigestService->>WeeklyDigestService: tick()
  WeeklyDigestService->>Prisma: read and create weeklyDigestSnapshot rows
  WeeklyDigestService->>DiscordChannel: send digest embed

Loading

Possibly related PRs

• LucasSantana-Dev/Lucky#676: Both PRs modify the bot shutdown path in packages/bot/src/bot/start/initializer.ts.
• LucasSantana-Dev/Lucky#1608: Both PRs add orderly service teardown during BotInitializer shutdown.
• LucasSantana-Dev/Lucky#1613: Both PRs extend BotInitializer lifecycle teardown with an additional service stop step.

Suggested labels: enhancement

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main addition: a weekly community digest service for the bot.
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.

✨ 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/bot-weekly-digest

---

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

[github-actions]

Failed to generate code suggestions for PR

[coderabbitai]

Actionable comments posted: 5

🤖 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 `@packages/bot/src/services/WeeklyDigestService.ts`:
- Around line 144-147: Make WeeklyDigestService digest delivery idempotent
across restarts by not relying on lastDigestTime alone for deduping. Before
sending, check the current digest window in weeklyDigestSnapshot and skip if
that window was already processed; then only persist/update the snapshot after
digestChannel.send succeeds so a failed send does not advance the baseline. If
multiple bot instances can run, include a unique week key in the snapshot state
and use it in the send/check flow to prevent duplicate delivery.
- Around line 233-234: The weekly growth calculation in WeeklyDigestService is
treating the first snapshot as growth by default because previousMemberCount
falls back to 0. Update the logic around previousSnapshot, previousMemberCount,
and memberDelta so that when no prior snapshot exists the digest uses no weekly
delta instead of reporting all members as growth. Keep the delta calculation
only for cases where a previous snapshot is available.
- Around line 16-18: The tick interval parsing in WeeklyDigestService should
reject partially parsed or overflowing values instead of silently accepting
them. Update the env parsing used for the tick delay so parsePositiveIntEnv only
accepts fully numeric input, and in the scheduling path that uses
DEFAULT_TICK_INTERVAL_MS/MS_PER_DAY/MS_PER_WEEK, cap the final delay to Node’s
timer range rather than letting large values clamp to 1ms. Focus the fix around
the interval parsing and timer setup in WeeklyDigestService.
- Around line 206-238: The weekly digest message collection in
WeeklyDigestService.getTopReactedMessages currently treats forum channels like
TextChannel and does not enforce the 7-day window. Update the fetch logic to
branch on forum vs text channels, using forumChannel.threads and
ThreadChannel.fetchStarterMessage() for GuildForum posts, and apply a
createdTimestamp cutoff based on this.clock() minus MS_PER_WEEK so only recent
messages are ranked.

In `@prisma/schema.prisma`:
- Around line 1186-1193: Add a week-scoped idempotency key to
WeeklyDigestSnapshot so WeeklyDigestService cannot create duplicate snapshots
for the same guild/week. Update the WeeklyDigestSnapshot model to include a
normalized week field such as weekStart and enforce uniqueness with a composite
constraint on guildId and weekStart, then adjust WeeklyDigestService to write
through upsert instead of a blind create after reading the latest snapshot.

🪄 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: CHILL

Plan: Pro

Run ID: 6e861e14-b072-4864-8440-609497cc22ed

📥 Commits

Reviewing files that changed from the base of the PR and between 2807cad and 8770ebd.

📒 Files selected for processing (6)

• packages/bot/src/bot/start/initializer.spec.ts
• packages/bot/src/bot/start/initializer.ts
• packages/bot/src/services/WeeklyDigestService.ts
• prisma/migrations/20260625100000_add_weekly_digest_snapshot/migration.sql
• prisma/schema.prisma
• tsconfig.json

💤 Files with no reviewable changes (1)

• tsconfig.json

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@packages/bot/src/services/WeeklyDigestService.spec.ts`:
- Around line 314-337: The weekly digest snapshot test currently only checks
that WeeklyDigestSnapshot.create is called, so it does not verify the member
delta behavior. Update the test around WeeklyDigestService.tick and the mocked
digestChannel output to assert on the actual rendered embed or sent payload, and
confirm the week-over-week delta reflects the previous snapshot from
weeklyDigestSnapshot.findFirst instead of defaulting to +0.
- Around line 181-239: The timing-guard tests in WeeklyDigestService.tick only
assert that weeklyDigestSnapshot.create is skipped, but they should also verify
no Discord API calls happen on early return. Update the guard-path specs in
WeeklyDigestService.spec.ts to assert the channel fetch/send mocks on the Client
stub are not called when tick exits early, especially around the tickInProgress
and lastDigestTime branches, so regressions in Discord access are caught.
- Around line 361-423: The digest embed tests only verify that
digestChannel.send is called, so they do not confirm the reacted message or
scheduled event actually appear in the payload. Update the tests in
WeeklyDigestService.spec.ts to inspect the argument passed to
digestChannel.send, and assert the embed content/fields includes the data
derived from msg-1 in the top-reacted-message case and evt-1 in the
upcoming-event case. Use the existing makeSvc, tick, and digestChannel.send
mocks to locate the sent embed payload and validate its rendered text or fields
directly.

🪄 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: CHILL

Plan: Pro

Run ID: 86dc8641-aa33-4a81-a5e8-ac1b8abe3035

📥 Commits

Reviewing files that changed from the base of the PR and between 8770ebd and 69a9bcc.

📒 Files selected for processing (1)

• packages/bot/src/services/WeeklyDigestService.spec.ts

[coderabbitai]

Caution

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

⚠️ Outside diff range comments (1)

packages/bot/src/services/WeeklyDigestService.ts (1)

382-386: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Escape the message label before building the markdown link. msg.content is community-controlled and can break [label](url) rendering with ]( sequences, making the digest misleading. escapeMarkdown comes from @discordjs/formatters, not discord.js, so use that helper here (and add the dependency if needed).

🤖 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/services/WeeklyDigestService.ts` around lines 382 - 386, The
markdown link label built in WeeklyDigestService’s topMessagesList is using raw
community-controlled msg.content, which can break the [label](url) format.
Update this mapping to escape the label text before composing the link, using
escapeMarkdown from `@discordjs/formatters` rather than discord.js, and ensure the
helper is imported/added wherever WeeklyDigestService is defined.

🧹 Nitpick comments (1)

packages/bot/src/services/WeeklyDigestService.ts (1)

105-124: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Route scheduler skip logs through the logger.

These console.log calls will emit every non-due tick in production. Use debugLog or remove them to keep scheduler noise consistent with the rest of the service.

Proposed cleanup

         if (this.tickInProgress || !this.client) {
-            console.log('Tick early return', {
-                tickInProgress: this.tickInProgress,
-                client: !!this.client,
-            })
+            debugLog({
+                message: 'Weekly digest tick skipped',
+                data: {
+                    tickInProgress: this.tickInProgress,
+                    hasClient: !!this.client,
+                },
+            })
             return
         }
...
             if (dayOfWeek !== 1 || hour !== 12) {
-                console.log('Not Monday 12 UTC', { dayOfWeek, hour })
+                debugLog({
+                    message: 'Weekly digest not due',
+                    data: { dayOfWeek, hour },
+                })
                 return
             } // Not Monday 12:xx UTC

🤖 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/services/WeeklyDigestService.ts` around lines 105 - 124, The
scheduler in WeeklyDigestService is using console.log for normal early-return
paths, which creates noisy production output. Replace the Tick early return and
Not Monday 12 UTC console.log calls in the tick logic with debugLog, or remove
them if they are not needed, so logging stays consistent with the rest of the
service and only goes through the existing logger path.

🤖 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/bot/src/services/WeeklyDigestService.ts`:
- Around line 382-386: The markdown link label built in WeeklyDigestService’s
topMessagesList is using raw community-controlled msg.content, which can break
the [label](url) format. Update this mapping to escape the label text before
composing the link, using escapeMarkdown from `@discordjs/formatters` rather than
discord.js, and ensure the helper is imported/added wherever WeeklyDigestService
is defined.

---

Nitpick comments:
In `@packages/bot/src/services/WeeklyDigestService.ts`:
- Around line 105-124: The scheduler in WeeklyDigestService is using console.log
for normal early-return paths, which creates noisy production output. Replace
the Tick early return and Not Monday 12 UTC console.log calls in the tick logic
with debugLog, or remove them if they are not needed, so logging stays
consistent with the rest of the service and only goes through the existing
logger path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 19ea1b65-bc2a-4802-ba71-3d79766fb1fa

📥 Commits

Reviewing files that changed from the base of the PR and between 69a9bcc and d51d062.

📒 Files selected for processing (2)

• packages/bot/src/services/WeeklyDigestService.spec.ts
• packages/bot/src/services/WeeklyDigestService.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/bot/src/services/WeeklyDigestService.spec.ts

[LucasSantana-Dev]

Code review

Found 4 issues:

1. getTopReactedMessages() throws on the intended channel type: the config check accepts ChannelType.GuildForum, but the channel is then treated as a TextChannel and .messages.fetch() is called on it — forum channels have .threads, not .messages, so a configured forum channel (env is CRIATIVARIA_FORUM_CHANNEL_ID; PR description says forum) fails at runtime and top-reacted messages never work. Branch on channel type and iterate threads (e.g. fetchActive() + starter/thread messages) for forums.

Lucky/packages/bot/src/services/WeeklyDigestService.ts

Lines 279 to 286 in d51d062

	private async getTopReactedMessages(
	forumChannel: TextChannel,
	): Promise<ReactionCount[]> {
	try {
	// Fetch last 100 messages from forum
	const messages = await forumChannel.messages.fetch({ limit: 100 })
	const oneWeekAgo = this.clock() - MS_PER_WEEK

2. Snapshot persisted before the digest send: prisma.weeklyDigestSnapshot.create() runs before digestChannel.send(), and the catch path doesn't undo it — a failed send (rate limit, permissions, network) advances the weekly baseline, the idempotency check suppresses retry, and that week's digest is silently lost. Persist (or update) the snapshot only after the send succeeds. Same ordering issue was raised on feat(bot): add RSS bridge service for Criativaria guides #1608 and feat(bot): criativaria live twitch notification (poll every 2 min) #1613.

Lucky/packages/bot/src/services/WeeklyDigestService.ts

Lines 253 to 263 in d51d062

	// Save snapshot
	await prisma.weeklyDigestSnapshot.create({
	data: {
	guildId,
	memberCount: currentMemberCount,
	postedAt: new Date(this.clock()),
	},
	})
	// Send embed
	await digestChannel.send({ embeds: [embed] })

3. Leftover debug console.log statements bypass the shared logger: console.log('Tick early return', ...) and console.log('Not Monday 12 UTC', ...) fire every hourly tick in prod stdout, outside the debugLog/infoLog pipeline this same file already uses everywhere else.

Lucky/packages/bot/src/services/WeeklyDigestService.ts

Lines 105 to 124 in d51d062

	if (this.tickInProgress || !this.client) {
	console.log('Tick early return', {
	tickInProgress: this.tickInProgress,
	client: !!this.client,
	})
	return
	}
	this.tickInProgress = true
	try {
	const now = this.clock()
	const utcDate = new Date(now)
	// Only send on Mondays between 12:00 and 12:59 UTC
	const dayOfWeek = utcDate.getUTCDay()
	const hour = utcDate.getUTCHours()
	if (dayOfWeek !== 1 || hour !== 12) {
	console.log('Not Monday 12 UTC', { dayOfWeek, hour })
	return

4. Tick-interval env parsing accepts partial numerics: Number.parseInt(raw, 10) turns "1h" into 1 (a 1 ms tick — hot loop) and the finite/positive guards don't catch it. The shared parseIntEnv helper in packages/shared/src/utils/env.ts already does full-string validation (/^[+-]?\d+$/) — use it instead of the local reimplementation.

Lucky/packages/bot/src/services/WeeklyDigestService.ts

Lines 38 to 40 in d51d062

	if (raw === undefined) return fallback
	const parsed = Number.parseInt(raw, 10)
	if (!Number.isFinite(parsed) || parsed <= 0) {

Checked for bugs, CLAUDE.md compliance, git-history regressions, prior-PR feedback, and in-code guidance. Notable near-misses (verified, below report threshold): WeeklyDigestSnapshot has no week-scoped unique key (check-then-create race is restart-window-only for a single-instance bot), and the new criativariaLiveNotificationService mock isn't exercised in the initializer spec's failingStops matrix.

[LucasSantana-Dev]

Review findings addressed in d10485a:

1. GuildForum support — getTopReactedMessages now branches on ChannelType.GuildForum and collects active-thread starter messages via threads.fetchActive() + fetchStarterMessage(); text channels keep the last-100 fetch. Regression test added.
2. Send-before-persist — weeklyDigestSnapshot.create() moved after digestChannel.send(); failed send no longer advances the weekly baseline. Test now asserts create is NOT called when send throws.
3. console.log leftovers — both replaced with debugLog (structured pipeline).
4. Env parsing — local parsePositiveIntEnv deleted; uses shared parseIntEnv (full-string validation, { min: 1 }). Added "1h" rejection test.

Bonus fix found while running the suite: uses previous snapshot for member delta was a time-bomb — postedAt: new Date() (real wall clock) drifted out of the mocked week (clock pinned to 2026-06-22), tripping the idempotency skip; it fails on clean HEAD today. Now anchored to the mocked clock minus 7 days.

Suite: 65/65 passing (26 digest + 39 initializer).

[github-actions]

Preparing review...

[cubic-dev-ai]

7 issues found across 7 files

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

Re-trigger cubic</sub>

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud