feat(discover): add tmdb list discover source

AintGotNoLoveToday · AintGotNoLoveToday · commit 24fa3f80aeb2 · 2025-12-07T18:13:13.000Z
support creating discover sliders from public tmdb lists
diff --git a/seerr-api.yml b/seerr-api.yml
@@ -5868,6 +5868,52 @@ paths:
                         - $ref: '#/components/schemas/MovieResult'
                         - $ref: '#/components/schemas/TvResult'
                         - $ref: '#/components/schemas/PersonResult'
+  /discover/list/{listId}:
+    get:
+      summary: Get TMDB list by ID
+      description: Returns items from a public TMDB list as discovery results.
+      tags:
+        - search
+      parameters:
+        - in: path
+          name: listId
+          required: true
+          schema:
+            type: number
+            example: 8234446
+        - in: query
+          name: language
+          schema:
+            type: string
+            example: en
+        - in: query
+          name: page
+          required: false
+          schema:
+            type: number
+            example: 1
+      responses:
+        '200':
+          description: Results
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  page:
+                    type: number
+                  totalPages:
+                    type: number
+                  totalResults:
+                    type: number
+                  results:
+                    type: array
+                    items:
+                      anyOf:
+                        - $ref: '#/components/schemas/MovieResult'
+                        - $ref: '#/components/schemas/TvResult'
+                        - $ref: '#/components/schemas/PersonResult'
+                        - $ref: '#/components/schemas/Collection'
   /discover/keyword/{keywordId}/movies:
     get:
       summary: Get movies from keyword
