Archivos de la Carpeta src/utils #

import { Request, Response, NextFunction, RequestHandler } from "express";

/**
 * asyncHandler
 * Esta función de utilidad se encarga de envolver funciones asíncronas de Express
 * (controladores o middlewares) para capturar automáticamente cualquier error
 * y pasarlo al siguiente middleware de manejo de errores de Express.
 * Esto evita la necesidad de escribir bloques try-catch repetitivos en cada función asíncrona.
 *
 * @param fn La función asíncrona de Express (req, res, next) que queremos envolver.
 * @returns Una función RequestHandler compatible con Express que maneja los errores.
 */
export const asyncHandler = (
  fn: (req: Request, res: Response, next: NextFunction) => Promise<void>
): RequestHandler => {
  // Retorna una nueva función RequestHandler.
  return (req, res, next) => {
    // Ejecuta la función asíncrona original.
    // Si la promesa resultante se rechaza (es decir, ocurre un error),
    // el error es capturado por .catch() y se pasa a la función 'next()',
    // lo que permite que el middleware global de manejo de errores lo procese.
    fn(req, res, next).catch(next);
  };
};

import jwt from "jsonwebtoken"; // Importa la librería jsonwebtoken para trabajar con JWTs

// Intenta obtener el secreto de JWT de las variables de entorno.
// Esto es crucial para la seguridad, ya que la clave secreta no debe estar hardcodeada.
const secret = process.env.JWT_SECRET;

// Verifica si la clave secreta se ha proporcionado.
// Si no está definida, lanza un error, deteniendo la aplicación,
// ya que la generación y verificación de tokens no sería segura.
if (!secret) {
  throw new Error("JWT_SECRET must be provided");
}

/**
 * generateAccessToken
 * Genera un JSON Web Token (JWT) con el email y el UID del usuario.
 * @param email El correo electrónico del usuario.
 * @param uid El ID único del usuario.
 * @returns El token de acceso JWT firmado.
 */
export const generateAccessToken = (email: string, uid: string) => {
  return jwt.sign({ email, uid }, secret, {
    expiresIn: "24h", // El token expirará después de 24 horas para mayor seguridad.
  });
};

/**
 * verifyAccessToken
 * Verifica y decodifica un JSON Web Token (JWT).
 * @param token El token JWT a verificar.
 * @returns El payload decodificado del JWT si es válido.
 * @throws Si el token es inválido, ha expirado, o la firma no coincide.
 */
export const verifyAccessToken = (token: string) => {
  // Verifica el token utilizando la clave secreta.
  // El 'as jwt.JwtPayload' es para informar a TypeScript el tipo del payload esperado.
  return jwt.verify(token, secret) as jwt.JwtPayload;
};

import { User } from "../models/user.model"; // Importa el modelo User para interactuar con la tabla de usuarios

/**
 * getUserEmail
 * Busca un usuario por su ID en la base de datos y retorna su dirección de correo electrónico.
 *
 * @param userId El ID único del usuario a buscar.
 * @returns Una Promise que resuelve con la dirección de correo electrónico del usuario (string)
 * o null si el usuario no se encuentra o si ocurre un error.
 */
export const getUserEmail = async (userId: string): Promise<string | null> => {
  try {
    // Intenta encontrar un usuario en la base de datos por el ID proporcionado.
    const user = await User.findOne({
      where: {
        id: userId,
      },
    });

    // Si se encuentra el usuario, retorna su email.
    if (user) {
      return user.email;
    } else {
      // Si no se encuentra el usuario, retorna null.
      return null;
    }
  } catch (error) {
    // Si ocurre cualquier error durante la consulta a la base de datos,
    // registra el error (opcionalmente) y retorna null para indicar que no se pudo obtener el email.
    // console.error("Error al obtener el email del usuario:", error); // Podrías agregar un logger aquí
    return null;
  }
};

/**
 * HttpError
 * Clase de error personalizada que extiende la clase 'Error' nativa de JavaScript.
 * Esta clase permite asociar un código de estado HTTP específico a un error,
 * lo que facilita el manejo de errores semánticos en una API REST.
 */
export class HttpError extends Error {
  /**
   * Constructor de HttpError.
   * @param message El mensaje descriptivo del error.
   * @param code El código de estado HTTP asociado a este error (ej., 400, 404, 500).
   */
  constructor(message: string, public code: number) {
    // Llama al constructor de la clase base (Error) con el mensaje.
    super(message);

    // Captura la pila de llamadas (stack trace) para este error.
    // Esto es útil para la depuración, ya que el stack trace comenzará desde el punto
    // donde se lanzó el HttpError, en lugar de desde el constructor de la clase Error.
    Error.captureStackTrace(this, this.constructor);
  }
}

// Importa los módulos necesarios
import path from "path"; // Para trabajar con rutas de archivos y directorios
import winston from "winston"; // Librería para manejar logs en Node.js

