@fluojs/email 1.0.0-beta.1

package/dist/channel.js

@@ -0,0 +1,64 @@
+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 { EmailService } from './service.js';
+import { EMAIL_OPTIONS } from './tokens.js';
+function createIncompleteDeliveryError(receipt) {
+  const error = new Error(`Email transport reported an incomplete delivery (accepted=${String(receipt.accepted.length)}, pending=${String(receipt.pending.length)}, rejected=${String(receipt.rejected.length)}).`);
+  error.name = 'EmailDeliveryError';
+  return error;
+}
+
+/**
+ * Notification channel implementation that bridges `@fluojs/notifications` to {@link EmailService}.
+ *
+ * @remarks
+ * This class keeps the foundation package channel-agnostic while allowing `@fluojs/email`
+ * to interpret email-specific payload fields, template rendering, and transport delivery.
+ */
+let _EmailChannel;
+class EmailChannel {
+  static {
+    [_EmailChannel, _initClass] = _applyDecs(this, [Inject(EmailService, EMAIL_OPTIONS)], []).c;
+  }
+  channel;
+  constructor(email, options) {
+    this.email = email;
+    this.channel = options.notifications.channel;
+  }
+
+  /**
+   * Sends one notifications foundation request through the configured email transport.
+   *
+   * @param notification Shared notification envelope understood by the email package.
+   * @param context Optional abort context propagated from the notifications service.
+   * @returns A normalized channel delivery result with the provider message id exposed as `externalId`.
+   */
+  async send(notification, context) {
+    const receipt = await this.email.sendNotification(notification, {
+      signal: context.signal
+    });
+    if (receipt.accepted.length === 0 || receipt.pending.length > 0 || receipt.rejected.length > 0) {
+      throw createIncompleteDeliveryError(receipt);
+    }
+    return {
+      externalId: receipt.messageId,
+      metadata: {
+        accepted: receipt.accepted,
+        pending: receipt.pending,
+        rejected: receipt.rejected,
+        response: receipt.response
+      },
+      receipt,
+      status: 'delivered'
+    };
+  }
+  static {
+    _initClass();
+  }
+}
+export { _EmailChannel as EmailChannel };

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+import type { EmailQueueWorkerOptions } from './types.js';
+/** Stable queue job name used by the email notifications worker contract. */
+export declare const EMAIL_QUEUE_JOB_NAME = "fluo.email.notification";
+/** Default worker options used by the built-in email notifications queue seam. */
+export declare const DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS: Required<EmailQueueWorkerOptions>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AAE9D,kFAAkF;AAClF,eAAO,MAAM,kCAAkC,EAAE,QAAQ,CAAC,uBAAuB,CAY/E,CAAC"}

package/dist/constants.js

