feat(countries): implement country profile endpoint and related services

- Add endpoint to retrieve country profile by ID, including detailed
  analytics and statistics

- Implement countries controller and service logic to handle
  data retrieval from the database

- Enhance documentation in USAGE.md with usage examples
  and error response structures for the new endpoint

- Introduce integration and unit tests to ensure functionality
  and reliability of country profile features

Author: angoca

docs/USAGE.md

@@ -368,9 +368,58 @@ curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
 
 ### Country Profile Endpoint
 
+Get detailed country profile with analytics and statistics.
+
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     http://localhost:3000/api/v1/countries/42
+```
+
+**Response**:
+```json
+{
+  "data": {
+    "dimension_country_id": 45,
+    "country_id": 42,
+    "country_name": "Colombia",
+    "country_name_en": "Colombia",
+    "country_name_es": "Colombia",
+    "iso_alpha2": "CO",
+    "history_whole_open": 1000,
+    "history_whole_closed": 800,
+    "avg_days_to_resolution": 7.2,
+    "resolution_rate": 80.0,
+    "notes_health_score": 75.5,
+    "new_vs_resolved_ratio": 1.2,
+    "notes_backlog_size": 50,
+    "notes_created_last_30_days": 100,
+    "notes_resolved_last_30_days": 80,
+    "users_open_notes": [
+      {
+        "rank": 1,
+        "user_id": 12345,
+        "username": "top_user",
+        "quantity": 50
+      }
+    ],
+    "applications_used": [],
+    "hashtags": [],
+    "activity_by_year": {},
+    "working_hours_of_week_opening": []
+  }
+}
+```
+
+**Error Responses**:
+- `400 Bad Request`: Invalid country ID format
+- `404 Not Found`: Country does not exist
+- `500 Internal Server Error`: Server error
+
+**Example**:
 ```bash
+# Get country profile
 curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
