feat: guild integrations pack

[LucasSantana-Dev]

Summary

Implemented 3 generalized guild integration features to replace hardcoded per-guild hacks:

• Twitch role mentions: Optional role ID on TwitchNotification; mentions role on both eventsub and polling paths
• Scheduled event announcements: New listener posts guild scheduled events to configured channel with optional role mention
• Per-guild RSS subscriptions: Refactored RssBridgeService from single env-configured feed to multi-subscription model with per-subscription role mentions and GUID-based dedup

Schema Changes

Single migration guild_integrations_pack:

• Add mentionRoleId String? to TwitchNotification
• Create ScheduledEventNotification table (guildId unique, enabled by default)
• Create RssFeedSubscription table (guildId+feedUrl unique, lastItemGuid tracking, role mention optional)

Backward Compatibility

RssBridgeService auto-seeds Criativaria subscription from env if not exists:

• Reads CRIATIVARIA_GUILD_ID, CRIATIVARIA_GUIDES_CHANNEL_ID, CRIATIVARIA_GUIDES_FEED_URL (optional, defaults to criativaria.com.br/rss.xml)
• Creates row only once (idempotent on startup)

Test Coverage

Added tests for:

• Twitch eventsub role mention (with/without mentionRoleId)
• ScheduledEventNotificationService (enabled/disabled, with/without mention, missing config)
• RssBridgeService per-guild behavior (role mention, backward compat seeding)

Files: prisma/schema.prisma, migration, RssBridgeService, CriativariaLiveNotificationService, eventsubSubscriptions, ScheduledEventNotificationService + tests

---

Summary by cubic

Adds a guild integrations pack: role-mentionable Twitch alerts, scheduled event announcements, and per-guild RSS subscriptions. Improves reliability with per-guild RSS dedup keys (legacy-safe), a correct lastItemGuid cursor, channel guild checks, and no interval stacking.

• New Features

  • Twitch alerts can mention a role via mentionRoleId on TwitchNotification (EventSub and polling; uses allowedMentions).
  • Scheduled event announcements post new guild events to a configured channel with optional role mention; listener added in eventHandler; rejects channels from other guilds.
  • Per-guild RSS subscriptions with per-item dedup via RssDiscoveredGuide scoped by guildId:slug (with raw-slug fallback), a lastItemGuid fast-path anchored to the newest item each poll, better GUID handling and link fallback; optional role mentions; replaces the single env-based feed; auto-seeds one subscription from env for backward compatibility.

• Migration

  • Run migration 20260702012040_guild_integrations_pack.
  • Add a ScheduledEventNotification row per guild to enable event posts.
  • Add RssFeedSubscription rows per guild/feed to start RSS posting.
  • Optional backward-compat seeding: set CRIATIVARIA_GUILD_ID, CRIATIVARIA_GUIDES_CHANNEL_ID, CRIATIVARIA_GUIDES_FEED_URL to auto-create one subscription.

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

Summary by CodeRabbit

• New Features
  • Added Discord scheduled event announcements with rich embeds and optional role mentions.
  • Added optional role mentions for RSS and Twitch notifications when messages are sent.
  • Upgraded RSS support to per-guild subscriptions, each with its own feed, channel, enablement, and optional mention role.
• Bug Fixes
  • Improved RSS deduplication and item handling to better prevent repeated or skipped posts.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds optional Discord role-mention support to Twitch, Criativaria, RSS, and a new scheduled-event notification pipeline. It introduces ScheduledEventNotificationService with a wired-in event handler, refactors RssBridgeService from a single hardcoded feed to a per-guild subscription model, and updates the Prisma schema and migration accordingly.

Changes

Guild integrations pack

