feat(users): implement user profile endpoint and related services

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

- Implement user profile 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 user profile features

Author: angoca

docs/USAGE.md

@@ -303,7 +303,65 @@ curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
 
 ### User Profile Endpoint
 
+Get detailed user profile with analytics and statistics.
+
+```bash
+curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
+     http://localhost:3000/api/v1/users/12345
+```
+
+**Response**:
+```json
+{
+  "data": {
+    "dimension_user_id": 123,
+    "user_id": 12345,
+    "username": "example_user",
+    "history_whole_open": 100,
+    "history_whole_closed": 50,
+    "history_whole_commented": 75,
+    "avg_days_to_resolution": 5.5,
+    "resolution_rate": 50.0,
+    "user_response_time": 2.3,
+    "days_since_last_action": 5,
+    "applications_used": [
+      {
+        "application_id": 1,
+        "application_name": "JOSM",
+        "count": 80
+      }
+    ],
+    "collaboration_patterns": {
+      "mentions_given": 10,
+      "mentions_received": 5,
+      "replies_count": 20,
+      "collaboration_score": 0.75
+    },
+    "countries_open_notes": [
+      {
+        "rank": 1,
+        "country": "Colombia",
+        "quantity": 50
+      }
+    ],
+    "hashtags": ["#MapColombia", "#MissingMaps"],
+    "date_starting_creating_notes": "2020-01-15",
+    "date_starting_solving_notes": "2020-02-01",
+    "last_year_activity": null,
+    "working_hours_of_week_opening": [],
+    "activity_by_year": {}
+  }
+}
+```
+
+**Error Responses**:
+- `400 Bad Request`: Invalid user ID format
+- `404 Not Found`: User does not exist
+- `500 Internal Server Error`: Server error
+
+**Example**:
 ```bash
+# Get user profile
 curl -H "User-Agent: MyApp/1.0 (contact@example.com)" \
      http://localhost:3000/api/v1/users/12345
 ```

src/controllers/usersController.ts

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

src/routes/index.ts

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

src/routes/users.ts

@@ -0,0 +1,26 @@
+/**
+ * Users routes
+ */
+
+import { Router, Request, Response, NextFunction } from 'express';
+import * as usersController from '../controllers/usersController';
+
+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/users/:user_id
+ * @desc    Get user profile by ID
+ * @access  Public
+ */
+router.get('/:user_id', asyncHandler(usersController.getUserProfile));
+
+export default router;

src/services/userService.ts

@@ -0,0 +1,153 @@
+/**
+ * User service
+ * Handles business logic for user operations
+ */
+
+import { getDatabasePool } from '../config/database';
+import { logger } from '../utils/logger';
+import { ApiError } from '../middleware/errorHandler';
+import { UserProfile } from '../types';
+
+/**
+ * Database row type for user query result
+ */
+interface UserRow {
+  dimension_user_id: number;
+  user_id: number;
+  username: string | null;
+  history_whole_open: number | string;
+  history_whole_closed: number | string;
+  history_whole_commented: number | string;
+  avg_days_to_resolution: number | string | null;
+  resolution_rate: number | string | null;
+  user_response_time: number | string | null;
+  days_since_last_action: number | string | null;
+  applications_used?: unknown;
+  collaboration_patterns?: unknown;
+  countries_open_notes?: unknown;
+  hashtags?: unknown;
+  date_starting_creating_notes?: Date | string | null;
+  date_starting_solving_notes?: Date | string | null;
+  last_year_activity?: string | null;
+  working_hours_of_week_opening?: unknown;
+  activity_by_year?: unknown;
+}
+
+/**
+ * Get user profile by user ID
+ * @param userId - The user ID
+ * @returns The user profile object
+ * @throws ApiError with 404 if user not found
+ * @throws ApiError with 500 if database error occurs
+ */
+export async function getUserProfile(userId: number): Promise<UserProfile> {
+  const pool = getDatabasePool();
+
+  try {
+    const query = `
+      SELECT 
+        dimension_user_id,
+        user_id,
+        username,
+        history_whole_open,
+        history_whole_closed,
+        history_whole_commented,
+        avg_days_to_resolution,
+        resolution_rate,
+        user_response_time,
+        days_since_last_action,
+        applications_used,
+        collaboration_patterns,
+        countries_open_notes,
+        hashtags,
+        date_starting_creating_notes,
+        date_starting_solving_notes,
+        last_year_activity,
+        working_hours_of_week_opening,
+        activity_by_year
+      FROM dwh.datamartUsers
+      WHERE user_id = $1
+    `;
+
+    logger.debug('Executing query to get user profile', { userId });
+
+    const result = await pool.query<UserRow>(query, [userId]);
+
+    if (result.rows.length === 0) {
+      logger.warn('User not found', { userId });
+      throw new ApiError(404, 'User not found');
+    }
+
+    const row = result.rows[0];
+
+    // Convert numeric fields from string to number if needed
+    const userProfile: UserProfile = {
+      dimension_user_id: row.dimension_user_id,
+      user_id: row.user_id,
+      username: row.username,
+      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,
+      history_whole_commented:
+        typeof row.history_whole_commented === 'string'
+          ? parseInt(row.history_whole_commented, 10)
+          : row.history_whole_commented,
+      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,
+      user_response_time:
+        row.user_response_time === null
+          ? null
+          : typeof row.user_response_time === 'string'
+            ? parseFloat(row.user_response_time)
+            : row.user_response_time,
+      days_since_last_action:
+        row.days_since_last_action === null
+          ? null
+          : typeof row.days_since_last_action === 'string'
+            ? parseInt(row.days_since_last_action, 10)
+            : row.days_since_last_action,
+      applications_used: row.applications_used,
+      collaboration_patterns: row.collaboration_patterns,
+      countries_open_notes: row.countries_open_notes,
+      hashtags: row.hashtags,
+      date_starting_creating_notes: row.date_starting_creating_notes,
+      date_starting_solving_notes: row.date_starting_solving_notes,
+      last_year_activity: row.last_year_activity,
+      working_hours_of_week_opening: row.working_hours_of_week_opening,
+      activity_by_year: row.activity_by_year,
+    };
+
+    logger.debug('User profile retrieved successfully', {
+      userId,
+      username: userProfile.username,
+    });
+
+    return userProfile;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+
+    logger.error('Error getting user profile', {
+      userId,
+      error: error instanceof Error ? error.message : String(error),
+    });
+
+    throw new ApiError(500, 'Internal server error');
+  }
+}

src/types/index.ts

@@ -69,3 +69,28 @@ export interface SearchResult<T> {
   pagination: Pagination;
   filters?: Partial<SearchFilters>;
 }
+
+/**
+ * User profile from datamartUsers
+ */
+export interface UserProfile {
+  dimension_user_id: number;
+  user_id: number;
+  username: string | null;
+  history_whole_open: number;
+  history_whole_closed: number;
+  history_whole_commented: number;
+  avg_days_to_resolution: number | null;
+  resolution_rate: number | null;
+  user_response_time: number | null;
+  days_since_last_action: number | null;
+  applications_used?: unknown; // JSON array
+  collaboration_patterns?: unknown; // JSON object
+  countries_open_notes?: unknown; // JSON array
+  hashtags?: unknown; // JSON array (string[])
+  date_starting_creating_notes?: Date | string | null;
+  date_starting_solving_notes?: Date | string | null;
+  last_year_activity?: string | null;
+  working_hours_of_week_opening?: unknown; // JSON array (number[])
+  activity_by_year?: unknown; // JSON object
+}