feat(notes): implement notes management endpoints and services

- Add endpoints for retrieving notes by ID, fetching comments for a note,
  and searching notes with filters

- Implement corresponding controller and service logic to handle business
  operations for notes

- Enhance documentation in USAGE.md to include detailed usage examples
  for new notes endpoints

- Introduce integration and unit tests to ensure functionality and
  reliability of notes management features

Author: angoca

docs/USAGE.md

@@ -134,27 +134,187 @@ curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
 
 ## Usage Examples
 
-### Get User Profile
+### Notes Endpoints
+
+#### Get Note by ID
+
+Get detailed information about a specific note.
 
 ```bash
 curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
-     http://localhost:3000/api/v1/users/12345
+     http://localhost:3000/api/v1/notes/12345
+```
+
+**Response**:
+```json
+{
+  "data": {
+    "note_id": 12345,
+    "latitude": 4.6097,
+    "longitude": -74.0817,
+    "status": "open",
+    "created_at": "2024-01-15T10:30:00Z",
+    "closed_at": null,
+    "id_user": 67890,
+    "id_country": 42,
+    "comments_count": 3
+  }
+}
 ```
 
-### Get Country Profile
+**Error Responses**:
+- `400 Bad Request`: Invalid note ID format
+- `404 Not Found`: Note does not exist
+- `500 Internal Server Error`: Server error
+
+#### Get Note Comments
+
+Get all comments for a specific note.
 
 ```bash
 curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
-     http://localhost:3000/api/v1/countries/CO
+     http://localhost:3000/api/v1/notes/12345/comments
+```
+
+**Response**:
+```json
+{
+  "data": [
+    {
+      "comment_id": 1,
+      "note_id": 12345,
+      "user_id": 67890,
+      "username": "test_user",
+      "action": "opened",
+      "created_at": "2024-01-15T10:30:00Z",
+      "text": "This is a test note"
+    },
+    {
+      "comment_id": 2,
+      "note_id": 12345,
+      "user_id": 67891,
+      "username": "another_user",
+      "action": "commented",
+      "created_at": "2024-01-15T11:00:00Z",
+      "text": "I can help with this"
+    }
+  ],
+  "count": 2
+}
 ```
 
-### Search Notes
+**Error Responses**:
+- `400 Bad Request`: Invalid note ID format
+- `500 Internal Server Error`: Server error
+
+#### Search Notes
 
+Search notes with various filters and pagination.
+
+**Basic Search**:
 ```bash
 curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
      "http://localhost:3000/api/v1/notes?status=open&limit=10"
 ```
 
+**With Filters**:
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     "http://localhost:3000/api/v1/notes?country=42&status=open&date_from=2024-01-01&date_to=2024-12-31&page=1&limit=20"
+```
+
+**Query Parameters**:
+- `country` (number): Filter by country ID
+- `status` (string): Filter by status (`open`, `closed`, `reopened`)
+- `user_id` (number): Filter by user ID
+- `date_from` (string): Filter notes created from this date (ISO format: `YYYY-MM-DD`)
+- `date_to` (string): Filter notes created until this date (ISO format: `YYYY-MM-DD`)
+- `bbox` (string): Filter by bounding box (format: `min_lon,min_lat,max_lon,max_lat`)
+- `page` (number): Page number (default: 1, minimum: 1)
+- `limit` (number): Results per page (default: 20, maximum: 100, minimum: 1)
+
+**Response**:
+```json
+{
+  "data": [
+    {
+      "note_id": 12345,
+      "latitude": 4.6097,
+      "longitude": -74.0817,
+      "status": "open",
+      "created_at": "2024-01-15T10:30:00Z",
+      "closed_at": null,
+      "id_user": 67890,
+      "id_country": 42,
+      "comments_count": 3
+    },
+    {
+      "note_id": 12346,
+      "latitude": 4.6100,
+      "longitude": -74.0820,
+      "status": "open",
+      "created_at": "2024-01-16T10:30:00Z",
+      "closed_at": null,
+      "id_user": 67891,
+      "id_country": 42,
+      "comments_count": 1
+    }
+  ],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 250,
+    "total_pages": 13
+  },
+  "filters": {
+    "country": 42,
+    "status": "open",
+    "date_from": "2024-01-01",
+    "date_to": "2024-12-31",
+    "page": 1,
+    "limit": 20
+  }
+}
+```
+
+**Error Responses**:
+- `400 Bad Request`: Invalid parameters (invalid status, invalid page/limit values)
+- `500 Internal Server Error`: Server error
+
+**Examples**:
+
+Search open notes in Colombia:
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     "http://localhost:3000/api/v1/notes?country=42&status=open"
+```
+
+Search notes by user:
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     "http://localhost:3000/api/v1/notes?user_id=67890"
+```
+
+Search notes in a bounding box:
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     "http://localhost:3000/api/v1/notes?bbox=-74.1,4.6,-74.0,4.7"
+```
+
+### User Profile Endpoint
+
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     http://localhost:3000/api/v1/users/12345
+```
+
+### Country Profile Endpoint
+
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     http://localhost:3000/api/v1/countries/CO
+```
+
 ## Error Handling
 
 ### HTTP Status Codes

