@nathapp/nestjs-notification 2.2.0 → 3.0.0

package/docs/20260214-fix-plan-notification.md

@@ -0,0 +1,149 @@
+# Fix Plan: @nathapp/nestjs-notification Code Review Issues
+
+**Date:** 2026-02-14
+**Branch:** `feat/notification-enterprise-upgrade`
+**Priority:** Fix all 🔴 Critical first, then 🟡 Medium, then 🟢 Low
+
+---
+
+## Phase 1: Critical Fixes (🔴)
+
+### Fix 1: SMS Data Corruption in `sendToChannel` [C2]
+**File:** `lib/notification/notification.service.ts`
+**Impact:** Actively corrupting SMS data in production
+**Change:**
+- Replace `countryIso2: payload.phoneNumber` → `countryIso2: payload.countryIso2`
+- Replace `dialCode: payload.phoneNumber` → `dialCode: payload.dialCode`
+- Add `countryIso2` and `dialCode` to `NotificationPayload` interface in `payload.inteface.ts`
+
+### Fix 2: Push Template Args Silently Dropped [C3]
+**File:** `lib/notification/notification.service.ts`
+**Impact:** Template variables not resolved for push notifications
+**Change:**
+- Replace `resolveOption` → `resolvedResolveOption` in the `templateLoader.resolve()` call inside `sendPushNotification`
+
+### Fix 3: Consolidate Duplicate `SendResult` [C5]
+**Files:** `lib/interface/result.interface.ts`, `lib/interface/payload.inteface.ts`
+**Impact:** Type confusion across codebase
+**Change:**
+- Remove `SendResult` from `payload.inteface.ts`
+- Add `error?: any` field to the canonical `SendResult` in `result.interface.ts`
+- Rename `payload.inteface.ts` → `payload.interface.ts` (fixes M1 typo)
+- Update all imports
+
+### Fix 4: `sendPushNotificationMulticastRaw` Returns null [C4]
+**File:** `lib/notification/notification.service.ts`
+**Impact:** Callers NPE on `result.successCount`
+**Change:**
+- Return `{ successCount: 0, failureCount: 0, responses: [] }` instead of `null`
+- Same fix for `sendPushNotificationMulticast`
+
+### Fix 5: Firebase App Memory Leak [C1]
+**File:** `lib/push-notification/fcm-push-notification.provider.ts`
+**Impact:** Memory leak on re-registration / testing
+**Change:**
+- Use unique app name: `fcm-${randomUUID()}`
+- Add `destroy()` method to delete Firebase app
+- Add `OnModuleDestroy` lifecycle hook awareness (document for consumers)
+- Wrap `JSON.parse(serviceAccount)` in try/catch (also fixes M7)
+
+---
+
+## Phase 2: Medium Fixes (🟡)
+
+### Fix 6: Fix `paltform` Typo [M2]
+**Files:** `lib/push-notification/push-notification-provider.manager.ts`, related files
+**Change:**
+- Rename parameter `paltform` → `platform` in `ProviderManager.getProvider()`
+- Keep `paltform` field in `PushMessage` as deprecated alias (backward compat)
+
+### Fix 7: `SmtpHostOption.port` String → Number [M3]
+**File:** `lib/email/email.interface.ts`
+**Change:**
+- Change `port: string` → `port: number`
+- Remove `parseInt()` in `email.provider.ts`
+
+### Fix 8: Remove `async` from `forRootAsync` [M10]
+**File:** `lib/notification/notification.module.ts`
+**Change:**
+- `static async forRootAsync(...)` → `static forRootAsync(...)`
+- Return `DynamicModule` not `Promise<DynamicModule>`
+
+### Fix 9: Fix `sendMulticast` Empty Array Crash [M9]
+**File:** `lib/push-notification/push-notification.service.ts`
+**Change:**
+- Add initial value to `reduce()`: `{ successCount: 0, failureCount: 0, responses: [] }`
+
+### Fix 10: Fix `EmailModule` Custom Provider Returns Class [M5]
+**File:** `lib/email/email.module.ts`
+**Change:**
+- `return moduleOption.option.provider` → `return new moduleOption.option.provider()`
+- Or better: use NestJS DI to instantiate
+
+### Fix 11: Fix `InMemoryUserTokenStore` Single Token [M8]
+**File:** `lib/push-notification/user-token.store.ts`
+**Change:**
+- Change `cache` to store arrays: `Record<string, DeviceToken[]>`
+- `saveUserToken` appends instead of overwrites
+- `getUserDeviceTokens` returns the array directly
+
+### Fix 12: Clean Up Unused Exports [M12]
+**Files:** Multiple
+**Change:**
+- Remove `EMAIL_SERVICE` constant (unused)
+- Remove `WHATSAPP_SERVICE` constant (unused)
+- Remove `import fs from "fs"` from `message.interface.ts`
+- Remove or deprecate `NOTIFICATION_SERVICE`, `TEMPLATE_SERVICE`
+- Remove `DefaultSmtpEmailModuleOptionsFactory` or keep as opt-in
+
+### Fix 13: Fix `sanitizeOptions` No-Op + Typo [M4]
+**File:** `lib/email/email.module.ts`
+**Change:**
+- Rename `santitizeOptions` → `sanitizeOptions`
+- Either implement validation or remove the method
+
+### Fix 14: Type Safety Improvements [M6]
+**Files:** Multiple
+**Change:**
+- Add generic type parameter to `ProviderConfig<C, O>` for options typing
+- Replace critical `any` usages with proper types where feasible
+
+---
+
+## Phase 3: Low Priority Fixes (🟢)
+
+### Fix 15: Grammar Fixes [L1]
+- `"is not configure"` → `"is not configured"`
+- `"template has set"` → `"template is set"`
+
+### Fix 16: Fix Input Mutation in Email Provider [L4]
+- Create new attachment objects instead of mutating input
+
+### Fix 17: Fix `result.response` Destructuring [L7]
+- Use `result.messageId` directly (nodemailer puts it on the result object, not response)
+
+### Fix 18: Fix `FakeTemplateLoader` Promise Pattern [L3]
+- Use `async` / `Promise.resolve()` instead of `new Promise()`
+
+### Fix 19: Fix `CachableTemplateLoader` Constructor [L6]
+- Move `cacheOptions` to be last or use options object pattern
+
+### Fix 20: Deprecate Old Modules [L5]
+- Add `@deprecated` JSDoc to `EmailModule`, `PushNotificationModule`
+- Add deprecation log warning when used
+- Document migration path to `NotificationModule`
+
+---
+
+## Test Strategy
+
+- Run full test suite after each phase
+- Target: all existing 159 tests passing + new tests for fixed edge cases
+- Add tests for: empty multicast array, null provider scenarios, Firebase cleanup
+
+## Commits
+
+One commit per phase:
+1. `fix: resolve all critical bugs (C1-C5)`
+2. `fix: resolve medium issues (M2-M14)`
+3. `chore: clean up low priority issues (L1-L7)`

