@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
2. Tecnologías que utiliza
3. Instalación rápida
4. Configuración de entorno (.env)
5. Uso en un proyecto consumidor
   • 5.1 Ejecutar migraciones del paquete
   • 5.2 Cargar seeds (datos por defecto)
   • 5.3 Usar el cliente Prisma del paquete
6. Desarrollo de la librería
   • 6.1 Agregar/editar modelos o relaciones
   • 6.2 Crear nuevas migraciones
   • 6.3 Probar localmente
   • 6.4 Publicar una nueva versión en npm
   • 6.5 Actualización y Migraciones
7. Notas y troubleshooting
8. 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

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:

# .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

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

O bien en package.json:

{
  "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

npx itbaf-subscriptions-seed

B) Ejecutar el seed compilado

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

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

npx prisma migrate dev --name <descripcion> --schema ./prisma/schema.prisma

6.3 Probar localmente

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

npm run release:patch   # fixes
npm run release:minor   # nuevas features
npm run release:major   # cambios incompatibles

Luego en el consumidor:

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:

   npm update @itbaf/subscriptions-models
   # o
   npm install @itbaf/subscriptions-models@latest

2. Verificar si hay nuevas migraciones:

   # Listar migraciones pendientes
   npx prisma migrate status --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma

3. Aplicar migraciones pendientes:

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

4. Regenerar el cliente Prisma (si es necesario):

   npx prisma generate --schema node_modules/@itbaf/subscriptions-models/prisma/schema.prisma

5. Ejecutar seed si hay nuevos datos por defecto:

   npx itbaf-subscriptions-seed

Scripts recomendados para package.json del consumidor:

{
  "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:

  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"

# 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"

# 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:

# 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