@fluojs/notifications 1.0.0-beta.1

package/dist/service.d.ts

@@ -0,0 +1,62 @@
+import type { NormalizedNotificationsModuleOptions, NotificationChannel, NotificationDispatchBatchResult, NotificationDispatchManyOptions, NotificationDispatchOptions, NotificationDispatchRequest, NotificationDispatchResult, Notifications } from './types.js';
+/**
+ * Injectable orchestration service for shared notification dispatch.
+ *
+ * @remarks
+ * The foundation package keeps channel-specific payload semantics opaque. It only
+ * resolves channels by name, applies optional queue delegation, and emits optional
+ * lifecycle events through the configured publisher seam.
+ */
+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.
+     *
+     * @typeParam TRequest Shared notification request envelope subtype.
+     * @param notification Request envelope identifying the channel and opaque payload.
+     * @param options Optional abort, queue, and lifecycle-publication controls.
+     * @returns A normalized dispatch result describing direct vs queued delivery.
+     * @throws {NotificationChannelNotFoundError} When no registered channel matches `notification.channel`.
+     * @throws {NotificationQueueNotConfiguredError} When queue delivery is requested without a queue adapter.
+     *
+     * @example
+     * ```ts
+     * await notifications.dispatch({
+     *   channel: 'email',
+     *   subject: 'Welcome',
+     *   payload: { template: 'welcome', userId: 'u_123' },
+     *   recipients: ['hello@example.com'],
+     * });
+     * ```
+     */
+    dispatch<TRequest extends NotificationDispatchRequest>(notification: TRequest, options?: NotificationDispatchOptions): Promise<NotificationDispatchResult>;
+    /**
+     * Dispatches multiple notifications in input order with optional bulk queue delegation.
+     *
+     * @typeParam TRequest Shared notification request envelope subtype.
+     * @param notifications Ordered notification envelopes to send or enqueue.
+     * @param options Optional queue preference and tolerant error-handling controls.
+     * @returns A batch summary containing successes and captured failures.
+     * @throws {NotificationQueueNotConfiguredError} When queue-backed bulk delivery is requested without a queue adapter.
+     */
+    dispatchMany<TRequest extends NotificationDispatchRequest>(notifications: readonly TRequest[], options?: NotificationDispatchManyOptions): Promise<NotificationDispatchBatchResult<TRequest>>;
+    /**
+     * Creates a health/readiness snapshot for the active notifications wiring.
+     *
+     * @returns A structured snapshot describing registered channels and optional integration seams.
+     */
+    createPlatformStatusSnapshot(): import("./status.js").NotificationsPlatformStatusSnapshot;
+    private createQueueJob;
+    private requireChannel;
+    private normalizeDeliveryId;
+    private requireQueueAdapter;
+    private shouldPublishLifecycleEvents;
+    private shouldQueueSingleDispatch;
+    private shouldQueue;
+    private publishLifecycleEvent;
+    private publishLifecycleEventSafely;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +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"}

package/dist/service.js

