feat(episodes): add episode availability tracking and sync

This allows Jellyseerr to track the availability status of individual
episodes, enabling better status reporting for partially available seasons.

Author: 0xSysR3ll

server/api/servarr/sonarr.ts

@@ -380,6 +380,21 @@ class SonarrAPI extends ServarrBase<{
       });
     }
   };
+
+  public async getEpisodesBySeriesId(
+    seriesId: number
+  ): Promise<EpisodeResult[]> {
+    try {
+      const response = await this.axios.get<EpisodeResult[]>(`/episode`, {
+        params: { seriesId },
+      });
+      return response.data;
+    } catch (e) {
+      throw new Error(
+        `[Sonarr] Failed to retrieve episodes for series: ${e.message}`
+      );
+    }
+  }
 }
 
 export default SonarrAPI;

server/entity/Episode.ts

@@ -0,0 +1,43 @@
+import { MediaStatus } from '@server/constants/media';
+import { DbAwareColumn } from '@server/utils/DbColumnHelper';
+import { Column, Entity, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
+import Season from './Season';
+
+@Entity()
+class Episode {
+  @PrimaryGeneratedColumn()
+  public id: number;
+
+  @Column()
+  public episodeNumber: number;
+
+  @Column({ type: 'int', default: MediaStatus.UNKNOWN })
+  public status: MediaStatus;
+
+  @Column({ type: 'int', default: MediaStatus.UNKNOWN })
+  public status4k: MediaStatus;
+
+  @ManyToOne(() => Season, (season: Season) => season.episodes, {
+    onDelete: 'CASCADE',
+    nullable: true,
+  })
+  public season?: Promise<Season>;
+
+  @DbAwareColumn({ type: 'datetime', default: () => 'CURRENT_TIMESTAMP' })
+  public createdAt: Date;
+
+  @DbAwareColumn({
+    type: 'datetime',
+    default: () => 'CURRENT_TIMESTAMP',
+    onUpdate: 'CURRENT_TIMESTAMP',
+  })
+  public updatedAt: Date;
+
+  constructor(init?: Partial<Episode>) {
+    if (init) {
+      Object.assign(this, init);
+    }
+  }
+}
+
+export default Episode;

server/entity/Media.ts

@@ -70,9 +70,27 @@ class Media {
     const mediaRepository = getRepository(Media);
 
     try {
+      const relations: {
+        requests: boolean;
+        issues: boolean;
+        seasons?: {
+          episodes: boolean;
+        };
+      } = {
+        requests: true,
+        issues: true,
+      };
+
+      // Only load seasons for TV shows
+      if (mediaType === MediaType.TV) {
+        relations.seasons = {
+          episodes: true,
+        };
+      }
+
       const media = await mediaRepository.findOne({
         where: { tmdbId: id, mediaType: mediaType },
-        relations: { requests: true, issues: true },
+        relations,
       });
 
       return media ?? undefined;

server/entity/Season.ts

@@ -1,6 +1,13 @@
 import { MediaStatus } from '@server/constants/media';
 import { DbAwareColumn } from '@server/utils/DbColumnHelper';
-import { Column, Entity, ManyToOne, PrimaryGeneratedColumn } from 'typeorm';
+import {
+  Column,
+  Entity,
+  ManyToOne,
+  OneToMany,
+  PrimaryGeneratedColumn,
+} from 'typeorm';
+import Episode from './Episode';
 import Media from './Media';
 
 @Entity()
@@ -22,6 +29,12 @@ class Season {
   })
   public media: Promise<Media>;
 
+  @OneToMany(() => Episode, (episode) => episode.season, {
+    cascade: true,
+    eager: true,
+  })
+  public episodes: Episode[];
+
   @DbAwareColumn({ type: 'datetime', default: () => 'CURRENT_TIMESTAMP' })
   public createdAt: Date;
 

server/lib/availabilitySync.ts

@@ -8,6 +8,7 @@ import SonarrAPI from '@server/api/servarr/sonarr';
 import { MediaRequestStatus, MediaStatus } from '@server/constants/media';
 import { MediaServerType } from '@server/constants/server';
 import { getRepository } from '@server/datasource';
+import Episode from '@server/entity/Episode';
 import Media from '@server/entity/Media';
 import MediaRequest from '@server/entity/MediaRequest';
 import type Season from '@server/entity/Season';
@@ -804,6 +805,7 @@ class AvailabilitySync {
     is4k: boolean
   ): Promise<boolean> {
     let seasonExists = false;
+    const episodeRepository = getRepository(Episode);
 
     // Check each sonarr instance to see if the media still exists
     // If found, we will assume the media exists and prevent removal
@@ -832,6 +834,82 @@ class AvailabilitySync {
 
       if (seasonIsAvailable && sonarrSeasons) {
         seasonExists = true;
+
+        const sonarrApi = new SonarrAPI({
+          url: SonarrAPI.buildUrl(server, '/api/v3'),
+          apiKey: server.apiKey,
+        });
+
+        try {
+          const serviceId = is4k
+            ? media.externalServiceId4k
+            : media.externalServiceId;
+
+          if (!serviceId) {
+            logger.error('Missing service ID for episode sync', {
+              label: 'Availability Sync',
+              tvId: media.tmdbId,
+              seasonNumber: season.seasonNumber,
+              is4k,
+            });
+            return seasonExists;
+          }
+
+          const episodes = await sonarrApi.getEpisodesBySeriesId(serviceId);
+
+          for (const ep of episodes) {
+            if (ep.seasonNumber === season.seasonNumber) {
+              const existingEpisode = await episodeRepository.findOne({
+                where: {
+                  episodeNumber: ep.episodeNumber,
+                  season: { id: season.id },
+                },
+                relations: ['season'],
+              });
+
+              if (existingEpisode) {
+                existingEpisode[is4k ? 'status4k' : 'status'] = ep.hasFile
+                  ? MediaStatus.AVAILABLE
+                  : MediaStatus.UNKNOWN;
+                await episodeRepository.save(existingEpisode);
+              } else {
+                const newEpisode = new Episode();
+                newEpisode.episodeNumber = ep.episodeNumber;
+                newEpisode.status = is4k
+                  ? MediaStatus.UNKNOWN
+                  : ep.hasFile
+                  ? MediaStatus.AVAILABLE
+                  : MediaStatus.UNKNOWN;
+                newEpisode.status4k = is4k
+                  ? ep.hasFile
+                    ? MediaStatus.AVAILABLE
+                    : MediaStatus.UNKNOWN
+                  : MediaStatus.UNKNOWN;
+                newEpisode.season = Promise.resolve(season);
+
+                try {
+                  await episodeRepository.save(newEpisode);
+                } catch (saveError) {
+                  logger.error('Failed to save new episode', {
+                    label: 'Availability Sync',
+                    errorMessage: saveError.message,
+                    tvId: media.tmdbId,
+                    seasonNumber: season.seasonNumber,
+                    episodeNumber: ep.episodeNumber,
+                  });
+                }
+              }
+            }
+          }
+        } catch (err) {
+          logger.error('Failed to update episode availability', {
+            label: 'Availability Sync',
+            errorMessage: err.message,
+            tvId: media.tmdbId,
+            seasonNumber: season.seasonNumber,
+            sonarrServerId: server.id,
+          });
+        }
       }
     }
 

server/migration/postgres/1747690625482-AddEpisodeTable.ts

@@ -0,0 +1,21 @@
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddEpisodeTable1747690625482 implements MigrationInterface {
+  name = 'AddEpisodeTable1747690625482';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `CREATE TABLE "episode" ("id" SERIAL NOT NULL, "episodeNumber" integer NOT NULL, "status" integer NOT NULL DEFAULT '1', "status4k" integer NOT NULL DEFAULT '1', "createdAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "updatedAt" TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(), "seasonId" integer, CONSTRAINT "PK_7258b95d6d2bf7f621845a0e143" PRIMARY KEY ("id"))`
+    );
+    await queryRunner.query(
+      `ALTER TABLE "episode" ADD CONSTRAINT "FK_e73d28c1e5e3c85125163f7c9cd" FOREIGN KEY ("seasonId") REFERENCES "season"("id") ON DELETE CASCADE ON UPDATE NO ACTION`
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "episode" DROP CONSTRAINT "FK_e73d28c1e5e3c85125163f7c9cd"`
+    );
+    await queryRunner.query(`DROP TABLE "episode"`);
+  }
+}

server/migration/sqlite/1747690625482-AddEpisodeTable.ts

@@ -0,0 +1,34 @@
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddEpisodeTable1747690625482 implements MigrationInterface {
+  name = 'AddEpisodeTable1747690625482';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `CREATE TABLE "episode" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "episodeNumber" integer NOT NULL, "status" integer NOT NULL DEFAULT (1), "status4k" integer NOT NULL DEFAULT (1), "createdAt" datetime NOT NULL DEFAULT (CURRENT_TIMESTAMP), "updatedAt" datetime NOT NULL DEFAULT (CURRENT_TIMESTAMP), "seasonId" integer)`
+    );
+    await queryRunner.query(
+      `CREATE TABLE "temporary_episode" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "episodeNumber" integer NOT NULL, "status" integer NOT NULL DEFAULT (1), "status4k" integer NOT NULL DEFAULT (1), "createdAt" datetime NOT NULL DEFAULT (CURRENT_TIMESTAMP), "updatedAt" datetime NOT NULL DEFAULT (CURRENT_TIMESTAMP), "seasonId" integer, CONSTRAINT "FK_e73d28c1e5e3c85125163f7c9cd" FOREIGN KEY ("seasonId") REFERENCES "season" ("id") ON DELETE CASCADE ON UPDATE NO ACTION)`
+    );
+    await queryRunner.query(
+      `INSERT INTO "temporary_episode"("id", "episodeNumber", "status", "status4k", "createdAt", "updatedAt", "seasonId") SELECT "id", "episodeNumber", "status", "status4k", "createdAt", "updatedAt", "seasonId" FROM "episode"`
+    );
+    await queryRunner.query(`DROP TABLE "episode"`);
+    await queryRunner.query(
+      `ALTER TABLE "temporary_episode" RENAME TO "episode"`
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE "episode" RENAME TO "temporary_episode"`
+    );
+    await queryRunner.query(
+      `CREATE TABLE "episode" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "episodeNumber" integer NOT NULL, "status" integer NOT NULL DEFAULT (1), "status4k" integer NOT NULL DEFAULT (1), "createdAt" datetime NOT NULL DEFAULT (CURRENT_TIMESTAMP), "updatedAt" datetime NOT NULL DEFAULT (CURRENT_TIMESTAMP), "seasonId" integer)`
+    );
+    await queryRunner.query(
+      `INSERT INTO "episode"("id", "episodeNumber", "status", "status4k", "createdAt", "updatedAt", "seasonId") SELECT "id", "episodeNumber", "status", "status4k", "createdAt", "updatedAt", "seasonId" FROM "temporary_episode"`
+    );
+    await queryRunner.query(`DROP TABLE "temporary_episode"`);
+  }
+}