// Obtiene el directorio actual del archivo utilizando `import.meta.dirname`.
// Esto es una característica moderna de ES Modules en Node.js para obtener la ruta del directorio.
const __dirname = import.meta.dirname;

// Define la ruta completa del archivo donde se guardarán los logs.
// La ruta es relativa al directorio actual y apunta a un archivo llamado "app.log"
// dentro de la carpeta "logs" que se encuentra dos niveles arriba (fuera de src).
const logFilePath = path.join(__dirname, "../../logs/app.log");

// Configura el logger utilizando la librería winston.
const logger = winston.createLogger({
  // Establece el nivel mínimo de logs que se registrarán.
  // Solo los mensajes con nivel 'info' o superior (warn, error) serán procesados.
  level: "info",

  // Define el formato de los logs. Se combinan varios formatos:
  format: winston.format.combine(
    winston.format.timestamp(), // Agrega una marca de tiempo a cada mensaje de log.
    // Define un formato personalizado para la salida del log.
    // Incluye la marca de tiempo, el nivel del mensaje (en mayúsculas) y el contenido del mensaje.
    winston.format.printf(({ timestamp, level, message }) => {
      return `${timestamp} [${level.toUpperCase()}]: ${message}`;
    })
  ),

  // Configura los "transports" (lugares o medios donde se envían los logs).
  transports: [
    // Transport para la consola: los logs se mostrarán en la terminal.
    new winston.transports.Console({
      // Formato específico para la consola para una mejor legibilidad:
      format: winston.format.combine(
        winston.format.colorize(), // Colorea los niveles de los logs (ej. errores en rojo).
        winston.format.simple() // Utiliza un formato de mensaje más compacto para la consola.
      ),
    }),

    // Transport para el archivo: los logs se guardarán en un archivo.
    new winston.transports.File({ filename: logFilePath }),
    // Todos los mensajes que cumplan con el 'level' mínimo se escribirán en el archivo "app.log".
  ],
});

// Exporta la instancia del logger para que pueda ser importada y utilizada
// en cualquier otro módulo de la aplicación para registrar eventos.
export default logger;

// Ejemplo de uso (una vez importado en otro módulo):
// import logger from "../utils/logger.util";
// logger.info("Este es un mensaje informativo de la aplicación.");
// logger.error("Se ha producido un error crítico:", new Error("Algo salió mal."));

// utils/student.util.ts
import { MulterRequest } from "../interfaces/express.interface"; // Interfaz para solicitudes con archivos de Multer
import {
  uploadFileToDrive, // Función para subir archivos a Google Drive
  setFilePublic, // Función para hacer públicos los archivos en Google Drive
} from "../services/google.drive.service"; // Importa el servicio de Google Drive
import fs from "fs"; // Módulo de Node.js para operaciones de sistema de archivos
import path from "path"; // Módulo de Node.js para trabajar con rutas de archivos y directorios
import { DateTime } from "luxon"; // Librería para el manejo avanzado de fechas

/**
 * transformStringsToUppercase
 * Transforma recursivamente todas las propiedades de tipo string dentro de un objeto
 * a mayúsculas. Ignora los valores "undefined" que sean strings.
 *
 * @param obj El objeto a transformar.
 * @returns Un nuevo objeto con todas las cadenas transformadas a mayúsculas.
 */
export function transformStringsToUppercase(obj: any): any {
  // Si el valor no es un objeto o es null, se retorna tal cual.
  if (typeof obj !== "object" || obj === null) {
    return obj;
  }

  const transformedObj: any = {};
  // Itera sobre las propiedades del objeto.
  for (const key in obj) {
    // Asegura que la propiedad sea propia del objeto (no heredada).
    if (Object.prototype.hasOwnProperty.call(obj, key)) {
      const value = obj[key];
      // Si el valor es una cadena y no es la cadena literal "undefined".
      if (typeof value === "string" && value !== "undefined") {
        transformedObj[key] = value.toUpperCase(); // Convierte a mayúsculas.
      } else if (typeof value === "object" && value !== null) {
        // Si el valor es un objeto (no null), se llama recursivamente a la función.
        transformedObj[key] = transformStringsToUppercase(value);
      } else {
        // Para cualquier otro tipo de valor, se copia tal cual.
        transformedObj[key] = value;
      }
    }
  }
  return transformedObj;
}

/**
 * handleFileUpload
 * Función interna para subir un archivo temporal de Multer a Google Drive,
 * hacerlo público y luego eliminar el archivo local.
 *
 * @param file El objeto de archivo de Multer (Express.Multer.File).
 * @returns Un objeto con el enlace web y el ID del archivo en Google Drive, o null si falla.
 */
