@nathapp/nestjs-notification 2.2.0 → 3.0.0

package/docs/20260214-review-post-refactor.md

@@ -0,0 +1,285 @@
+# Post-Refactor Code Review: @nathapp/nestjs-notification
+
+**Date:** 2026-02-14
+**Branch:** `feat/notification-enterprise-upgrade`
+**Purpose:** Ensure the refactored package is clean and consistent before redesigning external provider packages.
+
+---
+
+## 1. Provider/Service Consistency
+
+### Current Provider Contracts
+
+| Channel | Abstract Class | Methods | Extra Requirements |
+|---------|---------------|---------|-------------------|
+| Email | `EmailProvider` | `send(EmailMessage)`, `get isSupportAttachments` | ⚠️ Extra getter |
+| Push | `PushNotificationProvider` | `send(PushMessage)`, `sendMulticast(...)` | ⚠️ `readonly type: PushNotificationPlatform` + extra method |
+| SMS | `SmsProvider` | `send(SmsMessage)` | ✅ Clean |
+| WhatsApp | `WhatsAppProvider` | `send(WhatsAppMessage)` | ✅ Clean |
+
+### 🟡 M1: EmailProvider Has Extra `isSupportAttachments` Getter
+
+```typescript
+// EmailProvider
+abstract send(message: EmailMessage): Promise<SendResult>;
+abstract get isSupportAttachments(): boolean;  // ← extra requirement
+```
+
+SMS, WhatsApp, and Push don't have capability-query methods. An external dev writing `BrevoEmailProvider` must implement this extra getter, which is inconsistent.
+
+**Recommendation:** Either remove `isSupportAttachments` (most modern email providers support attachments) or add it to the interface doc as an explicit email-only requirement.
+
+### 🟡 M2: PushNotificationProvider Has Extra `type` Property and `sendMulticast`
+
+```typescript
+// PushNotificationProvider
+abstract readonly type: PushNotificationPlatform;  // ← extra
+abstract send(message: PushMessage): Promise<SendResult>;
+abstract sendMulticast(tokens: string[], message: PushMessageOnly): Promise<BatchSendResult>;  // ← extra method
+```
+
+This is justified (push has android/ios/huawei platforms and multicast), but it makes push the most complex channel to implement. Should be documented clearly.
+
+### 🟢 L1: Interface Naming Inconsistency
+
+- Email: `IEmailProvider`
+- SMS: `ISmsProvider`
+- WhatsApp: `IWhatsAppProvider`
+- Push: `IPushNotificationProvider`
+
+All fine, but `EmailProvider` also has `SmtpEmailProvider` in the same file — a concrete built-in impl mixed with the abstract. SMS/WhatsApp keep them separate (no built-in impl in core).
+
+---
+
+## 2. Public API Surface
+
+### What External Devs Need to Import
+
+| Channel | Import | Extend | Implement |
+|---------|--------|--------|-----------|
+| Email | `EmailProvider`, `EmailMessage`, `SendResult` | `EmailProvider` | `send()`, `isSupportAttachments` |
+| Push | `PushNotificationProvider`, `PushMessage`, `SendResult`, `BatchSendResult`, `PushNotificationPlatform` | `PushNotificationProvider` | `send()`, `sendMulticast()`, `type` |
+| SMS | `SmsProvider`, `SmsMessage`, `SendResult` | `SmsProvider` | `send()` |
+| WhatsApp | `WhatsAppProvider`, `WhatsAppMessage`, `SendResult` | `WhatsAppProvider` | `send()` |
+
+### 🟡 M3: Unnecessary Exports Leaking Internals
+
+The barrel `lib/index.ts` exports internal implementation details that external devs shouldn't depend on:
+
+- `EMAIL_OPTIONS`, `EMAIL_SERVICE` — internal DI tokens from old `EmailModule`
+- `EmailOption`, `SmtpOption`, `SmtpHostOption`, `SmtpUriOption`, `CustomEmailOption` — old config types
+- `EmailProviderFactory` — superseded by `NotificationProviderFactory`
+- `FCMPushNotificationOption`, `PushNotificationOption` — FCM-specific config
+- `PushNotificationProviderFactory` (via `push-notification/index.ts`) — old factory
+- `DefaultProviderManager`, `InMemoryUserTokenStore` — internal implementations
+- `WHATSAPP_SERVICE` — unused constant
+
+**Risk:** If we change any of these internals, external packages importing them will break.
+
+**Recommendation:** Create a clean public API surface. Only export what external devs actually need:
+- Abstract providers (`EmailProvider`, `SmsProvider`, `WhatsAppProvider`, `PushNotificationProvider`)
+- Message types (`EmailMessage`, `SmsMessage`, `WhatsAppMessage`, `PushMessage`)
+- Result types (`SendResult`, `BatchSendResult`)
+- `NotificationModule` and its option interfaces
+- `ProviderConfig` for registration
+
+---
+
+## 3. Breaking Changes for Existing Consumers
+
+| Change | Impact | Migration |
+|--------|--------|-----------|
+| `SmsService` no longer abstract | Packages extending `SmsService` break | Extend `SmsProvider` instead |
+| `WhatsAppService` no longer abstract | Packages extending `WhatsAppService` break | Extend `WhatsAppProvider` instead |
+| New injection tokens `SMS_PROVIDER`, `WHATSAPP_PROVIDER` | Code using `@Inject(SmsService)` still works | No change needed |
+| `strict: true` by default | Unconfigured channels now **throw** instead of returning `{ success: false }` | Set `strict: false` to keep old behavior |
+
+---
+
+## 4. Registration Flow Trace
+
+```
+NotificationModule.forRoot({
+  providers: [
+    { channel: 'email', provider: BrevoEmailProvider, options: { apiKey: '...' } }
+  ]
+})
+  ↓
+createChannelProviders(configs)
+  ↓
+groupProvidersByChannel(configs) → { email: [...], push: [...], sms: [...], whatsapp: [...] }
+  ↓
+NotificationProviderFactory.create(config)
+  → new config.provider(config.options)         // creates instance
+  → instanceof check against EmailProvider      // validates
+  ↓
+Register as { provide: EMAIL_PROVIDER, useValue: instance }
+Register as { provide: EmailService, useFactory: (p) => new EmailService(p), inject: [EMAIL_PROVIDER] }
+  ↓
+NotificationService injects @Optional() EmailService
+```
+
+### 🟢 L2: `forRootAsync` — Providers Created in Factory, Not at Module Init
+
+In `forRootAsync`, channel providers are created inside `useFactory` callbacks that depend on `NOTIFICATION_OPTIONS`. This is correct — options are resolved first, then providers created. No race condition.
+
+### 🟢 L3: Null Providers with `@Optional()`
+
+When a channel is not configured, its service is `null`. `NotificationService` handles this with null checks before each `send*` call. Clean.
+
+---
+
+## 5. Type Safety: `ProviderConfig.options: any`
+
+### 🟡 M4: No Type Constraint on Provider Options
+
+```typescript
+export interface ProviderConfig<C extends NotificationChannel = NotificationChannel> {
+  channel: C;
+  provider: Type<ChannelProviderMap[C]>;
+  options?: any;  // ← no type safety
+}
+```
+
+A developer can pass `{ channel: 'email', provider: BrevoEmailProvider, options: 12345 }` and TypeScript won't complain. The error only surfaces at runtime in the provider constructor.
+
+**Options to fix:**
+1. Generic options type: `ProviderConfig<C, O = any>` — but this makes registration verbose
+2. Provider-level static typing: each provider exports a helper `BrevoEmailProvider.config(opts): ProviderConfig` — cleanest for consumers
+3. Leave as `any` but document clearly — pragmatic choice
+
+**Recommendation:** Option 3 for now (document), option 2 for external provider packages (each exports a typed helper).
+
+---
+
+## 6. Remaining Dead Code
+
+### 🟡 M5: Legacy Modules Still Present
+
+| File | Status | Action |
+|------|--------|--------|
+| `email/email.module.ts` | Superseded by `NotificationModule` | Deprecate or remove |
+| `email/email-provider.factory.ts` | Superseded by `NotificationProviderFactory` | Deprecate or remove |
+| `push-notification/push-notification.module.ts` | Superseded | Deprecate or remove |
+| `push-notification/push-notification-provider.factory.ts` | Superseded | Deprecate or remove |
+| `push-notification/push-notification-provider-module.factory.ts` | Superseded | Remove |
+| `push-notification/push-notification-module.interface.ts` | Superseded | Remove |
+
+These add ~500 lines of dead code and confuse developers about which pattern to use.
+
+**Recommendation:** Add `@deprecated` JSDoc to `EmailModule` and `PushNotificationModule`. Remove the internal factories that are no longer used by any code path.
+
+---
+
+## 7. External Provider Developer Guide
+
+### Minimum Requirements per Channel
+
+#### Email Provider
+```typescript
+import { EmailProvider, EmailMessage, SendResult } from '@nathapp/nestjs-notification';
+
+export interface MyEmailOptions {
+  apiKey: string;
+}
+
+export class MyEmailProvider extends EmailProvider {
+  constructor(private readonly options: MyEmailOptions) {
+    super();
+  }
+
+  get isSupportAttachments(): boolean {
+    return true;
+  }
+
+  async send(message: EmailMessage): Promise<SendResult> {
+    // message.recipient, message.subject, message.message, message.attachments
+    return { success: true, requestId: '...' };
+  }
+}
+```
+
+#### SMS Provider
+```typescript
+import { SmsProvider, SmsMessage, SendResult } from '@nathapp/nestjs-notification';
+
+export class MySmsProvider extends SmsProvider {
+  constructor(private readonly options: any) { super(); }
+
+  async send(message: SmsMessage): Promise<SendResult> {
+    // message.recipient, message.message, message.countryIso2, message.dialCode
+    return { success: true };
+  }
+}
+```
+
+#### WhatsApp Provider
+```typescript
+import { WhatsAppProvider, WhatsAppMessage, SendResult } from '@nathapp/nestjs-notification';
+
+export class MyWhatsAppProvider extends WhatsAppProvider {
+  constructor(private readonly options: any) { super(); }
+
+  async send(message: WhatsAppMessage): Promise<SendResult> {
+    // message.recipient, message.message, message.templateName, message.bodyParams
+    return { success: true };
+  }
+}
+```
+
+#### Push Provider
+```typescript
+import { PushNotificationProvider, PushMessage, PushMessageOnly, SendResult, BatchSendResult, PushNotificationPlatform } from '@nathapp/nestjs-notification';
+
+export class MyPushProvider extends PushNotificationProvider {
+  readonly type: PushNotificationPlatform = 'firebase'; // or custom string
+
+  constructor(private readonly options: any) { super(); }
+
+  async send(message: PushMessage): Promise<SendResult> {
+    return { success: true };
+  }
+
+  async sendMulticast(tokens: string[], message: PushMessageOnly): Promise<BatchSendResult> {
+    return { successCount: tokens.length, failureCount: 0, responses: [] };
+  }
+}
+```
+
+### Consumer Registration
+```typescript
+import { NotificationModule } from '@nathapp/nestjs-notification';
+import { BrevoEmailProvider } from '@nathapp/nestjs-notification-brevo';
+
+@Module({
+  imports: [
+    NotificationModule.forRoot({
+      providers: [
+        { channel: 'email', provider: BrevoEmailProvider, options: { apiKey: '...' } },
+      ],
+      templateLoader: MyTemplateLoader,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+---
+
+## Summary
+
+| Severity | Count | Key Items |
+|----------|-------|-----------|
+| 🔴 Critical | 0 | None — previous fixes resolved all criticals |
+| 🟡 Medium | 5 | Provider inconsistencies (M1-M2), leaky exports (M3), untyped options (M4), dead code (M5) |
+| 🟢 Low | 3 | Naming inconsistency (L1), async flow (L2-L3) |
+
+### Before Merging to Master
+1. Decide: remove `isSupportAttachments` from `EmailProvider` or keep as email-only requirement
+2. Decide: deprecate or remove legacy modules (`EmailModule`, `PushNotificationModule`)
+3. Clean up barrel exports to only expose public API
+
+### Before Redesigning External Providers
+- The provider contract is clear and documented above
+- Each external package: export provider class + options interface, peer dep on `@nathapp/nestjs-notification`
+- Consider typed config helpers per provider package