@@ -0,0 +1,260 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { NotificationChannelNotFoundError, NotificationQueueNotConfiguredError } from './errors.js';
+import { createNotificationsPlatformStatusSnapshot } from './status.js';
+import { NOTIFICATION_CHANNELS, NOTIFICATIONS_OPTIONS } from './tokens.js';
+let _NotificationsService;
+/**
+ * Injectable orchestration service for shared notification dispatch.
+ *
+ * @remarks
+ * The foundation package keeps channel-specific payload semantics opaque. It only
+ * resolves channels by name, applies optional queue delegation, and emits optional
+ * lifecycle events through the configured publisher seam.
+ */
+class NotificationsService {
+  static {
+    [_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) {
+      this.channelsByName.set(channel.channel, channel);
+    }
+  }
+
+  /**
+   * Dispatches one notification through a registered channel or the configured queue seam.
+   *
+   * @typeParam TRequest Shared notification request envelope subtype.
+   * @param notification Request envelope identifying the channel and opaque payload.
+   * @param options Optional abort, queue, and lifecycle-publication controls.
+   * @returns A normalized dispatch result describing direct vs queued delivery.
+   * @throws {NotificationChannelNotFoundError} When no registered channel matches `notification.channel`.
+   * @throws {NotificationQueueNotConfiguredError} When queue delivery is requested without a queue adapter.
+   *
+   * @example
+   * ```ts
+   * await notifications.dispatch({
+   *   channel: 'email',
+   *   subject: 'Welcome',
+   *   payload: { template: 'welcome', userId: 'u_123' },
+   *   recipients: ['hello@example.com'],
+   * });
+   * ```
+   */
+  async dispatch(notification, options = {}) {
+    await this.publishLifecycleEventSafely('notification.dispatch.requested', notification, options);
+    if (this.shouldQueueSingleDispatch(options)) {
+      this.requireChannel(notification.channel);
+      const job = this.createQueueJob(notification);
+      try {
+        const deliveryId = await this.requireQueueAdapter().enqueue(job);
+        const result = {
+          channel: notification.channel,
+          deliveryId: this.normalizeDeliveryId(deliveryId, notification),
+          queued: true,
+          status: 'queued'
+        };
+        await this.publishLifecycleEventSafely('notification.dispatch.queued', notification, options, result.deliveryId);
+        return result;
+      } catch (error) {
+        await this.publishLifecycleEventSafely('notification.dispatch.failed', notification, options, undefined, error);
+        throw error;
+      }
+    }
+    const channel = this.requireChannel(notification.channel);
+    try {
+      const delivery = await channel.send(notification, {
+        signal: options.signal
+      });
+      const result = {
+        channel: notification.channel,
+        deliveryId: this.normalizeDeliveryId(delivery.externalId, notification),
+        metadata: delivery.metadata,
+        queued: delivery.status === 'queued',
+        status: delivery.status ?? 'delivered'
+      };
+      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);
+      throw error;
+    }
+  }
+
+  /**
+   * Dispatches multiple notifications in input order with optional bulk queue delegation.
+   *
+   * @typeParam TRequest Shared notification request envelope subtype.
+   * @param notifications Ordered notification envelopes to send or enqueue.
+   * @param options Optional queue preference and tolerant error-handling controls.
+   * @returns A batch summary containing successes and captured failures.
+   * @throws {NotificationQueueNotConfiguredError} When queue-backed bulk delivery is requested without a queue adapter.
+   */
+  async dispatchMany(notifications, options = {}) {
+    if (notifications.length === 0) {
+      return {
+        failed: 0,
+        failures: [],
+        queued: 0,
+        results: [],
+        succeeded: 0
+      };
+    }
+    if (this.shouldQueue(notifications.length, options)) {
+      const queue = this.requireQueueAdapter();
+      for (const notification of notifications) {
+        this.requireChannel(notification.channel);
+      }
+      const jobs = notifications.map(notification => this.createQueueJob(notification));
+      for (const notification of notifications) {
+        await this.publishLifecycleEventSafely('notification.dispatch.requested', notification, options);
+      }
+      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)));
+        throw error;
+      }
+      const results = notifications.map((notification, index) => ({
+        channel: notification.channel,
+        deliveryId: this.normalizeDeliveryId(ids[index], notification),
+        queued: true,
+        status: 'queued'
+      }));
+      for (let index = 0; index < notifications.length; index += 1) {
+        const notification = notifications[index];
+        await this.publishLifecycleEventSafely('notification.dispatch.queued', notification, options, results[index]?.deliveryId);
+      }
+      return {
+        failed: 0,
+        failures: [],
+        queued: results.length,
+        results,
+        succeeded: results.length
+      };
+    }
+    const results = [];
+    const failures = [];
+    for (const notification of notifications) {
+      try {
+        results.push(await this.dispatch(notification, options));
+      } catch (error) {
+        const failure = {
+          error: error instanceof Error ? error : new Error('Notification dispatch failed.'),
+          notification
+        };
+        if (!(options.continueOnError ?? false)) {
+          throw failure.error;
+        }
+        failures.push(failure);
+      }
+    }
+    return {
+      failed: failures.length,
+      failures,
+      queued: results.filter(result => result.queued).length,
+      results,
+      succeeded: results.length
+    };
+  }
+
+  /**
+   * Creates a health/readiness snapshot for the active notifications wiring.
+   *
+   * @returns A structured snapshot describing registered channels and optional integration seams.
+   */
+  createPlatformStatusSnapshot() {
+    return createNotificationsPlatformStatusSnapshot({
+      bulkQueueThreshold: this.options.queue?.bulkThreshold ?? 0,
+      channelsRegistered: this.channelsByName.size,
+      eventPublisherConfigured: this.options.events !== undefined,
+      queueConfigured: this.options.queue !== undefined
+    });
+  }
+  createQueueJob(notification) {
+    return {
+      channel: notification.channel,
+      notification,
+      queuedAt: new Date().toISOString()
+    };
+  }
+  requireChannel(channelName) {
+    const channel = this.channelsByName.get(channelName);
+    if (!channel) {
+      throw new NotificationChannelNotFoundError(channelName);
+    }
+    return channel;
+  }
+  normalizeDeliveryId(value, fallback) {
+    if (value && value.length > 0) {
+      return value;
+    }
+    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)}`;
+  }
+  requireQueueAdapter() {
+    if (!this.options.queue) {
+      throw new NotificationQueueNotConfiguredError();
+    }
+    return this.options.queue.adapter;
+  }
+  shouldPublishLifecycleEvents(options) {
+    if (typeof options.publishLifecycleEvents === 'boolean') {
+      return options.publishLifecycleEvents;
+    }
+    return this.options.events?.publishLifecycleEvents ?? false;
+  }
+  shouldQueueSingleDispatch(options) {
+    return options.queue === true;
+  }
+  shouldQueue(notificationCount, options) {
+    if (options.queue === true) {
+      return true;
+    }
+    if (options.queue === false || !this.options.queue) {
+      return false;
+    }
+    return notificationCount >= this.options.queue.bulkThreshold;
+  }
+  async publishLifecycleEvent(name, notification, options, deliveryId, error) {
+    if (!this.options.events || !this.shouldPublishLifecycleEvents(options)) {
+      return;
+    }
+    const event = {
+      channel: notification.channel,
+      deliveryId,
+      error: error instanceof Error ? {
+        message: error.message,
+        name: error.name
+      } : undefined,
+      name,
+      notification,
+      occurredAt: new Date().toISOString()
+    };
+    await this.options.events.publisher.publish(event);
+  }
+  async publishLifecycleEventSafely(name, notification, options, deliveryId, error) {
+    try {
+      await this.publishLifecycleEvent(name, notification, options, deliveryId, error);
+    } catch {
+      return;
+    }
+  }
+  static {
+    _initClass();
+  }
+}
+export { _NotificationsService as NotificationsService };

package/dist/status.d.ts

@@ -0,0 +1,25 @@
+import type { PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/** Resolved notification runtime mode used for diagnostics. */
+export type NotificationsOperationMode = 'direct-only' | 'direct-with-events' | 'queue-backed' | 'queue-backed-with-events' | 'unconfigured';
+/** Input required to describe the package health/readiness contract. */
+export interface NotificationsStatusAdapterInput {
+    bulkQueueThreshold: number;
+    channelsRegistered: number;
+    eventPublisherConfigured: boolean;
+    queueConfigured: boolean;
+}
+/** Structured snapshot returned by {@link createNotificationsPlatformStatusSnapshot}. */
+export interface NotificationsPlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+/**
+ * Creates a health/readiness snapshot for the notifications orchestration layer.
+ *
+ * @param input Registered-channel and optional-integration counts derived from the active module wiring.
+ * @returns A structured snapshot suitable for status endpoints and operational diagnostics.
+ */
+export declare function createNotificationsPlatformStatusSnapshot(input: NotificationsStatusAdapterInput): NotificationsPlatformStatusSnapshot;
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,+DAA+D;AAC/D,MAAM,MAAM,0BAA0B,GAClC,aAAa,GACb,oBAAoB,GACpB,cAAc,GACd,0BAA0B,GAC1B,cAAc,CAAC;AAEnB,wEAAwE;AACxE,MAAM,WAAW,+BAA+B;IAC9C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wBAAwB,EAAE,OAAO,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,yFAAyF;AACzF,MAAM,WAAW,mCAAmC;IAClD,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAyDD;;;;;GAKG;AACH,wBAAgB,yCAAyC,CACvD,KAAK,EAAE,+BAA+B,GACrC,mCAAmC,CAoBrC"}

package/dist/status.js

@@ -0,0 +1,76 @@
+/** Resolved notification runtime mode used for diagnostics. */
+
+/** Input required to describe the package health/readiness contract. */
+
+/** Structured snapshot returned by {@link createNotificationsPlatformStatusSnapshot}. */
+
+function resolveOperationMode(input) {
+  if (input.channelsRegistered === 0 && !input.queueConfigured && !input.eventPublisherConfigured) {
+    return 'unconfigured';
+  }
+  if (input.queueConfigured && input.eventPublisherConfigured) {
+    return 'queue-backed-with-events';
+  }
+  if (input.queueConfigured) {
+    return 'queue-backed';
+  }
+  if (input.eventPublisherConfigured) {
+    return 'direct-with-events';
+  }
+  return 'direct-only';
+}
+function createReadiness(input) {
+  if (input.channelsRegistered > 0) {
+    return {
+      critical: true,
+      status: 'ready'
+    };
+  }
+  return {
+    critical: true,
+    reason: 'No notification channels are registered.',
+    status: 'not-ready'
+  };
+}
+function createHealth(input) {
+  if (input.channelsRegistered > 0) {
+    return {
+      status: 'healthy'
+    };
+  }
+  if (input.queueConfigured || input.eventPublisherConfigured) {
+    return {
+      reason: 'Notifications infrastructure is configured, but no delivery channels are registered yet.',
+      status: 'degraded'
+    };
+  }
+  return {
+    reason: 'Notifications module has no registered channels or optional integrations.',
+    status: 'unhealthy'
+  };
+}
+
+/**
+ * Creates a health/readiness snapshot for the notifications orchestration layer.
+ *
+ * @param input Registered-channel and optional-integration counts derived from the active module wiring.
+ * @returns A structured snapshot suitable for status endpoints and operational diagnostics.
+ */
+export function createNotificationsPlatformStatusSnapshot(input) {
+  return {
+    details: {
+      bulkQueueThreshold: input.bulkQueueThreshold,
+      channelsRegistered: input.channelsRegistered,
+      dependencies: [...(input.queueConfigured ? ['notifications.queue-adapter'] : []), ...(input.eventPublisherConfigured ? ['notifications.event-publisher'] : [])],
+      eventPublisherConfigured: input.eventPublisherConfigured,
+      operationMode: resolveOperationMode(input),
+      queueConfigured: input.queueConfigured
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: input.queueConfigured || input.eventPublisherConfigured,
+      ownsResources: false
+    },
+    readiness: createReadiness(input)
+  };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,9 @@
+import type { Token } from '@fluojs/core';
+import type { Notifications, NormalizedNotificationsModuleOptions, NotificationChannel } from './types.js';
+/** Compatibility injection token for the facade returned by {@link NotificationsModule.forRoot}. */
+export declare const NOTIFICATIONS: Token<Notifications>;
+/** Injection token for the normalized channel registry exposed to sibling notification packages. */
+export declare const NOTIFICATION_CHANNELS: Token<readonly NotificationChannel[]>;
+/** Injection token for normalized notifications module options consumed by {@link NotificationsService}. */
+export declare const NOTIFICATIONS_OPTIONS: Token<NormalizedNotificationsModuleOptions>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,aAAa,EAAE,oCAAoC,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAE3G,oGAAoG;AACpG,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,aAAa,CAAoC,CAAC;AACpF,oGAAoG;AACpG,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,SAAS,mBAAmB,EAAE,CAA6C,CAAC;AACtH,4GAA4G;AAC5G,eAAO,MAAM,qBAAqB,EAAE,KAAK,CAAC,oCAAoC,CAA4C,CAAC"}

package/dist/tokens.js

@@ -0,0 +1,6 @@
+/** Compatibility injection token for the facade returned by {@link NotificationsModule.forRoot}. */
+export const NOTIFICATIONS = Symbol.for('fluo.notifications');
+/** Injection token for the normalized channel registry exposed to sibling notification packages. */
+export const NOTIFICATION_CHANNELS = Symbol.for('fluo.notifications.channels');
+/** Injection token for normalized notifications module options consumed by {@link NotificationsService}. */
+export const NOTIFICATIONS_OPTIONS = Symbol.for('fluo.notifications.options');

package/dist/types.d.ts

@@ -0,0 +1,188 @@
+import type { AsyncModuleOptions } from '@fluojs/core';
+/** Opaque payload shape carried through the shared notification contract. */
+export type NotificationPayload = Record<string, unknown>;
+/**
+ * Shared request envelope that leaf notification packages must understand.
+ *
+ * @typeParam TPayload Channel-specific payload shape supplied by the caller.
+ */
+export interface NotificationDispatchRequest<TPayload extends NotificationPayload = NotificationPayload> {
+    channel: string;
+    id?: string;
+    locale?: string;
+    metadata?: Record<string, unknown>;
+    payload: TPayload;
+    recipients?: readonly string[];
+    subject?: string;
+    template?: string;
+}
+/** Delivery statuses emitted by direct and queue-backed notification workflows. */
+export type NotificationDispatchStatus = 'delivered' | 'queued';
+/**
+ * Channel-level delivery response returned by one concrete notification implementation.
+ *
+ * @typeParam TReceipt Provider-specific receipt or transport response shape.
+ */
+export interface NotificationChannelDelivery<TReceipt = unknown> {
+    externalId?: string;
+    metadata?: Record<string, unknown>;
+    receipt?: TReceipt;
+    status?: NotificationDispatchStatus;
+}
+/** Context object passed to one registered notification channel. */
+export interface NotificationChannelContext {
+    signal?: AbortSignal;
+}
+/**
+ * Stable contract that downstream channel packages (email, Slack, Discord, etc.) implement.
+ *
+ * @typeParam TRequest Shared request envelope subtype accepted by the channel implementation.
+ * @typeParam TReceipt Provider-specific delivery receipt returned by the channel.
+ */
+export interface NotificationChannel<TRequest extends NotificationDispatchRequest = NotificationDispatchRequest, TReceipt = unknown> {
+    channel: string;
+    /**
+     * Sends one notification through the concrete channel implementation.
+     *
+     * @param notification Shared request envelope received from the notifications foundation package.
+     * @param context Optional dispatch-time context, including abort propagation.
+     * @returns Provider-specific delivery details normalized into the shared contract.
+     */
+    send(notification: TRequest, context: NotificationChannelContext): Promise<NotificationChannelDelivery<TReceipt>>;
+}
+/** Job payload forwarded to an optional queue adapter for deferred delivery. */
+export interface NotificationsQueueJob<TRequest extends NotificationDispatchRequest = NotificationDispatchRequest> {
+    channel: string;
+    notification: TRequest;
+    queuedAt: string;
+}
+/**
+ * Queue seam used when applications prefer background delivery for bulk notifications.
+ *
+ * @remarks
+ * The foundation package intentionally depends on this abstract contract instead of
+ * a concrete `@fluojs/queue` type so that queue-backed delivery remains optional.
+ */
+export interface NotificationsQueueAdapter {
+    /**
+     * Enqueues one notification delivery job.
+     *
+     * @param job Serialized notification envelope ready for background processing.
+     * @returns A queue-assigned identifier that can be surfaced to callers.
+     */
+    enqueue(job: NotificationsQueueJob): Promise<string>;
+    /**
+     * Enqueues multiple notification delivery jobs in one operation when supported.
+     *
+     * @param jobs Ordered notification envelopes to enqueue.
+     * @returns Ordered queue identifiers aligned with the input order.
+     */
+    enqueueMany?(jobs: readonly NotificationsQueueJob[]): Promise<readonly string[]>;
+}
+/** Lifecycle event names emitted through the optional event publication seam. */
+export type NotificationLifecycleEventName = 'notification.dispatch.requested' | 'notification.dispatch.queued' | 'notification.dispatch.delivered' | 'notification.dispatch.failed';
+/** Published event payload emitted around notification lifecycle transitions. */
+export interface NotificationLifecycleEvent<TRequest extends NotificationDispatchRequest = NotificationDispatchRequest> {
+    channel: string;
+    deliveryId?: string;
+    error?: {
+        message: string;
+        name: string;
+    };
+    name: NotificationLifecycleEventName;
+    notification: TRequest;
+    occurredAt: string;
+}
+/** Optional event publication seam for notification lifecycle visibility. */
+export interface NotificationsEventPublisher {
+    /**
+     * Publishes one notification lifecycle event.
+     *
+     * @param event Lifecycle event describing a requested, queued, delivered, or failed dispatch step.
+     * @returns A promise that resolves once the caller-visible publication completes.
+     */
+    publish(event: NotificationLifecycleEvent): Promise<void>;
+}
+/** Queue configuration for optional bulk-delivery offloading. */
+export interface NotificationsQueueOptions {
+    adapter: NotificationsQueueAdapter;
+    bulkThreshold?: number;
+}
+/** Optional lifecycle publication configuration. */
+export interface NotificationsEventsOptions {
+    publisher: NotificationsEventPublisher;
+    publishLifecycleEvents?: boolean;
+}
+/** Module options accepted by {@link NotificationsModule.forRoot} and `forRootAsync`. */
+export interface NotificationsModuleOptions {
+    channels?: readonly NotificationChannel[];
+    events?: NotificationsEventsOptions;
+    queue?: NotificationsQueueOptions;
+}
+/** Normalized module options resolved once during module registration. */
+export interface NormalizedNotificationsModuleOptions {
+    channels: readonly NotificationChannel[];
+    events?: {
+        publishLifecycleEvents: boolean;
+        publisher: NotificationsEventPublisher;
+    };
+    queue?: {
+        adapter: NotificationsQueueAdapter;
+        bulkThreshold: number;
+    };
+}
+/** Runtime dispatch controls applied to one notification call. */
+export interface NotificationDispatchOptions {
+    publishLifecycleEvents?: boolean;
+    queue?: boolean;
+    signal?: AbortSignal;
+}
+/** Additional controls for one bulk dispatch invocation. */
+export interface NotificationDispatchManyOptions extends NotificationDispatchOptions {
+    continueOnError?: boolean;
+}
+/** Caller-visible normalized result for one dispatched notification. */
+export interface NotificationDispatchResult {
+    channel: string;
+    deliveryId: string;
+    metadata?: Record<string, unknown>;
+    queued: boolean;
+    status: NotificationDispatchStatus;
+}
+/** Failure record returned by tolerant bulk dispatch operations. */
+export interface NotificationDispatchFailure<TRequest extends NotificationDispatchRequest = NotificationDispatchRequest> {
+    error: Error;
+    notification: TRequest;
+}
+/** Summary returned by {@link NotificationsService.dispatchMany}. */
+export interface NotificationDispatchBatchResult<TRequest extends NotificationDispatchRequest = NotificationDispatchRequest> {
+    failed: number;
+    failures: readonly NotificationDispatchFailure<TRequest>[];
+    queued: number;
+    results: readonly NotificationDispatchResult[];
+    succeeded: number;
+}
+/** Facade exposed to application code and the compatibility token. */
+export interface Notifications {
+    /**
+     * Dispatches one notification to a registered channel or the optional queue seam.
+     *
+     * @typeParam TRequest Shared notification request envelope subtype.
+     * @param notification Request envelope identifying the channel and opaque payload.
+     * @param options Optional abort, queue, and lifecycle-publication controls.
+     * @returns A normalized dispatch result describing whether the delivery was queued or completed directly.
+     */
+    dispatch<TRequest extends NotificationDispatchRequest>(notification: TRequest, options?: NotificationDispatchOptions): Promise<NotificationDispatchResult>;
+    /**
+     * Dispatches multiple notifications in input order with optional tolerant error handling.
+     *
+     * @typeParam TRequest Shared notification request envelope subtype.
+     * @param notifications Ordered notification envelopes to send or enqueue.
+     * @param options Optional queue preference and bulk error-handling controls.
+     * @returns A batch summary containing normalized results and any captured failures.
+     */
+    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>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};