server/models/Tv.ts

@@ -38,6 +38,7 @@ interface Episode {
   stillPath?: string;
   voteAverage: number;
   voteCount: number;
+  available?: boolean;
 }
 
 interface Season {
@@ -114,7 +115,10 @@ export interface TvDetails {
   onUserWatchlist?: boolean;
 }
 
-const mapEpisodeResult = (episode: TmdbTvEpisodeResult): Episode => ({
+const mapEpisodeResult = (
+  episode: TmdbTvEpisodeResult,
+  availableMap?: Record<number, boolean>
+): Episode => ({
   id: episode.id,
   airDate: episode.air_date,
   episodeNumber: episode.episode_number,
@@ -126,6 +130,9 @@ const mapEpisodeResult = (episode: TmdbTvEpisodeResult): Episode => ({
   voteAverage: episode.vote_average,
   voteCount: episode.vote_cuont,
   stillPath: episode.still_path,
+  available: availableMap
+    ? availableMap[episode.episode_number] ?? false
+    : undefined,
 });
 
 const mapSeasonResult = (season: TmdbTvSeasonResult): Season => ({
@@ -139,10 +146,13 @@ const mapSeasonResult = (season: TmdbTvSeasonResult): Season => ({
 });
 
 export const mapSeasonWithEpisodes = (
-  season: TmdbSeasonWithEpisodes
+  season: TmdbSeasonWithEpisodes,
+  availableMap?: Record<number, boolean>
 ): SeasonWithEpisodes => ({
   airDate: season.air_date,
-  episodes: season.episodes.map(mapEpisodeResult),
+  episodes: season.episodes.map((episode) =>
+    mapEpisodeResult(episode, availableMap)
+  ),
   externalIds: mapExternalIds(season.external_ids),
   id: season.id,
   name: season.name,

server/routes/tv.ts

@@ -1,6 +1,6 @@
 import RottenTomatoes from '@server/api/rating/rottentomatoes';
 import TheMovieDb from '@server/api/themoviedb';
-import { MediaType } from '@server/constants/media';
+import { MediaStatus, MediaType } from '@server/constants/media';
 import { getRepository } from '@server/datasource';
 import Media from '@server/entity/Media';
 import { Watchlist } from '@server/entity/Watchlist';
@@ -62,7 +62,30 @@ tvRoutes.get('/:id/season/:seasonNumber', async (req, res, next) => {
       language: (req.query.language as string) ?? req.locale,
     });
 
-    return res.status(200).json(mapSeasonWithEpisodes(season));
+    const media = await Media.getMedia(Number(req.params.id), MediaType.TV);
+    const availableMap: Record<number, boolean> = {};
+
+    if (media?.seasons) {
+      const dbSeason = media.seasons.find(
+        (s) => s.seasonNumber === Number(req.params.seasonNumber)
+      );
+      if (dbSeason) {
+        if (dbSeason.status === MediaStatus.AVAILABLE) {
+          for (const episode of season.episodes) {
+            availableMap[episode.episode_number] = true;
+          }
+        } else if (dbSeason.status === MediaStatus.PARTIALLY_AVAILABLE) {
+          if (dbSeason.episodes) {
+            for (const episode of dbSeason.episodes) {
+              availableMap[episode.episodeNumber] =
+                episode.status === MediaStatus.AVAILABLE;
+            }
+          }
+        }
+      }
+    }
+
+    return res.status(200).json(mapSeasonWithEpisodes(season, availableMap));
   } catch (e) {
     logger.debug('Something went wrong retrieving season', {
       label: 'API',

src/components/TvDetails/Season/index.tsx

@@ -1,6 +1,8 @@
 import AirDateBadge from '@app/components/AirDateBadge';
+import Badge from '@app/components/Common/Badge';
 import CachedImage from '@app/components/Common/CachedImage';
 import LoadingSpinner from '@app/components/Common/LoadingSpinner';
+import globalMessages from '@app/i18n/globalMessages';
 import defineMessages from '@app/utils/defineMessages';
 import type { SeasonWithEpisodes } from '@server/models/Tv';
 import { useIntl } from 'react-intl';
@@ -52,6 +54,13 @@ const Season = ({ seasonNumber, tvId }: SeasonProps) => {
                     {episode.airDate && (
                       <AirDateBadge airDate={episode.airDate} />
                     )}
+                    <Badge badgeType={episode.available ? 'success' : 'danger'}>
+                      {intl.formatMessage(
+                        episode.available
+                          ? globalMessages.available
+                          : globalMessages.unavailable
+                      )}
+                    </Badge>
                   </div>
                   {episode.overview && <p>{episode.overview}</p>}
                 </div>