-     http://localhost:3000/api/v1/countries/CO
+     http://localhost:3000/api/v1/countries/42
 ```
 
 ## Error Handling

src/controllers/countriesController.ts

@@ -0,0 +1,37 @@
+/**
+ * Countries controller
+ * Handles HTTP requests for countries endpoints
+ */
+
+import { Request, Response, NextFunction } from 'express';
+import * as countryService from '../services/countryService';
+import { logger } from '../utils/logger';
+import { ApiError } from '../middleware/errorHandler';
+
+/**
+ * Get country profile by ID
+ * GET /api/v1/countries/:country_id
+ */
+export async function getCountryProfile(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): Promise<void> {
+  try {
+    const countryId = parseInt(req.params.country_id, 10);
+
+    if (isNaN(countryId) || countryId <= 0) {
+      throw new ApiError(400, 'Invalid country ID');
+    }
+
+    logger.debug('Getting country profile by ID', { countryId });
+
+    const countryProfile = await countryService.getCountryProfile(countryId);
+
+    res.json({
+      data: countryProfile,
+    });
+  } catch (error) {
+    next(error);
+  }
+}

src/routes/countries.ts

@@ -0,0 +1,26 @@
+/**
+ * Countries routes
+ */
+
+import { Router, Request, Response, NextFunction } from 'express';
+import * as countriesController from '../controllers/countriesController';
+
+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/countries/:country_id
+ * @desc    Get country profile by ID
+ * @access  Public
+ */
+router.get('/:country_id', asyncHandler(countriesController.getCountryProfile));
+
+export default router;

src/routes/index.ts

@@ -7,6 +7,7 @@ import { getAppConfig } from '../config/app';
 import healthRouter from './health';
 import notesRouter from './notes';
 import usersRouter from './users';
+import countriesRouter from './countries';
 
 const router = Router();
 const { apiVersion } = getAppConfig();
@@ -38,4 +39,9 @@ router.use(`/api/${apiVersion}/notes`, notesRouter);
  */
 router.use(`/api/${apiVersion}/users`, usersRouter);
 
+/**
+ * Countries routes
+ */
+router.use(`/api/${apiVersion}/countries`, countriesRouter);
+
 export default router;

src/services/countryService.ts

@@ -0,0 +1,168 @@
+/**
+ * Country service
+ * Handles business logic for country operations
+ */
+
+import { getDatabasePool } from '../config/database';
+import { logger } from '../utils/logger';
+import { ApiError } from '../middleware/errorHandler';
+import { CountryProfile } from '../types';
+
+/**
+ * Database row type for country query result
+ */
+interface CountryRow {
+  dimension_country_id: number;
+  country_id: number;
+  country_name: string | null;
+  country_name_en: string | null;
+  country_name_es: string | null;
+  iso_alpha2: string | null;
+  history_whole_open: number | string;
+  history_whole_closed: number | string;
+  avg_days_to_resolution: number | string | null;
+  resolution_rate: number | string | null;
+  notes_health_score: number | string | null;
+  new_vs_resolved_ratio: number | string | null;
+  notes_backlog_size: number | string | null;
+  notes_created_last_30_days: number | string | null;
+  notes_resolved_last_30_days: number | string | null;
+  users_open_notes?: unknown;
+  applications_used?: unknown;
+  hashtags?: unknown;
+  activity_by_year?: unknown;
+  working_hours_of_week_opening?: unknown;
+}
+
+/**
+ * Get country profile by country ID
+ * @param countryId - The country ID
+ * @returns The country profile object
+ * @throws ApiError with 404 if country not found
+ * @throws ApiError with 500 if database error occurs
+ */
+export async function getCountryProfile(countryId: number): Promise<CountryProfile> {
+  const pool = getDatabasePool();
+
+  try {
+    const query = `
+      SELECT 
+        dimension_country_id,
+        country_id,
+        country_name,
+        country_name_en,
+        country_name_es,
+        iso_alpha2,
+        history_whole_open,
+        history_whole_closed,
+        avg_days_to_resolution,
+        resolution_rate,
+        notes_health_score,
+        new_vs_resolved_ratio,
+        notes_backlog_size,
+        notes_created_last_30_days,
+        notes_resolved_last_30_days,
+        users_open_notes,
+        applications_used,
+        hashtags,
+        activity_by_year,
+        working_hours_of_week_opening
+      FROM dwh.datamartCountries
+      WHERE country_id = $1
+    `;
+
+    logger.debug('Executing query to get country profile', { countryId });
+
+    const result = await pool.query<CountryRow>(query, [countryId]);
+
+    if (result.rows.length === 0) {
+      logger.warn('Country not found', { countryId });
+      throw new ApiError(404, 'Country not found');
+    }
+
+    const row = result.rows[0];
+
+    // Convert numeric fields from string to number if needed
+    const countryProfile: CountryProfile = {
+      dimension_country_id: row.dimension_country_id,
+      country_id: row.country_id,
+      country_name: row.country_name,
+      country_name_en: row.country_name_en,
+      country_name_es: row.country_name_es,
+      iso_alpha2: row.iso_alpha2,
+      history_whole_open:
+        typeof row.history_whole_open === 'string'
+          ? parseInt(row.history_whole_open, 10)
+          : row.history_whole_open,
+      history_whole_closed:
+        typeof row.history_whole_closed === 'string'
+          ? parseInt(row.history_whole_closed, 10)
+          : row.history_whole_closed,
+      avg_days_to_resolution:
+        row.avg_days_to_resolution === null
+          ? null
+          : typeof row.avg_days_to_resolution === 'string'
+            ? parseFloat(row.avg_days_to_resolution)
+            : row.avg_days_to_resolution,
+      resolution_rate:
+        row.resolution_rate === null
+          ? null
+          : typeof row.resolution_rate === 'string'
+            ? parseFloat(row.resolution_rate)
+            : row.resolution_rate,
+      notes_health_score:
+        row.notes_health_score === null
+          ? null
+          : typeof row.notes_health_score === 'string'
+            ? parseFloat(row.notes_health_score)
+            : row.notes_health_score,
+      new_vs_resolved_ratio:
+        row.new_vs_resolved_ratio === null
+          ? null
+          : typeof row.new_vs_resolved_ratio === 'string'
+            ? parseFloat(row.new_vs_resolved_ratio)
+            : row.new_vs_resolved_ratio,
+      notes_backlog_size:
+        row.notes_backlog_size === null
+          ? null
+          : typeof row.notes_backlog_size === 'string'
+            ? parseInt(row.notes_backlog_size, 10)
+            : row.notes_backlog_size,
+      notes_created_last_30_days:
+        row.notes_created_last_30_days === null
+          ? null
+          : typeof row.notes_created_last_30_days === 'string'
+            ? parseInt(row.notes_created_last_30_days, 10)
+            : row.notes_created_last_30_days,
+      notes_resolved_last_30_days:
+        row.notes_resolved_last_30_days === null
+          ? null
+          : typeof row.notes_resolved_last_30_days === 'string'
+            ? parseInt(row.notes_resolved_last_30_days, 10)
+            : row.notes_resolved_last_30_days,
+      users_open_notes: row.users_open_notes,
+      applications_used: row.applications_used,
+      hashtags: row.hashtags,
+      activity_by_year: row.activity_by_year,
+      working_hours_of_week_opening: row.working_hours_of_week_opening,
+    };
+
+    logger.debug('Country profile retrieved successfully', {
+      countryId,
+      countryName: countryProfile.country_name,
+    });
+
+    return countryProfile;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+
+    logger.error('Error getting country profile', {
+      countryId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    throw new ApiError(500, 'Internal server error');
+  }
+}

src/types/index.ts

@@ -94,3 +94,29 @@ export interface UserProfile {
   working_hours_of_week_opening?: unknown; // JSON array (number[])
   activity_by_year?: unknown; // JSON object
 }
+
+/**
+ * Country profile from datamartCountries
+ */
+export interface CountryProfile {
+  dimension_country_id: number;
+  country_id: number;
+  country_name: string | null;
+  country_name_en: string | null;
+  country_name_es: string | null;
+  iso_alpha2: string | null;
+  history_whole_open: number;
+  history_whole_closed: number;
+  avg_days_to_resolution: number | null;
+  resolution_rate: number | null;
+  notes_health_score: number | null;
+  new_vs_resolved_ratio: number | null;
+  notes_backlog_size: number | null;
+  notes_created_last_30_days: number | null;
+  notes_resolved_last_30_days: number | null;
+  users_open_notes?: unknown; // JSON array
+  applications_used?: unknown; // JSON array
+  hashtags?: unknown; // JSON array (string[])
+  activity_by_year?: unknown; // JSON object
+  working_hours_of_week_opening?: unknown; // JSON array (number[])
+}