flyer-crawler.projectium.com/src/routes/category.routes.ts

// src/routes/category.routes.ts
import { Router, Request, Response, NextFunction } from 'express';
import { CategoryDbService } from '../services/db/category.db';

const router = Router();

/**
 * @swagger
 * /api/categories:
 *   get:
 *     summary: List all available grocery categories
 *     description: Returns a list of all predefined grocery categories. Use this endpoint to populate category dropdowns in the UI.
 *     tags: [Categories]
 *     responses:
 *       200:
 *         description: List of categories ordered alphabetically by name
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                   example: true
 *                 data:
 *                   type: array
 *                   items:
 *                     type: object
 *                     properties:
 *                       category_id:
 *                         type: integer
 *                         example: 3
 *                       name:
 *                         type: string
 *                         example: "Dairy & Eggs"
 *                       created_at:
 *                         type: string
 *                         format: date-time
 *                       updated_at:
 *                         type: string
 *                         format: date-time
 *       500:
 *         description: Server error
 */
router.get('/', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const categories = await CategoryDbService.getAllCategories(req.log);

    res.json({
      success: true,
      data: categories,
    });
  } catch (error) {
    next(error);
  }
});

/**
 * @swagger
 * /api/categories/lookup:
 *   get:
 *     summary: Lookup category by name
 *     description: Find a category by its name (case-insensitive). This endpoint is provided for migration support to help clients transition from using category names to category IDs.
 *     tags: [Categories]
 *     parameters:
 *       - in: query
 *         name: name
 *         required: true
 *         schema:
 *           type: string
 *         description: The category name to search for (case-insensitive)
 *         example: "Dairy & Eggs"
 *     responses:
 *       200:
 *         description: Category found
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: object
 *                   properties:
 *                     category_id:
 *                       type: integer
 *                     name:
 *                       type: string
 *       404:
 *         description: Category not found
 *       400:
 *         description: Missing or invalid query parameter
 */
router.get('/lookup', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const name = req.query.name as string;

    if (!name || typeof name !== 'string' || name.trim() === '') {
      return res.status(400).json({
        success: false,
        error: 'Query parameter "name" is required and must be a non-empty string',
      });
    }

    const category = await CategoryDbService.getCategoryByName(name, req.log);

    if (!category) {
      return res.status(404).json({
        success: false,
        error: `Category '${name}' not found`,
      });
    }

    res.json({
      success: true,
      data: category,
    });
  } catch (error) {
    next(error);
  }
});

/**
 * @swagger
 * /api/categories/{id}:
 *   get:
 *     summary: Get a specific category by ID
 *     description: Retrieve detailed information about a single category
 *     tags: [Categories]
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: integer
 *         description: The category ID
 *     responses:
 *       200:
 *         description: Category details
 *         content:
 *           application/json:
 *             schema:
 *               type: object
 *               properties:
 *                 success:
 *                   type: boolean
 *                 data:
 *                   type: object
 *                   properties:
 *                     category_id:
 *                       type: integer
 *                     name:
 *                       type: string
 *                     created_at:
 *                       type: string
 *                       format: date-time
 *                     updated_at:
 *                       type: string
 *                       format: date-time
 *       404:
 *         description: Category not found
 *       400:
 *         description: Invalid category ID
 */
router.get('/:id', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const categoryId = parseInt(req.params.id, 10);

    if (isNaN(categoryId) || categoryId <= 0) {
      return res.status(400).json({
        success: false,
        error: 'Invalid category ID. Must be a positive integer.',
      });
    }

    const category = await CategoryDbService.getCategoryById(categoryId, req.log);

    if (!category) {
      return res.status(404).json({
        success: false,
        error: `Category with ID ${categoryId} not found`,
      });
    }

    res.json({
      success: true,
      data: category,
    });
  } catch (error) {
    next(error);
  }
});

export default router;