package/docs/20260214-fix-plan-post-refactor.md

@@ -0,0 +1,118 @@
+# Fix Plan: Post-Refactor Cleanup
+
+**Date:** 2026-02-14
+**Branch:** `feat/notification-enterprise-upgrade`
+**Review Source:** `docs/20260214-review-post-refactor.md`
+
+---
+
+## Phase 1: Standardize Attachment Support (M1)
+
+### Fix 1: Rename `isSupportAttachments` to capability query pattern
+
+**Files:**
+- `lib/email/email.provider.ts`
+- `lib/whatsapp/whatsapp.provider.ts`
+- `lib/sms/sms.provider.ts`
+- `lib/push-notification/push-notification.provider.ts`
+
+**Change:**
+- Rename `isSupportAttachments` → `supportsAttachments` (cleaner naming)
+- Add `supportsAttachments` as optional with default `false` to ALL provider base classes
+- Email and WhatsApp default to abstract (must implement), SMS and Push default to `false`
+- Update `SmtpEmailProvider` to use new name
+- Update any references in tests
+
+## Phase 2: Document Push Provider (M2)
+
+### Fix 2: Add JSDoc to PushNotificationProvider
+
+**File:** `lib/push-notification/push-notification.provider.ts`
+
+**Change:**
+- Add comprehensive JSDoc explaining why push requires `type` and `sendMulticast`
+- Document that `type` maps to platform (firebase, huawei, apns, etc.)
+- Add usage examples in JSDoc
+
+## Phase 3: Clean Public API Exports (M3)
+
+### Fix 3: Restructure barrel exports
+
+**File:** `lib/index.ts`
+
+**Change:**
+Remove internal exports:
+- `EMAIL_OPTIONS`, `EMAIL_SERVICE` — internal/unused tokens
+- `EmailOption`, `SmtpOption`, `SmtpHostOption`, `SmtpUriOption`, `CustomEmailOption` — old config types
+- `EmailProviderFactory` — superseded
+- `SmtpEmailProvider` — built-in impl, keep but document as convenience export
+- `FCMPushNotificationOption`, `PushNotificationOption` — FCM-specific, move to push-specific export
+- `DefaultProviderManager`, `InMemoryUserTokenStore` — internal implementations
+- `WHATSAPP_SERVICE` — unused
+
+Keep public API:
+- Abstract providers: `EmailProvider`, `SmsProvider`, `WhatsAppProvider`, `PushNotificationProvider`
+- Services: `EmailService`, `SmsService`, `WhatsAppService`, `PushNotificationService`
+- Provider tokens: `EMAIL_PROVIDER`, `SMS_PROVIDER`, `WHATSAPP_PROVIDER`, `PUSH_NOTIFICATION_PROVIDERS`
+- Message types: all from `./interface`
+- Module: `NotificationModule` and option interfaces from `./notification`
+- Template: all from `./template`
+- Built-in providers (convenience): `SmtpEmailProvider`, `FCMPushNotificationProvider`
+- Push extras (needed by push provider authors): `PushNotificationPlatform`, `PlatformOS`, `ProviderManager`, `UserTokenStore`, `DeviceToken`, `TokenId`
+
+## Phase 4: Type Safety for ProviderConfig (M4)
+
+### Fix 4: Add generic options type
+
+**File:** `lib/notification/provider-config.ts`
+
+**Change:**
+- Keep `options?: any` for backward compat in `ProviderConfig`
+- Add typed helper pattern and document it:
+```typescript
+/**
+ * Helper to create a typed provider config.
+ * External packages should export a similar helper:
+ * 
+ * ```typescript
+ * // In @nathapp/nestjs-notification-brevo
+ * export function brevoEmailConfig(options: BrevoEmailOptions): ProviderConfig<'email'> {
+ *   return { channel: 'email', provider: BrevoEmailProvider, options };
+ * }
+ * ```
+ */
+```
+
+## Phase 5: Remove Legacy Modules (M5)
+
+### Fix 5: Remove deprecated modules and factories
+
+**Files to DELETE:**
+- `lib/email/email.module.ts`
+- `lib/email/email-provider.factory.ts`
+- `lib/push-notification/push-notification.module.ts`
+- `lib/push-notification/push-notification-provider.factory.ts`
+- `lib/push-notification/push-notification-provider-module.factory.ts`
+- `lib/push-notification/push-notification-module.interface.ts`
+
+**Files to UPDATE:**
+- `lib/email/index.ts` — remove module/factory exports
+- `lib/push-notification/index.ts` — remove module/factory exports
+
+**Document:** These modules were removed in v2.3.0 (or next version). Migration: use `NotificationModule.forRoot()` with unified `providers` array.
+
+---
+
+## Test Strategy
+
+- Run full test suite after each phase
+- All 159+ existing tests must pass
+- No new tests needed (this is cleanup, not new functionality)
+
+## Commits
+
+1. `refactor: standardize attachment support across all providers (M1)`
+2. `docs: add JSDoc to PushNotificationProvider (M2)`
+3. `refactor: clean public API exports (M3)`
+4. `feat: add typed provider config helper pattern (M4)`
+5. `refactor!: remove legacy EmailModule, PushNotificationModule and old factories (M5)`

