fix(api): swagger docs

chore: generate api-client
fix(web): improved new generative api-client support
fix(web): force update metadata on scan action click
fix(api): proper TMDB_API lookup

Author: AlkenD

apps/api/src/config/env.ts

@@ -36,7 +36,7 @@ const envSchema = z.object({
   CORS_ORIGIN: z.string().default("http://localhost:5173"),
   WEB_URL: z.string().optional(),
 
-  // API Keys
+  // External API Keys (Legacy - prefer configuring via Settings UI)
   TMDB_API_KEY: z.string().optional(),
 
   // Rate Limiting

apps/api/src/config/swagger.ts

@@ -644,6 +644,23 @@ const options: swaggerJsdoc.Options = {
               nullable: true,
               example: "https://example.com/backdrop.jpg",
             },
+            isLibrary: {
+              type: "boolean",
+              example: false,
+            },
+            libraryPath: {
+              type: "string",
+              nullable: true,
+              example: "/media/movies",
+            },
+            libraryType: {
+              $ref: "#/components/schemas/MediaType",
+              nullable: true,
+            },
+            mediaCount: {
+              type: "integer",
+              example: 42,
+            },
           },
         },
         MediaCollection: {
@@ -703,6 +720,51 @@ const options: swaggerJsdoc.Options = {
             },
           },
         },
+        Settings: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string",
+              example: "default",
+            },
+            isSetupComplete: {
+              type: "boolean",
+              example: false,
+            },
+            tmdbApiKey: {
+              type: "string",
+              nullable: true,
+              example: "your_tmdb_api_key",
+            },
+            requireAuth: {
+              type: "boolean",
+              example: true,
+            },
+            allowRegistration: {
+              type: "boolean",
+              example: false,
+            },
+            sessionDuration: {
+              type: "integer",
+              example: 604800,
+              description: "Session duration in seconds",
+            },
+            createdAt: {
+              type: "string",
+              format: "date-time",
+            },
+            updatedAt: {
+              type: "string",
+              format: "date-time",
+            },
+            libraries: {
+              type: "array",
+              items: {
+                $ref: "#/components/schemas/Collection",
+              },
+            },
+          },
+        },
       },
     },
   },

apps/api/src/lib/metadata/providers/tmdb.ts

@@ -4,6 +4,7 @@ import {
 } from "../../../generated/prisma/index.js";
 import { BaseMetadataProvider } from "../provider.js";
 import logger from "../../../config/logger.js";