diff --git a/server/api/themoviedb/index.ts b/server/api/themoviedb/index.ts
@@ -5,6 +5,7 @@ import { getSettings } from '@server/lib/settings';
 import { sortBy } from 'lodash';
 import type {
   TmdbCollection,
+  TmdbCollectionResult,
   TmdbCompanySearchResponse,
   TmdbExternalIdResponse,
   TmdbGenre,
@@ -13,16 +14,19 @@ import type {
   TmdbKeywordSearchResponse,
   TmdbLanguage,
   TmdbMovieDetails,
+  TmdbMovieResult,
   TmdbNetwork,
   TmdbPersonCombinedCredits,
   TmdbPersonDetails,
+  TmdbPersonResult,
   TmdbProductionCompany,
   TmdbRegion,
   TmdbSearchMovieResponse,
   TmdbSearchMultiResponse,
   TmdbSearchTvResponse,
   TmdbSeasonWithEpisodes,
   TmdbTvDetails,
+  TmdbTvResult,
   TmdbUpcomingMoviesResponse,
   TmdbWatchProviderDetails,
   TmdbWatchProviderRegion,
@@ -758,6 +762,62 @@ class TheMovieDb extends ExternalAPI implements TvShowProvider {
     }
   };
 
+  /**
+   * Retrieve a public TMDB list by its ID. The TMDB API returns a list of mixed
+   * media items under the `items` property. This helper normalises the response
+   * to the same paginated structure used by discover and trending endpoints.
+   * If the list is private or does not exist, an exception will be thrown.
+   */
+  public getList = async ({
+    listId,
+    language = this.locale,
+  }: {
+    listId: number;
+    language?: string;
+  }): Promise<{
+    page: number;
+    total_pages: number;
+    total_results: number;
+    results: (
+      | TmdbMovieResult
+      | TmdbTvResult
+      | TmdbPersonResult
+      | TmdbCollectionResult
+    )[];
+  }> => {
+    try {
+      const data = await this.get<any>(`/list/${listId}`, {
+        params: {
+          language,
+        },
+      });
+
+      // The API does not provide pagination on lists so we normalise here.
+      const items =
+        data?.items ??
+        ([] as (
+          | TmdbMovieResult
+          | TmdbTvResult
+          | TmdbPersonResult
+          | TmdbCollectionResult
+        )[]);
+
+      return {
+        page: 1,
+        total_pages: 1,
+        total_results: items.length,
+        results: items as (
+          | TmdbMovieResult
+          | TmdbTvResult
+          | TmdbPersonResult
+          | TmdbCollectionResult
+        )[],
+      };
+    } catch (e) {
+      throw new Error(`[TMDB] Failed to fetch list: ${e.message}`);
+    }
+  };
+
   public async getByExternalId({
     externalId,
     type,
diff --git a/server/api/tvdb/index.ts b/server/api/tvdb/index.ts
@@ -204,6 +204,10 @@ class Tvdb extends ExternalAPI implements TvShowProvider {
     seasonNumber: number;
     language?: string;
   }): Promise<TmdbSeasonWithEpisodes> {
+    if (seasonNumber === 0) {
+      return this.createEmptySeasonResponse(tvId);
+    }
+
     try {
       const tmdbTvShow = await this.tmdb.getTvShow({ tvId, language });
 
@@ -277,12 +281,12 @@ class Tvdb extends ExternalAPI implements TvShowProvider {
     }
 
     const seasons = tvdbData.seasons
-      .filter((season) => season.type && season.type.type === 'official')
-      .sort((a, b) => a.number - b.number)
-      .map((season) => this.createSeasonData(season, tvdbData))
       .filter(
-        (season) => season && season.season_number >= 0
-      ) as TmdbTvSeasonResult[];
+        (season) =>
+          season.number > 0 && season.type && season.type.type === 'official'
+      )
+      .sort((a, b) => a.number - b.number)
+      .map((season) => this.createSeasonData(season, tvdbData));
 
     return seasons;
   }
@@ -291,14 +295,13 @@ class Tvdb extends ExternalAPI implements TvShowProvider {
     season: TvdbSeasonDetails,
     tvdbData: TvdbTvDetails
   ): TmdbTvSeasonResult {
-    const seasonNumber = season.number ?? -1;
-    if (seasonNumber < 0) {
+    if (!season.number) {
       return {
         id: 0,
         episode_count: 0,
         name: '',
         overview: '',
-        season_number: -1,
+        season_number: 0,
         poster_path: '',
         air_date: '',
       };
diff --git a/server/constants/discover.ts b/server/constants/discover.ts
@@ -22,6 +22,7 @@ export enum DiscoverSliderType {
   TMDB_NETWORK,
   TMDB_MOVIE_STREAMING_SERVICES,
   TMDB_TV_STREAMING_SERVICES,
+  TMDB_LIST,
 }
 
 export const defaultSliders: Partial<DiscoverSlider>[] = [
diff --git a/server/routes/discover.ts b/server/routes/discover.ts
@@ -712,7 +712,7 @@ discoverRoutes.get('/trending', async (req, res, next) => {
   } catch (e) {
     logger.debug('Something went wrong retrieving trending items', {
       label: 'API',
-      errorMessage: e.message,
+      errorMessage: (e as Error).message,
     });
     return next({
       status: 500,
@@ -917,4 +917,145 @@ discoverRoutes.get<Record<string, unknown>, WatchlistResponse>(
   }
 );
 
+// TMDB list slider: return items from a TMDB list by id
+discoverRoutes.get<{ listId: string }>(
+  '/list/:listId',
+  async (req, res, next) => {
+    const listId = Number(req.params.listId);
+    if (!listId || Number.isNaN(listId)) {
+      return next({ status: 400, message: 'Invalid list ID.' });
+    }
+
+    // same helper as in /trending etc.
+    const tmdb = createTmdbWithRegionLanguage(req.user);
+    const language = (req.query.language as string) ?? req.locale;
+    const page = req.query.page ? Number(req.query.page) || 1 : 1;
+
+    try {
+      let data: { results: any[] } | null = null;
+
+      // 1) v3: all items come without pagination
+      try {
+        const v3 = await tmdb.getList({ listId, language });
+        data = v3;
+      } catch {
+        data = null;
+      }
+
+      // 2) fallback to v4 if v3 is empty or failed
+      if (!data || !Array.isArray(data.results) || data.results.length === 0) {
+        // use the existing Axios instance of the TMDB client (proxy/timeouts are preserved)
+        const axiosInstance: any = (tmdb as any).axios;
+        const v4Url = `https://api.themoviedb.org/4/list/${listId}`;
+
+        try {
+          const resp = await axiosInstance.get(v4Url, {
+            params: { page, language },
+          });
+
+          const v4 = resp.data as {
+            page?: number;
+            total_pages?: number;
+            total_results?: number;
+            results?: { id: number; media_type: string }[];
+          };
+
+          const media = await Media.getRelatedMedia(
+            req.user,
+            (v4.results ?? []).map((r) => r.id)
+          );
+
+          const mappedResults = (v4.results ?? []).map((r) => {
+            switch (r.media_type) {
+              case 'movie':
+                return mapMovieResult(
+                  r as any,
+                  media.find(
+                    (m) => m.tmdbId === r.id && m.mediaType === MediaType.MOVIE
+                  )
+                );
+              case 'tv':
+                return mapTvResult(
+                  r as any,
+                  media.find(
+                    (m) => m.tmdbId === r.id && m.mediaType === MediaType.TV
+                  )
+                );
+              case 'person':
+                return mapPersonResult(r as any);
+              default:
+                return mapCollectionResult(r as any);
+            }
+          });
+
+          return res.status(200).json({
+            page: v4.page ?? 1,
+            totalPages: v4.total_pages ?? 1,
+            totalResults: mappedResults.length,
+            results: mappedResults,
+          });
+        } catch {
+          // if v4 also fails → continue to empty response below
+        }
+      }
+
+      // 3) return v3 data if available
+      if (data && Array.isArray(data.results) && data.results.length > 0) {
+        const media = await Media.getRelatedMedia(
+          req.user,
+          data.results.map((r) => r.id)
+        );
+
+        const mappedResults = data.results.map((result) =>
+          isMovie(result)
+            ? mapMovieResult(
+                result,
+                media.find(
+                  (m) =>
+                    m.tmdbId === result.id && m.mediaType === MediaType.MOVIE
+                )
+              )
+            : isPerson(result)
+            ? mapPersonResult(result)
+            : isCollection(result)
+            ? mapCollectionResult(result)
+            : mapTvResult(
+                result,
+                media.find(
+                  (m) => m.tmdbId === result.id && m.mediaType === MediaType.TV
+                )
+              )
+        );
+
+        return res.status(200).json({
+          page: 1,
+          totalPages: 1,
+          totalResults: mappedResults.length,
+          results: mappedResults,
+        });
+      }
+
+      // 4) both paths empty → return empty response
+      return res.status(200).json({
+        page: 1,
+        totalPages: 1,
+        totalResults: 0,
+        results: [],
+      });
+    } catch (err) {
+      logger.debug('TMDB list slider failed', {
+        label: 'API',
+        errorMessage: (err as Error).message,
+        listId: req.params.listId,
+      });
+      return res.status(200).json({
+        page: 1,
+        totalPages: 1,
+        totalResults: 0,
+        results: [],
+      });
+    }
+  }
+);
+
 export default discoverRoutes;
diff --git a/src/components/Discover/CreateSlider/index.tsx b/src/components/Discover/CreateSlider/index.tsx
@@ -44,6 +44,7 @@ const messages = defineMessages('components.Discover.CreateSlider', {
   searchStudios: 'Search studios…',
   starttyping: 'Starting typing to search.',
   nooptions: 'No results.',
+  providetmdblistid: 'Provide a TMDB List ID',
 });
 
 type CreateSliderProps = {
@@ -295,6 +296,13 @@ const CreateSlider = ({ onCreate, slider }: CreateSliderProps) => {
       params: 'watchRegion=$regionValue&watchProviders=$providersValue',
       titlePlaceholderText: intl.formatMessage(messages.slidernameplaceholder),
     },
+    {
+      type: DiscoverSliderType.TMDB_LIST,
+      title: intl.formatMessage(sliderTitles.tmdbList),
+      dataUrl: '/api/v1/discover/list/$value',
+      titlePlaceholderText: intl.formatMessage(messages.slidernameplaceholder),
+      dataPlaceholderText: intl.formatMessage(messages.providetmdblistid),
+    },
   ];
 
   return (
@@ -470,6 +478,18 @@ const CreateSlider = ({ onCreate, slider }: CreateSliderProps) => {
               />
             );
             break;
+          case DiscoverSliderType.TMDB_LIST:
+            dataInput = (
+              <Field
+                type="text"
+                inputMode="numeric"
+                pattern="[0-9]*"
+                name="data"
+                id="data"
+                placeholder={activeOption?.dataPlaceholderText}
+              />
+            );
+            break;
           default:
             dataInput = (
               <Field
diff --git a/src/components/Discover/DiscoverSliderEdit/index.tsx b/src/components/Discover/DiscoverSliderEdit/index.tsx
diff --git a/src/components/Discover/constants.ts b/src/components/Discover/constants.ts
diff --git a/src/components/Discover/index.tsx b/src/components/Discover/index.tsx

Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,7 @@ export enum DiscoverSliderType {`
`22`	`22`	`TMDB_NETWORK,`
`23`	`23`	`TMDB_MOVIE_STREAMING_SERVICES,`
`24`	`24`	`TMDB_TV_STREAMING_SERVICES,`
	`25`	`+ TMDB_LIST,`
`25`	`26`	`}`
`26`	`27`
`27`	`28`	`export const defaultSliders: Partial<DiscoverSlider>[] = [`