typeorm-library

Librería de entidades TypeORM compartida para todo el stack AWS de Ellie Care. Define cada entidad de la base de datos, cada enum y tipo TypeScript compartido, y exporta el array canónico Entities que consumen todos los servicios que hablan con la PostgreSQL de la plataforma.

Esto no es un servicio — no corre en ningún lado. Es un package TypeScript compilado que se instala vía npm install desde otros repos.

---

⚠️ Dato crítico

Esta librería es la dependencia de más alto riesgo del stack AWS. Los consumers trackean la rama develop directamente:

typeorm-library#develop  ─┬──►  ec-be             (NestJS / ECS Fargate)
                          ├──►  lambdas-sensors   (5 Lambdas)
                          ├──►  aws-lambdas       (Contact Center)
                          └──►  lambdas-ec-reporting

Todo push a develop se propaga a estos 4 servicios en el siguiente cold start. No hay pin SemVer y no hay rollback por versión. Revisá cada cambio con eso en mente.

---

Install (desde un consumer)

// package.json
{
  "dependencies": {
    "typeorm-library": "github:elliecare/typeorm-library#develop"
  }
}

npm install

---

Uso

import { DataSource, DataSourceOptions } from "typeorm";
import { Entities, Battery, User } from "typeorm-library";

const options: DataSourceOptions = {
  type: "postgres",
  host: "...",
  port: 5432,
  username: "...",
  password: "...",
  database: "...",
  entities: Entities,        // ← siempre usar el array completo
  synchronize: false,        // ← debe estar en false en producción
  logging: false,
};

const dataSource = new DataSource(options);
await dataSource.initialize();

const batteries = await dataSource.getRepository(Battery).find({
  where: { device_id: "..." },
  order: { created_on_device: "ASC" },
});

Regla: nunca listar entities manualmente — siempre pasar Entities desde esta librería.

---

Qué contiene

Grupo	Ejemplos
Sensor / dispositivo	Battery, HeartRate, Location, OffBody, Steps, Calories, Sensors, Measurement
Smartwatch	Smartwatch, UserSmartwatch, Gateway, WifiConnected, PhoneLine, LineProvider
Users / red de apoyo	User, SupportNetwork, Role_SupportNetwork, OperationalRole, UserOperationalRole, PatientAgentContact
Auth / acceso	AccessCode, InviteCode, PasswordResetToken, StaticToken, DiscountCode
Alertas / eventos	Alert, AlertConfiguration, AlertLogs, EventEntity, EventSubscription, Notification, Message, Tracking
Planes / pagos	Plans, PlansDescription, Purchase, CompanyClient, HealthSystem
Config / AI	Config, Assessment, CanaryData, FallThresholdFactorAIModelEntity
Módulos	ConnectModule, CommercialModule, IntegrationModule, MailingModule, SmartwatchModule, WhatsappModule, CanaryModule (+ audit hermanos)

Más enums e interfaces compartidos en src/types.ts:

• UserRole, SupportNetworkUserType, SupportNetworkStatus, PlanType, GenderType, Language
• PhoneNumber, LowBatteryNotification

Catálogo completo en docs/_for_agents/repo-map.md.

---

Estructura del repo

typeorm-library/
├── index.ts                 ← entry point — imports + Entities[] + named exports
├── package.json
├── tsconfig.json
├── dist/                    ← ⚠️ COMMITEADO — output compilado
└── src/
    ├── types.ts             ← enums e interfaces compartidos
    └── entity/
        ├── *.entity.ts      ← 50+ clases de entity
        └── modules/
            └── *.module.entity.ts  ← 14 module entities + audits

dist/ está commiteado porque los consumers instalan vía github: y no corren un build de postinstall — necesitan el JavaScript pre-compilado.

---

Desarrollo

git clone git@github.com:elliecare/typeorm-library.git
cd typeorm-library
npm install
npm run build       # tsc → dist/
npm run clean       # rm -rf dist

No hay tests, no hay lint, no hay formatter. La única validación es tsc.

