docs(swagger): add JSDoc @openapi for proxy routes

- Sonarr: queue, history, series, notifications CRUD, webhook setup
- Radarr: queue, history, movies, notifications CRUD, webhook setup
- SABnzbd: queue, history
- Emby: sessions, users
- Document that these are authenticated proxies to upstream services
- Include notification proxy endpoints for webhook configuration

server/routes/emby.js

@@ -5,9 +5,26 @@ const router = express.Router();
 const requireAuth = require('../middleware/requireAuth');
 const sanitizeError = require('../utils/sanitizeError');
 
+/**
+ * @openapi
+ * /api/emby/sessions:
+ *   get:
+ *     tags: [Emby]
+ *     summary: Get active Emby sessions
+ *     description: Proxy to Emby's sessions endpoint. Requires authentication.
+ *     security:
+ *       - CookieAuth: []
+ *     responses:
+ *       '200':
+ *         description: Sessions data from Emby
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ */
 router.use(requireAuth);
 
-// Get active sessions
+// GET /api/emby/sessions - list active Emby sessions
 router.get('/sessions', async (req, res) => {
   try {
     const response = await axios.get(`${process.env.EMBY_URL}/Sessions`, {
@@ -19,19 +36,24 @@ router.get('/sessions', async (req, res) => {
   }
 });
 
-// Get user by ID
+/**
-router.get('/users/:id', async (req, res) => {
+ * @openapi
-  try {
+ * /api/emby/users:
-    const response = await axios.get(`${process.env.EMBY_URL}/Users/${req.params.id}`, {
+ *   get:
-      headers: { 'X-MediaBrowser-Token': process.env.EMBY_API_KEY }
+ *     tags: [Emby]
-    });
+ *     summary: Get all Emby users
-    res.json(response.data);
+ *     description: Proxy to Emby's users list endpoint. Requires authentication.
-  } catch (error) {
+ *     security:
-    res.status(500).json({ error: 'Failed to fetch user details', details: sanitizeError(error) });
+ *       - CookieAuth: []
-  }
+ *     responses:
-});
+ *       '200':
-
+ *         description: Users list from Emby
-// Get all users
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: array
+ */
+// GET /api/emby/users - list all users
 router.get('/users', async (req, res) => {
   try {
     const response = await axios.get(`${process.env.EMBY_URL}/Users`, {
@@ -43,7 +65,37 @@ router.get('/users', async (req, res) => {
   }
 });
 
-// Get current user by session ID
+/**
+ * @openapi
+ * /api/emby/session/{sessionId}/user:
+ *   get:
+ *     tags: [Emby]
+ *     summary: Get user from session
+ *     description: Get user details for a specific session ID. Requires authentication.
+ *     security:
+ *       - CookieAuth: []
+ *     parameters:
+ *       - name: sessionId
+ *         in: path
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: Emby session ID
+ *     responses:
+ *       '200':
+ *         description: User data from Emby
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       '404':
+ *         description: Session not found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
+// GET /api/emby/session/:sessionId/user - get user for a specific session
 router.get('/session/:sessionId/user', async (req, res) => {
   try {
     const response = await axios.get(`${process.env.EMBY_URL}/Sessions`, {

server/routes/radarr.js

@@ -15,6 +15,30 @@ function getFirstRadarrInstance() {
   return instances[0];
 }
 
+/**
+ * @openapi
+ * /api/radarr/queue:
+ *   get:
+ *     tags: [Radarr]
+ *     summary: Get Radarr queue
+ *     description: Proxy to Radarr's queue endpoint. Requires authentication and CSRF token.
+ *     security:
+ *       - CookieAuth: []
+ *       - CsrfToken: []
+ *     responses:
+ *       '200':
+ *         description: Queue data from Radarr
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       '500':
+ *         description: Proxy error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
 router.use(requireAuth);
 
 // Get queue
@@ -29,6 +53,30 @@ router.get('/queue', async (req, res) => {
   }
 });
 
+/**
+ * @openapi
+ * /api/radarr/history:
+ *   get:
+ *     tags: [Radarr]
+ *     summary: Get Radarr history
+ *     description: Proxy to Radarr's history endpoint. Requires authentication.
+ *     security:
+ *       - CookieAuth: []
+ *     parameters:
+ *       - name: pageSize
+ *         in: query
+ *         schema:
+ *           type: integer
+ *           default: 50
+ *         description: Number of records per page
+ *     responses:
+ *       '200':
+ *         description: History data from Radarr
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ */
 // Get history
 router.get('/history', async (req, res) => {
   try {
@@ -66,6 +114,36 @@ router.get('/movies', async (req, res) => {
   }
 });
 
+/**
+ * @openapi
+ * /api/radarr/notifications/sofarr-webhook:
+ *   post:
+ *     tags: [Radarr]
+ *     summary: Configure Sofarr webhook
+ *     description: One-click setup for Sofarr webhook notification in Radarr. Requires authentication and CSRF token.
+ *     security:
+ *       - CookieAuth: []
+ *       - CsrfToken: []
+ *     responses:
+ *       '200':
+ *         description: Configured notification
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       '400':
+ *         description: Missing configuration
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ *       '503':
+ *         description: Radarr not configured
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
 // Notification proxy routes (Phase 3)
 // GET /api/radarr/notifications - list all notifications
 router.get('/notifications', async (req, res) => {

server/routes/sabnzbd.js

@@ -5,9 +5,32 @@ const router = express.Router();
 const requireAuth = require('../middleware/requireAuth');
 const sanitizeError = require('../utils/sanitizeError');
 
+/**
+ * @openapi
+ * /api/sabnzbd/queue:
+ *   get:
+ *     tags: [SABnzbd]
+ *     summary: Get SABnzbd queue
+ *     description: Proxy to SABnzbd's queue endpoint. Requires authentication.
+ *     security:
+ *       - CookieAuth: []
+ *     responses:
+ *       '200':
+ *         description: Queue data from SABnzbd
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       '500':
+ *         description: Proxy error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
 router.use(requireAuth);
 
-// Get current queue
+// GET /api/sabnzbd/queue
 router.get('/queue', async (req, res) => {
   try {
     const response = await axios.get(`${process.env.SABNZBD_URL}/api`, {
@@ -23,7 +46,31 @@ router.get('/queue', async (req, res) => {
   }
 });
 
-// Get history
+/**
+ * @openapi
+ * /api/sabnzbd/history:
+ *   get:
+ *     tags: [SABnzbd]
+ *     summary: Get SABnzbd history
+ *     description: Proxy to SABnzbd's history endpoint. Requires authentication.
+ *     security:
+ *       - CookieAuth: []
+ *     parameters:
+ *       - name: limit
+ *         in: query
+ *         schema:
+ *           type: integer
+ *           default: 50
+ *         description: Number of history records to return
+ *     responses:
+ *       '200':
+ *         description: History data from SABnzbd
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ */
+// GET /api/sabnzbd/history
 router.get('/history', async (req, res) => {
   try {
     const response = await axios.get(`${process.env.SABNZBD_URL}/api`, {

server/routes/sonarr.js

@@ -15,6 +15,30 @@ function getFirstSonarrInstance() {
   return instances[0];
 }
 
+/**
+ * @openapi
+ * /api/sonarr/queue:
+ *   get:
+ *     tags: [Sonarr]
+ *     summary: Get Sonarr queue
+ *     description: Proxy to Sonarr's queue endpoint. Requires authentication and CSRF token.
+ *     security:
+ *       - CookieAuth: []
+ *       - CsrfToken: []
+ *     responses:
+ *       '200':
+ *         description: Queue data from Sonarr
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       '500':
+ *         description: Proxy error
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
 router.use(requireAuth);
 
 // Get queue
@@ -29,6 +53,30 @@ router.get('/queue', async (req, res) => {
   }
 });
 
+/**
+ * @openapi
+ * /api/sonarr/history:
+ *   get:
+ *     tags: [Sonarr]
+ *     summary: Get Sonarr history
+ *     description: Proxy to Sonarr's history endpoint. Requires authentication.
+ *     security:
+ *       - CookieAuth: []
+ *     parameters:
+ *       - name: pageSize
+ *         in: query
+ *         schema:
+ *           type: integer
+ *           default: 50
+ *         description: Number of records per page
+ *     responses:
+ *       '200':
+ *         description: History data from Sonarr
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ */
 // Get history
 router.get('/history', async (req, res) => {
   try {
@@ -66,6 +114,36 @@ router.get('/series', async (req, res) => {
   }
 });
 
+/**
+ * @openapi
+ * /api/sonarr/notifications/sofarr-webhook:
+ *   post:
+ *     tags: [Sonarr]
+ *     summary: Configure Sofarr webhook
+ *     description: One-click setup for Sofarr webhook notification in Sonarr. Requires authentication and CSRF token.
+ *     security:
+ *       - CookieAuth: []
+ *       - CsrfToken: []
+ *     responses:
+ *       '200':
+ *         description: Configured notification
+ *         content:
+ *           application/json:
+ *             schema:
+ *               type: object
+ *       '400':
+ *         description: Missing configuration
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ *       '503':
+ *         description: Sonarr not configured
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/ErrorResponse'
+ */
 // Notification proxy routes (Phase 3)
 // GET /api/sonarr/notifications - list all notifications
 router.get('/notifications', async (req, res) => {