@@ -0,0 +1,17 @@
+/** Stable queue job name used by the email notifications worker contract. */
+export const EMAIL_QUEUE_JOB_NAME = 'fluo.email.notification';
+
+/** Default worker options used by the built-in email notifications queue seam. */
+export const DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS = Object.freeze({
+  attempts: 3,
+  backoff: {
+    delayMs: 1_000,
+    type: 'exponential'
+  },
+  concurrency: 5,
+  jobName: EMAIL_QUEUE_JOB_NAME,
+  rateLimiter: {
+    duration: 1_000,
+    max: 50
+  }
+});

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Base error type for caller-visible email module configuration failures.
+ */
+export declare class EmailConfigurationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when an email message or notification payload is missing one required contract field.
+ */
+export declare class EmailMessageValidationError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;gBACxC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Base error type for caller-visible email module configuration failures.
+ */
+export class EmailConfigurationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'EmailConfigurationError';
+  }
+}
+
+/**
+ * Thrown when an email message or notification payload is missing one required contract field.
+ */
+export class EmailMessageValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'EmailMessageValidationError';
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { EmailConfigurationError, EmailMessageValidationError, } from './errors.js';
+export { EmailChannel } from './channel.js';
+export { EmailModule } from './module.js';
+export { EmailService } from './service.js';
+export { createEmailPlatformStatusSnapshot } from './status.js';
+export type { EmailLifecycleState, EmailPlatformStatusSnapshot, EmailStatusAdapterInput } from './status.js';
+export { EMAIL, EMAIL_CHANNEL } from './tokens.js';
+export type { Email, EmailAddress, EmailAddressLike, EmailAsyncModuleOptions, EmailAttachment, EmailMessage, EmailModuleOptions, EmailNotificationDispatchRequest, EmailNotificationPayload, EmailSendBatchResult, EmailSendFailure, EmailSendManyOptions, EmailSendOptions, EmailSendResult, NormalizedEmailAddressList, NormalizedEmailMessage, EmailTemplateRenderInput, EmailTemplateRenderer, EmailTemplateRenderResult, EmailTransport, EmailTransportContext, EmailTransportFactory, EmailTransportReceipt, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,iCAAiC,EAAE,MAAM,aAAa,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC7G,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EACV,KAAK,EACL,YAAY,EACZ,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,gCAAgC,EAChC,wBAAwB,EACxB,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { EmailConfigurationError, EmailMessageValidationError } from './errors.js';
+export { EmailChannel } from './channel.js';
+export { EmailModule } from './module.js';
+export { EmailService } from './service.js';
+export { createEmailPlatformStatusSnapshot } from './status.js';
+export { EMAIL, EMAIL_CHANNEL } from './tokens.js';

package/dist/module.d.ts

@@ -0,0 +1,45 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { EmailAsyncModuleOptions, EmailModuleOptions } from './types.js';
+/** Runtime module entrypoint for email delivery and notifications integration. */
+export declare class EmailModule {
+    /**
+     * Registers email providers using static options.
+     *
+     * @param options Static email module options including transport wiring and optional template rendering behavior.
+     * @returns A global module definition that exports {@link EmailService}, {@link EmailChannel}, and queue integration tokens.
+     *
+     * @example
+      * ```ts
+      * EmailModule.forRoot({
+      *   defaultFrom: 'noreply@example.com',
+      *   transport: {
+      *     kind: 'example-transport',
+      *     create: async () => exampleTransport,
+      *   },
+      * });
+      * ```
+      */
+    static forRoot(options: EmailModuleOptions): ModuleType;
+    /**
+     * Registers email providers from an async DI factory.
+     *
+     * @param options Async module options that resolve email transport and renderer configuration through DI.
+     * @returns A global module definition that memoizes async option resolution per module instance.
+     *
+     * @example
+      * ```ts
+      * EmailModule.forRootAsync({
+      *   inject: [ConfigService],
+      *   useFactory: (config) => ({
+      *     defaultFrom: config.mail.from,
+      *     transport: {
+      *       kind: config.mail.kind,
+      *       create: () => config.mail.transport,
+      *     },
+      *   }),
+      * });
+      * ```
+     */
+    static forRootAsync(options: EmailAsyncModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOhE,OAAO,KAAK,EAGV,uBAAuB,EAGvB,kBAAkB,EAEnB,MAAM,YAAY,CAAC;AA0HpB,kFAAkF;AAClF,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;QAgBI;IACJ,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,GAAG,UAAU;IAIvD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,UAAU;CAGlE"}

package/dist/module.js

@@ -0,0 +1,151 @@
+import { defineModule } from '@fluojs/runtime';
+import { EmailConfigurationError } from './errors.js';
+import { EmailChannel } from './channel.js';
+import { EmailNotificationsQueueWorker } from './queue.js';
+import { EmailService } from './service.js';
+import { EMAIL, EMAIL_CHANNEL, EMAIL_OPTIONS } from './tokens.js';
+function normalizeAddress(address) {
+  if (!address) {
+    return undefined;
+  }
+  if (typeof address === 'string') {
+    return {
+      address: address.trim()
+    };
+  }
+  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)).filter(entry => entry !== undefined);
+}
+function isTransportFactory(value) {
+  return typeof value === 'object' && value !== null && 'create' in value;
+}
+function normalizeEmailModuleOptions(options) {
+  if (!options.transport) {
+    throw new EmailConfigurationError('EmailModule requires an explicit `transport` to be configured.');
+  }
+  const transport = options.transport;
+  const createTransport = isTransportFactory(transport) ? async () => transport.create() : async () => transport;
+  return {
+    defaultFrom: normalizeAddress(options.defaultFrom),
+    defaultReplyTo: normalizeAddressList(options.defaultReplyTo),
+    notifications: {
+      channel: options.notifications?.channel?.trim() || 'email'
+    },
+    renderer: options.renderer,
+    transport: {
+      create: createTransport,
+      kind: isTransportFactory(transport) ? transport.kind?.trim() || 'custom-factory' : 'custom-instance',
+      ownsResources: isTransportFactory(transport) ? transport.ownsResources ?? true : false
+    },
+    verifyOnModuleInit: options.verifyOnModuleInit ?? false
+  };
+}
+function createEmailRuntimeProviders(optionsProvider) {
+  return [optionsProvider, EmailService, EmailChannel, EmailNotificationsQueueWorker, {
+    inject: [EmailService],
+    provide: EMAIL,
+    useFactory: service => ({
+      send: (message, options) => service.send(message, options),
+      sendMany: (messages, options) => service.sendMany(messages, options),
+      sendNotification: (notification, options) => service.sendNotification(notification, options)
+    })
+  }, {
+    inject: [EmailChannel],
+    provide: EMAIL_CHANNEL,
+    useFactory: channel => channel
+  }];
+}
+function createEmailProviders(options) {
+  return createEmailRuntimeProviders({
+    provide: EMAIL_OPTIONS,
+    useValue: normalizeEmailModuleOptions(options)
+  });
+}
+function buildEmailModule(options) {
+  class EmailRootModuleDefinition {}
+  return defineModule(EmailRootModuleDefinition, {
+    exports: [EmailService, EmailChannel, EMAIL, EMAIL_CHANNEL],
+    global: true,
+    providers: createEmailProviders(options)
+  });
+}
+function buildEmailModuleAsync(options) {
+  class EmailAsyncModuleDefinition {}
+  const factory = options.useFactory;
+  let cachedResult;
+  const memoizedFactory = (...deps) => {
+    if (!cachedResult) {
+      cachedResult = Promise.resolve(factory(...deps)).then(resolved => normalizeEmailModuleOptions(resolved));
+    }
+    return cachedResult;
+  };
+  return defineModule(EmailAsyncModuleDefinition, {
+    exports: [EmailService, EmailChannel, EMAIL, EMAIL_CHANNEL],
+    global: true,
+    providers: createEmailRuntimeProviders({
+      inject: options.inject,
+      provide: EMAIL_OPTIONS,
+      scope: 'singleton',
+      useFactory: (...deps) => memoizedFactory(...deps)
+    })
+  });
+}
+
+/** Runtime module entrypoint for email delivery and notifications integration. */
+export class EmailModule {
+  /**
+   * Registers email providers using static options.
+   *
+   * @param options Static email module options including transport wiring and optional template rendering behavior.
+   * @returns A global module definition that exports {@link EmailService}, {@link EmailChannel}, and queue integration tokens.
+   *
+   * @example
+    * ```ts
+    * EmailModule.forRoot({
+    *   defaultFrom: 'noreply@example.com',
+    *   transport: {
+    *     kind: 'example-transport',
+    *     create: async () => exampleTransport,
+    *   },
+    * });
+    * ```
+    */
+  static forRoot(options) {
+    return buildEmailModule(options);
+  }
+
+  /**
+   * Registers email providers from an async DI factory.
+   *
+   * @param options Async module options that resolve email transport and renderer configuration through DI.
+   * @returns A global module definition that memoizes async option resolution per module instance.
+   *
+   * @example
+    * ```ts
+    * EmailModule.forRootAsync({
+    *   inject: [ConfigService],
+    *   useFactory: (config) => ({
+    *     defaultFrom: config.mail.from,
+    *     transport: {
+    *       kind: config.mail.kind,
+    *       create: () => config.mail.transport,
+    *     },
+    *   }),
+    * });
+    * ```
+   */
+  static forRootAsync(options) {
+    return buildEmailModuleAsync(options);
+  }
+}

package/dist/node/node.d.ts

@@ -0,0 +1,2 @@
+export * from './nodemailer.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/node/node.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/node/node.js

@@ -0,0 +1 @@
+export * from './nodemailer.js';

package/dist/node/nodemailer.d.ts

@@ -0,0 +1,104 @@
+import type Mail from 'nodemailer/lib/mailer';
+import type SMTPTransport from 'nodemailer/lib/smtp-transport';
+import type { EmailTransport, EmailTransportContext, EmailTransportFactory, EmailTransportReceipt, NormalizedEmailMessage } from '../types.js';
+/** Node-only Nodemailer transporter type used by the explicit `@fluojs/email/node` seam. */
+export type NodemailerTransporter = Mail<SMTPTransport.SentMessageInfo>;
+/**
+ * Options for wrapping an existing Nodemailer transporter without transferring resource ownership.
+ *
+ * @remarks
+ * Use this when your application already constructs and manages the Nodemailer transporter
+ * at the Node boundary, but you still want to satisfy the shared {@link EmailTransport}
+ * contract consumed by `@fluojs/email`.
+ */
+export interface NodemailerEmailTransportOptions {
+    /** Existing Nodemailer transporter instance that remains owned by the caller. */
+    transporter: NodemailerTransporter;
+}
+/**
+ * Options for creating a factory-owned SMTP transporter behind `@fluojs/email/node`.
+ *
+ * @remarks
+ * The resulting factory advertises `ownsResources: true`, allowing the shared email module
+ * to close the Nodemailer transporter during application shutdown while keeping that behavior
+ * isolated to the Node-only subpath.
+ */
+export interface NodemailerEmailTransportFactoryOptions {
+    /** Optional diagnostic label surfaced through the root email status snapshot. */
+    kind?: string;
+    /** SMTP connection settings or SMTP URL passed directly to `nodemailer.createTransport(...)`. */
+    smtp: SMTPTransport.Options | string;
+}
+/**
+ * Node-only {@link EmailTransport} adapter that forwards normalized email messages to Nodemailer.
+ *
+ * @remarks
+ * This adapter intentionally lives behind `@fluojs/email/node` so SMTP/Nodemailer behavior,
+ * verification, and connection cleanup never leak into the transport-agnostic root barrel.
+ */
+export declare class NodemailerEmailTransport implements EmailTransport {
+    private readonly transporter;
+    constructor(transporter: NodemailerTransporter);
+    /**
+     * Sends one normalized email message through the wrapped Nodemailer transporter.
+     *
+     * @param message Normalized message generated by the shared email package before provider hand-off.
+     * @param _context Optional transport context accepted for contract compatibility with the shared root API.
+     * @returns A normalized receipt containing accepted/rejected recipients, response details, and message id.
+     *
+     * @example
+     * ```ts
+     * const transport = createNodemailerEmailTransport({ transporter });
+     * await transport.send(message, {});
+     * ```
+     */
+    send(message: NormalizedEmailMessage, _context: EmailTransportContext): Promise<EmailTransportReceipt>;
+    /**
+     * Verifies SMTP connectivity and authentication through the wrapped Nodemailer transporter.
+     *
+     * @returns A promise that resolves once Nodemailer reports the transporter is ready.
+     */
+    verify(): Promise<void>;
+    /**
+     * Closes the wrapped Nodemailer transporter.
+     *
+     * @returns A promise that resolves after the close signal has been forwarded.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Wraps an existing Nodemailer transporter as an `EmailTransport` without transferring ownership.
+ *
+ * @param options Existing transporter wiring owned by the caller.
+ * @returns A Node-only transport implementation that can be passed directly to `EmailModule.forRoot(...)`.
+ *
+ * @example
+ * ```ts
+ * const transporter = nodemailer.createTransport({ host: 'smtp.example.com', port: 587, secure: false });
+ * const transport = createNodemailerEmailTransport({ transporter });
+ * ```
+ */
+export declare function createNodemailerEmailTransport(options: NodemailerEmailTransportOptions): EmailTransport;
+/**
+ * Creates a factory-owned Nodemailer SMTP transport for the explicit `@fluojs/email/node` entrypoint.
+ *
+ * @param options SMTP connection settings and an optional diagnostic label.
+ * @returns An {@link EmailTransportFactory} that lazily creates a Nodemailer transport and marks ownership as internal.
+ *
+ * @example
+ * ```ts
+ * EmailModule.forRoot({
+ *   transport: createNodemailerEmailTransportFactory({
+ *     smtp: {
+ *       auth: { pass: 'secret', user: 'mailer' },
+ *       host: 'smtp.example.com',
+ *       port: 587,
+ *       secure: false,
+ *     },
+ *   }),
+ *   verifyOnModuleInit: true,
+ * });
+ * ```
+ */
+export declare function createNodemailerEmailTransportFactory(options: NodemailerEmailTransportFactoryOptions): EmailTransportFactory;
+//# sourceMappingURL=nodemailer.d.ts.map

package/dist/node/nodemailer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodemailer.d.ts","sourceRoot":"","sources":["../../src/node/nodemailer.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAC9C,OAAO,KAAK,aAAa,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAEV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB,4FAA4F;AAC5F,MAAM,MAAM,qBAAqB,GAAG,IAAI,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,+BAA+B;IAC9C,iFAAiF;IACjF,WAAW,EAAE,qBAAqB,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,sCAAsC;IACrD,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,iGAAiG;IACjG,IAAI,EAAE,aAAa,CAAC,OAAO,GAAG,MAAM,CAAC;CACtC;AAoDD;;;;;;GAMG;AACH,qBAAa,wBAAyB,YAAW,cAAc;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,qBAAqB;IAE/D;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,OAAO,EAAE,sBAAsB,EAAE,QAAQ,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAa5G;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAI7B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,+BAA+B,GAAG,cAAc,CAEvG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qCAAqC,CACnD,OAAO,EAAE,sCAAsC,GAC9C,qBAAqB,CAQvB"}

package/dist/node/nodemailer.js

@@ -0,0 +1,166 @@
+import { Buffer } from 'node:buffer';
+import nodemailer from 'nodemailer';
+
+/** Node-only Nodemailer transporter type used by the explicit `@fluojs/email/node` seam. */
+
+/**
+ * Options for wrapping an existing Nodemailer transporter without transferring resource ownership.
+ *
+ * @remarks
+ * Use this when your application already constructs and manages the Nodemailer transporter
+ * at the Node boundary, but you still want to satisfy the shared {@link EmailTransport}
+ * contract consumed by `@fluojs/email`.
+ */
+
+/**
+ * Options for creating a factory-owned SMTP transporter behind `@fluojs/email/node`.
+ *
+ * @remarks
+ * The resulting factory advertises `ownsResources: true`, allowing the shared email module
+ * to close the Nodemailer transporter during application shutdown while keeping that behavior
+ * isolated to the Node-only subpath.
+ */
+
+function createAddress(address) {
+  return address.name ? `${address.name} <${address.address}>` : address.address;
+}
+function createAddressList(addresses) {
+  if (addresses.length === 0) {
+    return undefined;
+  }
+  return addresses.map(address => createAddress(address));
+}
+function createAttachments(attachments) {
+  if (!attachments || attachments.length === 0) {
+    return undefined;
+  }
+  return attachments.map(attachment => ({
+    content: typeof attachment.content === 'string' ? attachment.content : Buffer.from(attachment.content.buffer, attachment.content.byteOffset, attachment.content.byteLength),
+    contentType: attachment.contentType,
+    filename: attachment.filename
+  }));
+}
+function createSendMailOptions(message) {
+  return {
+    attachments: createAttachments(message.attachments),
+    bcc: createAddressList(message.bcc),
+    cc: createAddressList(message.cc),
+    from: createAddress(message.from),
+    headers: message.headers,
+    html: message.html,
+    replyTo: createAddressList(message.replyTo),
+    subject: message.subject,
+    text: message.text,
+    to: createAddressList(message.to)
+  };
+}
+function normalizeAddressList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map(entry => String(entry));
+}
+
+/**
+ * Node-only {@link EmailTransport} adapter that forwards normalized email messages to Nodemailer.
+ *
+ * @remarks
+ * This adapter intentionally lives behind `@fluojs/email/node` so SMTP/Nodemailer behavior,
+ * verification, and connection cleanup never leak into the transport-agnostic root barrel.
+ */
+export class NodemailerEmailTransport {
+  constructor(transporter) {
+    this.transporter = transporter;
+  }
+
+  /**
+   * Sends one normalized email message through the wrapped Nodemailer transporter.
+   *
+   * @param message Normalized message generated by the shared email package before provider hand-off.
+   * @param _context Optional transport context accepted for contract compatibility with the shared root API.
+   * @returns A normalized receipt containing accepted/rejected recipients, response details, and message id.
+   *
+   * @example
+   * ```ts
+   * const transport = createNodemailerEmailTransport({ transporter });
+   * await transport.send(message, {});
+   * ```
+   */
+  async send(message, _context) {
+    const receipt = await this.transporter.sendMail(createSendMailOptions(message));
+    return {
+      accepted: normalizeAddressList(receipt.accepted),
+      messageId: typeof receipt.messageId === 'string' ? receipt.messageId : undefined,
+      metadata: receipt.envelope ? {
+        envelope: receipt.envelope
+      } : undefined,
+      pending: normalizeAddressList(receipt.pending),
+      rejected: normalizeAddressList(receipt.rejected),
+      response: typeof receipt.response === 'string' ? receipt.response : undefined
+    };
+  }
+
+  /**
+   * Verifies SMTP connectivity and authentication through the wrapped Nodemailer transporter.
+   *
+   * @returns A promise that resolves once Nodemailer reports the transporter is ready.
+   */
+  async verify() {
+    await this.transporter.verify();
+  }
+
+  /**
+   * Closes the wrapped Nodemailer transporter.
+   *
+   * @returns A promise that resolves after the close signal has been forwarded.
+   */
+  async close() {
+    this.transporter.close();
+  }
+}
+
+/**
+ * Wraps an existing Nodemailer transporter as an `EmailTransport` without transferring ownership.
+ *
+ * @param options Existing transporter wiring owned by the caller.
+ * @returns A Node-only transport implementation that can be passed directly to `EmailModule.forRoot(...)`.
+ *
+ * @example
+ * ```ts
+ * const transporter = nodemailer.createTransport({ host: 'smtp.example.com', port: 587, secure: false });
+ * const transport = createNodemailerEmailTransport({ transporter });
+ * ```
+ */
+export function createNodemailerEmailTransport(options) {
+  return new NodemailerEmailTransport(options.transporter);
+}
+
+/**
+ * Creates a factory-owned Nodemailer SMTP transport for the explicit `@fluojs/email/node` entrypoint.
+ *
+ * @param options SMTP connection settings and an optional diagnostic label.
+ * @returns An {@link EmailTransportFactory} that lazily creates a Nodemailer transport and marks ownership as internal.
+ *
+ * @example
+ * ```ts
+ * EmailModule.forRoot({
+ *   transport: createNodemailerEmailTransportFactory({
+ *     smtp: {
+ *       auth: { pass: 'secret', user: 'mailer' },
+ *       host: 'smtp.example.com',
+ *       port: 587,
+ *       secure: false,
+ *     },
+ *   }),
+ *   verifyOnModuleInit: true,
+ * });
+ * ```
+ */
+export function createNodemailerEmailTransportFactory(options) {
+  const kind = options.kind?.trim() || 'nodemailer-smtp';
+  return {
+    create: async () => new NodemailerEmailTransport(nodemailer.createTransport(options.smtp)),
+    kind,
+    ownsResources: true
+  };
+}

package/dist/node.d.ts

@@ -0,0 +1,2 @@
+export * from './node/node.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/node.js

@@ -0,0 +1 @@
+export * from './node/node.js';

package/dist/queue-entry.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_EMAIL_QUEUE_WORKER_OPTIONS } from './constants.js';
+export { createEmailNotificationsQueueAdapter } from './queue.js';
+export type { EmailQueueWorkerOptions } from './types.js';
+//# sourceMappingURL=queue-entry.d.ts.map