const handleFileUpload = async (file: Express.Multer.File) => {
  try {
    // Construye la ruta completa del archivo temporal.
    const filePath = path.join("uploads", file.filename);

    // Sube el archivo a Google Drive.
    const uploadedFile = await uploadFileToDrive(filePath, file.filename);

    // Hace el archivo público en Google Drive.
    await setFilePublic(uploadedFile.id ?? ""); // Usa el operador '??' para manejar el caso de ID nulo/indefinido.

    // Elimina el archivo temporal del sistema de archivos local de forma síncrona.
    fs.unlinkSync(filePath);

    // Retorna el enlace y el ID del archivo subido en Google Drive.
    return {
      link: uploadedFile.webViewLink || uploadedFile.webContentLink,
      id: uploadedFile.id,
    };
  } catch (error) {
    // En caso de error, se registra (opcionalmente) y se retorna null.
    // console.error("Error al procesar la subida de archivo:", error);
    return null;
  }
};

/**
 * processStudentFiles
 * Procesa los archivos adjuntos en una solicitud de Multer (para estudiantes),
 * subiéndolos a Google Drive y retornando sus enlaces e IDs.
 *
 * @param req La solicitud Express extendida por Multer (MulterRequest).
 * @returns Una Promise que resuelve con un objeto conteniendo los enlaces e IDs
 * de los archivos subidos, o null si un archivo no se subió.
 */
export const processStudentFiles = async (
  req: MulterRequest
): Promise<{
  studentImage?: { link: string | null; id: string | null };
  birthCertificate?: { link: string | null; id: string | null };
  studyCertificate?: { link: string | null; id: string | null };
  linkDni?: { link: string | null; id: string | null };
}> => {
  // Accede a los archivos subidos por Multer.
  const files = req.files as
    | { [fieldname: string]: Express.Multer.File[] } // Define el tipo de 'files' de Multer
    | undefined;

  // Objeto para almacenar los enlaces e IDs de los archivos subidos.
  const uploadedFiles: {
    studentImage?: { link: string | null; id: string | null };
    birthCertificate?: { link: string | null; id: string | null };
    studyCertificate?: { link: string | null; id: string | null };
    linkDni?: { link: string | null; id: string | null };
  } = {};

  // Procesa cada tipo de archivo si está presente.
  // Para 'studentImage':
  if (files?.["studentImage"]?.[0]) {
    const uploaded = await handleFileUpload(files["studentImage"][0]);
    uploadedFiles.studentImage = {
      link: uploaded?.link ?? null,
      id: uploaded?.id ?? null,
    };
  } else {
    uploadedFiles.studentImage = { link: null, id: null }; // Si no hay archivo, se establece a null.
  }

  // Para 'birthCertificate':
  if (files?.["birthCertificate"]?.[0]) {
    const uploaded = await handleFileUpload(files["birthCertificate"][0]);
    uploadedFiles.birthCertificate = {
      link: uploaded?.link ?? null,
      id: uploaded?.id ?? null,
    };
  } else {
    uploadedFiles.birthCertificate = { link: null, id: null };
  }

  // Para 'studyCertificate':
  if (files?.["studyCertificate"]?.[0]) {
    const uploaded = await handleFileUpload(files["studyCertificate"][0]);
    uploadedFiles.studyCertificate = {
      link: uploaded?.link ?? null,
      id: uploaded?.id ?? null,
    };
  } else {
    uploadedFiles.studyCertificate = { link: null, id: null };
  }

  // Para 'linkDni':
  if (files?.["linkDni"]?.[0]) {
    const uploaded = await handleFileUpload(files["linkDni"][0]);
    uploadedFiles.linkDni = {
      link: uploaded?.link ?? null,
      id: uploaded?.id ?? null,
    };
  } else {
    uploadedFiles.linkDni = { link: null, id: null };
  }

  return uploadedFiles; // Retorna el objeto con los datos de los archivos subidos.
};

/**
 * normalizeStudentData
 * Normaliza los datos de un estudiante:
 * - Convierte la cadena "undefined" a null para propiedades que no tienen valor.
 * - Transforma todas las propiedades de tipo string a mayúsculas.
 * - Parsea y convierte las fechas (birthdate, contactDate) a objetos Date.
 *
 * @param rawData Los datos crudos del estudiante recibidos de la solicitud.
 * @returns Los datos del estudiante normalizados y listos para ser usados.
 */
export const normalizeStudentData = (rawData: any): any => {
  const data = { ...rawData }; // Crea una copia de los datos para no modificar el original.

  // Itera sobre las propiedades y convierte la cadena "undefined" a null.
  for (const key in data) {
    if (data[key] === "undefined") {
      data[key] = null;
    }
  }

  // Aplica la transformación a mayúsculas a todas las cadenas del objeto.
  const uppercased = transformStringsToUppercase(data);

  // Parsea y convierte las fechas de formato ISO a objetos Date de JavaScript.
  // Esto es útil si las fechas se reciben como cadenas ISO de un formulario o API.
  if (uppercased.birthdate) {
    uppercased.birthdate = DateTime.fromISO(uppercased.birthdate).toJSDate();
  }

  if (uppercased.contactDate) {
    uppercased.contactDate = DateTime.fromISO(
      uppercased.contactDate
    ).toJSDate();
  }

  return uppercased; // Retorna los datos normalizados.
};