Installation

Integrating Kaizen Payments into your API is: configure registry access (once), add the dependency and import its entities. There's nothing to "spin up": the library lives inside your app.

Environment

• Node.js 18+
• NestJS 11+
• PostgreSQL 13+
• Package manager: pnpm (recommended), npm or yarn

Step 1 — Private registry access

@kaizen/payments-gateway is not on the public npm: it's distributed from a private registry (https://npm.amandita.me). Before installing it, your project needs to know where to fetch it from and you need to be authenticated. This is a one-time setup.

1. Point the @kaizen scope to your registry. Create an .npmrc file at the root of your consumer project:

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

This tells pnpm/npm: "anything starting with @kaizen/, fetch it here, not from the public npm". Every other package (@nestjs/*, etc.) still comes from the normal npm.

Commit this file

The .npmrc with the scope goes into the repo: it has no secrets, just the registry address. That way the install works the same on your machine, on the server and in your CI.

2. Authenticate. The registry is private, so you need credentials (provided by whoever maintains the library). Log in:

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

It asks for username, password and email in the terminal, and stores a token in your personal ~/.npmrc (C:\Users\<you>\.npmrc), outside the repo. Without this login, the pnpm add in the next step fails with 401 Unauthorized.

The token is a secret

The token lives in your personal ~/.npmrc, never in the project's .npmrc or in git. On a server or CI it's provided as an environment variable or a non-versioned .npmrc.

Step 2 — Add the dependency

pnpm

pnpm add @kaizen/payments-gateway

npm

npm install @kaizen/payments-gateway

yarn

yarn add @kaizen/payments-gateway

Step 3 — Import the entities

npx @kaizen/payments-gateway setup

This command creates a payments module in your project with an entities file that re-exports the library's entities (Payment, Refund, WebhookEventEntity):

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

// generated by the setup command
export { Payment, Refund, WebhookEventEntity } from '@kaizen/payments-gateway'

By default it creates it under src/modules. If your structure differs, pass the path:

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

What does your ORM do with that file?

It depends on how you load entities in your DataSource / TypeOrmModule:

• You load them by pattern (a glob like **/*.entity.ts, or autoLoadEntities: true): nothing else to do, the generated file is already included.
• You declare them by hand in an entities array: add the three entities there, importing them from the file the command generated.

Peer dependencies

The library declares the framework and the ORM as peerDependencies: they must be the same instance as your app's, or dependency injection and metadata registration break. Install them in your consumer if you don't have them already:

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

Package	Role
@nestjs/common, @nestjs/core	Framework
@nestjs/typeorm, typeorm	ORM and connection
@nestjs/event-emitter	Domain events (payment.captured, …)
class-validator, class-transformer	ChargeDto validation
reflect-metadata, rxjs	NestJS base requirements
pg	PostgreSQL driver (you provide it)

You do not install stripe: it's an internal dependency of the library, because it's a gateway detail and the library controls its version.

You can now register the module. Continue with Configuration.