![\"@bymax-one/nest-notification\"](\"https://img.shields.io/badge/%40bymax--one-nest--notification-000000?style=for-the-badge&logo=nestjs&logoColor=E0234E\"){kind=icon}
\n\n
\n Transactional notification for NestJS & React
\n Email · OTP · Multi-Tenant · Pluggable Providers · Prisma-Free · Zero Runtime Dependencies\n
\n ![\"npm](\"https://img.shields.io/npm/v/@bymax-one/nest-notification?style=flat-square&colorA=000000&colorB=000000\")
![\"npm](\"https://img.shields.io/npm/dm/@bymax-one/nest-notification?style=flat-square&colorA=000000&colorB=000000\")
![\"CI](\"https://img.shields.io/github/actions/workflow/status/bymaxone/nest-notification/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI\")
![\"coverage\"](\"https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
![\"mutation](\"https://img.shields.io/badge/mutation-100.00%25-brightgreen?style=flat-square&colorA=000000\"){kind=icon}
\n
![\"license\"](\"https://img.shields.io/github/license/bymaxone/nest-notification?style=flat-square&colorA=000000&colorB=000000\")
![\"TypeScript\"](\"https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white\"){kind=icon}
![\"Node.js\"](\"https://img.shields.io/badge/Node.js-24%2B-339933?style=flat-square&logo=node.js&logoColor=white\"){kind=icon}
\n GitHub ·\n Issues ·\n Quick Start ·\n API Reference ·\n Example App\n
\n\n---\n\n## ✨ Overview\n\n`@bymax-one/nest-notification` is a **transactional notification library for NestJS 11** that ships two channels — **email** and **OTP** (one-time passwords) — behind a single dynamic module, plus a React subpath for the OTP input box.\n\nEverything that touches the outside world — the email transport, the OTP store, the template renderer, the audit sink — is an **interface** you implement or pick from the bundled reference adapters. The same module runs on Resend or SendGrid, on Redis or an in-memory map, with a Prisma audit log or none at all, without changing a single call site.\n\n### Why nest-notification?\n\n- **🔌 Your database, your provider** — The library defines the contracts (`IEmailProvider`, `IOtpStorage`, `IEmailTemplateRenderer`, `INotificationLogRepository`). You supply the implementations. It **never imports `@prisma/client`** or any other ORM — a CI gate fails the build if one appears — so a cross-cutting concern never hard-wires your schema.\n- **🏢 Multi-tenant from the first line** — Every operation is scoped by `tenantId`, store keys are `sha256(sha256(tenantId):sha256(recipient))`, and the audit interceptor resolves the trusted tenant from the request rather than the request body when you configure a resolver.\n- **🔒 Native crypto only** — Codes come from `crypto.randomInt` and are compared with `crypto.timingSafeEqual`. No `crypto-js`, no `otpauth`, no `uuid`, no `nanoid` — the most security-sensitive path carries no third-party supply-chain risk.\n- **⚛️ Atomic by construction** — The attempt counter and the resend cooldown are mutated **inside the storage** (Redis Lua / `SET NX EX`), never by a service-side read-then-write. A `get` + `update` pair races, and the race is exactly how a max-attempts ceiling gets bypassed under concurrent requests.\n- **🪶 Pay for what you use** — `\"dependencies\": {}`. NestJS, your email SDK, your Redis client, and React are all peer dependencies, and only the channels you configure are registered in the container.\n\n```\npnpm add @bymax-one/nest-notification\n```\n\n---\n\n## 🔥 Features\n\n### 📧 Email\n\n- ✅ **Pluggable transport** — `IEmailProvider` with a bundled `ResendEmailProvider`, an `SmtpEmailProvider` that speaks the protocol every relay and mail-capture server understands, and a `NoOpEmailProvider` for dev/test that logs subject and recipient only, never the body\n- ✅ **Template rendering** — `IEmailTemplateRenderer` with a bundled `{{var}}` renderer that **HTML-escapes** interpolated values in the HTML body\n- ✅ **Canonical template names** — `CANONICAL_EMAIL_TEMPLATES` so providers and templates agree on the wire\n- ✅ **Attachment guard** — a configurable total size ceiling (10 MiB by default) rejected before the provider is called\n\n### 🔢 OTP\n\n- ✅ **CSPRNG codes** — `numeric` / `alpha` / `alphanumeric`, built character by character from `crypto.randomInt` so every position is uniform\n- ✅ **TTL + max attempts** — with the counter spent atomically inside the storage\n- ✅ **Atomic resend cooldown** — acquired with `SET NX EX` and released only on delivery failure, so two concurrent resends cannot both win\n- ✅ **Constant-time verification** — `crypto.timingSafeEqual`, never `===`\n- ✅ **Per-purpose overrides** — length, code type, TTL, attempts, and cooldown tuned per purpose (a password reset is not an email verification)\n- ✅ **Optional email delivery** — hand the code to the email channel, or take it and deliver it yourself\n\n### 🏢 Multi-Tenant & Audit\n\n- ✅ **SHA-256 storage keys** — `sha256(sha256(tenantId):sha256(recipient))`: no recipient PII in a key, and the encoding adds no ambiguity of its own, so two pairs never share one by construction\n- ✅ **`tenantIdResolver`** — the audited tenant comes from a trusted source (a JWT claim, a subdomain, a gateway-checked header), not the payload\n- ✅ **Opt-in audit log** — a fire-and-forget `INotificationLogRepository` plus a `NotificationAuditInterceptor`; audit failures never break delivery\n- ✅ **This library never logs a code** — not to a logger, not to an audit entry, not into an error message it authors, enforced by a regression test. Text a **provider** authors is a separate problem with a documented ceiling: an error quoting the body in another encoding survives every guard, so control whether provider error text reaches your logs at all\n\n### 🧩 Developer Experience\n\n- ✅ **Three subpaths** — server, zero-dependency shared types, and React hooks\n- ✅ **Stable error catalog** — 23 namespaced codes shared byte-for-byte between server and frontend, so you localize on the `code`\n- ✅ **Dual-format output** — ESM + CJS + declarations for both, verified against the packed tarball on every PR\n- ✅ **Typed end to end** — TypeScript `strict` with `exactOptionalPropertyTypes` and `noUncheckedIndexedAccess`; zero `any`\n\n---\n\n## 📦 Subpath Exports\n\nOne package, four entry points — import only what your app needs:\n\n| Subpath | Import | Purpose | Peer deps |\n| ----------- | -------------------------------------- | ------------------------------------------------------ | :------------------------------------: |\n| **Server** | `@bymax-one/nest-notification` | NestJS module, services, providers, errors, tokens | NestJS 11 (+ your provider/store SDKs) |\n| **Shared** | `@bymax-one/nest-notification/shared` | Types + constants (error codes, TTLs) | None |\n| **React** | `@bymax-one/nest-notification/react` | `useOtpInput` + `useOtpCountdown` (UX/state only) | React 19 |\n| **Testing** | `@bymax-one/nest-notification/testing` | Executable `IOtpStorage` contract for your own storage | None |\n\n```\nshared (zero deps)\n ↗ ↖\nserver react\n```\n\n`shared` is independent, `react` depends only on `react`, and `server` is independent — importing one never drags in another's peers. Every subpath ships ESM (`.mjs`), CJS (`.cjs`), and declarations for both formats (`.d.ts` + `.d.cts`).\n\n---\n\n> [!TIP]\n> Prefer to learn from a working app? See the [nest-notification-example](https://github.com/bymaxone/nest-notification-example) — a full NestJS project wired with this library.\n\n## 🚀 Quick Start\n\n### 1. Install\n\n```bash\n# Using pnpm (recommended)\npnpm add @bymax-one/nest-notification\n\n# Using npm\nnpm install @bymax-one/nest-notification\n\n# Using yarn\nyarn add @bymax-one/nest-notification\n```\n\n> [!IMPORTANT]\n> You must also install the **peer dependencies** for the subpaths and channels you use:\n\n```bash\n# Server subpath (required)\npnpm add @nestjs/common @nestjs/core reflect-metadata rxjs\n\n# Production email + OTP over Redis (optional — pick your own provider/store)\npnpm add resend ioredis\n\n# …or SMTP instead of Resend (any relay, plus Mailpit/MailHog in tests)\npnpm add nodemailer ioredis\n\n# React subpath (optional)\npnpm add react\n```\n\n> [!NOTE]\n> Requires Node.js **24+** and NestJS **11**. Every provider and storage SDK is an _optional_ peer dependency: install only the ones your configuration actually names.\n\n### 2. Development — `NoOpEmailProvider` + `InMemoryOtpStorage`\n\nNo external services. Emails are logged (subject and recipient only, never the body), and OTP state lives in process memory. Ideal for local dev and tests.\n\n```typescript\nimport { Module } from '@nestjs/common'\nimport {\n BymaxNotificationModule,\n NoOpEmailProvider,\n InMemoryOtpStorage\n} from '@bymax-one/nest-notification'\n\n@Module({\n imports: [\n BymaxNotificationModule.forRoot({\n email: {\n provider: new NoOpEmailProvider(),\n defaultFrom: 'no-reply@dev.local'\n },\n otp: {\n storage: new InMemoryOtpStorage(),\n defaultLength: 6,\n defaultTtlSeconds: 600,\n defaultMaxAttempts: 5,\n resendCooldownSeconds: 60\n }\n })\n ]\n})\nexport class AppModule {}\n```\n\nInject `OtpService` anywhere and the two-step flow is complete:\n\n```typescript\nimport { Injectable } from '@nestjs/common'\nimport { OtpService } from '@bymax-one/nest-notification'\n\n@Injectable()\nexport class VerificationService {\n constructor(private readonly otp: OtpService) {}\n\n /** Generate + deliver an email-verification OTP. */\n async start(tenantId: string, email: string): Promise<{ expiresAt: number }> {\n const { expiresAt } = await this.otp.generate({\n tenantId,\n recipient: email,\n purpose: 'email_verification',\n deliverVia: 'email'\n })\n return { expiresAt }\n }\n\n /** Verify a submitted code. */\n async confirm(tenantId: string, email: string, code: string): PromiseYour code is {{code}}. It expires in {{expiresInMinutes}} minutes.
',\n text: 'Your code is {{code}}. It expires in {{expiresInMinutes}} minutes.'\n }\n }\n })\n },\n otp: {\n storage: new RedisOtpStorage({ redisClient: redis }),\n defaultLength: 6,\n defaultCodeType: 'numeric',\n defaultTtlSeconds: 600,\n defaultMaxAttempts: 5,\n resendCooldownSeconds: 60,\n perPurpose: {\n password_reset: {\n length: 8,\n codeType: 'alphanumeric',\n ttlSeconds: 900,\n maxAttempts: 5,\n resendCooldownSeconds: 60\n }\n }\n }\n })\n ]\n})\nexport class AppModule {}\n```\n\nFor async configuration (e.g. reading secrets from `ConfigService`), use `forRootAsync`:\n\n```typescript\nimport { ConfigModule, ConfigService } from '@nestjs/config'\n\nBymaxNotificationModule.forRootAsync({\n imports: [ConfigModule],\n inject: [ConfigService],\n useFactory: (config: ConfigService) => ({\n email: {\n provider: new ResendEmailProvider({ apiKey: config.getOrThrow('RESEND_API_KEY') }),\n defaultFrom: config.getOrThrow('MAIL_FROM')\n },\n otp: { storage: new RedisOtpStorage({ redisClient: redis }) }\n })\n})\n```\n\n> [!IMPORTANT]\n> `forRootAsync` supports the `useFactory` pattern. `useClass` / `useExisting` are not implemented and are rejected at startup.\n\n### 4. SMTP — any relay, and end-to-end tests\n\n`SmtpEmailProvider` speaks the protocol rather than one vendor's HTTP API, so the same adapter drives a corporate relay, Postfix, SES-via-SMTP, and the mail-capture servers (Mailpit, MailHog) that make email flows testable end to end. Requires the optional `nodemailer` peer dependency.\n\n```typescript\nimport { BymaxNotificationModule, SmtpEmailProvider } from '@bymax-one/nest-notification'\n\n// Local capture server — no credentials, no TLS. Read the captured mail at :8025.\nconst mailpit = new SmtpEmailProvider({ host: 'localhost', port: 1025, secure: false })\n\n// Authenticated production relay. STARTTLS is already mandatory by default here.\nconst relay = new SmtpEmailProvider({\n host: process.env.SMTP_HOST,\n port: 587,\n credentials: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }\n})\n\nBymaxNotificationModule.forRoot({\n email: {\n provider: process.env.NODE_ENV === 'production' ? relay : mailpit,\n defaultFrom: 'no-reply@acme.com'\n }\n})\n```\n\n| Option | Default | Notes |\n| --------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------- |\n| `host` | — | Required. Without it `isConfigured()` is `false` and `send()` throws. |\n| `port` | `587` | Submission port. |\n| `secure` | `true` iff port 465 | Implicit TLS from the first byte. |\n| `requireTls` | `true` off-loopback | Makes the STARTTLS upgrade mandatory. See the TLS note below. |\n| `credentials` | — (open relay) | `{ user, pass }`. Supplying it declares the deployment logs in. |\n| `tls` | — | `rejectUnauthorized` / `servername` / `ca`, for a relay behind a private CA. |\n| `connectionTimeout` / `greetingTimeout` / `socketTimeout` | `10s` / `10s` / `20s` | Bounded on purpose — Nodemailer's own defaults run into minutes. |\n\n> [!IMPORTANT]\n> `isConfigured()` answers on the real configuration, not on \"a transport object exists\". Omitting `credentials` marks the relay as open and is fine; supplying them half-loaded — an `SMTP_PASS` that never made it into the environment — reports **not configured** and fails the send closed, rather than silently attempting an anonymous delivery a permissive relay might accept.\n\n> [!WARNING]\n> **STARTTLS is mandatory by default for any non-loopback host.** On a connection that does not start out encrypted, whether TLS happens at all is decided by the _plaintext_ EHLO banner: an attacker with network position strips the `250-STARTTLS` line, the transport never upgrades, and the credentials and the message body — which carries the OTP code — cross the network in the clear. So `requireTls` defaults to `true` unless the host is `localhost` / `127.0.0.1` / `::1` or `secure` is already on. If your relay genuinely cannot upgrade, opt out explicitly with `requireTls: false`; a Mailpit or MailHog container reached by its compose service name rather than over loopback is the common case.\n\nThree further behaviours worth knowing:\n\n- The returned `messageId` is the RFC-5322 `Message-ID` with its angle brackets, so an audit entry correlates with the header the recipient received.\n- `tags` are not forwarded, because SMTP has no tag facility — they still reach the audit log through `EmailService`.\n- A line break in `from`, `replyTo`, a recipient, or a custom header name/value is **rejected before the send**. Nodemailer already neutralizes those, so this is defence in depth — but header injection is the one place where trusting a peer dependency's current behaviour would be the whole security boundary. The subject is deliberately exempt: a stray trailing newline from a template is plausible there, and Nodemailer folds it away.\n\n### 5. Bring Your Own Provider\n\nEvery external boundary is an interface — implement it and pass the instance (or class) to `forRoot`. The bundled `ResendEmailProvider` and `RedisOtpStorage` are reference implementations, not requirements.\n\n```typescript\nimport type {\n IEmailProvider,\n EmailSendOptions,\n EmailSendResult\n} from '@bymax-one/nest-notification'\n\nexport class SendGridEmailProvider implements IEmailProvider {\n readonly name = 'sendgrid'\n\n isConfigured(): boolean {\n return Boolean(this.apiKey)\n }\n\n async send(options: EmailSendOptions): Promise\n ![\"NestJS\"](\"https://img.shields.io/badge/NestJS-11-E0234E?style=flat-square&logo=nestjs&logoColor=white\"){kind=icon}
![\"React\"](\"https://img.shields.io/badge/React-19-61DAFB?style=flat-square&logo=react&logoColor=black\"){kind=icon}
![\"Redis\"](\"https://img.shields.io/badge/Redis-7%2B-DC382D?style=flat-square&logo=redis&logoColor=white\"){kind=icon}
![\"Resend\"](\"https://img.shields.io/badge/Resend-email-000000?style=flat-square&logo=resend&logoColor=white\"){kind=icon}
![\"Jest\"](\"https://img.shields.io/badge/Jest-30-C21325?style=flat-square&logo=jest&logoColor=white\"){kind=icon}
\n Built with ❤️ by Bymax One\n
\n","readmeFilename":"README.md"}