+import { prisma } from "../../../lib/prisma.js";
 import type {
   MediaMetadata,
   MediaSearchResult,
@@ -14,9 +15,8 @@ import type {
 
 /**
  * TMDB API configuration
- * Set TMDB_API_KEY environment variable to enable
+ * Configure via application settings (Settings > Libraries > TMDB API Key)
  */
-const TMDB_API_KEY = process.env.TMDB_API_KEY;
 const TMDB_BASE_URL = "https://api.themoviedb.org/3";
 const TMDB_IMAGE_BASE_URL = "https://image.tmdb.org/t/p";
 
@@ -133,11 +133,28 @@ export class TMDBProvider extends BaseMetadataProvider {
   readonly source = ExternalIdSource.TMDB;
   readonly supportedMediaTypes = [MediaType.MOVIE, MediaType.TV_SHOW];
 
+  /**
+   * Get TMDB API key from database settings
+   */
+  private async getApiKey(): Promise<string | null> {
+    try {
+      const settings = await prisma.settings.findUnique({
+        where: { id: "default" },
+        select: { tmdbApiKey: true },
+      });
+      return settings?.tmdbApiKey || null;
+    } catch (error) {
+      logger.error("Failed to fetch TMDB API key from database:", { error });
+      return null;
+    }
+  }
+
   /**
    * Check if TMDB API key is configured
    */
   override async isAvailable(): Promise<boolean> {
-    return !!TMDB_API_KEY;
+    const apiKey = await this.getApiKey();
+    return !!apiKey;
   }
 
   /**
@@ -147,14 +164,16 @@ export class TMDBProvider extends BaseMetadataProvider {
     endpoint: string,
     params: Record<string, string | number | boolean> = {}
   ): Promise<T | null> {
-    if (!TMDB_API_KEY) {
+    const apiKey = await this.getApiKey();
+
+    if (!apiKey) {
       logger.warn("TMDB API key not configured");
       return null;
     }
 
     try {
       const url = new URL(`${TMDB_BASE_URL}${endpoint}`);
-      url.searchParams.append("api_key", TMDB_API_KEY);
+      url.searchParams.append("api_key", apiKey);
 
       for (const [key, value] of Object.entries(params)) {
         url.searchParams.append(key, String(value));

apps/api/src/lib/rateLimiter.ts

@@ -107,8 +107,12 @@ function createRateLimiter(
         userId: req.user?.id,
       });
 
+      // CORS headers are already set by cors middleware, just send response
       res.status(429).json(rateLimitResponse);
     },
+
+    // Skip rate limiting in development
+    skip: () => env.NODE_ENV === "development",
   };
 
   // Use Redis store if cache is enabled (distributed rate limiting)

apps/api/src/routes/collections/collections.module.ts

@@ -51,6 +51,22 @@ router.get(
  *     responses:
  *       200:
  *         description: Successfully retrieved libraries
+ *         content:
+ *           application/json:
+ *             schema:
+ *               allOf:
+ *                 - $ref: '#/components/schemas/SuccessResponse'
+ *                 - type: object
+ *                   properties:
+ *                     data:
+ *                       type: object
+ *                       properties:
+ *                         message:
+ *                           type: string
+ *                         collections:
+ *                           type: array
+ *                           items:
+ *                             $ref: '#/components/schemas/Collection'
  */
 router.get(
   "/libraries",

apps/api/src/routes/comics/comics.module.ts

@@ -5,7 +5,7 @@ const router: RouterType = Router();
 
 /**
  * @openapi
- * /api/comics:
+ * /api/v1/comics:
  *   get:
  *     summary: Get all comics
  *     description: Retrieve all comics with optional filtering, sorting, and pagination

apps/api/src/routes/media/media.module.ts

@@ -5,7 +5,7 @@ const router: RouterType = Router();
 
 /**
  * @openapi
- * /api/media:
+ * /api/v1/media:
  *   get:
  *     summary: Get all media
  *     description: Retrieve all media items with optional filtering, sorting, and pagination
@@ -126,7 +126,7 @@ router.get("/", (req, res, next) => {
 
 /**
  * @openapi
- * /api/media/statistics:
+ * /api/v1/media/statistics:
  *   get:
  *     summary: Get media statistics
  *     description: Retrieve statistics about media in the library
@@ -170,7 +170,7 @@ router.get("/statistics", (req, res, next) => {
 
 /**
  * @openapi
- * /api/media/{id}:
+ * /api/v1/media/{id}:
  *   get:
  *     summary: Get media by ID
  *     description: Retrieve a specific media item by its ID
@@ -213,7 +213,7 @@ router.get("/:id", (req, res, next) => {
 
 /**
  * @openapi
- * /api/media/stream/movie/{id}:
+ * /api/v1/media/stream/movie/{id}:
  *   get:
  *     summary: Stream a movie
  *     description: Stream a movie file with byte-range support for seeking
@@ -255,7 +255,7 @@ router.get("/stream/movie/:id", (req, res, next) => {
 
 /**
  * @openapi
- * /api/media/stream/episode/{id}/{seasonNumber}/{episodeNumber}:
+ * /api/v1/media/stream/episode/{id}/{seasonNumber}/{episodeNumber}:
  *   get:
  *     summary: Stream a TV episode
  *     description: Stream a TV episode file with byte-range support for seeking

apps/api/src/routes/movies/movies.module.ts

@@ -5,7 +5,7 @@ const router: RouterType = Router();
 
 /**
  * @openapi
- * /api/movies:
+ * /api/v1/movies:
  *   get:
  *     summary: Get all movies
  *     description: Retrieve all movies with optional filtering, sorting, and pagination
@@ -121,7 +121,7 @@ router.get("/", (req, res, next) => {
 
 /**
  * @openapi
- * /api/movies/{id}:
+ * /api/v1/movies/{id}:
  *   get:
  *     summary: Get movie by ID
  *     description: Retrieve a specific movie by its ID

apps/api/src/routes/music/music.module.ts

@@ -5,7 +5,7 @@ const router: RouterType = Router();
 
 /**
  * @openapi
- * /api/music:
+ * /api/v1/music:
  *   get:
  *     summary: Get all music
  *     description: Retrieve all music items with optional filtering, sorting, and pagination

apps/api/src/routes/scan/scan.module.ts

@@ -5,7 +5,7 @@ const router: RouterType = Router();
 
 /**
  * @openapi
- * /api/scan:
+ * /api/v1/scan:
  *   post:
  *     summary: Scan a directory for media files
  *     description: Recursively scans a directory and returns all media files matching the specified media type
@@ -73,7 +73,7 @@ router.post("/", (req, res, next) => {
 
 /**
  * @openapi
- * /api/scan/sync:
+ * /api/v1/scan/sync:
  *   post:
  *     summary: Sync a collection
  *     description: Checks for file modifications and removals in a collection
@@ -126,7 +126,7 @@ router.post("/sync", (req, res, next) => {
 
 /**
  * @openapi
- * /api/scan/sync-all:
+ * /api/v1/scan/sync-all:
  *   post:
  *     summary: Sync all collections
  *     description: Checks for file modifications and removals across all collections (for cron jobs)