@fluojs/notifications 1.0.0-beta.2 → 1.0.0-beta.4

package/README.ko.md

@@ -89,7 +89,7 @@ export class WelcomeService {
 }
 ```
 
-`NotificationsModule.forRoot(...)`는 `NotificationsService`, `NOTIFICATIONS`, `NOTIFICATION_CHANNELS`를 global provider로 export합니다. 애플리케이션 서비스는 fluo의 class-level `@Inject(...)` decorator로 의존성을 선언해야 standard-decorator DI container가 legacy parameter decorator 없이 서비스를 resolve할 수 있습니다.
+`NotificationsModule.forRoot(...)`와 `NotificationsModule.forRootAsync(...)`는 `NotificationsService`, `NOTIFICATIONS`, `NOTIFICATION_CHANNELS`를 global provider로 export합니다. 애플리케이션 서비스는 fluo의 class-level `@Inject(...)` decorator로 의존성을 선언해야 standard-decorator DI container가 parameter decorator 없이 서비스를 resolve할 수 있습니다.
 
 ## 일반적인 패턴
 
@@ -118,8 +118,12 @@ Behavioral contract 메모:
 
 - 알림 개수가 `bulkThreshold` 이상이면 대량 큐 위임이 시작됩니다.
 - `dispatch()`는 queue adapter가 구성되어 있어도 기본적으로 직접 전달을 유지합니다. 단건 알림을 큐로 보내려면 `dispatch(..., { queue: true })`를 사용합니다.
+- queue adapter가 있어도 직접 전달을 강제하려면 `dispatch(..., { queue: false })`를 사용합니다.
 - 큐 기반 전달은 단건 dispatch에서는 opt-in이고, `dispatchMany(...)`에서는 threshold 기반으로 동작합니다.
+- Queue job에는 `notification.id`가 있으면 그 값을, 없으면 notification envelope에서 파생한 deterministic `id` idempotency key가 포함됩니다. Queue adapter는 deduplication을 지원하는 backing queue에 이 값을 전달해야 합니다.
+- `dispatchMany(..., { continueOnError: true })`는 direct delivery에서 첫 실패를 던지는 대신 실패들을 수집합니다.
 - queue enqueue가 실패하면 서비스는 enqueue 에러를 다시 던지기 전에 결정적인 `notification.dispatch.failed` 라이프사이클 이벤트를 발행합니다.
+- `enqueueMany(...)`가 없으면 대량 queue delivery는 각 job을 개별적으로 enqueue하는 방식으로 fallback합니다.
 - foundation 패키지는 특정 큐 구현을 가정하거나 import하지 않습니다.
 
 ### 이벤트 발행자를 통한 라이프사이클 발행
@@ -147,6 +151,8 @@ NotificationsModule.forRoot({
 - `notification.dispatch.delivered`
 - `notification.dispatch.failed`
 
+`events.publisher`가 구성되어 있으면 `publishLifecycleEvents: false`를 설정하지 않는 한 lifecycle event publication은 기본으로 켜집니다. 채널 delivery가 `externalId`를 생략하면 시간이나 난수에 의존하지 않고 notification envelope에서 파생한 deterministic fallback delivery id가 부여되어 dispatch result가 호출자에게 안정적으로 유지됩니다. 채널 해석 실패는 `NotificationChannelNotFoundError`를 던지기 전에 `requested` 이후 `failed` 이벤트를 발행하며, 이는 영구적인 구성 오류로 취급해야 합니다. Queue enqueue와 provider delivery 실패도 `failed` 이벤트를 발행하지만, retry 여부는 underlying adapter/provider error를 기준으로 분류해야 합니다. 성공 경로 lifecycle event의 publication failure는 이미 전달된 알림을 애플리케이션 실패로 바꾸지 않도록 best-effort로 유지됩니다. `notification.dispatch.failed` publication failure는 원래 dispatch error와 publisher error를 모두 포함하는 `AggregateError`로 호출자에게 드러나므로 failed-event 보장이 조용히 약해지지 않습니다.
+
 ### 의도적인 제한 사항
 
 foundation 패키지는 의도적으로 다음을 **포함하지 않습니다**:
@@ -164,24 +170,45 @@ foundation 패키지는 의도적으로 다음을 **포함하지 않습니다**:
 
 - `NotificationsModule.forRoot(options)` / `NotificationsModule.forRootAsync(options)`
 - `NotificationsService`
+- `NotificationsService.createPlatformStatusSnapshot()`
+- `Notifications`
 - `NOTIFICATIONS`
 - `NOTIFICATION_CHANNELS`
 
 ### 계약(Contracts)
 
 - `NotificationDispatchRequest`
+- `NotificationDispatchOptions`
+- `NotificationDispatchManyOptions`
+- `NotificationDispatchResult`
+- `NotificationDispatchBatchResult`
+- `NotificationDispatchFailure`
+- `NotificationDispatchStatus`
 - `NotificationChannel`
+- `NotificationChannelContext`
+- `NotificationChannelDelivery`
+- `NotificationPayload`
 - `NotificationsQueueAdapter`
+- `NotificationsQueueJob`
+- `NotificationsQueueOptions`
+- `NotificationsModuleOptions`
+- `NotificationsAsyncModuleOptions`
+- `NotificationsEventsOptions`
 - `NotificationsEventPublisher`
 - `NotificationLifecycleEvent`
+- `NotificationLifecycleEventName`
 
 ### 상태 및 에러
 
 - `createNotificationsPlatformStatusSnapshot(...)`
+- `NotificationsPlatformStatusSnapshot`
+- `NotificationsStatusAdapterInput`
 - `NotificationsConfigurationError`
 - `NotificationChannelNotFoundError`
 - `NotificationQueueNotConfiguredError`
 
+상태 snapshot은 platform diagnostics를 위해 `operationMode`, dependency diagnostics, ownership, readiness, health 필드를 포함합니다.
+
 ## 관련 패키지
 
 - `@fluojs/queue`: 대량 알림 전달을 백그라운드에서 처리하려는 경우 권장됩니다.

package/README.md

@@ -89,7 +89,7 @@ export class WelcomeService {
 }
 ```
 