src/controllers/notesController.ts

@@ -0,0 +1,109 @@
+/**
+ * Notes controller
+ * Handles HTTP requests for notes endpoints
+ */
+
+import { Request, Response, NextFunction } from 'express';
+import * as noteService from '../services/noteService';
+import { logger } from '../utils/logger';
+import { ApiError } from '../middleware/errorHandler';
+import { SearchFilters } from '../types';
+
+/**
+ * Get a note by ID
+ * GET /api/v1/notes/:note_id
+ */
+export async function getNoteById(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const noteId = parseInt(req.params.note_id, 10);
+
+    if (isNaN(noteId) || noteId <= 0) {
+      throw new ApiError(400, 'Invalid note ID');
+    }
+
+    logger.debug('Getting note by ID', { noteId });
+
+    const note = await noteService.getNoteById(noteId);
+
+    res.json({
+      data: note,
+    });
+  } catch (error) {
+    next(error);
+  }
+}
+
+/**
+ * Get comments for a note
+ * GET /api/v1/notes/:note_id/comments
+ */
+export async function getNoteComments(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): Promise<void> {
+  try {
+    const noteId = parseInt(req.params.note_id, 10);
+
+    if (isNaN(noteId) || noteId <= 0) {
+      throw new ApiError(400, 'Invalid note ID');
+    }
+
+    logger.debug('Getting note comments', { noteId });
+
+    const comments = await noteService.getNoteComments(noteId);
+
+    res.json({
+      data: comments,
+      count: comments.length,
+    });
+  } catch (error) {
+    next(error);
+  }
+}
+
+/**
+ * Search notes with filters
+ * GET /api/v1/notes
+ */
+export async function searchNotes(req: Request, res: Response, next: NextFunction): Promise<void> {
+  try {
+    const filters: SearchFilters = {
+      country: req.query.country ? parseInt(String(req.query.country), 10) : undefined,
+      status: req.query.status as 'open' | 'closed' | 'reopened' | undefined,
+      hashtag: req.query.hashtag ? String(req.query.hashtag) : undefined,
+      date_from: req.query.date_from ? String(req.query.date_from) : undefined,
+      date_to: req.query.date_to ? String(req.query.date_to) : undefined,
+      user_id: req.query.user_id ? parseInt(String(req.query.user_id), 10) : undefined,
+      application: req.query.application ? String(req.query.application) : undefined,
+      bbox: req.query.bbox ? String(req.query.bbox) : undefined,
+      page: req.query.page ? parseInt(String(req.query.page), 10) : 1,
+      limit: req.query.limit ? parseInt(String(req.query.limit), 10) : 20,
+    };
+
+    // Validate page and limit
+    if (filters.page !== undefined && (isNaN(filters.page) || filters.page < 1)) {
+      throw new ApiError(400, 'Invalid page number');
+    }
+
+    if (
+      filters.limit !== undefined &&
+      (isNaN(filters.limit) || filters.limit < 1 || filters.limit > 100)
+    ) {
+      throw new ApiError(400, 'Invalid limit (must be between 1 and 100)');
+    }
+
+    // Validate status if provided
+    if (filters.status && !['open', 'closed', 'reopened'].includes(filters.status)) {
+      throw new ApiError(400, 'Invalid status (must be open, closed, or reopened)');
+    }
+
+    logger.debug('Searching notes', { filters });
+
+    const result = await noteService.searchNotes(filters);
+
+    res.json(result);
+  } catch (error) {
+    next(error);
+  }
+}

src/routes/index.ts

@@ -5,6 +5,7 @@
 import { Router } from 'express';
 import { getAppConfig } from '../config/app';
 import healthRouter from './health';
+import notesRouter from './notes';
 
 const router = Router();
 const { apiVersion } = getAppConfig();
@@ -26,4 +27,9 @@ router.get(`/api/${apiVersion}`, (_req, res) => {
  */
 router.use('/health', healthRouter);
 
+/**
+ * Notes routes
+ */
+router.use(`/api/${apiVersion}/notes`, notesRouter);
+
 export default router;

src/routes/notes.ts

@@ -0,0 +1,40 @@
+/**
+ * Notes routes
+ */
+
+import { Router, Request, Response, NextFunction } from 'express';
+import * as notesController from '../controllers/notesController';
+
+const router = Router();
+
+/**
+ * Async wrapper for route handlers
+ */
+function asyncHandler(fn: (req: Request, res: Response, next: NextFunction) => Promise<void>) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    void Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+/**
+ * @route   GET /api/v1/notes
+ * @desc    Search notes with filters
+ * @access  Public
+ */
+router.get('/', asyncHandler(notesController.searchNotes));
+
+/**
+ * @route   GET /api/v1/notes/:note_id
+ * @desc    Get a note by ID
+ * @access  Public
+ */
+router.get('/:note_id', asyncHandler(notesController.getNoteById));
+
+/**
+ * @route   GET /api/v1/notes/:note_id/comments
+ * @desc    Get comments for a note
+ * @access  Public
+ */
+router.get('/:note_id/comments', asyncHandler(notesController.getNoteComments));
+
+export default router;