feat(notifications): adds a NEW_EPISODE notification for Jellyfin

[parkuman]

This feature adds a new NEW_EPISODE notification type and a trigger specifically built for Jellyfin. It fires during the "recently added" scan of Jellyfin when Jellyfin returns an episode in the newly added array.

• it will only fire notifications for seasons in the partiall available status that have new episodes
• it only detects new episodes that Jellyfin returns as new episodes

re #480

Description

• updates the MediaSubscriber.ts class to trigger this new notification type before an update the the Media entity
• adds the new notification setting in the

Screenshot (if UI-related)

discord example:

example log for the first fire (in dev mode):

2025-04-14T20:10:04.541Z [info][Jellyfin Sync]: Beginning to process recently added for library: TV Shows
2025-04-14T20:10:04.753Z [info][Jellyfin Sync]: New standard episode detected for The Last of Us S2E1
2025-04-14T20:10:04.756Z [debug][Notifications]: Checking for new episodes {"mediaId":47,"is4k":false}
2025-04-14T20:10:04.756Z [debug][Notifications]: Partially available seasons {"mediaId":47,"is4k":false,"partiallyAvailableSeasons":[2]}
2025-04-14T20:10:04.756Z [debug][Notifications]: Detected lastSeasonChange update {"mediaId":47,"is4k":false,"oldTimestamp":"2025-04-14T20:00:04.719Z","newTimestamp":"2025-04-14T20:10:04.753Z"}
2025-04-14T20:10:04.764Z [debug][Notifications]: Found requests for media {"mediaId":47,"is4k":false,"requestCount":1,"requestIds":[3]}
2025-04-14T20:10:04.798Z [debug][Notifications]: Checking request for matching seasons {"mediaId":47,"is4k":false,"requestId":3,"requestedSeasons":[1,2],"partiallyAvailableSeasons":[2],"matchFound":true}
2025-04-14T20:10:04.798Z [info][Notifications]: Sending new episode notification {"mediaId":47,"is4k":false,"requestId":3,"userId":1,"seasons":[2]}
2025-04-14T20:10:04.798Z [info][Notifications]: Sending notification(s) for EPISODE_AVAILABLE {"subject":"The Last of Us (2023)"}
2025-04-14T20:10:04.798Z [debug][Notifications]: Sending Discord notification {"type":"EPISODE_AVAILABLE","subject":"The Last of Us (2023)"}

example log if the notification has already been fired:

2025-04-14T20:30:04.497Z [info][Jellyfin Sync]: Beginning to process recently added for library: TV Shows
2025-04-14T20:30:04.608Z [debug][Jellyfin Sync]: Skipping notification - show The Last of Us was recently notified (0 hours ago)

To-Dos

• fire new episode notification for jellyfin
• handle full scans?
• plex

Issues Fixed or Closed

• implements Ability to send notifications for new episodes of ongoing seasons #480

[ErgEnn]

Hey!

I had idea of solving the issue myself, but never got around to it so I had a look how you made it.
Since the feature request mentioned ongoing seasons, my implementation idea was that whenever new episode is detected in Jellyfin, the TMDB would be queried for the release date of that episode and if it is after season/media request date, send notification. But some shows release whole(or half) season at once so it would have been quite spammy.

I noticed some potential issues in your code tho. Note that I may be wrong about those, since I never actually tested the code, just thought it through.

1. If multiple seasons are requested at the same time and their episodes start getting downloaded, only one notification for random episode would be sent out every 12h.
2. If first episode of the season arrives, the existing code updates the seasonLastUpdated date(since the season is newly created) and the notification wouldn't be sent out for episode, since 12h has not passed since last update.
3. If last episode of the season arrives, the existing code updates the season status to AVAILABLE and no episode notification is sent out, since notifications are sent out only for PARTIALLY_AVAILABLE seasons
4. If multiple episodes are released for same season at the same time, only some episodes would get notification due to 12h notification limit.

[parkuman]

Hey!

I had idea of solving the issue myself, but never got around to it so I had a look how you made it. Since the feature request mentioned ongoing seasons, my implementation idea was that whenever new episode is detected in Jellyfin, the TMDB would be queried for the release date of that episode and if it is after season/media request date, send notification. But some shows release whole(or half) season at once so it would have been quite spammy.

I noticed some potential issues in your code tho. Note that I may be wrong about those, since I never actually tested the code, just thought it through.

1. If multiple seasons are requested at the same time and their episodes start getting downloaded, only one notification for random episode would be sent out every 12h.

2. If first episode of the season arrives, the existing code updates the seasonLastUpdated date(since the season is newly created) and the notification wouldn't be sent out for episode, since 12h has not passed since last update.

3. If last episode of the season arrives, the existing code updates the season status to AVAILABLE and no episode notification is sent out, since notifications are sent out only for PARTIALLY_AVAILABLE seasons

4. If multiple episodes are released for same season at the same time, only some episodes would get notification due to 12h notification limit.

After messing around with my approach and considering all the points you've brought up I think we need a better solution! I was laser focused on the one scenario, but you're right there's many places where this won't work.

I like your approach by checking the release date, though. I think it would cover the main use case which is notifications for episodes of shows that are actively airing, rather than notifications just for when new episodes get pulled into Jellyfin (which would get very spammy). In the scenario where a whole season drops at once, we could try to batch the notification and list all the new episodes that got added in one notification so it isn't all that spammy.

I think it could also be quite cool to be able to opt in / opt out of notifications on a per-series basis. Example:

• I enable notifications for new episodes of actively airing series episodes
• I request a show that is actively airing
• by default I'll get notifications for this
• I can opt out if I want

Would also be useful to track this on a per-user basis, since Jellyseerr has notifications server-wide and per-user. What do you think about this? Would definitely take much more work but I think would be a more complete feature.

Seems to me like we might need a new entity to for Episodes 👀 Thoughts?

[github-actions]

This pull request has merge conflicts. Please resolve the conflicts so the PR can be successfully reviewed and merged.

[gauthier-th]

Hey, sorry for the late answer.

I think we should either close this or rewrite it once #1671 is implemented.
It will be much more clean and easier to implement notification for each episode once the logic for episode availability is implemented.

[parkuman]

Hey, sorry for the late answer.

I think we should either close this or rewrite it once #1671 is implemented. It will be much more clean and easier to implement notification for each episode once the logic for episode availability is implemented.

Agreed! Happy to close, this solution requires indirect and sort of hacky ways to determine things.