-`NotificationsModule.forRoot(...)` exports `NotificationsService`, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS` as global providers. Application services should declare dependencies with fluo's class-level `@Inject(...)` decorator so the standard-decorator DI container can resolve the service without legacy parameter decorators.
+`NotificationsModule.forRoot(...)` and `NotificationsModule.forRootAsync(...)` export `NotificationsService`, `NOTIFICATIONS`, and `NOTIFICATION_CHANNELS` as global providers. Application services should declare dependencies with fluo's class-level `@Inject(...)` decorator so the standard-decorator DI container can resolve the service without parameter decorators.
 
 ## Common Patterns
 
@@ -118,8 +118,12 @@ 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.
+- Use `dispatch(..., { queue: false })` to force direct delivery even when a queue adapter exists.
 - Queue-backed delivery is opt-in for single dispatch and threshold-driven for `dispatchMany(...)`.
+- Queue jobs include a deterministic `id` idempotency key derived from `notification.id` when present, otherwise from the notification envelope. Queue adapters should pass this value to backing queues that support deduplication.
+- `dispatchMany(..., { continueOnError: true })` collects failures instead of throwing on the first failed direct delivery.
 - When queue enqueue fails, the service emits deterministic `notification.dispatch.failed` lifecycle events before rethrowing the enqueue error to the caller.
+- If `enqueueMany(...)` is unavailable, bulk queue delivery falls back to enqueueing each job individually.
 - The foundation package does not assume or import a concrete queue implementation.
 
 ### Lifecycle publication through an event publisher
@@ -147,6 +151,8 @@ Published event names:
 - `notification.dispatch.delivered`
 - `notification.dispatch.failed`
 
+If `events.publisher` is configured, lifecycle event publication defaults to on unless `publishLifecycleEvents: false` is set. Channel deliveries that omit `externalId` receive a deterministic fallback delivery id derived from the notification envelope so dispatch results remain stable for callers without relying on time or random data. Channel resolution failures publish `requested` and then `failed` events before throwing `NotificationChannelNotFoundError`; treat those failures as permanent configuration errors. Queue enqueue and provider delivery failures also publish `failed` events, but callers should classify their retry behavior from the underlying adapter/provider error. Publication failures for success-path lifecycle events remain best-effort so a delivered notification is not converted into an application failure. Publication failures for `notification.dispatch.failed` are caller-visible as `AggregateError` values that include both the original dispatch error and the publisher error so failed-event guarantees are not silently weakened.
+
 ### Intentional limitations
 
 The foundation package intentionally does **not**:
@@ -164,24 +170,45 @@ These limitations are part of the package contract so leaf packages can evolve i
 
 - `NotificationsModule.forRoot(options)` / `NotificationsModule.forRootAsync(options)`
 - `NotificationsService`
+- `NotificationsService.createPlatformStatusSnapshot()`
+- `Notifications`
 - `NOTIFICATIONS`
 - `NOTIFICATION_CHANNELS`
 
 ### Contracts
 
 - `NotificationDispatchRequest`
+- `NotificationDispatchOptions`
+- `NotificationDispatchManyOptions`
+- `NotificationDispatchResult`
+- `NotificationDispatchBatchResult`
+- `NotificationDispatchFailure`
+- `NotificationDispatchStatus`
 - `NotificationChannel`
+- `NotificationChannelContext`
+- `NotificationChannelDelivery`
+- `NotificationPayload`
 - `NotificationsQueueAdapter`
+- `NotificationsQueueJob`
+- `NotificationsQueueOptions`
+- `NotificationsModuleOptions`
+- `NotificationsAsyncModuleOptions`
+- `NotificationsEventsOptions`
 - `NotificationsEventPublisher`
 - `NotificationLifecycleEvent`
+- `NotificationLifecycleEventName`
 
 ### Status and errors
 
 - `createNotificationsPlatformStatusSnapshot(...)`
+- `NotificationsPlatformStatusSnapshot`
+- `NotificationsStatusAdapterInput`
 - `NotificationsConfigurationError`
 - `NotificationChannelNotFoundError`
 - `NotificationQueueNotConfiguredError`
 
+Status snapshots include `operationMode`, dependency diagnostics, ownership, readiness, and health fields for platform diagnostics.
+
 ## Related Packages
 
 - `@fluojs/queue`: Recommended when bulk notification delivery should run in the background.

package/dist/module.d.ts

@@ -1,6 +1,5 @@
-import type { AsyncModuleOptions } from '@fluojs/core';
 import { type ModuleType } from '@fluojs/runtime';
-import type { NotificationsModuleOptions } from './types.js';
+import type { NotificationsAsyncModuleOptions, NotificationsModuleOptions } from './types.js';
 /** Runtime module entrypoint for notification orchestration. */
 export declare class NotificationsModule {
     /**
@@ -33,6 +32,6 @@ export declare class NotificationsModule {
      * });
      * ```
      */