Layer / File(s)	Summary
Prisma schema and migration prisma/schema.prisma, prisma/migrations/20260702012040_guild_integrations_pack/migration.sql	Adds mentionRoleId to TwitchNotification, and new ScheduledEventNotification/RssFeedSubscription models and tables with uniqueness, timestamps, and cascading guild foreign keys.
Twitch and Criativaria role mentions packages/bot/src/twitch/eventsubSubscriptions.ts, packages/bot/src/twitch/eventsubSubscriptions.spec.ts, packages/bot/src/services/CriativariaLiveNotificationService.ts	Notification sends now optionally include role mentions and restricted allowedMentions when a mention role is configured.
Scheduled event notifications packages/bot/src/services/ScheduledEventNotificationService.ts, packages/bot/src/services/ScheduledEventNotificationService.spec.ts, packages/bot/src/handlers/eventHandler.ts	Adds a scheduled-event notification service, tests for enabled/disabled/missing config and mention behavior, and runtime wiring for GuildScheduledEventCreate.
RSS subscription polling packages/bot/src/services/RssBridgeService.ts, packages/bot/src/services/RssBridgeService.spec.ts	Replaces single-feed polling with per-guild subscriptions, adds backward-compatible seeding, item identity/dedup handling, optional role mentions, and lastItemGuid updates with expanded tests.

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

Possibly related PRs

• LucasSantana-Dev/Lucky#1608: Both touch RssBridgeService.ts; this PR builds on the earlier RSS bridge flow with a subscription-driven model.
• LucasSantana-Dev/Lucky#1613: Both touch the Criativaria live-notification path, and this PR adds role-mention handling to that service.

Suggested labels: backend, enhancement

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and broadly matches the PR’s main theme of adding guild integration features.
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.

✨ 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/guild-integrations-pack

---

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

[github-actions]

Failed to generate code suggestions for PR

[coderabbitai]

Actionable comments posted: 5

🧹 Nitpick comments (1)

packages/bot/src/twitch/eventsubSubscriptions.ts (1)

248-257: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider extracting a shared "role mention" helper.

This content/allowedMentions construction pattern is duplicated verbatim in CriativariaLiveNotificationService.ts (and, per the PR stack outline, likely repeated again in the scheduled-event and RSS services). A small shared helper (e.g., buildRoleMentionPayload(roleId?: string | null)) would reduce duplication across the guild-integrations pack.

♻️ Example helper

export function buildRoleMentionPayload(roleId?: string | null) {
    return {
        content: roleId ? `<@&${roleId}>` : undefined,
        allowedMentions: roleId ? { roles: [roleId] } : undefined,
    }
}

🤖 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/twitch/eventsubSubscriptions.ts` around lines 248 - 257, The
role mention payload is duplicated in this send path, so extract it into a
shared helper and reuse it here instead of building content and allowedMentions
inline. Add a utility like buildRoleMentionPayload(roleId?: string | null) in
the shared guild-integrations area, then update this channel.send call in
eventsubSubscriptions to spread the helper result alongside the embed. Also
apply the same helper in CriativariaLiveNotificationService and the other
repeated notification flows from the stack.

🤖 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/handlers/eventHandler.ts`:
- Around line 394-407: Replace the runtime require in
handleGuildScheduledEventCreate with an ESM-compatible import pattern, since
packages/bot runs as a module and
require('../services/ScheduledEventNotificationService') will fail when the
listener fires. Update the code in eventHandler.ts to use the existing import or
await import() approach to access ScheduledEventNotificationService, then keep
calling scheduledEventNotificationService.notifyScheduledEvent(event, client)
from the handler.

In `@packages/bot/src/services/RssBridgeService.spec.ts`:
- Around line 422-424: The Prisma override for RssBridgeService is being applied
too late, so startRssBridgeService may still use the previously loaded mock
instead of mockDb. Update the RssBridgeService.spec setup by hoisting the
`@lucky/shared/utils/database/prismaClient` mock before the RssBridgeService
import, or reload the service inside jest.isolateModulesAsync so the service
picks up the intended Prisma mock.

