Feature/whatsapp by y-aithnini · Pull Request #8 · CISCODE-MA/NotificationKit

y-aithnini · 2026-03-11T08:58:28Z

Summary

What does this PR change?

Why

Why is this change needed?

Checklist

Added/updated tests (if behavior changed)
npm run lint passes
npm run typecheck passes
npm test passes
npm run build passes
Added a changeset (npx changeset) if this affects consumers

Notes

Anything reviewers should pay attention to?

… into feature/comprehensive-testing

Copilot

Pull request overview

This PR introduces WhatsApp as a first-class notification channel and expands the package documentation/API surface to support WhatsApp delivery (including a Twilio-based sender and a mock sender), alongside extensive inline documentation updates across core and Nest integration.

Changes:

Add NotificationChannel.WHATSAPP plus Twilio and mock WhatsApp sender implementations, and export them via infra index barrels.
Expand NestJS integration docs and provider/module factory comments, and update README + add a template configuration guide.
Update core layer documentation/comments across ports, DTOs, errors, and service.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
src/nest/providers.ts	Adds extensive provider-factory documentation; adjusts provider definitions for defaults/dynamic imports.
src/nest/module.ts	Expands module documentation and refactors `registerAsync()` provider setup.
src/nest/index.ts	Adds public API documentation and keeps Nest integration barrel exports.
src/infra/senders/whatsapp/twilio-whatsapp.sender.ts	New Twilio-based WhatsApp sender (media + template support).
src/infra/senders/whatsapp/mock-whatsapp.sender.ts	New mock WhatsApp sender for development/testing.
src/infra/senders/whatsapp/index.ts	Barrel export for WhatsApp senders.
src/infra/senders/index.ts	Exports WhatsApp senders from the infra senders index.
src/infra/senders/email/nodemailer.sender.ts	Adds extensive documentation/comments to the Nodemailer sender.
src/index.ts	Adds package-level entrypoint documentation; continues exporting core/infra/nest.
src/core/types.ts	Adds `WHATSAPP` channel and expands inline documentation.
src/core/ports.ts	Expands inline documentation for ports/interfaces.
src/core/notification.service.ts	Adds extensive documentation/comments describing service behavior.
src/core/index.ts	Adds documentation and clarifies export intent for the core layer.
src/core/errors.ts	Expands error documentation and examples.
src/core/dtos.ts	Expands DTO/schema documentation; keeps validation logic.
docs/TEMPLATE_CONFIGURATION.md	Adds a comprehensive template configuration guide (provider vs global templates).
README.md	Updates positioning/features and adds WhatsApp + template/content guidance sections.

Comments suppressed due to low confidence (2)

src/core/dtos.ts:156

