@fluojs/notifications 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,192 @@
+# @fluojs/notifications
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo를 위한 채널 중립(notification channel-agnostic) 알림 오케스트레이션 패키지입니다. 알림 채널의 공통 계약을 고정하고, Nest-like 모듈 API를 제공하며, 선택적인 큐 기반 전달 심(seam)과 라이프사이클 이벤트 발행 심을 노출합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [일반적인 패턴](#일반적인-패턴)
+  - [큐 기반 대량 전달](#큐-기반-대량-전달)
+  - [이벤트 발행자를 통한 라이프사이클 발행](#이벤트-발행자를-통한-라이프사이클-발행)
+  - [의도적인 제한 사항](#의도적인-제한-사항)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/notifications
+```
+
+## 사용 시점
+
+- 여러 알림 채널에 대해 하나의 공통 dispatch 계약을 두고, sibling 패키지끼리 직접 결합되지 않게 하고 싶을 때.
+- 애플리케이션 코드가 provider SDK나 전송 구현 세부사항 대신 `NotificationsService`에 의존해야 할 때.
+- 대량 전달은 큐로 넘길 수 있어야 하지만, 기본 경로는 여전히 인프로세스 직접 전달이어야 할 때.
+- 알림 라이프사이클 이벤트(requested, queued, delivered, failed)를 별도의 이벤트 발행 심으로 관찰하고 싶을 때.
+
+## 빠른 시작
+
+### 1. foundation 모듈 등록
+
+알림 모듈 등록은 `NotificationsModule.forRoot(...)` 또는 `NotificationsModule.forRootAsync(...)`로 구성합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import {
+  NotificationsModule,
+  type NotificationChannel,
+} from '@fluojs/notifications';
+
+const emailChannel: NotificationChannel = {
+  channel: 'email',
+  async send(notification) {
+    console.log('email 전송', notification.subject, notification.payload);
+
+    return {
+      externalId: 'email-123',
+      metadata: { provider: 'demo-email' },
+    };
+  },
+};
+
+@Module({
+  imports: [
+    NotificationsModule.forRoot({
+      channels: [emailChannel],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. `NotificationsService` 주입
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { NotificationsService } from '@fluojs/notifications';
+
+export class WelcomeService {
+  constructor(@Inject(NotificationsService) private readonly notifications: NotificationsService) {}
+
+  async sendWelcomeEmail(userId: string, email: string) {
+    await this.notifications.dispatch({
+      channel: 'email',
+      recipients: [email],
+      subject: 'fluo에 오신 것을 환영합니다',
+      payload: {
+        template: 'welcome-email',
+        userId,
+      },
+    });
+  }
+}
+```
+
+## 일반적인 패턴
+
+### 큐 기반 대량 전달
+
+많은 알림을 백그라운드 워커로 넘기고 싶다면 선택적인 queue seam을 사용합니다.
+
+```typescript
+NotificationsModule.forRoot({
+  channels: [emailChannel],
+  queue: {
+    adapter: {
+      async enqueue(job) {
+        return queue.enqueue(job);
+      },
+      async enqueueMany(jobs) {
+        return Promise.all(jobs.map((job) => queue.enqueue(job)));
+      },
+    },
+    bulkThreshold: 50,
+  },
+});
+```
+
+Behavioral contract 메모:
+
+- 알림 개수가 `bulkThreshold` 이상이면 대량 큐 위임이 시작됩니다.
+- `dispatch()`는 queue adapter가 구성되어 있어도 기본적으로 직접 전달을 유지합니다. 단건 알림을 큐로 보내려면 `dispatch(..., { queue: true })`를 사용합니다.
+- 큐 기반 전달은 단건 dispatch에서는 opt-in이고, `dispatchMany(...)`에서는 threshold 기반으로 동작합니다.
+- queue enqueue가 실패하면 서비스는 enqueue 에러를 다시 던지기 전에 결정적인 `notification.dispatch.failed` 라이프사이클 이벤트를 발행합니다.
+- foundation 패키지는 특정 큐 구현을 가정하거나 import하지 않습니다.
+
+### 이벤트 발행자를 통한 라이프사이클 발행
+
+foundation 패키지를 `@fluojs/event-bus` 구현에 직접 결합하지 않고도 caller-visible 라이프사이클 이벤트를 발행할 수 있습니다.
+
+```typescript
+NotificationsModule.forRoot({
+  channels: [emailChannel],
+  events: {
+    publishLifecycleEvents: true,
+    publisher: {
+      async publish(event) {
+        await eventBus.publish(event);
+      },
+    },
+  },
+});
+```
+
+발행되는 이벤트 이름:
+
+- `notification.dispatch.requested`
+- `notification.dispatch.queued`
+- `notification.dispatch.delivered`
+- `notification.dispatch.failed`
+
+### 의도적인 제한 사항
+
+foundation 패키지는 의도적으로 다음을 **포함하지 않습니다**:
+
+- 내장 email, Slack, Discord 구현
+- 직접적인 `process.env` 접근
+- `@fluojs/queue` 또는 `@fluojs/event-bus`의 concrete runtime 타입 의존성
+- provider별 payload 의미를 공유 계약에 인코딩하는 것
+
+이 제한 사항은 leaf 패키지가 하나의 안정적인 오케스트레이션 계층 위에서 독립적으로 진화할 수 있도록 하는 package contract의 일부입니다.
+
+## 공개 API 개요
+
+### 핵심
+
+- `NotificationsModule.forRoot(options)` / `NotificationsModule.forRootAsync(options)`
+- `NotificationsService`
+- `NOTIFICATIONS`
+- `NOTIFICATION_CHANNELS`
+
+### 계약(Contracts)
+
+- `NotificationDispatchRequest`
+- `NotificationChannel`
+- `NotificationsQueueAdapter`
+- `NotificationsEventPublisher`
+- `NotificationLifecycleEvent`
+
+### 상태 및 에러
+
+- `createNotificationsPlatformStatusSnapshot(...)`
+- `NotificationsConfigurationError`
+- `NotificationChannelNotFoundError`
+- `NotificationQueueNotConfiguredError`
+
+## 관련 패키지
+
+- `@fluojs/queue`: 대량 알림 전달을 백그라운드에서 처리하려는 경우 권장됩니다.
+- `@fluojs/event-bus`: 알림 라이프사이클 이벤트를 애플리케이션 전반에 발행하려는 경우 권장됩니다.
+- `@fluojs/config`: 환경 직접 접근 없이 `forRootAsync()`로 provider 설정을 전달하려는 경우 권장됩니다.
+
+## 예제 소스
+
+- `packages/notifications/src/module.test.ts`: 모듈 등록, async wiring, queue seam, tolerant bulk dispatch 예제.
+- `packages/notifications/src/public-surface.test.ts`: 루트 export와 TypeScript-only 타입에 대한 공개 계약 검증 예제.
+- `packages/notifications/src/status.test.ts`: health/readiness 계약 예제.

package/README.md

@@ -0,0 +1,192 @@
+# @fluojs/notifications
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Channel-agnostic notification orchestration for fluo. It freezes the shared contract for notification channels, provides a Nest-like module API, and exposes optional queue-backed delivery and lifecycle event publication seams.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+  - [Queue-backed bulk delivery](#queue-backed-bulk-delivery)
+  - [Lifecycle publication through an event publisher](#lifecycle-publication-through-an-event-publisher)
+  - [Intentional limitations](#intentional-limitations)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/notifications
+```
+
+## When to Use
+
+- When you want one shared dispatch contract for multiple notification channels without coupling sibling packages to each other.
+- When application code should depend on `NotificationsService` instead of provider-specific SDKs or transport details.
+- When bulk delivery may need to be offloaded to a queue, but direct in-process dispatch should still remain available.
+- When notification lifecycle events (requested, queued, delivered, failed) should be observable through an event publication seam.
+
+## Quick Start
+
+### 1. Register the foundation module
+
+Register notifications with `NotificationsModule.forRoot(...)` or `NotificationsModule.forRootAsync(...)`.
+
+```typescript
+import { Module } from '@fluojs/core';
+import {
+  NotificationsModule,
+  type NotificationChannel,
+} from '@fluojs/notifications';
+
+const emailChannel: NotificationChannel = {
+  channel: 'email',
+  async send(notification) {
+    console.log('sending email', notification.subject, notification.payload);
+
+    return {
+      externalId: 'email-123',
+      metadata: { provider: 'demo-email' },
+    };
+  },
+};
+
+@Module({
+  imports: [
+    NotificationsModule.forRoot({
+      channels: [emailChannel],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 2. Inject `NotificationsService`
+
+```typescript
+import { Inject } from '@fluojs/core';
+import { NotificationsService } from '@fluojs/notifications';
+
+export class WelcomeService {
+  constructor(@Inject(NotificationsService) private readonly notifications: NotificationsService) {}
+
+  async sendWelcomeEmail(userId: string, email: string) {
+    await this.notifications.dispatch({
+      channel: 'email',
+      recipients: [email],
+      subject: 'Welcome to fluo',
+      payload: {
+        template: 'welcome-email',
+        userId,
+      },
+    });
+  }
+}
+```
+
+## Common Patterns
+
+### Queue-backed bulk delivery
+
+Use the optional queue seam when many notifications should be deferred to background workers.
+
+```typescript
+NotificationsModule.forRoot({
+  channels: [emailChannel],
+  queue: {
+    adapter: {
+      async enqueue(job) {
+        return queue.enqueue(job);
+      },
+      async enqueueMany(jobs) {
+        return Promise.all(jobs.map((job) => queue.enqueue(job)));
+      },
+    },
+    bulkThreshold: 50,
+  },
+});
+```
+
+Behavioral contract notes:
+
+- Bulk queue delegation starts when the notification count reaches `bulkThreshold`.
+- `dispatch()` stays direct by default even when a queue adapter is configured. Use `dispatch(..., { queue: true })` to opt one single notification into queue-backed delivery.
+- Queue-backed delivery is opt-in for single dispatch and threshold-driven for `dispatchMany(...)`.
+- When queue enqueue fails, the service emits deterministic `notification.dispatch.failed` lifecycle events before rethrowing the enqueue error to the caller.
+- The foundation package does not assume or import a concrete queue implementation.
+
+### Lifecycle publication through an event publisher
+
+Publish caller-visible lifecycle events without coupling the foundation package to `@fluojs/event-bus` directly.
+
+```typescript
+NotificationsModule.forRoot({
+  channels: [emailChannel],
+  events: {
+    publishLifecycleEvents: true,
+    publisher: {
+      async publish(event) {
+        await eventBus.publish(event);
+      },
+    },
+  },
+});
+```
+
+Published event names:
+
+- `notification.dispatch.requested`
+- `notification.dispatch.queued`
+- `notification.dispatch.delivered`
+- `notification.dispatch.failed`
+
+### Intentional limitations
+
+The foundation package intentionally does **not**:
+
+- ship built-in email, Slack, or Discord implementations
+- inspect `process.env` directly
+- depend on `@fluojs/queue` or `@fluojs/event-bus` concrete runtime types
+- encode provider-specific payload semantics into the shared contract
+
+These limitations are part of the package contract so leaf packages can evolve independently while sharing one stable orchestration layer.
+
+## Public API Overview
+
+### Core
+
+- `NotificationsModule.forRoot(options)` / `NotificationsModule.forRootAsync(options)`
+- `NotificationsService`
+- `NOTIFICATIONS`
+- `NOTIFICATION_CHANNELS`
+
+### Contracts
+
+- `NotificationDispatchRequest`
+- `NotificationChannel`
+- `NotificationsQueueAdapter`
+- `NotificationsEventPublisher`
+- `NotificationLifecycleEvent`
+
+### Status and errors
+
+- `createNotificationsPlatformStatusSnapshot(...)`
+- `NotificationsConfigurationError`
+- `NotificationChannelNotFoundError`
+- `NotificationQueueNotConfiguredError`
+
+## Related Packages
+
+- `@fluojs/queue`: Recommended when bulk notification delivery should run in the background.
+- `@fluojs/event-bus`: Recommended when notification lifecycle events should be published to the wider app.
+- `@fluojs/config`: Recommended for passing provider configuration into `forRootAsync()` without direct environment access.
+
+## Example Sources
+
+- `packages/notifications/src/module.test.ts`: Module registration, async wiring, queue seam, and tolerant bulk dispatch examples.
+- `packages/notifications/src/public-surface.test.ts`: Public contract verification for root exports and TypeScript-only types.
+- `packages/notifications/src/status.test.ts`: Health/readiness contract examples.

package/dist/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Base error type for caller-visible notification module configuration failures.
+ */
+export declare class NotificationsConfigurationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a notification references a channel that is not registered.
+ */
+export declare class NotificationChannelNotFoundError extends Error {
+    readonly channel: string;
+    constructor(channel: string);
+}
+/**
+ * Thrown when queue-backed delivery is requested without a configured queue adapter.
+ */
+export declare class NotificationQueueNotConfiguredError extends Error {
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAIrC;AAED;;GAEG;AACH,qBAAa,mCAAoC,SAAQ,KAAK;;CAK7D"}

package/dist/errors.js

@@ -0,0 +1,30 @@
+/**
+ * Base error type for caller-visible notification module configuration failures.
+ */
+export class NotificationsConfigurationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NotificationsConfigurationError';
+  }
+}
+
+/**
+ * Thrown when a notification references a channel that is not registered.
+ */
+export class NotificationChannelNotFoundError extends Error {
+  constructor(channel) {
+    super(`No notification channel is registered for "${channel}".`);
+    this.channel = channel;
+    this.name = 'NotificationChannelNotFoundError';
+  }
+}
+
+/**
+ * Thrown when queue-backed delivery is requested without a configured queue adapter.
+ */
+export class NotificationQueueNotConfiguredError extends Error {
+  constructor() {
+    super('Queue-backed notification delivery requires a configured queue adapter.');
+    this.name = 'NotificationQueueNotConfiguredError';
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError, NotificationsConfigurationError, } from './errors.js';
+export { NotificationsModule } from './module.js';
+export { NotificationsService } from './service.js';
+export { createNotificationsPlatformStatusSnapshot } from './status.js';
+export type { NotificationsPlatformStatusSnapshot, NotificationsStatusAdapterInput } from './status.js';
+export { NOTIFICATION_CHANNELS, NOTIFICATIONS } from './tokens.js';
+export type { NotificationChannel, NotificationChannelContext, NotificationChannelDelivery, NotificationDispatchBatchResult, NotificationDispatchFailure, NotificationDispatchManyOptions, NotificationDispatchOptions, NotificationDispatchRequest, NotificationDispatchResult, NotificationDispatchStatus, NotificationLifecycleEvent, NotificationLifecycleEventName, NotificationPayload, Notifications, NotificationsAsyncModuleOptions, NotificationsEventPublisher, NotificationsEventsOptions, NotificationsModuleOptions, NotificationsQueueAdapter, NotificationsQueueJob, NotificationsQueueOptions, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gCAAgC,EAChC,mCAAmC,EACnC,+BAA+B,GAChC,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,yCAAyC,EAAE,MAAM,aAAa,CAAC;AACxE,YAAY,EAAE,mCAAmC,EAAE,+BAA+B,EAAE,MAAM,aAAa,CAAC;AACxG,OAAO,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EACV,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,2BAA2B,EAC3B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,0BAA0B,EAC1B,8BAA8B,EAC9B,mBAAmB,EACnB,aAAa,EACb,+BAA+B,EAC/B,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,yBAAyB,EACzB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError, NotificationsConfigurationError } from './errors.js';
+export { NotificationsModule } from './module.js';
+export { NotificationsService } from './service.js';
+export { createNotificationsPlatformStatusSnapshot } from './status.js';
+export { NOTIFICATION_CHANNELS, NOTIFICATIONS } from './tokens.js';

package/dist/module.d.ts

@@ -0,0 +1,38 @@
+import type { AsyncModuleOptions } from '@fluojs/core';
+import { type ModuleType } from '@fluojs/runtime';
+import type { NotificationsModuleOptions } from './types.js';
+/** Runtime module entrypoint for notification orchestration. */
+export declare class NotificationsModule {
+    /**
+     * Registers notifications providers using static options.
+     *
+     * @param options Static notifications module options including channels and optional queue/event integrations.
+     * @returns A global module definition that exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`.
+     *
+     * @example
+     * ```ts
+     * NotificationsModule.forRoot({
+     *   channels: [emailChannel],
+     * });
+     * ```
+     */
+    static forRoot(options?: NotificationsModuleOptions): ModuleType;
+    /**
+     * Registers notifications providers from an async DI factory.
+     *
+     * @param options Async module options that resolve channels and optional integration seams.
+     * @returns A global module definition that memoizes async options resolution per module instance.
+     *
+     * @example
+     * ```ts
+     * NotificationsModule.forRootAsync({
+     *   inject: [ConfigService],
+     *   useFactory: (config) => ({
+     *     channels: [createEmailChannel(config)],
+     *   }),
+     * });
+     * ```
+     */
+    static forRootAsync(options: AsyncModuleOptions<NotificationsModuleOptions>): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,cAAc,CAAC;AAErE,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAMV,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AA2GpB,gEAAgE;AAChE,qBAAa,mBAAmB;IAC9B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,0BAA+B,GAAG,UAAU;IAIpE;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,kBAAkB,CAAC,0BAA0B,CAAC,GAAG,UAAU;CAGzF"}

package/dist/module.js

@@ -0,0 +1,115 @@
+import { defineModule } from '@fluojs/runtime';
+import { NotificationsConfigurationError } from './errors.js';
+import { NotificationsService } from './service.js';
+import { NOTIFICATIONS, NOTIFICATION_CHANNELS, NOTIFICATIONS_OPTIONS } from './tokens.js';
+const DEFAULT_BULK_QUEUE_THRESHOLD = 10;
+function normalizeNotificationsModuleOptions(options = {}) {
+  const channels = [...(options.channels ?? [])];
+  const seenChannelNames = new Set();
+  for (const channel of channels) {
+    if (seenChannelNames.has(channel.channel)) {
+      throw new NotificationsConfigurationError(`Duplicate notification channel registration detected for "${channel.channel}".`);
+    }
+    seenChannelNames.add(channel.channel);
+  }
+  return {
+    channels: Object.freeze(channels),
+    events: options.events ? {
+      publishLifecycleEvents: options.events.publishLifecycleEvents ?? true,
+      publisher: options.events.publisher
+    } : undefined,
+    queue: options.queue ? {
+      adapter: options.queue.adapter,
+      bulkThreshold: Math.max(1, options.queue.bulkThreshold ?? DEFAULT_BULK_QUEUE_THRESHOLD)
+    } : undefined
+  };
+}
+function createNotificationsRuntimeProviders(optionsProvider) {
+  return [optionsProvider, {
+    inject: [NOTIFICATIONS_OPTIONS],
+    provide: NOTIFICATION_CHANNELS,
+    useFactory: options => options.channels
+  }, NotificationsService, {
+    inject: [NotificationsService],
+    provide: NOTIFICATIONS,
+    useFactory: service => ({
+      dispatch: (notification, options) => service.dispatch(notification, options),
+      dispatchMany: (notifications, options) => service.dispatchMany(notifications, options)
+    })
+  }];
+}
+function buildNotificationsProviders(options = {}) {
+  return createNotificationsRuntimeProviders({
+    provide: NOTIFICATIONS_OPTIONS,
+    useValue: normalizeNotificationsModuleOptions(options)
+  });
+}
+function buildNotificationsModule(options) {
+  class NotificationsRootModuleDefinition {}
+  return defineModule(NotificationsRootModuleDefinition, {
+    exports: [NotificationsService, NOTIFICATIONS, NOTIFICATION_CHANNELS],
+    global: true,
+    providers: buildNotificationsProviders(options)
+  });
+}
+function buildNotificationsModuleAsync(options) {
+  class NotificationsAsyncModuleDefinition {}
+  const factory = options.useFactory;
+  let cachedResult;
+  const memoizedFactory = (...deps) => {
+    if (!cachedResult) {
+      cachedResult = Promise.resolve(factory(...deps)).then(resolved => normalizeNotificationsModuleOptions(resolved));
+    }
+    return cachedResult;
+  };
+  return defineModule(NotificationsAsyncModuleDefinition, {
+    exports: [NotificationsService, NOTIFICATIONS, NOTIFICATION_CHANNELS],
+    global: true,
+    providers: createNotificationsRuntimeProviders({
+      inject: options.inject,
+      provide: NOTIFICATIONS_OPTIONS,
+      scope: 'singleton',
+      useFactory: (...deps) => memoizedFactory(...deps)
+    })
+  });
+}
+
+/** Runtime module entrypoint for notification orchestration. */
+export class NotificationsModule {
+  /**
+   * Registers notifications providers using static options.
+   *
+   * @param options Static notifications module options including channels and optional queue/event integrations.
+   * @returns A global module definition that exports {@link NotificationsService}, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS`.
+   *
+   * @example
+   * ```ts
+   * NotificationsModule.forRoot({
+   *   channels: [emailChannel],
+   * });
+   * ```
+   */
+  static forRoot(options = {}) {
+    return buildNotificationsModule(options);
+  }
+
+  /**
+   * Registers notifications providers from an async DI factory.
+   *
+   * @param options Async module options that resolve channels and optional integration seams.
+   * @returns A global module definition that memoizes async options resolution per module instance.
+   *
+   * @example
+   * ```ts
+   * NotificationsModule.forRootAsync({
+   *   inject: [ConfigService],
+   *   useFactory: (config) => ({
+   *     channels: [createEmailChannel(config)],
+   *   }),
+   * });
+   * ```
+   */
+  static forRootAsync(options) {
+    return buildNotificationsModuleAsync(options);
+  }
+}