In `@packages/bot/src/services/RssBridgeService.ts`:
- Around line 159-181: In RssBridgeService’s item-processing flow, lastItemGuid
is only updated when it is initially falsy, so subscriptions with an existing
marker never advance after posting new items. Update the logic around the feed
iteration and the state writeback so the latest posted item’s GUID is always
persisted after processing new items, regardless of whether
subscription.lastItemGuid was already set. Use the RssBridgeService loop and the
post-processing state update section to ensure the saved marker reflects the
newest successfully handled item.
- Around line 27-34: The startRssBridgeService polling setup can overwrite an
existing pollInterval, leaving the previous interval running and making
stopRssBridgeService() clear only the newest handle. Update
startRssBridgeService in RssBridgeService so it checks pollInterval before
creating a new setInterval, and either returns early or clears the existing
interval first; keep pollInterval as the single active handle used by
stopRssBridgeService().
- Around line 51-52: The shared Prisma client is missing the RssFeedSubscription
model, so getPrismaClient() still does not expose a typed rssFeedSubscription
delegate used by ensureBackwardCompatibleSubscription in RssBridgeService.
Regenerate the Prisma client under the shared generated Prisma output so the
schema includes RssFeedSubscription and the typed delegate becomes available
everywhere that imports getPrismaClient().

---

Nitpick comments:
In `@packages/bot/src/twitch/eventsubSubscriptions.ts`:
- Around line 248-257: The role mention payload is duplicated in this send path,
so extract it into a shared helper and reuse it here instead of building content
and allowedMentions inline. Add a utility like buildRoleMentionPayload(roleId?:
string | null) in the shared guild-integrations area, then update this
channel.send call in eventsubSubscriptions to spread the helper result alongside
the embed. Also apply the same helper in CriativariaLiveNotificationService and
the other repeated notification flows from the stack.

🪄 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: 3ef0f6eb-d615-49e7-aad1-4a8a76c12ee6

📥 Commits

Reviewing files that changed from the base of the PR and between 862426a and 0112f6c.

📒 Files selected for processing (10)

• packages/bot/src/handlers/eventHandler.ts
• packages/bot/src/services/CriativariaLiveNotificationService.ts
• packages/bot/src/services/RssBridgeService.spec.ts
• packages/bot/src/services/RssBridgeService.ts
• packages/bot/src/services/ScheduledEventNotificationService.spec.ts
• packages/bot/src/services/ScheduledEventNotificationService.ts
• packages/bot/src/twitch/eventsubSubscriptions.spec.ts
• packages/bot/src/twitch/eventsubSubscriptions.ts
• prisma/migrations/20260702012040_guild_integrations_pack/migration.sql
• prisma/schema.prisma

[LucasSantana-Dev]

