@rempays/data-core

PostgreSQL data layer para RemPays platform. Manejo centralizado de datos con TypeORM, seeders extensibles y arquitectura lista para Lambdas.

Características

• 🗄️ PostgreSQL con TypeORM: Soporte completo ESM con TypeScript
• 🔄 Sistema de Migraciones: Cambios de schema versionados
• 🌱 Seeders Extensibles: Seeders core + seeders registrables desde Lambdas
• 🐳 Docker Compose: Ambiente de desarrollo local
• 📦 Paquete NPM: Listo para consumo en Lambdas
• 🔐 Integración Cognito: Autenticación de usuarios
• 🤖 Configuración AI Agent: System prompts y reglas de validación
• 🔌 Connection Pooling: Optimizado para ambientes serverless
• 🎯 TypeScript Strict Mode: Type safety completo
• 🔑 UUID Primary Keys: Usando PostgreSQL uuid_generate_v4()
• 🗑️ Soft Delete: Todas las entidades soportan eliminación suave

Instalación

npm install @rempays/data-core

Quick Start

1. Setup Local

# Clonar e instalar
git clone <repository-url>
cd data-core
npm install

# Iniciar base de datos
npm run db:start

# Ejecutar migraciones
npm run migration:run

# Ejecutar seeders
npm run seed:run

2. Variables de Entorno

Crear .env:

# Local Development
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/rempays_dev
NODE_ENV=development

# Production (Neon)
# DATABASE_URL=postgresql://user:password@ep-xxx.neon.tech/rempays?sslmode=require
# NODE_ENV=production

Uso en Lambdas

Repositorios Básicos

import { 
    ConnectionManager, 
    UserRepository, 
    BusinessRepository 
} from '@rempays/data-core';

export const handler = async (event) => {
    const connectionManager = ConnectionManager.getInstance();
    const dataSource = await connectionManager.getDataSource();
    
    const userRepo = new UserRepository(dataSource);
    const user = await userRepo.findByEmail(event.email);
    
    return { 
        statusCode: 200, 
        body: JSON.stringify(user) 
    };
};

Registrar Seeders Personalizados

import { registerSeeder, runAllSeeders } from '@rempays/data-core';

registerSeeder({
    name: 'lambda-custom-data',
    priority: 100,
    fn: async (dataSource) => {
        // Tu lógica de seeding
    }
});

await runAllSeeders(dataSource);

Schema de Base de Datos

Tablas Core

• users: Perfiles de usuario vinculados a AWS Cognito
• businesses: Entidades de negocio con integración DIAN
• categories: Categorías de negocio con templates AI
• business_configs: Configuraciones de agente AI por negocio
• business_channels: Canales de comunicación (WhatsApp, Web, etc.)
• business_locations: Ubicaciones físicas de negocios
• validation_rules: Reglas globales de seguridad y validación

Relaciones Importantes

Business (1) → BusinessConfig (N)
BusinessChannel (1) → BusinessConfig (N)
Business (1) → BusinessChannel (N)
Business (1) → BusinessLocation (N)
Category (1) → Business (N)

Migraciones

# Generar migración
npm run migration:generate MiFeature

# Ejecutar migraciones
npm run migration:run

# Revertir última migración
npm run migration:revert

Seeders

# Generar seeder
npm run seeder:generate mi-seeder

# Ejecutar todos los seeders
npm run seed:run

# Ejecutar seeder específico
npm run seed:specific categories

Seeders Incluidos

1. 001-categories.seeder - 50 categorías de negocios colombianos
2. 002-validation-rules.seeder - 17 reglas de validación AI

Scripts Disponibles

Base de Datos

npm run db:start      # Iniciar PostgreSQL en Docker
npm run db:stop       # Detener base de datos
npm run db:reset      # Reiniciar (elimina datos)
npm run db:logs       # Ver logs

Build

npm run build         # Build producción
npm run build:watch   # Build en modo watch

Testing

npm run test:local    # Test completo local
npm run test:seeders  # Test sistema de seeders

CI/CD y Deployment Automático

Flujo Automático

Push to develop/main → Build → Publish NPM → Deploy DB (Migrations + Seeders)

Ambientes

GitHub Environments Setup

Configurar en Settings → Environments:

develop:

Secret: DATABASE_URL = <neon-develop-connection-string>

production:

Secret: DATABASE_URL = <neon-production-connection-string>
Required reviewers: [Tu usuario]

Workflow de Desarrollo

Beta Release:

git checkout develop
git commit -m "feat: nueva funcionalidad"
git push origin develop
# → Auto-publica @rempays/data-core@beta
# → Ejecuta migraciones y seeders en develop DB

Production Release:

git checkout main
git merge develop
npm version patch
git push origin main --tags
# → Auto-publica @rempays/data-core@latest
# → Ejecuta migraciones y seeders en production DB

Estructura del Proyecto

@rempays/data-core/
├── src/
│   ├── abstract/              # Entidades base
│   ├── constants/             # Constantes y tipos
│   ├── modules/               # Módulos de dominio
│   │   ├── user/
│   │   ├── business/
│   │   ├── category/
│   │   ├── business-config/
│   │   ├── business-channel/
│   │   ├── business-location/
│   │   └── validation-rule/
│   ├── migrations/            # Migraciones TypeORM
│   ├── seeders/               # Seeders de datos
│   ├── connection-manager.ts  # Gestor de conexiones
│   ├── data-source.ts         # DataSource TypeORM
│   └── index.ts               # Exports principales
├── scripts/                   # Scripts de utilidad
├── docker-compose.yml         # PostgreSQL local
├── .env.example               # Variables de entorno ejemplo
└── package.json

API Reference

ConnectionManager

const connectionManager = ConnectionManager.getInstance();
const dataSource = await connectionManager.getDataSource();

Repositorios Principales

UserRepository:

findByEmail(email: string)
findByCognitoSub(sub: string)
findByPhoneNumber(phone: string)
findByBusiness(businessId: string)

BusinessRepository:

findByNit(nit: string)
findByOwner(userId: string)
findActive()
findByCategory(categoryId: string)

BusinessChannelRepository:

findByBusinessId(businessId: string)
findActiveByBusinessId(businessId: string)
findByIdentifier(identifier: string)

BusinessLocationRepository:

findByBusinessId(businessId: string)
findPrimaryLocation(businessId: string)
findNearby(lat: number, lng: number, radiusKm: number)

Funciones de Seeders

registerSeeder({ name, priority, fn })
runAllSeeders(dataSource, options?)
runSeeder(dataSource, name)
listSeeders()
clearExternalSeeders()

Troubleshooting

Error: Cannot find module

# Rebuild el proyecto
rm -rf dist && npm run build

Error de conexión a base de datos

# Verificar que Docker esté corriendo
docker ps | grep rempays-postgres

# Reiniciar base de datos
npm run db:reset

Migraciones no se ejecutan

# Verificar estado de migraciones
docker exec rempays-postgres psql -U postgres -d rempays_dev -c "SELECT * FROM migrations;"

# Rebuild y ejecutar
npm run build && npm run migration:run

Licencia

MIT

Soporte

Para issues y preguntas, crear un issue en el repositorio de GitHub.