---

Workflow para cualquier cambio

1. git checkout develop && git pull
2. git checkout -b fix/<nombre-corto>
3. Editar src/entity/*.ts o index.ts o src/types.ts
4. npm run build              ← OBLIGATORIO — dist/ se commitea
5. git add src/ index.ts dist/
6. git commit
7. Abrir PR a develop

Olvidar el paso 4 es un modo de falla silenciosa. El cambio en src/ no llega a los consumers porque ellos consumen dist/. Siempre rebuild.

---

Agregar una entity nueva

1. Crear src/entity/my_new.entity.ts:

   import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn } from "typeorm";
   
   @Entity()
   export class MyNew {
     @PrimaryGeneratedColumn("uuid")
     id: string;
   
     @Column()
     some_field: string;
   
     @CreateDateColumn()
     created_at: Date;
   }

2. Abrir index.ts y agregar:

   • Import al inicio
   • El nombre de clase en el array Entities = [...]
   • export { MyNew }; al final

3. npm run build y commitear src/ + index.ts + dist/.

Importante: la tabla correspondiente en la DB debe existir (vía una migración en ec-be) antes de publicar la entity.

Ver docs/_for_agents/common-tasks.md para más recetas (agregar columna, eliminar columna, renombrar, relaciones, etc.).

---

Agregar una columna a una entity existente

Paso	Dónde	Notas
1	Migración en ec-be	Agregar la columna a la DB
2	Deploy + aplicar migración	Verificar que la columna existe en el ambiente target
3	Agregar la columna a la entity acá	Usar @Column({ nullable: true }) por seguridad
4	npm run build	Compilar a dist/
5	Commitear src/ + dist/	Ambos deben ir en el mismo PR
6	Mergear a develop	Los consumers la levantan en el siguiente cold start

Orden equivocado = fallas de queries en producción. Siempre: DB primero → entity acá segundo.

---

Ramas

Rama	Propósito	Riesgo
main	Referencia de producción	Bajo (consumers no la trackean)
develop	Los 4 consumers trackean esta rama	🔴 Cada push = deploy de facto a prod
uat	Referencia UAT	Bajo
dev-to-uat	Merges de staging	Bajo
add-user-id-in-metrics, fix/src-typeorm	Feature/bugfix branches	Nulo hasta que mergean

---

Stack

Componente	Versión
TypeScript	5.6
TypeORM	0.3.20 (locked en todo el stack)
typeorm-extension	2.4.2
reflect-metadata	0.2.2
Formato de módulo del output	CommonJS
Target del output	ES6

No actualices TypeORM sin coordinar con los 4 consumers.

---

Roadmap — Migración a SemVer

La tarea abierta más importante en el stack AWS. Plan (todavía no ejecutado):

1. Taggear el estado actual de develop como v1.0.0
2. Publicar a un registry npm privado (o GitHub Packages)
3. Actualizar consumers uno por uno, de menor riesgo a mayor: lambdas-ec-reporting → lambdas-sensors → aws-lambdas → ec-be
4. Después de que todos los consumers pinen ^1.0.0, develop deja de ser load-bearing
5. Cambios futuros siguen SemVer estándar

Esto requiere coordinación explícita entre 4 equipos — no atacarlo de forma unilateral.

---

AI-Ready

Este repo sigue el estándar AI-Ready de Ellie Care:

• AGENTS.md — instrucciones universales para agentes
• CLAUDE.md — guía específica para Claude Code
• docs/_for_agents/ — mapa del repo, glosario, zonas seguras, recetas comunes

Catálogo de la org: elliecare/.github Manifest de servicios: elliecare/.github/services.yaml

---

Repos relacionados

Repo	Relación
ec-be	Consumer principal — lee + escribe
lambdas-sensors	Consume Battery, HeartRate, Location, OffBody, Steps
aws-lambdas	Consume entidades relacionadas a Connect
lambdas-ec-reporting	Queries de reporting

---

Licencia

ISC