Orchestrator verification + repair (agent could not run tests — npm ci failed in its env; honest report, gates re-run here): initial state was 18/64 failing + 5 TS errors + 1 suite unable to load. Fixed: (1) restored RssDiscoveredGuide per-item dedup the refactor dropped (#1608 record other consumers read; lastItemGuid kept as fast-path); (2) TwitchNotificationRow Pick missing mentionRoleId; (3) sched service channel send type guard; (4) two jest.mock hoisting bugs (factory referencing consts pre-init); (5) spec prisma mock lacked rssFeedSubscription entirely — legacy suite updated to the DB-backed contract; (6) unparseable-link behavior documented via test (raw link becomes dedup key). Verified: 68/68 across 4 suites, bot+shared typecheck clean, initializer/eventHandler neighbors 71/71.

[cubic-dev-ai]

8 issues found and verified against the latest diff

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

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 5 files (changes from recent commits).

<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/bot/src/services/ScheduledEventNotificationService.ts (1)

15-28: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Regenerate the Prisma client for ScheduledEventNotification The checked-in client in packages/shared/src/generated/prisma/client.ts doesn’t include ScheduledEventNotification, so db.scheduledEventNotification.findUnique(...) stays untyped here. Regenerate and commit the client so CI/lint sees the new model.

🤖 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/ScheduledEventNotificationService.ts` around lines
15 - 28, Regenerate and commit the Prisma client so ScheduledEventNotification
is included in the shared generated types, because
ScheduledEventNotificationService currently relies on
db.scheduledEventNotification.findUnique and the checked-in client in the
generated prisma client does not expose that model. Update the generated Prisma
output used by packages/shared/src/generated/prisma/client.ts, then verify the
db.scheduledEventNotification access in ScheduledEventNotificationService is
fully typed and accepted by CI/lint.

Source: Linters/SAST tools

🧹 Nitpick comments (1)

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

120-130: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider deriving the subscription param type from the Prisma model instead of a hand-written literal.

This inline shape duplicates RssFeedSubscription; this PR already had to patch a similar hand-maintained Pick (TwitchNotificationRow) that drifted from the schema. Using the generated model type (or a Pick<> from it) avoids re-hitting that class of bug here.

🤖 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/RssBridgeService.ts` around lines 120 - 130, The
subscription parameter type in RssBridgeService is manually duplicating the
Prisma subscription shape, which risks drifting from the schema. Replace the
inline object literal with a type derived from the generated Prisma model for
RssFeedSubscription, or use a Pick<> based on that model, and update the
affected method signature in RssBridgeService so the type stays aligned
automatically.

🤖 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/ScheduledEventNotificationService.ts`:
- Around line 15-28: Regenerate and commit the Prisma client so
ScheduledEventNotification is included in the shared generated types, because
ScheduledEventNotificationService currently relies on
db.scheduledEventNotification.findUnique and the checked-in client in the
generated prisma client does not expose that model. Update the generated Prisma
output used by packages/shared/src/generated/prisma/client.ts, then verify the
db.scheduledEventNotification access in ScheduledEventNotificationService is
fully typed and accepted by CI/lint.

---

Nitpick comments:
In `@packages/bot/src/services/RssBridgeService.ts`:
- Around line 120-130: The subscription parameter type in RssBridgeService is
manually duplicating the Prisma subscription shape, which risks drifting from
the schema. Replace the inline object literal with a type derived from the
generated Prisma model for RssFeedSubscription, or use a Pick<> based on that
model, and update the affected method signature in RssBridgeService so the type
stays aligned automatically.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: d3e5f165-3cba-4cb6-b582-f40167947669

📥 Commits

Reviewing files that changed from the base of the PR and between 0112f6c and 29f5cdf.

📒 Files selected for processing (5)

• packages/bot/src/services/RssBridgeService.spec.ts
• packages/bot/src/services/RssBridgeService.ts
• packages/bot/src/services/ScheduledEventNotificationService.spec.ts
• packages/bot/src/services/ScheduledEventNotificationService.ts
• packages/shared/src/services/TwitchNotificationService/index.ts

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

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

[github-actions]

	Warnings
⚠️	Big PR — 829 lines changed across 11 files. Consider splitting into smaller, reviewable chunks.

Generated by 🚫 dangerJS against d585cce

[cubic-dev-ai]

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

<sub>Requires human review: Auto-approval blocked by 9 unresolved issues from previous reviews.

Re-trigger cubic</sub>

[LucasSantana-Dev]

Review-thread disposition (latest commit): Fixed — per-guild dedup scoping w/ legacy raw-slug fallback (cubic P1 cross-guild suppression); lastItemGuid cursor anchors to newest seen item per poll (CodeRabbit Major stale-cursor + cubic P2 full-rescan); scheduled-event channel must belong to the event's guild (cubic P1); no interval stacking on repeated start (CodeRabbit Minor + cubic P2 dup). Already fixed earlier — eventHandler require() → static import (cubic P2). Acknowledged, not changed — CRIATIVARIA_LIVE_MENTION_ROLE_ID env validation + role-existence check (mention of a stale role renders as plain text, harmless; validation deferred until the service folds into TwitchNotification rows); RssFeedSubscription FK/migration note (matches existing migration conventions); schema P2 (indexes follow repo pattern). 68/68 tests + typecheck clean after fixes.

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud