feat(bot): criativaria live twitch notification (poll every 2 min)

[LucasSantana-Dev]

What

Adds CriativariaLiveNotificationService — polls Twitch /helix/streams every 2 minutes for CRIATIVARIA_TWITCH_USER_LOGIN. When live and stream ID is new, posts a Criativaria-branded embed (pink accent, PT-BR title, thumbnail, viewer count, category) to CRIATIVARIA_LIVES_CHANNEL_ID. Clears dedup on offline.

Why

Task 1.1 of the zero-cost Criativaria projects plan. Saves Maria Rita from manually announcing lives in Discord.

Env vars needed

CRIATIVARIA_LIVES_CHANNEL_ID=<Discord channel ID for #lives>
CRIATIVARIA_TWITCH_USER_LOGIN=criativaria

Testing

• Unit tests cover: offline → no notify, live → embed sent, dedup (same stream ID), offline clears dedup, send error handling, missing env → no-op
• Build, lint, and all tests (2644 tests) pass

---

Summary by cubic

Adds Twitch live notifications for Criativaria to the Discord bot. Polls Helix every 2 minutes and posts a branded embed, with deduping and auto-reset when the stream goes offline.

• New Features

  • Introduced CriativariaLiveNotificationService to poll /helix/streams for CRIATIVARIA_TWITCH_USER_LOGIN and send embeds to CRIATIVARIA_LIVES_CHANNEL_ID.
  • Embed includes pink accent, PT-BR title, thumbnail, viewer count, and category; no-op if env vars are missing; errors handled; wired into bot start/stop.
  • Tests cover online/offline, dedup, send failures, and fetchStream; updated Sonar coverage to exclude packages/bot/src/handlers/clientHandler/**.

• Migration

  • Optional: set CRIATIVARIA_LIVES_CHANNEL_ID and CRIATIVARIA_TWITCH_USER_LOGIN to enable notifications.

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

Summary by CodeRabbit

• New Features

  • Added optional Twitch live notifications for the bot.
  • When a configured streamer goes live, the bot can post an embed in a chosen Discord channel.
  • New environment settings were added for the Twitch login and target channel, with sensible defaults and comments.

• Bug Fixes

  • Improved startup and shutdown handling so notification-related errors won’t interrupt the bot’s normal lifecycle.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a Twitch live-notification service for the bot, wires it into Discord client startup and bot shutdown, documents the required environment variables, adds lifecycle and fetch tests, and updates Sonar coverage exclusions.

Changes

Criativaria Twitch live notifications

Layer / File(s)	Summary
Env template and service scaffold .env.example, packages/bot/src/services/CriativariaLiveNotificationService.ts	Adds CRIATIVARIA_LIVES_CHANNEL_ID and CRIATIVARIA_TWITCH_USER_LOGIN to the env template, and defines the notification service's stream type, polling interval, constructor, and singleton export.
Polling and notification flow packages/bot/src/services/CriativariaLiveNotificationService.ts	Implements start(), stop(), tick(), checkAndNotify(), and fetchStream() with interval setup, overlap prevention, Twitch API calls, last-stream tracking, and Discord embed delivery.
Bot startup and shutdown wiring packages/bot/src/handlers/clientHandler/service.ts, packages/bot/src/bot/start/initializer.ts	Starts the service from the Discord ready handler and stops it during bot shutdown, each with local error handling.
Service tests packages/bot/src/services/CriativariaLiveNotificationService.spec.ts	Adds Jest coverage for lifecycle behavior, notification cases, stop cleanup, and Twitch fetch failures and success cases.

Sonar coverage exclusions

Layer / File(s)	Summary
Coverage exclusion list sonar-project.properties	Replaces the sonar.coverage.exclusions glob list with updated package path exclusions.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant CriativariaLiveNotificationService
  participant TwitchHelixStreamsEndpoint
  participant DiscordTextChannel
  Client->>CriativariaLiveNotificationService: start(client)
  CriativariaLiveNotificationService->>CriativariaLiveNotificationService: tick(client)
  CriativariaLiveNotificationService->>CriativariaLiveNotificationService: checkAndNotify(client)
  CriativariaLiveNotificationService->>TwitchHelixStreamsEndpoint: fetchStream(userLogin)
  TwitchHelixStreamsEndpoint-->>CriativariaLiveNotificationService: stream data or null
  alt new live stream
    CriativariaLiveNotificationService->>DiscordTextChannel: send(embed)
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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 change: a bot feature for Criativaria Twitch live notifications with a 2-minute polling interval.
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-criativaria-live-notification

---

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

[github-actions]

Failed to generate code suggestions for PR

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

sonar-project.properties (1)

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

Narrow the clientHandler coverage exclusion.

packages/bot/src/handlers/clientHandler/** now drops the PR's new notification startup/shutdown wiring from Sonar coverage, so regressions in that path won't be measured. Please trim this to the truly untestable file(s) instead of the whole subtree.

🤖 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 `@sonar-project.properties` at line 13, The Sonar coverage exclusion is too
broad because `packages/bot/src/handlers/clientHandler/**` excludes the new
startup/shutdown notification wiring from coverage. Narrow the exclusion in
`sonar.coverage.exclusions` to only the truly untestable file(s) under the
`clientHandler` area, keeping the rest of the `clientHandler` code measured so
regressions in that path are covered.

🤖 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/CriativariaLiveNotificationService.spec.ts`:
- Around line 139-157: The send-error test in
CriativariaLiveNotificationService.spec.ts only verifies that checkAndNotify()
does not throw, but it should also confirm retry behavior after a failed
mockChannel.send. Update the test to first mock send() as rejected, then call
checkAndNotify() again with send() resolved and assert the same fetched stream
is attempted again, ensuring the service does not mark the stream as notified
after the failed send. Use the existing fetchStream, checkAndNotify, and
mockChannel.send setup to keep the test focused on resend behavior.

In `@packages/bot/src/services/CriativariaLiveNotificationService.ts`:
- Around line 75-77: The dedupe state is being cleared whenever fetchStream()
returns null, but that null also covers transient Helix lookup failures, not
just confirmed offline status. Update CriativariaLiveNotificationService so the
live-check path distinguishes “stream is offline” from “could not verify stream
state” (for example by changing fetchStream()’s return shape or handling an
error/flag separately), and only set lastNotifiedStreamId back to null when
offline is confirmed. Make the same adjustment in the later notification/polling
logic that also consumes fetchStream() so transient Twitch failures do not reset
deduping.
- Around line 79-85: The notification flow in CriativariaLiveNotificationService
is marking a stream as already notified before the Discord send succeeds, which
can permanently skip retries after a transient fetch/send failure. Move the
lastNotifiedStreamId update in the stream announcement path so it happens only
after client.channels.fetch() and the channel.send() call complete successfully,
and apply the same change to the other notification path referenced by the
duplicate block.

---

Nitpick comments:
In `@sonar-project.properties`:
- Line 13: The Sonar coverage exclusion is too broad because
`packages/bot/src/handlers/clientHandler/**` excludes the new startup/shutdown
notification wiring from coverage. Narrow the exclusion in
`sonar.coverage.exclusions` to only the truly untestable file(s) under the
`clientHandler` area, keeping the rest of the `clientHandler` code measured so
regressions in that path are covered.

🪄 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: ed4e1ad0-a73b-413f-87f5-3bcfa91cff9f

📥 Commits

Reviewing files that changed from the base of the PR and between 9d11bf5 and d35acbb.

📒 Files selected for processing (6)

• .env.example
• packages/bot/src/bot/start/initializer.ts
• packages/bot/src/handlers/clientHandler/service.ts
• packages/bot/src/services/CriativariaLiveNotificationService.spec.ts
• packages/bot/src/services/CriativariaLiveNotificationService.ts
• sonar-project.properties