package/docs/20260214-nestjs-notification-review.md

@@ -0,0 +1,390 @@
+# 🔍 Deep Code Review: `@nathapp/nestjs-notification`
+
+**Date:** 2026-02-14
+**Branch:** `feat/notification-enterprise-upgrade`
+**Reviewer:** Sabrina (AI)
+
+---
+
+## 🔴 Critical Issues (5)
+
+### C1: Firebase App Never Cleaned Up — Memory Leak
+
+**File:** `lib/push-notification/fcm-push-notification.provider.ts`
+
+Every `FCMPushNotificationProvider` calls `Firebase.initializeApp()` without a unique name, and there's **no cleanup**. If the module is re-registered or during testing, this leaks Firebase app instances.
+
+```typescript
+// Problem: no name → collides; no cleanup → leaks
+this.client = Firebase.initializeApp({
+  credential: Firebase.credential.cert(JSON.parse(option.serviceAccount)),
+  databaseURL: option.databaseUrl,
+});
+```
+
+**Fix:** Use unique app name + add `destroy()` method:
+```typescript
+import { randomUUID } from 'crypto';
+
+const appName = `fcm-${randomUUID()}`;
+this.client = Firebase.initializeApp({ ... }, appName);
+
+async destroy(): Promise<void> {
+  await this.client.delete();
+}
+```
+
+---
+
+### C2: `sendToChannel('sms')` Passes Phone Number as `countryIso2` AND `dialCode`
+
+**File:** `lib/notification/notification.service.ts` (sendToChannel method)
+
+```typescript
+case 'sms':
+  return this.sendSms({
+    templateCode: payload.templateCode,
+    phoneNumber: payload.phoneNumber,
+    options: payload.options,
+    countryIso2: payload.phoneNumber, // ❌ BUG: should be payload.countryIso2
+    dialCode: payload.phoneNumber,     // ❌ BUG: should be payload.dialCode
+  });
+```
+
+This **actively corrupts data** sent to downstream SMS providers. The phone number is being passed as both country ISO code and dial code.
+
+---
+
+### C3: `sendPushNotification` Uses Wrong Variable for Template Resolution
+
+**File:** `lib/notification/notification.service.ts` (sendPushNotification method)
+
+```typescript
+const templateMessage = await this.templateLoader.resolve(
+  resolvedTemplateCode,
+  resolveOption  // ❌ should be resolvedResolveOption
+);
+```
+
+When called via the payload overload `sendPushNotification(payload)`, the `resolveOption` parameter is `undefined` (it's only set in the legacy 3-arg overload). Template arguments are **silently dropped**.
+
+---
+
+### C4: `sendPushNotificationMulticastRaw` Returns `null` Instead of `BatchSendResult`
+
+**File:** `lib/notification/notification.service.ts`
+
+```typescript
+if (this.strict) {
+  throw new NotificationConfigError("PushNotificationService");
+}
+return null; // ❌ violates return type Promise<BatchSendResult>
+```
+
+Same issue in `sendPushNotificationMulticast`. Callers will get a null pointer exception when accessing `result.successCount`.
+
+---
+
+### C5: Duplicate `SendResult` Interface — Conflicting Definitions
+
+**Files:** `lib/interface/result.interface.ts` vs `lib/interface/payload.inteface.ts`
+
+Two different `SendResult` interfaces with different fields:
+
+```typescript
+// result.interface.ts
+export interface SendResult {
+  success: boolean;
+  message?: string;
+  requestId?: string;  // ← has requestId
+  extra?: any;
+}
+
+// payload.inteface.ts (also exported)
+export interface SendResult {
+  success: boolean;
+  message?: string;
+  error?: any;  // ← has error field instead
+}
+```
+
+Both are exported from `interface/index.ts`. TypeScript may merge or shadow depending on import order — a silent bug source.
+
+---
+
+## 🟡 Medium Issues (12)
+
+### M1: Typo in Filename
+
+**File:** `lib/interface/payload.inteface.ts`
+
+Missing 'r' in filename. Should be `payload.interface.ts`.
+
+---
+
+### M2: Deprecated `paltform` Typo Persists
+
+**Files:** `lib/interface/message.interface.ts`, `lib/push-notification/push-notification-provider.manager.ts`
+
+```typescript
+// message.interface.ts
+/** @deprecated Use `platform` instead */
+paltform?: PlatformOS;  // typo of "platform"
+
+// push-notification-provider.manager.ts
+getProvider(paltform?: PlatformOS)  // parameter still uses typo
+```
+
+---
+
+### M3: `SmtpHostOption.port` Is `string` Instead of `number`
+
+**File:** `lib/email/email.interface.ts`
+
+```typescript
+export interface SmtpHostOption {
+  port: string;  // ← should be number; parseInt() is used later in email.provider.ts
+}
+```
+
+---
+
+### M4: `sanitizeOptions` Is a No-Op (+ Typo)
+
+**File:** `lib/email/email.module.ts`
+
+```typescript
+private static santitizeOptions<T>(options: T): T {
+  return options;  // does nothing
+}
+```
+
+Also note typo: `santitize` → `sanitize` (fixed in notification module but not email module).
+
+---
+
+### M5: `EmailModule.createEmailProvider` Returns Class Instead of Instance for Custom Type
+
+**File:** `lib/email/email.module.ts`
+
+```typescript
+if (moduleOption.option.type == "custom") {
+  return moduleOption.option.provider;  // ← returns the CLASS, not an instance
+}
+```
+
+Should be `new moduleOption.option.provider()` or use NestJS DI to resolve.
+
+---
+
+### M6: Extensive `any` Usage — Weak Type Safety
+
+**Files:** Multiple locations
+
+- `ProviderConfig.options?: any` — no type constraint on provider options
+- `resolveOption.args?: any` in payload interfaces
+- `error?: any` in `SendResult`
+- `useFactory?: (...args: any[])` everywhere
+- Multiple `as any` casts in `notification.service.ts`
+
+---
+
+### M7: No Try/Catch on `JSON.parse(serviceAccount)` in FCM Provider
+
+**File:** `lib/push-notification/fcm-push-notification.provider.ts`
+
+```typescript
+credential: Firebase.credential.cert(JSON.parse(option.serviceAccount)),
+```
+
+If `serviceAccount` is malformed JSON, this throws an unhelpful parse error during module initialization, crashing the entire app.
+
+---
+
+### M8: `InMemoryUserTokenStore` Only Stores One Token Per User
+
+**File:** `lib/push-notification/user-token.store.ts`
+
+```typescript
+async saveUserToken(userId, token): Promise<TokenId> {
+  this.cache[userId] = token;  // ← silently overwrites previous token
+}
+```
+
+But `getUserDeviceTokens` (plural) wraps result in an array, implying multi-token support. The store silently drops old tokens.
+
+---
+
+### M9: `sendMulticast` Crashes on Empty Array
+
+**File:** `lib/push-notification/push-notification.service.ts`
+
+```typescript
+return results.reduce((a, b) => { ... })  // ← no initial value; crashes if results is empty
+```
+
+`Array.reduce()` without initial value on an empty array throws `TypeError`.
+
+---
+
+### M10: `forRootAsync` Returns `Promise<DynamicModule>` — Should Be Sync
+
+**File:** `lib/notification/notification.module.ts`
+
+```typescript
+static async forRootAsync(options): Promise<DynamicModule> {
+```
+
+NestJS `forRootAsync` should return `DynamicModule` synchronously. The `async` keyword here is unnecessary and could cause issues with module scanning.
+
+---
+
+### M11: `apnsPushType` Set in Wrong Location
+
+**File:** `lib/push-notification/fcm-push-notification.provider.ts`
+
+```typescript
+aps: {
+  mutableContent: true,
+  contentAvailable: true,
+  apnsPushType: "background"  // ← should be in APNs headers, not aps payload
+}
+```
+
+This relies on `[customData: string]: any` catch-all in the `Aps` interface.
+
+---
+
+### M12: Unused Exports/Constants
+
+- `EMAIL_SERVICE` — defined, exported, never used
+- `WHATSAPP_SERVICE` — defined, exported, never used
+- `NOTIFICATION_SERVICE`, `TEMPLATE_SERVICE` — defined, exported, never used as injection tokens
+- `DefaultSmtpEmailModuleOptionsFactory` — exported but likely unused
+- `import fs from "fs"` in `message.interface.ts` — Node.js import in an interface file (never used)
+
+---
+
+## 🟢 Low Issues (7)
+
+### L1: Inconsistent Error Message Grammar
+
+**File:** `lib/notification/notification.service.ts`
+
+`"is not configure"` → `"is not configured"`, `"template has set"` → `"template is set"`.
+
+---
+
+### L2: `DefaultSmtpEmailModuleOptionsFactory` Reads `process.env` Directly
+
+**File:** `lib/email/email.module.ts`
+
+Should use NestJS `ConfigService` for testability.
+
+---
+
+### L3: `FakeTemplateLoader` Uses Unnecessary Promise Constructor
+
+**File:** `lib/template/fake-template.loader.ts`
+
+```typescript
+return new Promise<MessageTemplate>((resolve, reject) => {
+  resolve({...});
+});
+// Better: return Promise.resolve({...}) or use async
+```
+
+---
+
+### L4: `email.provider.ts` Mutates Input Attachment Objects
+
+**File:** `lib/email/email.provider.ts`
+
+```typescript
+emailMessage.attachments?.map(item => {
+  if(typeof item.content == "string") {
+    item.content = Buffer.from(item.content, "base64")  // ← mutates original object
+  }
+```
+
+Should create new object: `return { ...item, content: Buffer.from(...) }`.
+
+---
+
+### L5: Inconsistent Module Registration Patterns
+
+- `EmailModule` uses `forRoot` / `forRootAsync`
+- `PushNotificationModule` uses `register` / `registerAsync`
+- `NotificationModule` uses `forRoot` / `forRootAsync`
+- SMS and WhatsApp have no standalone modules
+
+---
+
+### L6: `CachableTemplateLoader` Constructor Parameter Order Issue
+
+**File:** `lib/template/template.loader.ts`
+
+```typescript
+constructor(
+  @Inject(CACHE_MANAGER) private cacheManager: Cache,
+  cacheOptions?: CacheOptions,           // ← plain param between DI params
+  @Optional() @Inject(TEMPLATE_ENGINE) engine?: TemplateEngine
+)
+```
+
+Having a non-DI parameter between DI parameters breaks NestJS injection.
+
+---
+
+### L7: `result.response` Destructuring Bug in SmtpEmailProvider
+
+**File:** `lib/email/email.provider.ts`
+
+```typescript
+const result = await this.transporter.sendMail(...);
+const { messageId } = result.response;  // ← result.response is a STRING like "250 OK", not an object
+```
+
+`messageId` will always be `undefined` here.
+
+---
+
+## 🔒 Security Notes
+
+### S1 (🟡): Firebase Service Account JSON as Plain String
+
+**File:** `lib/push-notification/fcm-push-notification.provider.ts`
+
+`option.serviceAccount` contains entire Firebase service account JSON. If logged or serialized in error objects, credentials leak.
+
+### S2 (🟢): No HTML Sanitization on Email Body
+
+**File:** `lib/email/email.provider.ts`
+
+`message` is passed directly as `html` in nodemailer. If user-controlled content reaches this, it's an XSS/phishing vector in email clients.
+
+---
+
+## 📊 Summary
+
+| Severity | Count | Key Themes |
+|----------|-------|------------|
+| 🔴 Critical | 5 | Data corruption (SMS), wrong variable (push template), null returns, duplicate types, Firebase leak |
+| 🟡 Medium | 12 | Typos, type safety, no-op methods, async module, empty array crash |
+| 🟢 Low | 7 | Style, input mutation, grammar, constructor ordering |
+
+### Top 3 Priorities
+
+1. **C2** — SMS `countryIso2`/`dialCode` bug is **actively corrupting data**
+2. **C3** — Push template args **silently dropped**
+3. **C5** — Duplicate `SendResult` causing **type confusion across codebase**
+
+### Deprecated / Dead Code Candidates for Removal
+
+- `EmailModule` — superseded by `NotificationModule`
+- `PushNotificationModule` — superseded by `NotificationModule`
+- `EmailProviderFactory` — superseded by `NotificationProviderFactory`
+- `push-notification-provider.factory.ts` — superseded by unified factory
+- `push-notification-provider-module.factory.ts` — superseded
+- `push-notification-module.interface.ts` — superseded
+- `email-provider.factory.ts` — superseded