-    static forRootAsync(options: AsyncModuleOptions<NotificationsModuleOptions>): ModuleType;
+    static forRootAsync(options: NotificationsAsyncModuleOptions): ModuleType;
 }
 //# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAMV,+BAA+B,EAC/B,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,+BAA+B,GAAG,UAAU;CAG1E"}

package/dist/module.js

@@ -48,7 +48,7 @@ function buildNotificationsModule(options) {
   class NotificationsRootModuleDefinition {}
   return defineModule(NotificationsRootModuleDefinition, {
     exports: [NotificationsService, NOTIFICATIONS, NOTIFICATION_CHANNELS],
-    global: true,
+    global: options.global ?? true,
     providers: buildNotificationsProviders(options)
   });
 }
@@ -64,7 +64,7 @@ function buildNotificationsModuleAsync(options) {
   };
   return defineModule(NotificationsAsyncModuleDefinition, {
     exports: [NotificationsService, NOTIFICATIONS, NOTIFICATION_CHANNELS],
-    global: true,
+    global: options.global ?? true,
     providers: createNotificationsRuntimeProviders({
       inject: options.inject,
       provide: NOTIFICATIONS_OPTIONS,

package/dist/service.d.ts

@@ -10,7 +10,6 @@ import type { NormalizedNotificationsModuleOptions, NotificationChannel, Notific
 export declare class NotificationsService implements Notifications {
     private readonly options;
     private readonly channelsByName;
-    private fallbackDeliveryIdSequence;
     constructor(options: NormalizedNotificationsModuleOptions, channels: readonly NotificationChannel[]);
     /**
      * Dispatches one notification through a registered channel or the configured queue seam.
@@ -50,6 +49,7 @@ export declare class NotificationsService implements Notifications {
      */
     createPlatformStatusSnapshot(): import("./status.js").NotificationsPlatformStatusSnapshot;
     private createQueueJob;
+    private createQueueJobId;
     private requireChannel;
     private normalizeDeliveryId;
     private requireQueueAdapter;
@@ -58,5 +58,6 @@ export declare class NotificationsService implements Notifications {
     private shouldQueue;
     private publishLifecycleEvent;
     private publishLifecycleEventSafely;
+    private publishFailureLifecycleEvent;
 }
 //# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,oCAAoC,EACpC,mBAAmB,EACnB,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAE1B,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,qBACa,oBAAqB,YAAW,aAAa;IAKtD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;IACzE,OAAO,CAAC,0BAA0B,CAAK;gBAGpB,OAAO,EAAE,oCAAoC,EAC9D,QAAQ,EAAE,SAAS,mBAAmB,EAAE;IAO1C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,QAAQ,SAAS,2BAA2B,EACzD,YAAY,EAAE,QAAQ,EACtB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC;IAkDtC;;;;;;;;OAQG;IACG,YAAY,CAAC,QAAQ,SAAS,2BAA2B,EAC7D,aAAa,EAAE,SAAS,QAAQ,EAAE,EAClC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IAuFrD;;;;OAIG;IACH,4BAA4B;IAS5B,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,yBAAyB;IAIjC,OAAO,CAAC,WAAW;YAYL,qBAAqB;YA4BrB,2BAA2B;CAa1C"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,oCAAoC,EACpC,mBAAmB,EACnB,+BAA+B,EAC/B,+BAA+B,EAC/B,2BAA2B,EAC3B,2BAA2B,EAC3B,0BAA0B,EAE1B,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB;;;;;;;GAOG;AACH,qBACa,oBAAqB,YAAW,aAAa;IAItD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAH1B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0C;gBAGtD,OAAO,EAAE,oCAAoC,EAC9D,QAAQ,EAAE,SAAS,mBAAmB,EAAE;IAO1C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,QAAQ,CAAC,QAAQ,SAAS,2BAA2B,EACzD,YAAY,EAAE,QAAQ,EACtB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,0BAA0B,CAAC;IA+DtC;;;;;;;;OAQG;IACG,YAAY,CAAC,QAAQ,SAAS,2BAA2B,EAC7D,aAAa,EAAE,SAAS,QAAQ,EAAE,EAClC,OAAO,GAAE,+BAAoC,GAC5C,OAAO,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IAuGrD;;;;OAIG;IACH,4BAA4B;IAS5B,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,mBAAmB;IAQ3B,OAAO,CAAC,4BAA4B;IAQpC,OAAO,CAAC,yBAAyB;IAIjC,OAAO,CAAC,WAAW;YAYL,qBAAqB;YA4BrB,2BAA2B;YAc3B,4BAA4B;CAW3C"}

package/dist/service.js

@@ -22,7 +22,6 @@ class NotificationsService {
     [_NotificationsService, _initClass] = _applyDecs(this, [Inject(NOTIFICATIONS_OPTIONS, NOTIFICATION_CHANNELS)], []).c;
   }
   channelsByName = new Map();
-  fallbackDeliveryIdSequence = 0;
   constructor(options, channels) {
     this.options = options;
     for (const channel of channels) {
@@ -53,7 +52,12 @@ class NotificationsService {
   async dispatch(notification, options = {}) {
     await this.publishLifecycleEventSafely('notification.dispatch.requested', notification, options);
     if (this.shouldQueueSingleDispatch(options)) {
-      this.requireChannel(notification.channel);
+      try {
+        this.requireChannel(notification.channel);
+      } catch (error) {
+        await this.publishFailureLifecycleEvent(notification, options, error);
+        throw error;
+      }
       const job = this.createQueueJob(notification);
       try {
         const deliveryId = await this.requireQueueAdapter().enqueue(job);
@@ -66,11 +70,17 @@ class NotificationsService {
         await this.publishLifecycleEventSafely('notification.dispatch.queued', notification, options, result.deliveryId);
         return result;
       } catch (error) {
-        await this.publishLifecycleEventSafely('notification.dispatch.failed', notification, options, undefined, error);
+        await this.publishFailureLifecycleEvent(notification, options, error);
         throw error;
       }
     }
-    const channel = this.requireChannel(notification.channel);
+    let channel;
+    try {
+      channel = this.requireChannel(notification.channel);
+    } catch (error) {
+      await this.publishFailureLifecycleEvent(notification, options, error);
+      throw error;
+    }
     try {
       const delivery = await channel.send(notification, {
         signal: options.signal
@@ -85,7 +95,7 @@ class NotificationsService {
       await this.publishLifecycleEventSafely(result.queued ? 'notification.dispatch.queued' : 'notification.dispatch.delivered', notification, options, result.deliveryId);
       return result;
     } catch (error) {
-      await this.publishLifecycleEventSafely('notification.dispatch.failed', notification, options, undefined, error);
+      await this.publishFailureLifecycleEvent(notification, options, error);
       throw error;
     }
   }
@@ -112,17 +122,26 @@ class NotificationsService {
     if (this.shouldQueue(notifications.length, options)) {
       const queue = this.requireQueueAdapter();
       for (const notification of notifications) {
-        this.requireChannel(notification.channel);
+        await this.publishLifecycleEventSafely('notification.dispatch.requested', notification, options);
       }
-      const jobs = notifications.map(notification => this.createQueueJob(notification));
       for (const notification of notifications) {
-        await this.publishLifecycleEventSafely('notification.dispatch.requested', notification, options);
+        try {
+          this.requireChannel(notification.channel);
+        } catch (error) {
+          await this.publishFailureLifecycleEvent(notification, options, error);
+          throw error;
+        }
       }
+      const jobs = notifications.map(notification => this.createQueueJob(notification));
       let ids;
       try {
         ids = queue.enqueueMany ? await queue.enqueueMany(jobs) : await Promise.all(jobs.map(job => queue.enqueue(job)));
       } catch (error) {
-        await Promise.all(notifications.map(notification => this.publishLifecycleEventSafely('notification.dispatch.failed', notification, options, undefined, error)));
+        const failurePublicationResults = await Promise.allSettled(notifications.map(notification => this.publishLifecycleEvent('notification.dispatch.failed', notification, options, undefined, error)));
+        const publicationFailures = failurePublicationResults.filter(result => result.status === 'rejected').map(result => result.reason);
+        if (publicationFailures.length > 0) {
+          throw createLifecyclePublicationFailureError(error, ...publicationFailures);
+        }
         throw error;
       }
       const results = notifications.map((notification, index) => ({
@@ -184,10 +203,17 @@ class NotificationsService {
   createQueueJob(notification) {
     return {
       channel: notification.channel,
+      id: this.createQueueJobId(notification),
       notification,
       queuedAt: new Date().toISOString()
     };
   }
+  createQueueJobId(notification) {
+    if (notification.id && notification.id.length > 0) {
+      return notification.id;
+    }
+    return `notification:${notification.channel}:${stableNotificationHash(notification)}`;
+  }
   requireChannel(channelName) {
     const channel = this.channelsByName.get(channelName);
     if (!channel) {
@@ -202,8 +228,7 @@ class NotificationsService {
     if (fallback.id) {
       return fallback.id;
     }
-    this.fallbackDeliveryIdSequence = (this.fallbackDeliveryIdSequence + 1) % Number.MAX_SAFE_INTEGER;
-    return `${fallback.channel}:${Date.now().toString(36)}:${this.fallbackDeliveryIdSequence.toString(36)}:${Math.random().toString(36).slice(2, 10)}`;
+    return `fallback:${fallback.channel}:${stableNotificationHash(fallback)}`;
   }
   requireQueueAdapter() {
     if (!this.options.queue) {
@@ -253,8 +278,38 @@ class NotificationsService {
       return;
     }
   }
+  async publishFailureLifecycleEvent(notification, options, error) {
+    try {
+      await this.publishLifecycleEvent('notification.dispatch.failed', notification, options, undefined, error);
+    } catch (publicationError) {
+      throw createLifecyclePublicationFailureError(error, publicationError);
+    }
+  }
   static {
     _initClass();
   }
 }
-export { _NotificationsService as NotificationsService };
+export { _NotificationsService as NotificationsService };
+function createLifecyclePublicationFailureError(dispatchError, ...publicationErrors) {
+  const primaryMessage = dispatchError instanceof Error ? dispatchError.message : 'Notification dispatch failed.';
+  return new AggregateError([dispatchError, ...publicationErrors], `Notification dispatch failed, and failed lifecycle event publication also failed: ${primaryMessage}`);
+}
+function stableNotificationHash(notification) {
+  let hash = 0x811c9dc5;
+  const input = stableStringify(notification);
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(36).padStart(7, '0');
+}
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value) ?? String(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(entry => stableStringify(entry)).join(',')}]`;
+  }
+  const entries = Object.entries(value).filter(([, entry]) => entry !== undefined).sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableStringify(entry)}`).join(',')}}`;
+}

package/dist/types.d.ts

@@ -53,6 +53,14 @@ export interface NotificationChannel<TRequest extends NotificationDispatchReques
 /** Job payload forwarded to an optional queue adapter for deferred delivery. */
 export interface NotificationsQueueJob<TRequest extends NotificationDispatchRequest = NotificationDispatchRequest> {
     channel: string;
+    /**
+     * Deterministic idempotency key derived from the notification envelope.
+     *
+     * @remarks
+     * Queue adapters should use this value as their deduplication key when the
+     * backing queue supports idempotent enqueue semantics.
+     */
+    id: string;
     notification: TRequest;
     queuedAt: string;
 }
@@ -117,6 +125,8 @@ export interface NotificationsEventsOptions {
 export interface NotificationsModuleOptions {
     channels?: readonly NotificationChannel[];
     events?: NotificationsEventsOptions;
+    /** Whether notification providers should be visible globally. Defaults to `true`. */
+    global?: boolean;
     queue?: NotificationsQueueOptions;
 }
 /** Normalized module options resolved once during module registration. */
@@ -184,5 +194,5 @@ export interface Notifications {
     dispatchMany<TRequest extends NotificationDispatchRequest>(notifications: readonly TRequest[], options?: NotificationDispatchManyOptions): Promise<NotificationDispatchBatchResult<TRequest>>;
 }
 /** Async registration options for notifications modules that derive config through DI. */
-export type NotificationsAsyncModuleOptions = AsyncModuleOptions<NotificationsModuleOptions>;
+export type NotificationsAsyncModuleOptions = AsyncModuleOptions<Omit<NotificationsModuleOptions, 'global'>> & Pick<NotificationsModuleOptions, 'global'>;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,2BAA2B,CAAC,QAAQ,SAAS,mBAAmB,GAAG,mBAAmB;IACrG,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,QAAQ,CAAC;IAClB,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mFAAmF;AACnF,MAAM,MAAM,0BAA0B,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,2BAA2B,CAAC,QAAQ,GAAG,OAAO;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,MAAM,CAAC,EAAE,0BAA0B,CAAC;CACrC;AAED,oEAAoE;AACpE,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAClC,QAAQ,SAAS,2BAA2B,GAAG,2BAA2B,EAC1E,QAAQ,GAAG,OAAO;IAElB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC,QAAQ,CAAC,CAAC,CAAC;CACnH;AAED,gFAAgF;AAChF,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,2BAA2B,GAAG,2BAA2B;IAC/G,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,QAAQ,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErD;;;;;OAKG;IACH,WAAW,CAAC,CAAC,IAAI,EAAE,SAAS,qBAAqB,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CAClF;AAED,iFAAiF;AACjF,MAAM,MAAM,8BAA8B,GACtC,iCAAiC,GACjC,8BAA8B,GAC9B,iCAAiC,GACjC,8BAA8B,CAAC;AAEnC,iFAAiF;AACjF,MAAM,WAAW,0BAA0B,CAAC,QAAQ,SAAS,2BAA2B,GAAG,2BAA2B;IACpH,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,IAAI,EAAE,8BAA8B,CAAC;IACrC,YAAY,EAAE,QAAQ,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,yBAAyB,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,0BAA0B;IACzC,SAAS,EAAE,2BAA2B,CAAC;IACvC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,yFAAyF;AACzF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC1C,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,KAAK,CAAC,EAAE,yBAAyB,CAAC;CACnC;AAED,0EAA0E;AAC1E,MAAM,WAAW,oCAAoC;IACnD,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACzC,MAAM,CAAC,EAAE;QACP,sBAAsB,EAAE,OAAO,CAAC;QAChC,SAAS,EAAE,2BAA2B,CAAC;KACxC,CAAC;IACF,KAAK,CAAC,EAAE;QACN,OAAO,EAAE,yBAAyB,CAAC;QACnC,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,kEAAkE;AAClE,MAAM,WAAW,2BAA2B;IAC1C,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,+BAAgC,SAAQ,2BAA2B;IAClF,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,wEAAwE;AACxE,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,0BAA0B,CAAC;CACpC;AAED,oEAAoE;AACpE,MAAM,WAAW,2BAA2B,CAAC,QAAQ,SAAS,2BAA2B,GAAG,2BAA2B;IACrH,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,QAAQ,CAAC;CACxB;AAED,qEAAqE;AACrE,MAAM,WAAW,+BAA+B,CAAC,QAAQ,SAAS,2BAA2B,GAAG,2BAA2B;IACzH,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,2BAA2B,CAAC,QAAQ,CAAC,EAAE,CAAC;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sEAAsE;AACtE,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,SAAS,2BAA2B,EACnD,YAAY,EAAE,QAAQ,EACtB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEvC;;;;;;;OAOG;IACH,YAAY,CAAC,QAAQ,SAAS,2BAA2B,EACvD,aAAa,EAAE,SAAS,QAAQ,EAAE,EAClC,OAAO,CAAC,EAAE,+BAA+B,GACxC,OAAO,CAAC,+BAA+B,CAAC,QAAQ,CAAC,CAAC,CAAC;CACvD;AAED,0FAA0F;AAC1F,MAAM,MAAM,+BAA+B,GAAG,kBAAkB,CAAC,0BAA0B,CAAC,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -9,7 +9,7 @@
     "event-bus",
     "channels"
   ],
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -36,9 +36,9 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.1",
-    "@fluojs/di": "^1.0.0-beta.2",
-    "@fluojs/runtime": "^1.0.0-beta.2"
+    "@fluojs/core": "^1.0.0-beta.5",
+    "@fluojs/di": "^1.0.0-beta.7",
+    "@fluojs/runtime": "^1.0.0-beta.12"
   },
   "devDependencies": {
     "vitest": "^3.2.4"