@nathapp/nestjs-notification 2.1.4 → 3.0.0-rc.4

package/CLAUDE.md

@@ -0,0 +1,21 @@
+# @nathapp/nestjs-notification
+
+Multi-channel notification library — Email, SMS, WhatsApp, Push.
+
+## Commands
+- Test: `npx jest --config test/jest-test.json --no-coverage`
+- Build: `npx tsc`
+
+## Provider/Service Pattern
+- `XxxProvider` (abstract) → external devs extend this for custom implementations.
+- `XxxService` (injectable wrapper) → internal, resolves provider via `XXX_PROVIDER` token.
+- Push is special: uses `ProviderManager` for multi-provider (Android/iOS/Huawei).
+
+## Key Tokens
+- `EMAIL_PROVIDER`, `SMS_PROVIDER`, `WHATSAPP_PROVIDER`, `PUSH_PROVIDER`
+- Register via `NotificationModule.forRoot({ providers: [...] })`
+
+## Gotchas
+- External providers extend `XxxProvider`, NOT `XxxService` (breaking change from v2).
+- Template system is custom (not using Handlebars/EJS) — uses `{{variable}}` interpolation.
+- Firebase push provider: ensure cleanup in `onModuleDestroy` to prevent memory leaks.

package/UPGRADE-PLAN-PHASE7-8.md