CreateNotificationDtoSchema’s cross-field validation doesn’t include the new WHATSAPP channel. As a result, DTO validation can accept WhatsApp notifications without recipient.phone even though the docs/state that phone is required. Extend the refine logic to require recipient.phone for NotificationChannel.WHATSAPP (and consider aligning the earlier comment block too).

      // Cross-field validation: Ensure recipient has required contact info for channel
      // Email channel requires email address
      if (data.channel === NotificationChannel.EMAIL && !data.recipient.email) {
        return false;
      }
      // SMS channel requires phone number
      if (data.channel === NotificationChannel.SMS && !data.recipient.phone) {
        return false;
      }
      // Push channel requires device token
      if (data.channel === NotificationChannel.PUSH && !data.recipient.deviceToken) {

src/nest/providers.ts:33

Unused imports DateTimeProvider as _DateTimeProvider and UuidGenerator as _UuidGenerator will fail lint/typecheck (and are not needed since the implementation uses dynamic imports). Remove them.

import { NotificationService } from "../core/notification.service";
import { DateTimeProvider as _DateTimeProvider } from "../infra/providers/datetime.provider";
import { UuidGenerator as _UuidGenerator } from "../infra/providers/id-generator.provider";

Copilot · 2026-03-11T09:06:24Z

src/nest/module.ts

+    // Create a factory provider that creates NotificationKit providers
+    // once the module options are available
    const providersFactory: Provider = {
      provide: "NOTIFICATION_PROVIDERS",
      useFactory: (moduleOptions: NotificationKitModuleOptions) => {
        return createNotificationKitProviders(moduleOptions);
      },
-      inject: [NOTIFICATION_KIT_OPTIONS],
+      inject: [NOTIFICATION_KIT_OPTIONS], // Wait for options to be resolved
    };


registerAsync() currently registers a provider ("NOTIFICATION_PROVIDERS") whose value is an array of providers returned by createNotificationKitProviders(). Nest will not treat that returned array as providers, so NOTIFICATION_SERVICE (and related tokens) will not actually be registered in async mode. Refactor async registration to register the real providers themselves (e.g., create providers that inject: [NOTIFICATION_KIT_OPTIONS] and read from resolved options, or add an async-aware createNotificationKitProviders variant that builds providers around the options token).

Copilot · 2026-03-11T09:06:24Z

src/nest/module.ts

  static registerAsync(options: NotificationKitModuleAsyncOptions): DynamicModule {
+    // Create provider that resolves module options asynchronously
    const asyncOptionsProvider = this.createAsyncOptionsProvider(options);
+
+    // Create any additional async providers (useClass providers)
    const asyncProviders = this.createAsyncProviders(options);

-    // We can't conditionally load controllers in async mode without the options
-    // So we'll need to always include them and they can handle being disabled internally
-    // Or we can create a factory provider that returns empty array
+    // Create a factory provider that creates NotificationKit providers
+    // once the module options are available
    const providersFactory: Provider = {
      provide: "NOTIFICATION_PROVIDERS",
      useFactory: (moduleOptions: NotificationKitModuleOptions) => {
        return createNotificationKitProviders(moduleOptions);
      },
-      inject: [NOTIFICATION_KIT_OPTIONS],
+      inject: [NOTIFICATION_KIT_OPTIONS], // Wait for options to be resolved
    };

+    // Combine all providers
    const allProviders = [asyncOptionsProvider, ...asyncProviders, providersFactory];
+
+    // Export providers for injection
    const exports = allProviders.map((p) =>
      typeof p === "object" && "provide" in p ? p.provide : p,
    );

    return {
-      global: true,
-      module: NotificationKitModule,
-      imports: options.imports || [],
+      global: true, // Module is global
+      module: NotificationKitModule, // This module class
+      imports: options.imports || [], // Import dependencies (ConfigModule, etc.)
      controllers: [], // Controllers disabled in async mode for simplicity
-      providers: allProviders,
-      exports,
+      providers: allProviders, // Async providers + factory
+      exports, // Make providers available for injection
    };


There is no test asserting that registerAsync() exposes NOTIFICATION_SERVICE / functional providers (the current tests only check NOTIFICATION_KIT_OPTIONS). Add a module test that moduleRef.get(NOTIFICATION_SERVICE) works in async mode to prevent regressions like the current provider-factory issue.

Copilot · 2026-03-11T09:06:25Z

src/infra/senders/whatsapp/twilio-whatsapp.sender.ts

+ * Usage with NotificationKit:
+ * ```typescript
+ * NotificationKitModule.forRoot({
+ *   senders: [whatsappSender],
+ *   // ... other config
+ * });
+ * ```


The usage example references NotificationKitModule.forRoot(...), but the module API is NotificationKitModule.register(...) / registerAsync(...). Update the example to match the actual public API.

Copilot · 2026-03-11T09:06:25Z

docs/TEMPLATE_CONFIGURATION.md

+```typescript
+await notificationService.send({
+  channel: NotificationChannel.WHATSAPP,
+  recipient: { phone: "+14155551234" },
+  content: {
+    templateId: "orderShipped", // Maps to 'order_shipped_v1'
+    templateVars: {
+      orderNumber: "12345",
+      trackingUrl: "https://track.com/12345",
+    },
+  },
+});


This doc example is missing required fields according to the package’s types/DTOs: recipient.id is required, and content currently requires title and body (even when using templates). Update the example (or relax the DTO/types) so it reflects what actually validates and runs.

Copilot · 2026-03-11T09:06:25Z

src/infra/senders/whatsapp/mock-whatsapp.sender.ts

+    return {
+      success: true,
+      notificationId: _recipient.id,
+      providerMessageId: `mock-whatsapp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,


Math.random().toString(36).substr(...) uses the legacy substr() API. Use slice()/substring() instead to avoid deprecated APIs and potential lint failures.

Suggested change

providerMessageId: `mock-whatsapp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,

providerMessageId: `mock-whatsapp-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,

Copilot · 2026-03-11T09:06:27Z

src/infra/senders/whatsapp/twilio-whatsapp.sender.ts

+        error: errorCode ? `[${errorCode}] ${errorMessage}` : errorMessage,
+        metadata: {
+          errorCode,
+          rawError: error,


On failure you return rawError: error in metadata. Twilio errors can include request/response details and other sensitive information; returning the full object can leak secrets/PII to callers or logs. Prefer returning only a sanitized subset (e.g., code, message, moreInfo, status) and omit the raw error object.

Suggested change

rawError: error,

message: errorMessage,

status: error?.status,

moreInfo: error?.moreInfo,

Copilot · 2026-03-11T09:06:27Z

src/infra/senders/whatsapp/mock-whatsapp.sender.ts

+ * Usage with NotificationKit:
+ * ```typescript
+ * NotificationKitModule.forRoot({
+ *   senders: [mockSender],
+ *   // ... other config
+ * });
+ * ```


The usage example references NotificationKitModule.forRoot(...), but the module API is NotificationKitModule.register(...) / registerAsync(...). Update the example to match the actual public API.

Copilot · 2026-03-11T09:06:27Z

docs/TEMPLATE_CONFIGURATION.md

+import { NotificationKitModule } from '@ciscode/notification-kit';
+import { SimpleTemplateEngine } from '@ciscode/notification-kit/infra';


Examples import from @ciscode/notification-kit/infra, but package.json currently exports only the root entry (.). These subpath imports will fail for consumers unless you add subpath exports. Prefer importing infrastructure exports from @ciscode/notification-kit (or update exports).

Suggested change

import { NotificationKitModule } from '@ciscode/notification-kit';

import { SimpleTemplateEngine } from '@ciscode/notification-kit/infra';

import { NotificationKitModule, SimpleTemplateEngine } from '@ciscode/notification-kit';

Copilot · 2026-03-11T09:06:27Z

src/core/errors.ts

+ * HTTP Status: 503 Service Unavailable
+ *
+ * Common causes:
+ * - Forgot to register sender: NotificationKitModule.forRoot({ senders: [emailSender] })


Documentation mentions NotificationKitModule.forRoot(...), but the module API in this package is NotificationKitModule.register(...) / registerAsync(...). Update this reference to the correct method name.

Suggested change

* - Forgot to register sender: NotificationKitModule.forRoot({ senders: [emailSender] })

* - Forgot to register sender: NotificationKitModule.register({ senders: [emailSender] })

Copilot · 2026-03-11T09:06:28Z

src/nest/index.ts

+ * NotificationKit NestJS Integration - Public API
+ *
+ * This file exports all public NestJS integration components for NotificationKit.
+ * Import from '@ciscode/notification-kit/nest' to use NotificationKit with NestJS.
+ *


This file’s JSDoc suggests consumers should import from @ciscode/notification-kit/nest, but package.json exports only the root entry (exports: {".": ...}), so that subpath import will fail in Node/bundlers. Update the docs/examples to import from @ciscode/notification-kit (or add the /nest subpath export if that’s intended).

sonarqubecloud · 2026-03-11T09:53:15Z

Quality Gate failed

Failed conditions
1 Security Hotspot

See analysis details on SonarQube Cloud

y-aithnini added 11 commits February 27, 2026 16:03

implemented decorators and providers

6aadbc9

Add notification and webhook controller tests

ada99be

remove in-memory repository and update exports

571aecc

removed mongoose

73009e2

Merge develop: resolve conflicts and update jest config for spec files

4210d2c

removed duplicate code for sonarqube

96a80f6

docs: add comprehensive documentation for testing implementation

aac7189

style: fix prettier formatting issues

81e390e

Merge branch 'develop' of https://github.com/CISCODE-MA/NotificationKit…

746f00e

… into feature/comprehensive-testing

integrated whatsapp notification msg

2b5c2f4

updated configuration

0e0de92

Copilot AI review requested due to automatic review settings March 11, 2026 08:58

Copilot started reviewing on behalf of y-aithnini March 11, 2026 08:58 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

fix: replace deprecated substr() with slice() in mock WhatsApp sender

804543a

y-aithnini closed this Mar 11, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/whatsapp#8

Feature/whatsapp#8
y-aithnini wants to merge 12 commits intodevelopfrom
feature/whatsapp

y-aithnini commented Mar 11, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

Copilot AI Mar 11, 2026

Uh oh!

sonarqubecloud bot commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	providerMessageId: `mock-whatsapp-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
	providerMessageId: `mock-whatsapp-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,

-          rawError: error,
+          message: errorMessage,
+          status: error?.status,
+          moreInfo: error?.moreInfo,

		import { NotificationKitModule } from '@ciscode/notification-kit';
		import { SimpleTemplateEngine } from '@ciscode/notification-kit/infra';

	import { NotificationKitModule } from '@ciscode/notification-kit';
	import { SimpleTemplateEngine } from '@ciscode/notification-kit/infra';
	import { NotificationKitModule, SimpleTemplateEngine } from '@ciscode/notification-kit';

	* - Forgot to register sender: NotificationKitModule.forRoot({ senders: [emailSender] })
	* - Forgot to register sender: NotificationKitModule.register({ senders: [emailSender] })

Conversation

y-aithnini commented Mar 11, 2026

Summary

Why

Checklist

Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 11, 2026

Choose a reason for hiding this comment

Uh oh!

sonarqubecloud bot commented Mar 11, 2026

Quality Gate failed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants