npm package: @itbaf/subscriptions-models
Description: Modelos **Prisma (MySQL)** reutilizables para integraciones de **suscripciones**: providers, integrators, platforms, countries, frequencies, integrations, subscriptions, registries y más.   Incluye **schema Prisma**, **migraciones versionadas** y **seed**
Latest version: 1.0.7

# @itbaf/subscriptions-models

Modelos **Prisma (MySQL)** reutilizables para integraciones de **suscripciones**: providers, integrators, platforms, countries, frequencies, integrations, subscriptions, registries y más.  
Incluye **schema Prisma**, **migraciones versionadas** y **seed** con datos por defecto para un arranque consistente en múltiples proyectos.

---

## Índice

1. [Objetivo de la librería](#objetivo-de-la-librería)  
2. [Tecnologías que utiliza](#tecnologías-que-utiliza)  
3. [Instalación rápida](#instalación-rápida)  
4. [Configuración de entorno (.env)](#configuración-de-entorno-env)  
5. [Uso en un proyecto consumidor](#uso-en-un-proyecto-consumidor)  
   - [5.1 Ejecutar migraciones del paquete](#51-ejecutar-migraciones-del-paquete)  
   - [5.2 Cargar seeds (datos por defecto)](#52-cargar-seeds-datos-por-defecto)  
   - [5.3 Usar el cliente Prisma del paquete](#53-usar-el-cliente-prisma-del-paquete)  
6. [Desarrollo de la librería](#desarrollo-de-la-librería)  
   - [6.1 Agregar/editar modelos o relaciones](#61-agregareditar-modelos-o-relaciones)  
   - [6.2 Crear nuevas migraciones](#62-crear-nuevas-migraciones)  
   - [6.3 Probar localmente](#63-probar-localmente)  
   - [6.4 Publicar una nueva versión en npm](#64-publicar-una-nueva-versión-en-npm)  
   - [6.5 Actualización y Migraciones](#65-actualización-y-migraciones)  
7. [Notas y troubleshooting](#notas-y-troubleshooting)  
8. [Licencia](#licencia)  

---

## Objetivo de la librería

Centralizar el **modelo de datos** de suscripciones (y sus integraciones) en un solo paquete para:  
- Evitar duplicar esquemas entre servicios y funciones.  
- Desplegar **migraciones** de forma consistente desde cada proyecto consumidor.  
- Sembrar **datos por defecto** (p. ej. `registry_types`, `subscription_status`, `frequencies`) con un solo comando.  
- Reutilizar un **PrismaClient** listo para usar.  

---

## Tecnologías que utiliza

- **TypeScript** (ESM)  
- **Prisma ORM** (datasource MySQL)  
- **Node.js** 18+  
- **Seeds** y **migraciones** gestionadas por Prisma  

---

## Instalación rápida

```bash
npm i @itbaf/subscriptions-models
# o
pnpm add @itbaf/subscriptions-models
# o
yarn add @itbaf/subscriptions-models
```

> El paquete incluye su propio `schema.prisma`, migraciones y seed.  
> El **cliente Prisma** del paquete se genera en la instalación/compilación del paquete.

---

## Configuración de entorno (.env)

En el **proyecto consumidor**, definí la variable `DATABASE_URL` (MySQL). Ejemplos:

```bash
# .env del proyecto consumidor
DATABASE_URL="mysql://usuario:password@host:3306/nombre_db"
```

> Esta URL es la que usarán las **migraciones** y el **seed** del paquete cuando se ejecuten desde tu proyecto.

---

## Uso en un proyecto consumidor

### 5.1 Ejecutar migraciones del paquete

```bash
npx prisma migrate deploy --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
```

O bien en `package.json`:

```jsonc
{
  "scripts": {
    "subs:migrate": "prisma migrate deploy --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma"
  }
}
```

### 5.2 Cargar seeds (datos por defecto)

**A) Binario listo del paquete**
```bash
npx itbaf-subscriptions-seed
```

**B) Ejecutar el seed compilado**
```bash
node node_modules/@itbaf/subscriptions-models/dist/prisma/seed.js
```

Se insertan automáticamente:
- `registry_types`  
- `subscription_status` 
- `frequencies`

### 5.3 Usar el cliente Prisma del paquete

```ts
import { db } from '@itbaf/subscriptions-models'

const prisma = db()
const types = await prisma.registryType.findMany()
```

---

## Desarrollo de la librería

### 6.1 Agregar/editar modelos o relaciones
Editá `prisma/schema.prisma`.

### 6.2 Crear nuevas migraciones
```bash
npx prisma migrate dev --name <descripcion> --schema ./prisma/schema.prisma
```

### 6.3 Probar localmente
```bash
npm i
npx prisma generate --schema ./prisma/schema.prisma
npm run build
export DATABASE_URL="mysql://user:pass@localhost:3306/prueba"
node dist/prisma/seed.js
```

### 6.4 Publicar una nueva versión en npm
```bash
npm run release:patch   # fixes
npm run release:minor   # nuevas features
npm run release:major   # cambios incompatibles
```

Luego en el consumidor:
```bash
npm update @itbaf/subscriptions-models
npm run subs:migrate
npx itbaf-subscriptions-seed
```

### 6.5 Actualización y Migraciones

#### **Importante: Flujo de actualización para proyectos consumidores**

Cuando se publica una nueva versión del paquete, los proyectos consumidores deben seguir este flujo:

1. **Actualizar el paquete:**
   ```bash
   npm update @itbaf/subscriptions-models
   # o
   npm install @itbaf/subscriptions-models@latest
   ```

2. **Verificar si hay nuevas migraciones:**
   ```bash
   # Listar migraciones pendientes
   npx prisma migrate status --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
   ```

3. **Aplicar migraciones pendientes:**
   ```bash
   npx prisma migrate deploy --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
   ```

4. **Regenerar el cliente Prisma (si es necesario):**
   ```bash
   npx prisma generate --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
   ```

5. **Ejecutar seed si hay nuevos datos por defecto:**
   ```bash
   npx itbaf-subscriptions-seed
   ```

#### **Scripts recomendados para package.json del consumidor:**

```jsonc
{
  "scripts": {
    "subs:update": "npm update @itbaf/subscriptions-models && npm run subs:migrate && npm run subs:seed",
    "subs:migrate": "prisma migrate deploy --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma",
    "subs:seed": "itbaf-subscriptions-seed",
    "subs:status": "prisma migrate status --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma"
  }
}
```

#### **Cuándo ejecutar migraciones:**

- ✅ **SÍ ejecutar:** Al instalar/actualizar el paquete
- ✅ **SÍ ejecutar:** Al hacer deploy en producción
- ✅ **SÍ ejecutar:** Al cambiar de versión del paquete
- ❌ **NO ejecutar:** En cada build/compilación del proyecto
- ❌ **NO ejecutar:** En cada request HTTP

---

## Notas y troubleshooting

- Node 18+ recomendado.  
- Si el consumer no tiene Prisma CLI:  
  ```bash
  npx -p prisma prisma migrate deploy --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
  ```  
- `prisma/generated/client` se crea con `prisma generate`, no hace falta versionarlo.  
- Las migraciones (`prisma/migrations`) sí se versionan.  

### **Problemas comunes con migraciones:**

#### **Error: "Migration failed"**
```bash
# Verificar estado de migraciones
npx prisma migrate status --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma

# Si hay conflictos, resetear y aplicar desde cero
npx prisma migrate reset --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
npx prisma migrate deploy --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
```

#### **Error: "Database schema is out of sync"**
```bash
# Regenerar cliente Prisma
npx prisma generate --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma

# Verificar que el schema coincida con la base de datos
npx prisma db pull --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
```

#### **Migraciones en entornos de CI/CD:**
```bash
# Script recomendado para pipelines
npm ci
npx prisma migrate deploy --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
npx prisma generate --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma
npx itbaf-subscriptions-seed
```

### **Versionado semántico del paquete:**

- **PATCH** (1.0.1): Solo fixes, no requieren migraciones
- **MINOR** (1.1.0): Nuevas features, pueden requerir migraciones
- **MAJOR** (2.0.0): Cambios incompatibles, siempre requieren migraciones

> **Nota:** Antes de actualizar a una versión MAJOR, revisar el changelog y las migraciones pendientes.

---

## Licencia

MIT