Contratos y Tipos (Shared Lib)

Este documento describe el paquete @softmena/yuruary-types, que actúa como la Única Fuente de Verdad para los tipos de datos en todo el ecosistema Yuruary. Este paquete no contiene lógica de negocio, únicamente definiciones .d.ts o .ts (interfaces, enums, types) que son compartidas entre el Backend (NestJS), el Web Portal (React) y el Desktop Client (Electron).

Instalación

Para utilizar estos tipos en cualquiera de los proyectos del ecosistema:

npm install @softmena/yuruary-types

Sección 1: Enums Críticos (El Vocabulario)

Estos Enums controlan el flujo de la lógica de negocio y aseguran consistencia en toda la plataforma.

Roles de Usuario (UserRole)

export enum UserRole {
  ADMIN = 'ADMIN',           // Administrador del Sistema
  CAJA = 'CAJA',             // Operador de Caja (Cobros)
  GERENCIA = 'GERENCIA',     // Gerente de Condominio (Vistas Administrativas)
  PROPIETARIO = 'PROPIETARIO' // Residente / Dueño de Inmueble
}

Estado del Recibo (BillStatus)

export enum BillStatus {
  PRELIMINARY = 'PRELIMINARY', // En borrador, no visible para el usuario
  OPEN = 'OPEN',               // Publicado y pendiente de pago
  PAID = 'PAID',               // Pagado totalmente
  OVERDUE = 'OVERDUE'          // Vencido
}

Métodos de Pago (PaymentMethod)

export enum PaymentMethod {
  ZELLE = 'ZELLE',
  PAGO_MOVIL = 'PAGO_MOVIL',
  TRANSFER = 'TRANSFER',
  CASH = 'CASH'
}

Alcance del Gasto (ExpenseScope)

export enum ExpenseScope {
  GLOBAL = 'GLOBAL',   // Afecta a todo el condominio
  SECTOR = 'SECTOR',   // Afecta a un grupo de unidades (ej. Torre A)
  UNIT = 'UNIT'        // Recargo específico a una unidad
}

Sección 2: Interfaces Core (Entidades)

Estas interfaces definen la estructura de los datos base, reflejando el esquema de la base de datos pero desacopladas de cualquier ORM.

Unidad Inmobiliaria (IUnit)

export interface IUnit {
  id: string;              // UUID
  number: string;          // Ej. "1-A"
  floor?: string;
  aliquots: {              // Porcentajes de participación
    main: number;          // Alícuota principal
    roof?: number;         // Alícuota de techo (si aplica)
  };
}

Condominio (ICondominium)

export interface ICondominium {
  id: string;
  name: string;
  rif: string;
  config: {
    currency: 'USD' | 'VED';
    billingDay: number;
  };
}

Recibo de Condominio (IBill)

export interface IBill {
  id: string;
  period: string;          // YYYY-MM
  amount: number;          // Monto total
  pendingBalance: number;  // Saldo pendiente
  status: BillStatus;
  issuedAt: string;        // ISO Date
}

Sección 3: DTOs de API (Requests & Responses)

Definiciones de cómo viajan los datos a través de la red.

Reporte de Pago (CreatePaymentReportDto)

Estructura del payload enviado por el Portal Web cuando un usuario reporta un pago.

export interface CreatePaymentReportDto {
  amount: number;
  reference: string;       // Nro de referencia bancaria
  paymentMethod: PaymentMethod;
  date: string;            // Fecha del pago
  proofOfPayment?: File;   // Imagen/PDF del comprobante (se sube a S3)
}

Wrapper de Respuesta Estándar (ApiResponse<T>)

Todas las respuestas del API siguen este formato estandarizado para garantizar un manejo de errores y datos predecible en el frontend.

export interface ApiResponse<T> {
  success: boolean;
  statusCode: number;      // HTTP Status Code (200, 201, 400, etc.)
  message?: string;        // Mensaje descriptivo (opcional)
  data: T;                 // Payload de respuesta
  timestamp: string;       // ISO Date del servidor
}

export interface PaginatedResponse<T> extends ApiResponse<T[]> {
  meta: {
    total: number;         // Total de items en BD
    page: number;          // Página actual
    lastPage: number;      // Última página disponible
  };
}