@fluojs/email 1.0.0-beta.1

package/dist/queue-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-entry.d.ts","sourceRoot":"","sources":["../src/queue-entry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kCAAkC,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,oCAAoC,EAAE,MAAM,YAAY,CAAC;AAClE,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}

package/dist/queue-entry.js

@@ -0,0 +1,2 @@
+export { DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS } from './constants.js';
+export { createEmailNotificationsQueueAdapter } from './queue.js';

package/dist/queue.d.ts

@@ -0,0 +1,38 @@
+import type { NotificationsQueueAdapter } from '@fluojs/notifications';
+import { QueueLifecycleService } from '@fluojs/queue';
+import { EmailService } from './service.js';
+import type { EmailNotificationDispatchRequest } from './types.js';
+/** Serialized queue payload used by the built-in notifications queue adapter. */
+export declare class EmailNotificationQueueJob {
+    readonly notification: EmailNotificationDispatchRequest;
+    readonly queuedAt: string;
+    constructor(notification: EmailNotificationDispatchRequest, queuedAt: string);
+}
+/**
+ * Creates a notifications queue adapter backed by {@link QueueLifecycleService}.
+ *
+ * @param queue Queue lifecycle service used to enqueue email notification jobs.
+ * @returns A queue adapter compatible with `NotificationsModule.forRoot(...)` queue wiring.
+ *
+ * @example
+ * ```ts
+ * NotificationsModule.forRootAsync({
+ *   inject: [EMAIL_CHANNEL, QueueLifecycleService],
+ *   useFactory: (channel, queue) => ({
+ *     channels: [channel],
+ *     queue: {
+ *       adapter: createEmailNotificationsQueueAdapter(queue),
+ *       bulkThreshold: 25,
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export declare function createEmailNotificationsQueueAdapter(queue: QueueLifecycleService): NotificationsQueueAdapter;
+/** Internal queue worker that converts queued notification jobs back into email delivery. */
+export declare class EmailNotificationsQueueWorker {
+    private readonly email;
+    constructor(email: EmailService);
+    handle(job: EmailNotificationQueueJob): Promise<void>;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,yBAAyB,EAAyB,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EAAE,qBAAqB,EAAe,MAAM,eAAe,CAAC;AAGnE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,YAAY,CAAC;AAEnE,iFAAiF;AACjF,qBAAa,yBAAyB;aAElB,YAAY,EAAE,gCAAgC;aAC9C,QAAQ,EAAE,MAAM;gBADhB,YAAY,EAAE,gCAAgC,EAC9C,QAAQ,EAAE,MAAM;CAEnC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,qBAAqB,GAAG,yBAAyB,CAW5G;AAED,6FAA6F;AAC7F,qBAEa,6BAA6B;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAE1C,MAAM,CAAC,GAAG,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5D"}

package/dist/queue.js

@@ -0,0 +1,66 @@
+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 { QueueWorker } from '@fluojs/queue';
+import { DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS } from './constants.js';
+import { EmailService } from './service.js';
+/** Serialized queue payload used by the built-in notifications queue adapter. */
+export class EmailNotificationQueueJob {
+  constructor(notification, queuedAt) {
+    this.notification = notification;
+    this.queuedAt = queuedAt;
+  }
+}
+
+/**
+ * Creates a notifications queue adapter backed by {@link QueueLifecycleService}.
+ *
+ * @param queue Queue lifecycle service used to enqueue email notification jobs.
+ * @returns A queue adapter compatible with `NotificationsModule.forRoot(...)` queue wiring.
+ *
+ * @example
+ * ```ts
+ * NotificationsModule.forRootAsync({
+ *   inject: [EMAIL_CHANNEL, QueueLifecycleService],
+ *   useFactory: (channel, queue) => ({
+ *     channels: [channel],
+ *     queue: {
+ *       adapter: createEmailNotificationsQueueAdapter(queue),
+ *       bulkThreshold: 25,
+ *     },
+ *   }),
+ * });
+ * ```
+ */
+export function createEmailNotificationsQueueAdapter(queue) {
+  return {
+    enqueue(job) {
+      return queue.enqueue(new EmailNotificationQueueJob(job.notification, job.queuedAt));
+    },
+    enqueueMany(jobs) {
+      return Promise.all(jobs.map(job => queue.enqueue(new EmailNotificationQueueJob(job.notification, job.queuedAt))));
+    }
+  };
+}
+
+/** Internal queue worker that converts queued notification jobs back into email delivery. */
+let _EmailNotificationsQu;
+class EmailNotificationsQueueWorker {
+  static {
+    [_EmailNotificationsQu, _initClass] = _applyDecs(this, [QueueWorker(EmailNotificationQueueJob, DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS), Inject(EmailService)], []).c;
+  }
+  constructor(email) {
+    this.email = email;
+  }
+  async handle(job) {
+    await this.email.sendNotification(job.notification);
+  }
+  static {
+    _initClass();
+  }
+}
+export { _EmailNotificationsQu as EmailNotificationsQueueWorker };

package/dist/service.d.ts

@@ -0,0 +1,81 @@
+import type { OnApplicationShutdown, OnModuleInit } from '@fluojs/runtime';
+import type { Email, EmailMessage, EmailNotificationDispatchRequest, EmailSendBatchResult, EmailSendManyOptions, EmailSendOptions, EmailSendResult, NormalizedEmailModuleOptions } from './types.js';
+/**
+ * Injectable email delivery service for standalone and notifications-backed usage.
+ *
+ * @remarks
+ * The service stays transport-agnostic at the shared package boundary, consumes only
+ * explicitly injected {@link EmailTransport} contracts, and translates
+ * `@fluojs/notifications` envelopes into concrete email messages.
+ */
+export declare class EmailService implements Email, OnModuleInit, OnApplicationShutdown {
+    private readonly options;
+    private lifecycleState;
+    private resolvedTransport;
+    private transportPromise;
+    constructor(options: NormalizedEmailModuleOptions);
+    onApplicationShutdown(): Promise<void>;
+    onModuleInit(): Promise<void>;
+    /**
+     * Creates a platform status snapshot for the active email transport wiring.
+     *
+     * @returns A structured snapshot describing lifecycle state, resource ownership, and notifications integration details.
+     */
+    createPlatformStatusSnapshot(): import("./status.js").EmailPlatformStatusSnapshot;
+    /**
+     * Sends one email message directly through the configured transport.
+     *
+     * @param message Caller-supplied email message with addresses, subject, and body content.
+     * @param options Optional abort signal propagated to the transport.
+     * @returns A normalized delivery receipt describing accepted/rejected recipients and the message id.
+     * @throws {EmailMessageValidationError} When the resolved message is missing required sender, recipient, or content fields.
+     *
+     * @example
+     * ```ts
+     * await email.send({
+     *   from: 'noreply@example.com',
+     *   to: ['user@example.com'],
+     *   subject: 'Welcome',
+     *   text: 'Hello from Fluo',
+     * });
+     * ```
+     */
+    send(message: EmailMessage, options?: EmailSendOptions): Promise<EmailSendResult>;
+    /**
+     * Sends multiple email messages in input order with optional tolerant failure handling.
+     *
+     * @param messages Ordered message list to deliver through the configured transport.
+     * @param options Optional tolerant batch controls such as `continueOnError`.
+     * @returns A batch summary containing successes and any captured failures.
+     *
+     * @example
+     * ```ts
+     * const result = await email.sendMany(messages, { continueOnError: true });
+     * console.log(result.succeeded, result.failed);
+     * ```
+     */
+    sendMany(messages: readonly EmailMessage[], options?: EmailSendManyOptions): Promise<EmailSendBatchResult>;
+    /**
+     * Converts one notifications foundation request into a concrete email delivery.
+     *
+     * @param notification Shared notification envelope interpreted by the email package.
+     * @param options Optional abort signal propagated to rendering and transport work.
+     * @returns A normalized delivery receipt for the resulting email message.
+     * @throws {EmailMessageValidationError} When the notification cannot resolve recipients or content.
+     *
+     * @example
+     * ```ts
+     * await email.sendNotification({
+     *   channel: 'email',
+     *   recipients: ['user@example.com'],
+     *   subject: 'Digest',
+     *   payload: { text: 'Your weekly update' },
+     * });
+     * ```
+     */
+    sendNotification(notification: EmailNotificationDispatchRequest, options?: EmailSendOptions): Promise<EmailSendResult>;
+    private ensureTransport;
+    private normalizeMessage;
+    private renderNotification;
+}
+//# 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":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAM3E,OAAO,KAAK,EACV,KAAK,EAGL,YAAY,EACZ,gCAAgC,EAC9B,oBAAoB,EAEpB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EAKf,4BAA4B,EAC7B,MAAM,YAAY,CAAC;AA2CtB;;;;;;;GAOG;AACH,qBACa,YAAa,YAAW,KAAK,EAAE,YAAY,EAAE,qBAAqB;IAKjE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,cAAc,CAAmF;IACzG,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,gBAAgB,CAAsC;gBAEjC,OAAO,EAAE,4BAA4B;IAE5D,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAetC,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBnC;;;;OAIG;IACH,4BAA4B;IAY5B;;;;;;;;;;;;;;;;;OAiBG;IACG,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAoB3F;;;;;;;;;;;;OAYG;IACG,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IA6BpH;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CACpB,YAAY,EAAE,gCAAgC,EAC9C,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC;YA0Bb,eAAe;IAe7B,OAAO,CAAC,gBAAgB;YAuBV,kBAAkB;CAejC"}

package/dist/service.js

@@ -0,0 +1,275 @@
+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 { DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS } from './constants.js';
+import { EmailMessageValidationError } from './errors.js';
+import { createEmailPlatformStatusSnapshot } from './status.js';
+import { EMAIL_OPTIONS } from './tokens.js';
+function normalizeAddress(address) {
+  if (typeof address === 'string') {
+    const trimmed = address.trim();
+    return {
+      address: trimmed
+    };
+  }
+  return {
+    address: address.address.trim(),
+    ...(address.name ? {
+      name: address.name
+    } : {})
+  };
+}
+function normalizeAddressList(value) {
+  if (!value) {
+    return [];
+  }
+  const list = Array.isArray(value) ? value : [value];
+  return list.map(entry => normalizeAddress(entry));
+}
+function createAbortError() {
+  const error = new Error('Email delivery was aborted.');
+  error.name = 'AbortError';
+  return error;
+}
+function assertMessageContent(message) {
+  if (message.to.length === 0) {
+    throw new EmailMessageValidationError('Email messages require at least one recipient in `to`.');
+  }
+  if (!message.from.address) {
+    throw new EmailMessageValidationError('Email messages require a resolved `from` address.');
+  }
+  if (!message.html && !message.text) {
+    throw new EmailMessageValidationError('Email messages require `html` or `text` content.');
+  }
+}
+
+/**
+ * Injectable email delivery service for standalone and notifications-backed usage.
+ *
+ * @remarks
+ * The service stays transport-agnostic at the shared package boundary, consumes only
+ * explicitly injected {@link EmailTransport} contracts, and translates
+ * `@fluojs/notifications` envelopes into concrete email messages.
+ */
+let _EmailService;
+class EmailService {
+  static {
+    [_EmailService, _initClass] = _applyDecs(this, [Inject(EMAIL_OPTIONS)], []).c;
+  }
+  lifecycleState = 'created';
+  resolvedTransport;
+  transportPromise;
+  constructor(options) {
+    this.options = options;
+  }
+  async onApplicationShutdown() {
+    this.lifecycleState = 'stopping';
+    try {
+      if (this.resolvedTransport && this.options.transport.ownsResources && this.resolvedTransport.close) {
+        await this.resolvedTransport.close();
+      }
+      this.lifecycleState = 'stopped';
+    } catch {
+      this.lifecycleState = 'failed';
+      throw new Error('Email transport failed to close cleanly.');
+    }
+  }
+  async onModuleInit() {
+    this.lifecycleState = 'starting';
+    try {
+      const transport = await this.ensureTransport();
+      if (this.options.verifyOnModuleInit && transport.verify) {
+        await transport.verify();
+      }
+      this.lifecycleState = 'ready';
+    } catch {
+      this.lifecycleState = 'failed';
+      throw new Error('Email transport failed to initialize.');
+    }
+  }
+
+  /**
+   * Creates a platform status snapshot for the active email transport wiring.
+   *
+   * @returns A structured snapshot describing lifecycle state, resource ownership, and notifications integration details.
+   */
+  createPlatformStatusSnapshot() {
+    return createEmailPlatformStatusSnapshot({
+      channelName: this.options.notifications.channel,
+      defaultFromConfigured: this.options.defaultFrom !== undefined,
+      lifecycleState: this.lifecycleState,
+      ownsTransportResources: this.options.transport.ownsResources,
+      queueWorkerJobName: DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS.jobName,
+      transportKind: this.options.transport.kind,
+      verifiedOnModuleInit: this.options.verifyOnModuleInit
+    });
+  }
+
+  /**
+   * Sends one email message directly through the configured transport.
+   *
+   * @param message Caller-supplied email message with addresses, subject, and body content.
+   * @param options Optional abort signal propagated to the transport.
+   * @returns A normalized delivery receipt describing accepted/rejected recipients and the message id.
+   * @throws {EmailMessageValidationError} When the resolved message is missing required sender, recipient, or content fields.
+   *
+   * @example
+   * ```ts
+   * await email.send({
+   *   from: 'noreply@example.com',
+   *   to: ['user@example.com'],
+   *   subject: 'Welcome',
+   *   text: 'Hello from Fluo',
+   * });
+   * ```
+   */
+  async send(message, options = {}) {
+    if (options.signal?.aborted) {
+      throw createAbortError();
+    }
+    const transport = await this.ensureTransport();
+    const normalized = this.normalizeMessage(message);
+    assertMessageContent(normalized);
+    const result = await transport.send(normalized, options);
+    return {
+      accepted: result.accepted ?? [],
+      messageId: result.messageId ?? '',
+      metadata: result.metadata,
+      pending: result.pending ?? [],
+      rejected: result.rejected ?? [],
+      response: result.response
+    };
+  }
+
+  /**
+   * Sends multiple email messages in input order with optional tolerant failure handling.
+   *
+   * @param messages Ordered message list to deliver through the configured transport.
+   * @param options Optional tolerant batch controls such as `continueOnError`.
+   * @returns A batch summary containing successes and any captured failures.
+   *
+   * @example
+   * ```ts
+   * const result = await email.sendMany(messages, { continueOnError: true });
+   * console.log(result.succeeded, result.failed);
+   * ```
+   */
+  async sendMany(messages, options = {}) {
+    const results = [];
+    const failures = [];
+    for (const message of messages) {
+      try {
+        results.push(await this.send(message, options));
+      } catch (error) {
+        const failure = {
+          error: error instanceof Error ? error : new Error('Email delivery failed.'),
+          message
+        };
+        if (!(options.continueOnError ?? false)) {
+          throw failure.error;
+        }
+        failures.push(failure);
+      }
+    }
+    return {
+      failed: failures.length,
+      failures,
+      results,
+      succeeded: results.length
+    };
+  }
+
+  /**
+   * Converts one notifications foundation request into a concrete email delivery.
+   *
+   * @param notification Shared notification envelope interpreted by the email package.
+   * @param options Optional abort signal propagated to rendering and transport work.
+   * @returns A normalized delivery receipt for the resulting email message.
+   * @throws {EmailMessageValidationError} When the notification cannot resolve recipients or content.
+   *
+   * @example
+   * ```ts
+   * await email.sendNotification({
+   *   channel: 'email',
+   *   recipients: ['user@example.com'],
+   *   subject: 'Digest',
+   *   payload: { text: 'Your weekly update' },
+   * });
+   * ```
+   */
+  async sendNotification(notification, options = {}) {
+    const payload = notification.payload;
+    const rendered = await this.renderNotification(notification);
+    return this.send({
+      attachments: payload.attachments,
+      bcc: payload.bcc,
+      cc: payload.cc,
+      from: payload.from,
+      headers: payload.headers,
+      html: payload.html ?? rendered?.html,
+      metadata: {
+        ...(payload.metadata ?? {}),
+        ...(notification.metadata ?? {}),
+        ...(notification.template ? {
+          template: notification.template
+        } : {})
+      },
+      replyTo: payload.replyTo,
+      subject: notification.subject ?? rendered?.subject,
+      text: payload.text ?? rendered?.text,
+      to: payload.to ?? notification.recipients ?? []
+    }, options);
+  }
+  async ensureTransport() {
+    if (this.resolvedTransport) {
+      return this.resolvedTransport;
+    }
+    if (!this.transportPromise) {
+      this.transportPromise = this.options.transport.create().then(transport => {
+        this.resolvedTransport = transport;
+        return transport;
+      });
+    }
+    return this.transportPromise;
+  }
+  normalizeMessage(message) {
+    const from = message.from ? normalizeAddress(message.from) : this.options.defaultFrom;
+    const replyTo = normalizeAddressList(message.replyTo);
+    if (!from) {
+      throw new EmailMessageValidationError('Email messages require `from` or `defaultFrom` to be configured.');
+    }
+    return {
+      attachments: message.attachments,
+      bcc: normalizeAddressList(message.bcc),
+      cc: normalizeAddressList(message.cc),
+      from,
+      headers: message.headers,
+      html: message.html,
+      metadata: message.metadata,
+      replyTo: replyTo.length > 0 ? replyTo : this.options.defaultReplyTo,
+      subject: message.subject,
+      text: message.text,
+      to: normalizeAddressList(message.to)
+    };
+  }
+  async renderNotification(notification) {
+    if (!notification.template || !this.options.renderer) {
+      return undefined;
+    }
+    return this.options.renderer.render({
+      locale: notification.locale,
+      metadata: notification.metadata,
+      payload: notification.payload,
+      subject: notification.subject,
+      template: notification.template
+    });
+  }
+  static {
+    _initClass();
+  }
+}
+export { _EmailService as EmailService };

package/dist/status.d.ts

@@ -0,0 +1,28 @@
+import type { PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/** Resolved email lifecycle state used for diagnostics and health checks. */
+export type EmailLifecycleState = 'created' | 'starting' | 'ready' | 'stopping' | 'stopped' | 'failed';
+/** Input required to describe the package health/readiness contract. */
+export interface EmailStatusAdapterInput {
+    channelName: string;
+    defaultFromConfigured: boolean;
+    lifecycleState: EmailLifecycleState;
+    ownsTransportResources: boolean;
+    queueWorkerJobName: string;
+    transportKind: string;
+    verifiedOnModuleInit: boolean;
+}
+/** Structured snapshot returned by {@link createEmailPlatformStatusSnapshot}. */
+export interface EmailPlatformStatusSnapshot {
+    details: Record<string, unknown>;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    readiness: PlatformReadinessReport;
+}
+/**
+ * Creates a health/readiness snapshot for the email delivery layer.
+ *
+ * @param input Lifecycle and ownership details derived from the active email module wiring.
+ * @returns A structured snapshot suitable for status endpoints and operational diagnostics.
+ */
+export declare function createEmailPlatformStatusSnapshot(input: EmailStatusAdapterInput): EmailPlatformStatusSnapshot;
+//# 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,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEvG,wEAAwE;AACxE,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,cAAc,EAAE,mBAAmB,CAAC;IACpC,sBAAsB,EAAE,OAAO,CAAC;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,iFAAiF;AACjF,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,SAAS,EAAE,uBAAuB,CAAC;CACpC;AA6DD;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,uBAAuB,GAAG,2BAA2B,CAkB7G"}

package/dist/status.js

@@ -0,0 +1,83 @@
+/** Resolved email lifecycle state used for diagnostics and health checks. */
+
+/** Input required to describe the package health/readiness contract. */
+
+/** Structured snapshot returned by {@link createEmailPlatformStatusSnapshot}. */
+
+function createReadiness(input) {
+  if (input.lifecycleState === 'ready') {
+    return {
+      critical: true,
+      status: 'ready'
+    };
+  }
+  if (input.lifecycleState === 'starting') {
+    return {
+      critical: true,
+      reason: 'Email transport is still starting.',
+      status: 'degraded'
+    };
+  }
+  if (input.lifecycleState === 'stopping' || input.lifecycleState === 'stopped') {
+    return {
+      critical: true,
+      reason: 'Email transport is shutting down or already stopped.',
+      status: 'not-ready'
+    };
+  }
+  if (input.lifecycleState === 'failed') {
+    return {
+      critical: true,
+      reason: 'Email transport failed to initialize.',
+      status: 'not-ready'
+    };
+  }
+  return {
+    critical: true,
+    reason: 'Email transport has not started yet.',
+    status: 'not-ready'
+  };
+}
+function createHealth(input) {
+  if (input.lifecycleState === 'failed' || input.lifecycleState === 'stopped') {
+    return {
+      reason: 'Email transport is unavailable.',
+      status: 'unhealthy'
+    };
+  }
+  if (input.lifecycleState === 'created' || input.lifecycleState === 'starting' || input.lifecycleState === 'stopping') {
+    return {
+      reason: 'Email transport is transitioning lifecycle state.',
+      status: 'degraded'
+    };
+  }
+  return {
+    status: 'healthy'
+  };
+}
+
+/**
+ * Creates a health/readiness snapshot for the email delivery layer.
+ *
+ * @param input Lifecycle and ownership details derived from the active email module wiring.
+ * @returns A structured snapshot suitable for status endpoints and operational diagnostics.
+ */
+export function createEmailPlatformStatusSnapshot(input) {
+  return {
+    details: {
+      channelName: input.channelName,
+      defaultFromConfigured: input.defaultFromConfigured,
+      dependencies: ['notifications.channel', 'email.transport'],
+      lifecycleState: input.lifecycleState,
+      queueWorkerJobName: input.queueWorkerJobName,
+      transportKind: input.transportKind,
+      verifiedOnModuleInit: input.verifiedOnModuleInit
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: !input.ownsTransportResources,
+      ownsResources: input.ownsTransportResources
+    },
+    readiness: createReadiness(input)
+  };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,10 @@
+import type { Token } from '@fluojs/core';
+import type { NotificationChannel } from '@fluojs/notifications';
+import type { Email, EmailNotificationDispatchRequest, NormalizedEmailModuleOptions } from './types.js';
+/** Compatibility token for the facade returned by {@link EmailModule.forRoot}. */
+export declare const EMAIL: Token<Email>;
+/** Injection token for the channel implementation consumed by `@fluojs/notifications`. */
+export declare const EMAIL_CHANNEL: Token<NotificationChannel<EmailNotificationDispatchRequest>>;
+/** Injection token for normalized email module options consumed internally by providers. */
+export declare const EMAIL_OPTIONS: Token<NormalizedEmailModuleOptions>;
+//# 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;AAC1C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,KAAK,EAAE,KAAK,EAAE,gCAAgC,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAExG,kFAAkF;AAClF,eAAO,MAAM,KAAK,EAAE,KAAK,CAAC,KAAK,CAA4B,CAAC;AAC5D,0FAA0F;AAC1F,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,mBAAmB,CAAC,gCAAgC,CAAC,CAAoC,CAAC;AAC5H,4FAA4F;AAC5F,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,4BAA4B,CAAoC,CAAC"}

package/dist/tokens.js

@@ -0,0 +1,6 @@
+/** Compatibility token for the facade returned by {@link EmailModule.forRoot}. */
+export const EMAIL = Symbol.for('fluo.email');
+/** Injection token for the channel implementation consumed by `@fluojs/notifications`. */
+export const EMAIL_CHANNEL = Symbol.for('fluo.email.channel');
+/** Injection token for normalized email module options consumed internally by providers. */
+export const EMAIL_OPTIONS = Symbol.for('fluo.email.options');