Instalación

Integrar Kaizen Payments en tu API es: configurar el acceso al registro (una sola vez), añadir la dependencia e importar sus entidades. No hay nada que "levantar": la librería vive dentro de tu app.

Entorno

• Node.js 18+
• NestJS 11+
• PostgreSQL 13+
• Gestor de paquetes: pnpm (recomendado), npm o yarn

Paso 1 — Acceso al registro privado

@kaizen/payments-gateway no está en el npm público: se distribuye desde un registro privado (https://npm.amandita.me). Antes de instalarla, tu proyecto tiene que saber de dónde bajarla y tú tienes que estar autenticada. Es una configuración que se hace una vez.

1. Apunta el scope @kaizen a tu registro. Crea un archivo .npmrc en la raíz de tu proyecto consumidor:

# .npmrc
@kaizen:registry=https://npm.amandita.me

Esto le dice a pnpm/npm: "todo lo que empiece por @kaizen/ búscalo aquí, no en el npm público". El resto de paquetes (@nestjs/*, etc.) siguen viniendo del npm normal.

Este archivo se commitea

El .npmrc con el scope va al repo: no tiene secretos, solo la dirección del registro. Así la instalación funciona igual en tu máquina, en el servidor y en tu CI.

2. Autentícate. El registro es privado, así que necesitas credenciales (te las facilita quien mantiene la librería). Inicia sesión:

npm login --registry https://npm.amandita.me --auth-type=legacy

Te pedirá usuario, contraseña y email en la terminal, y guarda un token en tu ~/.npmrc personal (C:\Users\<tú>\.npmrc), fuera del repo. Sin este login, el pnpm add del paso siguiente falla con 401 Unauthorized.

El token es secreto

El token vive en tu ~/.npmrc personal, nunca en el .npmrc del proyecto ni en git. En un servidor o CI se aporta como variable de entorno o en un .npmrc no versionado.

Paso 2 — Añade la dependencia

pnpm

pnpm add @kaizen/payments-gateway

npm

npm install @kaizen/payments-gateway

yarn

yarn add @kaizen/payments-gateway

Paso 3 — Importa las entidades

npx @kaizen/payments-gateway setup

Este comando crea en tu proyecto un módulo payments con un archivo de entidades que re-exporta las de la librería (Payment, Refund, WebhookEventEntity):

src/modules/payments/entities/payments.entity.ts

// generado por el comando setup
export { Payment, Refund, WebhookEventEntity } from '@kaizen/payments-gateway'

Por defecto lo crea bajo src/modules. Si tu estructura es distinta, pásale la ruta:

npx @kaizen/payments-gateway setup --path src

¿Y qué hace tu ORM con ese archivo?

Depende de cómo cargues las entidades en tu DataSource / TypeOrmModule:

• Las cargas por patrón (glob del tipo **/*.entity.ts, o autoLoadEntities: true): no tienes que hacer nada más, el archivo generado ya queda incluido.
• Las declaras a mano en un array entities: añade ahí las tres entidades importándolas desde el archivo que generó el comando.

Peer dependencies

La librería declara el framework y el ORM como peerDependencies: deben ser la misma instancia que la de tu app, o se rompen la inyección de dependencias y el registro de metadatos. Instálalas en tu consumidor si no las tienes ya:

pnpm add @nestjs/common @nestjs/core @nestjs/typeorm @nestjs/event-emitter \
  typeorm rxjs reflect-metadata class-validator class-transformer pg

Paquete	Rol
@nestjs/common, @nestjs/core	Framework
@nestjs/typeorm, typeorm	ORM y conexión
@nestjs/event-emitter	Eventos de dominio (payment.captured, …)
class-validator, class-transformer	Validación del ChargeDto
reflect-metadata, rxjs	Requisitos base de NestJS
pg	Driver de PostgreSQL (lo aportas tú)

stripe no lo instalas tú: es una dependencia interna de la librería, porque es detalle de la pasarela y su versión la controla ella.

Con esto ya puedes registrar el módulo. Sigue con la Configuración.