@@ -0,0 +1,307 @@
+# @nathapp/nestjs-notification — Phase 7 & 8: WhatsApp Channel + Fallback
+
+**Branch:** `feat/notification-enterprise-upgrade` (continue from Phase 6)
+**Prerequisite commits:** Phases 1-6 complete, coverage at 81%+
+
+---
+
+## Phase 7: WhatsApp Channel Support
+
+### Problem
+WhatsApp is a major messaging channel (especially in Asia) for OTPs, alerts, and transactional messages. It requires its own channel type because:
+- Pre-approved template requirements (Meta Business API)
+- Rich content support (buttons, media, lists)
+- Session-based delivery model (24h reply window)
+- Different from SMS — cannot reuse `SmsService`
+
+### Changes
+
+#### 7.1 Create `WhatsAppMessage` interface
+**File:** `lib/interface/message.interface.ts` (UPDATE)
+
+```typescript
+export interface WhatsAppMessage extends BaseMessage {
+  /** WhatsApp template name (required by Meta Business API) */
+  templateName?: string;
+  /** Template language code (e.g., 'en', 'zh_CN') */
+  languageCode?: string;
+  /** Template header parameters */
+  headerParams?: string[];
+  /** Template body parameters */
+  bodyParams?: string[];
+  /** Optional media attachment URL */
+  mediaUrl?: string;
+}
+```
+
+#### 7.2 Create `WhatsAppService` abstract class
+**File:** `lib/whatsapp/whatsapp.service.ts` (NEW)
+
+```typescript
+import { WhatsAppMessage, SendResult } from '../interface';
+
+export interface IWhatsAppService {
+  send(message: WhatsAppMessage): Promise<SendResult>;
+}
+
+export abstract class WhatsAppService implements IWhatsAppService {
+  abstract send(message: WhatsAppMessage): Promise<SendResult>;
+}
+```
+
+#### 7.3 Create WhatsApp index and constants
+**File:** `lib/whatsapp/index.ts` (NEW)
+**File:** `lib/whatsapp/constant.ts` (NEW) — `export const WHATSAPP_SERVICE = 'WHATSAPP_SERVICE';`
+
+#### 7.4 Add `WhatsAppNotificationPayload` interface
+**File:** `lib/interface/payload.inteface.ts` (UPDATE)
+
+```typescript
+export interface WhatsAppNotificationPayload {
+  phoneNumber: string;
+  templateCode: string;
+  options?: {
+    locale?: string;
+    fallbackLocale?: string;
+    args?: any;
+  };
+  /** WhatsApp-specific: Meta template name (if different from templateCode) */
+  whatsappTemplateName?: string;
+  /** WhatsApp-specific: media attachment URL */
+  mediaUrl?: string;
+}
+```
+
+#### 7.5 Update `NotificationChannel` type
+**File:** `lib/interface/payload.inteface.ts` (UPDATE)
+
+```typescript
+export type NotificationChannel = 'email' | 'push' | 'sms' | 'whatsapp';
+```
+
+#### 7.6 Add WhatsApp to `NotificationService`
+**File:** `lib/notification/notification.service.ts` (UPDATE)
+
+- Add `@Optional() @Inject(WhatsAppService) private readonly whatsAppService: WhatsAppService` to constructor
+- Implement `sendWhatsApp(data: WhatsAppNotificationPayload): Promise<SendResult>` method
+  - Resolves template via `templateLoader`
+  - Calls `whatsAppService.send()` with resolved message
+  - Respects `strict` mode (throw if not configured vs return `{ success: false }`)
+- Update `send()` unified method to handle `'whatsapp'` channel
+
+#### 7.7 Add WhatsApp options to `NotificationModule`
+**File:** `lib/notification/notification.module.ts` (UPDATE)
+
+```typescript
+export interface NotificationModuleOptions {
+  // ... existing
+  whatsAppService?: Type<WhatsAppService>;
+}
+```
+
+- Register `WhatsAppService` provider when `whatsAppService` option is provided
+- Support in both `forRoot` and `forRootAsync`
+
+#### 7.8 Update `NotificationContext` for interceptors
+**File:** `lib/notification/notification.interceptor.ts` (UPDATE)
+
+The existing `NotificationChannel` type update will automatically make interceptors aware of `'whatsapp'`.
+
+#### 7.9 Export new types
+**File:** `lib/whatsapp/index.ts` (NEW)
+**File:** `lib/index.ts` (UPDATE) — export WhatsApp types
+
+### Unit Tests
+
+**File:** `test/notification/notification-whatsapp.service.spec.ts` (NEW)
+- `sendWhatsApp()` with configured service → resolves template, calls `whatsAppService.send()`
+- `sendWhatsApp()` without service + `strict: true` → throws `NotificationConfigError`
+- `sendWhatsApp()` without service + `strict: false` → returns `{ success: false }`
+- `send({ channels: ['whatsapp'] })` routes to `sendWhatsApp()`
+- `send({ channels: ['email', 'whatsapp'] })` dispatches to both
+- `sendWhatsApp()` passes `whatsappTemplateName` and `mediaUrl` to service
+
+### E2E Tests
+
+**File:** `test/module/notification-whatsapp.module.e2e.spec.ts` (NEW)
+- Register module with mock `WhatsAppService` → `sendWhatsApp()` works
+- Register module without WhatsApp + `strict: false` → `send({ channels: ['whatsapp'] })` returns `{ success: false }`
+- Full module with email + WhatsApp → unified `send()` dispatches to both
+
+---
+
+## Phase 8: Channel Fallback Support
+
+### Problem
+When a preferred channel fails (e.g., WhatsApp undeliverable), the system should automatically try alternative channels. This must be:
+- Configurable per-notification (not global)
+- Observable via interceptors (log fallback events)
+- Provider-agnostic (WhatsApp via Meta, SMS via Twilio — doesn't matter)
+
+### Changes
+
+#### 8.1 Add `fallback` to `NotificationPayload`
+**File:** `lib/interface/payload.inteface.ts` (UPDATE)
+
+```typescript
+export interface NotificationPayload {
+  templateCode: string;
+  channels: NotificationChannel[];
+  /** Ordered fallback channels. Tried sequentially if ALL primary channels fail. */
+  fallback?: NotificationChannel[];
+  options?: {
+    locale?: string;
+    fallbackLocale?: string;
+    args?: any;
+  };
+  // Channel-specific recipient data
+  email?: string;
+  userId?: string | number;
+  deviceToken?: DeviceToken;
+  phoneNumber?: string;
+  /** WhatsApp-specific fields */
+  whatsappTemplateName?: string;
+  mediaUrl?: string;
+  // Optional
+  attachments?: EmailAttachment[];
+}
+```
+
+#### 8.2 Add `FallbackResult` to `NotificationResult`
+**File:** `lib/interface/payload.inteface.ts` (UPDATE)
+
+```typescript
+export interface NotificationResult {
+  results: Partial<Record<NotificationChannel, SendResult>>;
+  /** True if primary OR fallback succeeded */
+  success: boolean;
+  /** Which fallback channels were attempted (empty if primary succeeded) */
+  fallbackAttempted?: NotificationChannel[];
+  /** Which fallback channel succeeded (undefined if none) */
+  fallbackSucceeded?: NotificationChannel;
+}
+```
+
+#### 8.3 Update `send()` in `NotificationService` with fallback logic
+**File:** `lib/notification/notification.service.ts` (UPDATE)
+
+```typescript
+async send(payload: NotificationPayload): Promise<NotificationResult> {
+  // 1. Try all primary channels
+  const results: Partial<Record<NotificationChannel, SendResult>> = {};
+  for (const channel of payload.channels) {
+    results[channel] = await this.sendToChannel(channel, payload);
+  }
+
+  const primarySuccess = Object.values(results).some(r => r.success);
+
+  // 2. If ALL primary channels failed AND fallback is defined, try fallbacks
+  if (!primarySuccess && payload.fallback?.length) {
+    const fallbackAttempted: NotificationChannel[] = [];
+    let fallbackSucceeded: NotificationChannel | undefined;
+
+    for (const fallbackChannel of payload.fallback) {
+      fallbackAttempted.push(fallbackChannel);
+      const fallbackResult = await this.sendToChannel(fallbackChannel, payload);
+      results[fallbackChannel] = fallbackResult;
+
+      if (fallbackResult.success) {
+        fallbackSucceeded = fallbackChannel;
+        break; // Stop on first successful fallback
+      }
+    }
+
+    return {
+      results,
+      success: !!fallbackSucceeded,
+      fallbackAttempted,
+      fallbackSucceeded,
+    };
+  }
+
+  return {
+    results,
+    success: primarySuccess,
+  };
+}
+
+/** Internal: dispatch to a single channel */
+private async sendToChannel(
+  channel: NotificationChannel,
+  payload: NotificationPayload,
+): Promise<SendResult> {
+  switch (channel) {
+    case 'email':
+      return this.sendEmail({ ... });
+    case 'push':
+      return this.sendPushNotification({ ... });
+    case 'sms':
+      return this.sendSms({ ... });
+    case 'whatsapp':
+      return this.sendWhatsApp({ ... });
+    default:
+      return { success: false, message: `Unknown channel: ${channel}` };
+  }
+}
+```
+
+#### 8.4 Update interceptors to include fallback context
+**File:** `lib/notification/notification.interceptor.ts` (UPDATE)
+
+```typescript
+export interface NotificationContext {
+  channel: NotificationChannel;
+  templateCode: string;
+  recipient: string;
+  resolvedMessage?: { subject?: string; content: string };
+  /** True if this send is a fallback attempt */
+  isFallback?: boolean;
+  /** The original channel that failed (when isFallback is true) */
+  failedChannel?: NotificationChannel;
+}
+```
+
+#### 8.5 Handle unconfigured fallback channels
+**File:** `lib/notification/notification.service.ts` (UPDATE)
+
+When a fallback channel's service is not configured:
+- **`strict: true`** → throw `NotificationConfigError` (developer mistake — they specified a fallback they didn't configure)
+- **`strict: false`** → skip that fallback channel silently (log a warning), move to next fallback in the list. If all fallbacks are unconfigured/failed, return `{ success: false }`.
+
+The `sendToChannel()` method already handles this via the existing strict/lenient pattern. In lenient mode, an unconfigured channel returns `{ success: false }`, which the fallback loop treats as a failure and moves to the next channel.
+
+### Unit Tests
+
+**File:** `test/notification/notification-fallback.spec.ts` (NEW)
+- `send()` with `fallback: ['sms']` — primary email succeeds → no fallback attempted
+- `send()` with `channels: ['whatsapp'], fallback: ['sms']` — WhatsApp fails → SMS attempted and succeeds
+- `send()` with `channels: ['whatsapp'], fallback: ['sms']` — both fail → `success: false`, both in `fallbackAttempted`
+- `send()` with `channels: ['whatsapp'], fallback: ['sms', 'email']` — WhatsApp fails, SMS fails, email succeeds → `fallbackSucceeded: 'email'`
+- `send()` with no `fallback` — primary fails → no fallback, `success: false`
+- `send()` with `channels: ['email', 'push']` — email fails, push succeeds → `success: true`, no fallback needed
+- Interceptor `beforeSend` receives `isFallback: true` and `failedChannel` during fallback
+- Interceptor `afterSend` receives fallback context
+- **`send()` with `fallback: ['sms']` but SMS not configured + `strict: true` → throws `NotificationConfigError`**
+- **`send()` with `fallback: ['sms']` but SMS not configured + `strict: false` → skips SMS, returns `{ success: false }`**
+- **`send()` with `fallback: ['sms', 'email']` — SMS not configured (strict: false), email configured and succeeds → `fallbackSucceeded: 'email'`**
+
+### E2E Tests
+
+**File:** `test/module/notification-fallback.module.e2e.spec.ts` (NEW)
+- Full module with WhatsApp (mock fail) + SMS (mock success) → fallback works end-to-end
+- Full module with email only, `fallback: ['email']` but email succeeds on primary → no fallback
+- Verify interceptor hooks fire with correct `isFallback` flag
+
+---
+
+## Implementation Order
+
+1. **Phase 7** first (WhatsApp channel) — new channel, additive, no breaking changes
+2. **Phase 8** second (Fallback) — builds on Phase 7's `whatsapp` channel for the primary use case
+
+## Breaking Changes
+
+**None.** Both phases are purely additive:
+- `whatsapp` is a new channel option
+- `fallback` is an optional field on `NotificationPayload`
+- Existing `send()` calls without `fallback` behave identically

package/UPGRADE-PLAN-PHASE9.md

@@ -0,0 +1,361 @@
+# @nathapp/nestjs-notification — Phase 9: Unified Provider Registry
+
+**Branch:** `feat/notification-enterprise-upgrade` (continue from Phase 8)
+**Breaking Change:** Yes — replaces `emailOptions` / `pushNotificationOptions` with unified `providers` array.
+
+---
+
+## Overview
+
+Replace the per-channel module registration pattern (`EmailModule.forRoot()`, `PushNotificationModule.register()`) with a single, unified `providers` array on `NotificationModule`. Providers are just classes — no wrapper modules needed.
+
+### Before (current)
+```typescript
+NotificationModule.forRoot({
+  emailOptions: EmailModule.forRoot({ option: { type: 'smtp', options: {...} } }),
+  pushNotificationOptions: PushNotificationModule.register({ providers: [...] }),
+  smsService: TwilioSmsProvider,
+  whatsAppService: TwilioWhatsAppProvider,
+  templateLoader: MyLoader,
+})
+```
+
+### After (new)
+```typescript
+NotificationModule.forRoot({
+  providers: [
+    { channel: 'email', provider: SmtpEmailProvider, options: { url: 'smtp://...', from: 'noreply@app.com' } },
+    { channel: 'push', provider: FcmPushNotificationProvider, options: { projectId: '...' } },
+    { channel: 'sms', provider: TwilioSmsProvider, options: { accountSid: '...', authToken: '...', from: '+1...' } },
+    { channel: 'whatsapp', provider: TwilioWhatsAppProvider, options: { accountSid: '...' } },
+  ],
+  templateLoader: MyLoader,
+  strict: true,
+})
+```
+
+### Async with ModuleOptionsFactory
+```typescript
+@Injectable()
+export class AppNotificationOptionsFactory implements NotificationModuleOptionsFactory {
+  constructor(private config: ConfigService) {}
+
+  createOptions(): NotificationModuleOptions {
+    return {
+      providers: [
+        { channel: 'email', provider: SmtpEmailProvider, options: { url: this.config.get('SMTP_URL'), from: this.config.get('EMAIL_FROM') } },
+      ],
+      templateLoader: MyLoader,
+    };
+  }
+}
+
+NotificationModule.forRootAsync({
+  imports: [ConfigModule],
+  useClass: AppNotificationOptionsFactory,
+})
+```
+
+---
+
+## Changes
+
+### 9.1 Create `ProviderConfig` interface
+**File:** `lib/notification/provider-config.ts` (NEW)
+
+```typescript
+import { Type } from '@nestjs/common';
+import { NotificationChannel } from '../interface';
+import { EmailProvider } from '../email';
+import { PushNotificationProvider } from '../push-notification';
+import { SmsService } from '../sms';
+import { WhatsAppService } from '../whatsapp';
+
+export type ChannelProviderMap = {
+  email: EmailProvider;
+  push: PushNotificationProvider;
+  sms: SmsService;
+  whatsapp: WhatsAppService;
+};
+
+export interface ProviderConfig<C extends NotificationChannel = NotificationChannel> {
+  channel: C;
+  provider: Type<ChannelProviderMap[C]>;
+  options?: any;
+}
+```
+
+### 9.2 Create `NotificationProviderFactory`
+**File:** `lib/notification/notification-provider.factory.ts` (NEW)
+
+```typescript
+import { Logger } from '@nestjs/common';
+import { ProviderConfig, ChannelProviderMap } from './provider-config';
+import { EmailProvider } from '../email';
+import { PushNotificationProvider } from '../push-notification';
+import { SmsService } from '../sms';
+import { WhatsAppService } from '../whatsapp';
+
+const CHANNEL_BASE_CLASSES: Record<string, Function> = {
+  email: EmailProvider,
+  push: PushNotificationProvider,
+  sms: SmsService,
+  whatsapp: WhatsAppService,
+};
+
+export class NotificationProviderFactory {
+  private static readonly logger = new Logger(NotificationProviderFactory.name);
+
+  /**
+   * Create a provider instance from config.
+   * Validates that the provider class matches the expected base class for its channel.
+   * @throws Error if provider doesn't match its channel
+   */
+  static create<C extends keyof ChannelProviderMap>(
+    config: ProviderConfig<C>,
+  ): ChannelProviderMap[C] {
+    const { channel, provider, options } = config;
+    const baseClass = CHANNEL_BASE_CLASSES[channel];
+
+    if (!baseClass) {
+      throw new Error(`Unknown notification channel: ${channel}`);
+    }
+
+    // Validate: check prototype chain
+    const instance = new provider(options);
+
+    if (!(instance instanceof baseClass)) {
+      throw new Error(
+        `${provider.name} is not a valid ${channel} provider. ` +
+        `Expected ${baseClass.name} subclass.`,
+      );
+    }
+
+    this.logger.log(`Created ${channel} provider: ${provider.name}`);
+    return instance as ChannelProviderMap[C];
+  }
+}
+```
+
+### 9.3 Rewrite `NotificationModule` options interfaces
+**File:** `lib/notification/notification.module.ts` (REWRITE)
+
+Replace the old `NotificationModuleOptions` and `NotificationModuleAsyncOptions` with:
+
+```typescript
+export interface NotificationModuleOptions {
+  /** Unified provider registration */
+  providers?: ProviderConfig[];
+  /** Template loader class */
+  templateLoader: Type<TemplateLoader> | ProviderAsyncOptions<TemplateLoader>;
+  /** Template engine class (default: StringFormatEngine) */
+  templateEngine?: Type<TemplateEngine>;
+  /** Template service override */
+  templateService?: Type<TemplateService>;
+  /** Notification service override */
+  notificationService?: Type<NotificationService>;
+  /** Interceptors */
+  interceptors?: Type<NotificationInterceptor>[];
+  /** Strict mode (default: true) */
+  strict?: boolean;
+  /** Push notification provider manager override */
+  providerManager?: Type<ProviderManager>;
+  /** Push notification user token store override */
+  userTokenStore?: Type<UserTokenStore>;
+}
+
+export interface NotificationModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+  /** Use a factory class to create options */
+  useClass?: Type<NotificationModuleOptionsFactory>;
+  /** Reuse an existing factory */
+  useExisting?: Type<NotificationModuleOptionsFactory>;
+  /** Inline factory function */
+  useFactory?: (...args: any[]) => NotificationModuleOptions | Promise<NotificationModuleOptions>;
+  inject?: any[];
+}
+
+export interface NotificationModuleOptionsFactory {
+  createOptions(): NotificationModuleOptions | Promise<NotificationModuleOptions>;
+}
+```
+
+### 9.4 Rewrite `NotificationModule.forRoot()`
+**File:** `lib/notification/notification.module.ts` (REWRITE)
+
+The new `forRoot` should:
+1. Iterate `options.providers` array
+2. Use `NotificationProviderFactory.create()` for each
+3. Group by channel type
+4. Register each as the appropriate injection token:
+   - `email` → `EMAIL_PROVIDER` token + create `EmailService` wrapping it
+   - `push` → `PUSH_NOTIFICATION_PROVIDERS` token + create `PushNotificationService`
+   - `sms` → `SmsService` token
+   - `whatsapp` → `WhatsAppService` token
+5. Register template engine, template loader, template service, notification service, interceptors (same as current)
+6. Store `strict` option in `NOTIFICATION_OPTIONS`
+
+**Key implementation detail:** When a channel has no provider registered, do NOT create its service. `NotificationService` already handles missing services via `@Optional()` inject + strict mode.
+
+### 9.5 Rewrite `NotificationModule.forRootAsync()`
+**File:** `lib/notification/notification.module.ts` (REWRITE)
+
+Support all three async patterns:
+
+**`useClass`:**
+```typescript
+NotificationModule.forRootAsync({
+  imports: [ConfigModule],
+  useClass: AppNotificationOptionsFactory,
+})
+```
+- NestJS creates `AppNotificationOptionsFactory`, injects its dependencies
+- Calls `factory.createOptions()` to get `NotificationModuleOptions`
+- Then same provider registration as `forRoot`
+
+**`useExisting`:**
+```typescript
+NotificationModule.forRootAsync({
+  useExisting: AppNotificationOptionsFactory,
+})
+```
+- Reuses an already-registered factory
+
+**`useFactory`:**
+```typescript
+NotificationModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    providers: [
+      { channel: 'email', provider: SmtpEmailProvider, options: { url: config.get('SMTP_URL') } },
+    ],
+    templateLoader: MyLoader,
+  }),
+  inject: [ConfigService],
+})
+```
+
+### 9.6 Keep `EmailModule` and `PushNotificationModule` as internal
+**File:** `lib/email/email.module.ts`, `lib/push-notification/push-notification.module.ts`
+
+Do NOT delete these modules. They still work internally. But they are no longer the primary public API. The public API is `NotificationModule.forRoot({ providers: [...] })`.
+
+Remove `EmailModule` and `PushNotificationModule` from the main `index.ts` exports. Keep them accessible for advanced use cases via deep imports, but they're no longer the recommended approach.
+
+### 9.7 Update `NotificationService` constructor
+**File:** `lib/notification/notification.service.ts` (UPDATE)
+
+The constructor already uses `@Optional()` for all services. No changes needed here — the module registration changes handle which services are available.
+
+### 9.8 Export new types
+**File:** `lib/notification/index.ts` (UPDATE)
+**File:** `lib/index.ts` (UPDATE)
+
+Export: `ProviderConfig`, `ChannelProviderMap`, `NotificationProviderFactory`, `NotificationModuleOptionsFactory`
+
+Remove from top-level exports: `EmailModule`, `EmailModuleOptions`, `EmailModuleAsyncOptions`, `PushNotificationModule`, `PushNotificationModuleOptions`, `PushNotificationModuleAsyncOptions`
+
+---
+
+## Unit Tests
+
+**File:** `test/notification/notification-provider.factory.spec.ts` (NEW)
+- `create()` with `SmtpEmailProvider` + channel `email` → returns instance
+- `create()` with `FcmPushNotificationProvider` + channel `push` → returns instance
+- `create()` with options → passes options to constructor
+- `create()` with mismatched provider/channel → throws descriptive error (e.g., `TwilioSmsProvider` on `email` channel)
+- `create()` with unknown channel → throws `Unknown notification channel` error
+- `create()` without options → creates provider with undefined options (no crash)
+
+**File:** `test/notification/notification-module-unified.spec.ts` (NEW)
+- `forRoot()` with single email provider → `EmailService` is available, `NotificationService` can send email
+- `forRoot()` with multiple channels → all services registered
+- `forRoot()` with no providers → no services available, strict mode throws on send
+- `forRoot()` with `strict: false` + no providers → `send()` returns `{ success: false }`
+- `forRoot()` with custom `templateEngine` → engine is used
+- `forRoot()` with `interceptors` → interceptors are called
+
+**File:** `test/notification/notification-module-async.spec.ts` (NEW)
+- `forRootAsync()` with `useFactory` → providers created from factory result
+- `forRootAsync()` with `useClass` (NotificationModuleOptionsFactory) → factory `createOptions()` called, providers registered
+- `forRootAsync()` with `useExisting` → reuses existing factory
+- `forRootAsync()` with `inject: [ConfigService]` → config values passed to factory
+
+## E2E Tests
+
+**File:** `test/module/notification-unified-providers.module.e2e.spec.ts` (NEW)
+- Full module with `providers: [{ channel: 'email', provider: SmtpEmailProvider, options: {...} }]` → email sending works
+- Full module with email + sms providers → both channels work via unified `send()`
+- Module with mismatched provider → bootstrap throws
+- `forRootAsync` with `useClass` factory → full e2e send works
+
+**File:** `test/module/notification-options-factory.module.e2e.spec.ts` (NEW)
+- `useClass: TestOptionsFactory` → factory is instantiated, `createOptions()` called
+- Factory receives injected dependencies (e.g., a mock config service)
+- Options from factory are used to create providers correctly
+
+---
+
+## Migration Guide (for consumers)
+
+### Before
+```typescript
+NotificationModule.forRoot({
+  emailOptions: { option: { type: 'smtp', options: { url: '...', from: '...' } } },
+  pushNotificationOptions: { providers: [{ name: 'fcm', ... }] },
+  templateLoader: MyLoader,
+})
+```
+
+### After
+```typescript
+NotificationModule.forRoot({
+  providers: [
+    { channel: 'email', provider: SmtpEmailProvider, options: { url: '...', from: '...' } },
+    { channel: 'push', provider: FcmPushNotificationProvider, options: { projectId: '...' } },
+  ],
+  templateLoader: MyLoader,
+})
+```
+
+### Async Before
+```typescript
+NotificationModule.forRootAsync({
+  emailOptions: {
+    useFactory: (config) => ({ option: { type: 'smtp', options: { url: config.get('SMTP') } } }),
+    inject: [ConfigService],
+  },
+  templateLoader: MyLoader,
+})
+```
+
+### Async After
+```typescript
+NotificationModule.forRootAsync({
+  imports: [ConfigModule],
+  useClass: AppNotificationOptionsFactory,
+})
+// or
+NotificationModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    providers: [
+      { channel: 'email', provider: SmtpEmailProvider, options: { url: config.get('SMTP') } },
+    ],
+    templateLoader: MyLoader,
+  }),
+  inject: [ConfigService],
+})
+```
+
+---
+
+## Breaking Changes
+
+1. `NotificationModuleOptions.emailOptions` → removed (use `providers` array)
+2. `NotificationModuleOptions.pushNotificationOptions` → removed (use `providers` array)
+3. `NotificationModuleOptions.smsService` → removed (use `providers` array)
+4. `NotificationModuleOptions.whatsAppService` → removed (use `providers` array)
+5. `EmailModule`, `PushNotificationModule` no longer exported from main index (still accessible via deep import)
+6. `EmailModuleOptions`, `PushNotificationModuleOptions` etc. no longer exported from main index
+
+All changes are within the **same v2.2.0 release** since no prior release has shipped these new features yet.