@forinda/kickjs-mailer 1.1.0

package/LICENSE

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

package/dist/index.d.ts

@@ -0,0 +1,273 @@
+import { AppAdapter, Container } from '@forinda/kickjs-core';
+
+interface MailAddress {
+    name?: string;
+    address: string;
+}
+type MailRecipient = string | MailAddress;
+interface MailAttachment {
+    filename: string;
+    content?: string | Buffer;
+    path?: string;
+    contentType?: string;
+    encoding?: string;
+}
+interface MailMessage {
+    /** Sender address */
+    from?: MailRecipient;
+    /** Recipient(s) */
+    to: MailRecipient | MailRecipient[];
+    /** CC recipient(s) */
+    cc?: MailRecipient | MailRecipient[];
+    /** BCC recipient(s) */
+    bcc?: MailRecipient | MailRecipient[];
+    /** Reply-to address */
+    replyTo?: MailRecipient;
+    /** Email subject */
+    subject: string;
+    /** Plain text body */
+    text?: string;
+    /** HTML body */
+    html?: string;
+    /** File attachments */
+    attachments?: MailAttachment[];
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Provider-specific options (e.g. Resend tags, SES configuration set) */
+    metadata?: Record<string, any>;
+}
+interface MailResult {
+    /** Provider-assigned message ID */
+    messageId: string;
+    /** Whether the send was accepted (does not guarantee delivery) */
+    accepted: boolean;
+    /** Raw response from the provider */
+    raw?: any;
+}
+/**
+ * Template engine for rendering email bodies.
+ * Implement this to use EJS, Handlebars, Pug, or any template system.
+ *
+ * @example
+ * ```ts
+ * import Handlebars from 'handlebars'
+ *
+ * class HandlebarsEngine implements MailTemplateEngine {
+ *   private templates = new Map<string, HandlebarsTemplateDelegate>()
+ *
+ *   register(name: string, source: string) {
+ *     this.templates.set(name, Handlebars.compile(source))
+ *   }
+ *
+ *   async render(template: string, data: any) {
+ *     const fn = this.templates.get(template)
+ *     if (!fn) throw new Error(`Template "${template}" not found`)
+ *     return fn(data)
+ *   }
+ * }
+ * ```
+ */
+interface MailTemplateEngine {
+    /** Render a named template with data. Returns HTML string. */
+    render(template: string, data: Record<string, any>): Promise<string> | string;
+}
+/**
+ * Abstract mail provider. Implement this to use any email service:
+ * SMTP (nodemailer), Resend, AWS SES, SendGrid, Postmark, Mailgun, etc.
+ *
+ * @example
+ * ```ts
+ * class ResendProvider implements MailProvider {
+ *   name = 'resend'
+ *   private client: Resend
+ *
+ *   constructor(apiKey: string) {
+ *     this.client = new Resend(apiKey)
+ *   }
+ *
+ *   async send(message: MailMessage): Promise<MailResult> {
+ *     const { data, error } = await this.client.emails.send({
+ *       from: formatAddress(message.from),
+ *       to: formatRecipients(message.to),
+ *       subject: message.subject,
+ *       html: message.html,
+ *       text: message.text,
+ *     })
+ *     if (error) throw error
+ *     return { messageId: data.id, accepted: true, raw: data }
+ *   }
+ * }
+ * ```
+ */
+interface MailProvider {
+    /** Provider name for logging */
+    name: string;
+    /** Send an email message */
+    send(message: MailMessage): Promise<MailResult>;
+    /** Optional cleanup (close connections, etc.) */
+    shutdown?(): Promise<void>;
+}
+interface MailerOptions {
+    /** Mail provider to use */
+    provider: MailProvider;
+    /** Default "from" address for all emails */
+    defaultFrom?: MailRecipient;
+    /** Optional template engine for rendering HTML from templates */
+    templateEngine?: MailTemplateEngine;
+    /** Enable/disable sending (useful for testing — logs instead of sending) */
+    enabled?: boolean;
+}
+
+/** DI token for resolving MailerService from the container */
+declare const MAILER: unique symbol;
+/**
+ * Central mail service — send emails through any provider.
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * class UserService {
+ *   constructor(@Inject(MAILER) private mailer: MailerService) {}
+ *
+ *   async sendWelcome(user: User) {
+ *     await this.mailer.send({
+ *       to: user.email,
+ *       subject: 'Welcome!',
+ *       html: '<h1>Welcome to our app</h1>',
+ *     })
+ *   }
+ *
+ *   // Or with templates:
+ *   async sendInvoice(user: User, invoice: Invoice) {
+ *     await this.mailer.sendTemplate('invoice', {
+ *       to: user.email,
+ *       subject: `Invoice #${invoice.number}`,
+ *     }, { user, invoice })
+ *   }
+ * }
+ * ```
+ */
+declare class MailerService {
+    private provider;
+    private defaultFrom?;
+    private templateEngine?;
+    private enabled;
+    constructor(options: MailerOptions);
+    /**
+     * Send an email message.
+     * Applies defaultFrom if no from address is set.
+     */
+    send(message: MailMessage): Promise<MailResult>;
+    /**
+     * Render a template and send the resulting HTML as an email.
+     * Requires a templateEngine to be configured.
+     *
+     * @param template - Template name (resolved by the engine)
+     * @param message - Mail message (html will be overwritten by the rendered template)
+     * @param data - Template variables
+     */
+    sendTemplate(template: string, message: Omit<MailMessage, 'html'>, data: Record<string, any>): Promise<MailResult>;
+    /** Get the underlying provider (for advanced use) */
+    getProvider(): MailProvider;
+    /** Shutdown the provider */
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Mailer adapter — registers MailerService in the DI container.
+ *
+ * @example
+ * ```ts
+ * import { MailerAdapter, SmtpProvider } from '@forinda/kickjs-mailer'
+ *
+ * bootstrap({
+ *   adapters: [
+ *     new MailerAdapter({
+ *       provider: new SmtpProvider({ host: 'smtp.gmail.com', port: 587, auth: { ... } }),
+ *       defaultFrom: { name: 'My App', address: 'noreply@myapp.com' },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+declare class MailerAdapter implements AppAdapter {
+    private options;
+    name: string;
+    private mailer;
+    constructor(options: MailerOptions);
+    afterStart(_server: any, container: Container): void;
+    shutdown(): Promise<void>;
+}
+
+interface SmtpOptions {
+    /** SMTP host (e.g. 'smtp.gmail.com', 'smtp.resend.com') */
+    host: string;
+    /** SMTP port (default: 587) */
+    port?: number;
+    /** Use TLS (default: true for port 465, false otherwise) */
+    secure?: boolean;
+    /** Authentication credentials */
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    /** Connection timeout in ms (default: 10000) */
+    connectionTimeout?: number;
+}
+/**
+ * SMTP mail provider using nodemailer.
+ *
+ * Requires `nodemailer` as a peer dependency:
+ * ```bash
+ * pnpm add nodemailer @types/nodemailer
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Gmail
+ * new SmtpProvider({
+ *   host: 'smtp.gmail.com',
+ *   port: 587,
+ *   auth: { user: 'you@gmail.com', pass: 'app-password' },
+ * })
+ *
+ * // Resend via SMTP
+ * new SmtpProvider({
+ *   host: 'smtp.resend.com',
+ *   port: 465,
+ *   secure: true,
+ *   auth: { user: 'resend', pass: process.env.RESEND_API_KEY! },
+ * })
+ *
+ * // Mailpit (local dev)
+ * new SmtpProvider({ host: 'localhost', port: 1025 })
+ * ```
+ */
+declare class SmtpProvider implements MailProvider {
+    private options;
+    name: string;
+    private transporter;
+    constructor(options: SmtpOptions);
+    private ensureTransporter;
+    send(message: MailMessage): Promise<MailResult>;
+    shutdown(): Promise<void>;
+}
+
+/**
+ * Console mail provider — logs emails instead of sending them.
+ * Perfect for development and testing.
+ *
+ * @example
+ * ```ts
+ * new MailerAdapter({
+ *   provider: new ConsoleProvider(),
+ *   defaultFrom: 'dev@localhost',
+ * })
+ * ```
+ */
+declare class ConsoleProvider implements MailProvider {
+    name: string;
+    send(message: MailMessage): Promise<MailResult>;
+}
+
+export { ConsoleProvider, MAILER, type MailAddress, type MailAttachment, type MailMessage, type MailProvider, type MailRecipient, type MailResult, type MailTemplateEngine, MailerAdapter, type MailerOptions, MailerService, type SmtpOptions, SmtpProvider };

package/dist/index.js

@@ -0,0 +1,229 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/index.ts
+import "reflect-metadata";
+
+// src/mailer.service.ts
+import { Logger } from "@forinda/kickjs-core";
+var log = Logger.for("Mailer");
+var MAILER = /* @__PURE__ */ Symbol("MailerService");
+var MailerService = class {
+  static {
+    __name(this, "MailerService");
+  }
+  provider;
+  defaultFrom;
+  templateEngine;
+  enabled;
+  constructor(options) {
+    this.provider = options.provider;
+    this.defaultFrom = options.defaultFrom;
+    this.templateEngine = options.templateEngine;
+    this.enabled = options.enabled ?? true;
+  }
+  /**
+  * Send an email message.
+  * Applies defaultFrom if no from address is set.
+  */
+  async send(message) {
+    const msg = {
+      ...message
+    };
+    if (!msg.from && this.defaultFrom) {
+      msg.from = this.defaultFrom;
+    }
+    if (!this.enabled) {
+      log.info(`[dry-run] \u2192 ${formatRecipient(msg.to)} | ${msg.subject}`);
+      return {
+        messageId: "dry-run",
+        accepted: true
+      };
+    }
+    try {
+      const result = await this.provider.send(msg);
+      log.info(`Sent \u2192 ${formatRecipient(msg.to)} | ${msg.subject} [${result.messageId}]`);
+      return result;
+    } catch (err) {
+      log.error({
+        err
+      }, `Failed \u2192 ${formatRecipient(msg.to)} | ${msg.subject}`);
+      throw err;
+    }
+  }
+  /**
+  * Render a template and send the resulting HTML as an email.
+  * Requires a templateEngine to be configured.
+  *
+  * @param template - Template name (resolved by the engine)
+  * @param message - Mail message (html will be overwritten by the rendered template)
+  * @param data - Template variables
+  */
+  async sendTemplate(template, message, data) {
+    if (!this.templateEngine) {
+      throw new Error("MailerService: templateEngine is required for sendTemplate(). Pass one in MailerOptions or use send() with raw HTML.");
+    }
+    const html = await this.templateEngine.render(template, data);
+    return this.send({
+      ...message,
+      html
+    });
+  }
+  /** Get the underlying provider (for advanced use) */
+  getProvider() {
+    return this.provider;
+  }
+  /** Shutdown the provider */
+  async shutdown() {
+    if (this.provider.shutdown) {
+      await this.provider.shutdown();
+    }
+  }
+};
+function formatRecipient(to) {
+  if (Array.isArray(to)) {
+    return to.map((r) => typeof r === "string" ? r : r.address).join(", ");
+  }
+  return typeof to === "string" ? to : to.address;
+}
+__name(formatRecipient, "formatRecipient");
+
+// src/adapter.ts
+import { Logger as Logger2 } from "@forinda/kickjs-core";
+var log2 = Logger2.for("MailerAdapter");
+var MailerAdapter = class {
+  static {
+    __name(this, "MailerAdapter");
+  }
+  options;
+  name = "MailerAdapter";
+  mailer;
+  constructor(options) {
+    this.options = options;
+    this.mailer = new MailerService(options);
+  }
+  afterStart(_server, container) {
+    container.registerInstance(MAILER, this.mailer);
+    log2.info(`Mail provider: ${this.options.provider.name}${this.options.enabled === false ? " (disabled)" : ""}`);
+  }
+  async shutdown() {
+    await this.mailer.shutdown();
+    log2.info("Mailer shut down");
+  }
+};
+
+// src/providers/smtp.provider.ts
+var SmtpProvider = class {
+  static {
+    __name(this, "SmtpProvider");
+  }
+  options;
+  name = "smtp";
+  transporter;
+  constructor(options) {
+    this.options = options;
+  }
+  async ensureTransporter() {
+    if (this.transporter) return;
+    try {
+      const nodemailer = await import("nodemailer");
+      const createTransport = nodemailer.createTransport ?? nodemailer.default?.createTransport;
+      this.transporter = createTransport({
+        host: this.options.host,
+        port: this.options.port ?? 587,
+        secure: this.options.secure ?? this.options.port === 465,
+        auth: this.options.auth,
+        connectionTimeout: this.options.connectionTimeout ?? 1e4
+      });
+    } catch {
+      throw new Error('SmtpProvider requires "nodemailer" package. Install: pnpm add nodemailer');
+    }
+  }
+  async send(message) {
+    await this.ensureTransporter();
+    const result = await this.transporter.sendMail({
+      from: formatAddress(message.from),
+      to: formatRecipients(message.to),
+      cc: message.cc ? formatRecipients(message.cc) : void 0,
+      bcc: message.bcc ? formatRecipients(message.bcc) : void 0,
+      replyTo: message.replyTo ? formatAddress(message.replyTo) : void 0,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+      attachments: message.attachments,
+      headers: message.headers
+    });
+    return {
+      messageId: result.messageId,
+      accepted: (result.accepted?.length ?? 0) > 0,
+      raw: result
+    };
+  }
+  async shutdown() {
+    if (this.transporter) {
+      this.transporter.close();
+    }
+  }
+};
+function formatAddress(addr) {
+  if (!addr) return void 0;
+  if (typeof addr === "string") return addr;
+  return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address;
+}
+__name(formatAddress, "formatAddress");
+function formatRecipients(recipients) {
+  if (!recipients) return "";
+  if (typeof recipients === "string") return recipients;
+  if (Array.isArray(recipients)) {
+    return recipients.map((r) => formatAddress(r)).join(", ");
+  }
+  return formatAddress(recipients) ?? "";
+}
+__name(formatRecipients, "formatRecipients");
+
+// src/providers/console.provider.ts
+import { Logger as Logger3 } from "@forinda/kickjs-core";
+var log3 = Logger3.for("ConsoleMail");
+var counter = 0;
+var ConsoleProvider = class {
+  static {
+    __name(this, "ConsoleProvider");
+  }
+  name = "console";
+  async send(message) {
+    const id = `console-${++counter}`;
+    const to = Array.isArray(message.to) ? message.to.map((r) => typeof r === "string" ? r : r.address).join(", ") : typeof message.to === "string" ? message.to : message.to.address;
+    log3.info(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    log3.info(`From:    ${formatAddr(message.from)}`);
+    log3.info(`To:      ${to}`);
+    if (message.cc) log3.info(`CC:      ${formatAddr(message.cc)}`);
+    if (message.bcc) log3.info(`BCC:     ${formatAddr(message.bcc)}`);
+    log3.info(`Subject: ${message.subject}`);
+    if (message.text) log3.info(`Text:    ${message.text.slice(0, 200)}${message.text.length > 200 ? "..." : ""}`);
+    if (message.html) log3.info(`HTML:    ${message.html.slice(0, 200)}${message.html.length > 200 ? "..." : ""}`);
+    if (message.attachments?.length) {
+      log3.info(`Attach:  ${message.attachments.map((a) => a.filename).join(", ")}`);
+    }
+    log3.info(`ID:      ${id}`);
+    log3.info(`\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    return {
+      messageId: id,
+      accepted: true
+    };
+  }
+};
+function formatAddr(addr) {
+  if (!addr) return "(none)";
+  if (typeof addr === "string") return addr;
+  if (Array.isArray(addr)) return addr.map(formatAddr).join(", ");
+  return addr.name ? `"${addr.name}" <${addr.address}>` : addr.address;
+}
+__name(formatAddr, "formatAddr");
+export {
+  ConsoleProvider,
+  MAILER,
+  MailerAdapter,
+  MailerService,
+  SmtpProvider
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/mailer.service.ts","../src/adapter.ts","../src/providers/smtp.provider.ts","../src/providers/console.provider.ts"],"sourcesContent":["import 'reflect-metadata'\n\n// Types\nexport {\n  type MailProvider,\n  type MailMessage,\n  type MailResult,\n  type MailAddress,\n  type MailRecipient,\n  type MailAttachment,\n  type MailTemplateEngine,\n  type MailerOptions,\n} from './types'\n\n// Service\nexport { MailerService, MAILER } from './mailer.service'\n\n// Adapter\nexport { MailerAdapter } from './adapter'\n\n// Built-in providers\nexport { SmtpProvider, ConsoleProvider, type SmtpOptions } from './providers'\n","import { Logger } from '@forinda/kickjs-core'\nimport type {\n  MailProvider,\n  MailMessage,\n  MailResult,\n  MailRecipient,\n  MailTemplateEngine,\n  MailerOptions,\n} from './types'\n\nconst log = Logger.for('Mailer')\n\n/** DI token for resolving MailerService from the container */\nexport const MAILER = Symbol('MailerService')\n\n/**\n * Central mail service — send emails through any provider.\n *\n * @example\n * ```ts\n * @Service()\n * class UserService {\n *   constructor(@Inject(MAILER) private mailer: MailerService) {}\n *\n *   async sendWelcome(user: User) {\n *     await this.mailer.send({\n *       to: user.email,\n *       subject: 'Welcome!',\n *       html: '<h1>Welcome to our app</h1>',\n *     })\n *   }\n *\n *   // Or with templates:\n *   async sendInvoice(user: User, invoice: Invoice) {\n *     await this.mailer.sendTemplate('invoice', {\n *       to: user.email,\n *       subject: `Invoice #${invoice.number}`,\n *     }, { user, invoice })\n *   }\n * }\n * ```\n */\nexport class MailerService {\n  private provider: MailProvider\n  private defaultFrom?: MailRecipient\n  private templateEngine?: MailTemplateEngine\n  private enabled: boolean\n\n  constructor(options: MailerOptions) {\n    this.provider = options.provider\n    this.defaultFrom = options.defaultFrom\n    this.templateEngine = options.templateEngine\n    this.enabled = options.enabled ?? true\n  }\n\n  /**\n   * Send an email message.\n   * Applies defaultFrom if no from address is set.\n   */\n  async send(message: MailMessage): Promise<MailResult> {\n    const msg = { ...message }\n\n    // Apply default from\n    if (!msg.from && this.defaultFrom) {\n      msg.from = this.defaultFrom\n    }\n\n    if (!this.enabled) {\n      log.info(`[dry-run] → ${formatRecipient(msg.to)} | ${msg.subject}`)\n      return { messageId: 'dry-run', accepted: true }\n    }\n\n    try {\n      const result = await this.provider.send(msg)\n      log.info(`Sent → ${formatRecipient(msg.to)} | ${msg.subject} [${result.messageId}]`)\n      return result\n    } catch (err: any) {\n      log.error({ err }, `Failed → ${formatRecipient(msg.to)} | ${msg.subject}`)\n      throw err\n    }\n  }\n\n  /**\n   * Render a template and send the resulting HTML as an email.\n   * Requires a templateEngine to be configured.\n   *\n   * @param template - Template name (resolved by the engine)\n   * @param message - Mail message (html will be overwritten by the rendered template)\n   * @param data - Template variables\n   */\n  async sendTemplate(\n    template: string,\n    message: Omit<MailMessage, 'html'>,\n    data: Record<string, any>,\n  ): Promise<MailResult> {\n    if (!this.templateEngine) {\n      throw new Error(\n        'MailerService: templateEngine is required for sendTemplate(). ' +\n          'Pass one in MailerOptions or use send() with raw HTML.',\n      )\n    }\n\n    const html = await this.templateEngine.render(template, data)\n    return this.send({ ...message, html })\n  }\n\n  /** Get the underlying provider (for advanced use) */\n  getProvider(): MailProvider {\n    return this.provider\n  }\n\n  /** Shutdown the provider */\n  async shutdown(): Promise<void> {\n    if (this.provider.shutdown) {\n      await this.provider.shutdown()\n    }\n  }\n}\n\nfunction formatRecipient(to: MailRecipient | MailRecipient[]): string {\n  if (Array.isArray(to)) {\n    return to.map((r) => (typeof r === 'string' ? r : r.address)).join(', ')\n  }\n  return typeof to === 'string' ? to : to.address\n}\n","import { Logger, type AppAdapter, type Container } from '@forinda/kickjs-core'\nimport { MailerService, MAILER } from './mailer.service'\nimport type { MailerOptions } from './types'\n\nconst log = Logger.for('MailerAdapter')\n\n/**\n * Mailer adapter — registers MailerService in the DI container.\n *\n * @example\n * ```ts\n * import { MailerAdapter, SmtpProvider } from '@forinda/kickjs-mailer'\n *\n * bootstrap({\n *   adapters: [\n *     new MailerAdapter({\n *       provider: new SmtpProvider({ host: 'smtp.gmail.com', port: 587, auth: { ... } }),\n *       defaultFrom: { name: 'My App', address: 'noreply@myapp.com' },\n *     }),\n *   ],\n * })\n * ```\n */\nexport class MailerAdapter implements AppAdapter {\n  name = 'MailerAdapter'\n  private mailer: MailerService\n\n  constructor(private options: MailerOptions) {\n    this.mailer = new MailerService(options)\n  }\n\n  afterStart(_server: any, container: Container): void {\n    container.registerInstance(MAILER, this.mailer)\n    log.info(\n      `Mail provider: ${this.options.provider.name}${this.options.enabled === false ? ' (disabled)' : ''}`,\n    )\n  }\n\n  async shutdown(): Promise<void> {\n    await this.mailer.shutdown()\n    log.info('Mailer shut down')\n  }\n}\n","import type { MailProvider, MailMessage, MailResult } from '../types'\n\nexport interface SmtpOptions {\n  /** SMTP host (e.g. 'smtp.gmail.com', 'smtp.resend.com') */\n  host: string\n  /** SMTP port (default: 587) */\n  port?: number\n  /** Use TLS (default: true for port 465, false otherwise) */\n  secure?: boolean\n  /** Authentication credentials */\n  auth?: {\n    user: string\n    pass: string\n  }\n  /** Connection timeout in ms (default: 10000) */\n  connectionTimeout?: number\n}\n\n/**\n * SMTP mail provider using nodemailer.\n *\n * Requires `nodemailer` as a peer dependency:\n * ```bash\n * pnpm add nodemailer @types/nodemailer\n * ```\n *\n * @example\n * ```ts\n * // Gmail\n * new SmtpProvider({\n *   host: 'smtp.gmail.com',\n *   port: 587,\n *   auth: { user: 'you@gmail.com', pass: 'app-password' },\n * })\n *\n * // Resend via SMTP\n * new SmtpProvider({\n *   host: 'smtp.resend.com',\n *   port: 465,\n *   secure: true,\n *   auth: { user: 'resend', pass: process.env.RESEND_API_KEY! },\n * })\n *\n * // Mailpit (local dev)\n * new SmtpProvider({ host: 'localhost', port: 1025 })\n * ```\n */\nexport class SmtpProvider implements MailProvider {\n  name = 'smtp'\n  private transporter: any\n\n  constructor(private options: SmtpOptions) {}\n\n  private async ensureTransporter(): Promise<void> {\n    if (this.transporter) return\n    try {\n      const nodemailer: any = await import('nodemailer')\n      const createTransport = nodemailer.createTransport ?? nodemailer.default?.createTransport\n      this.transporter = createTransport({\n        host: this.options.host,\n        port: this.options.port ?? 587,\n        secure: this.options.secure ?? this.options.port === 465,\n        auth: this.options.auth,\n        connectionTimeout: this.options.connectionTimeout ?? 10000,\n      })\n    } catch {\n      throw new Error('SmtpProvider requires \"nodemailer\" package. Install: pnpm add nodemailer')\n    }\n  }\n\n  async send(message: MailMessage): Promise<MailResult> {\n    await this.ensureTransporter()\n\n    const result = await this.transporter.sendMail({\n      from: formatAddress(message.from),\n      to: formatRecipients(message.to),\n      cc: message.cc ? formatRecipients(message.cc) : undefined,\n      bcc: message.bcc ? formatRecipients(message.bcc) : undefined,\n      replyTo: message.replyTo ? formatAddress(message.replyTo) : undefined,\n      subject: message.subject,\n      text: message.text,\n      html: message.html,\n      attachments: message.attachments,\n      headers: message.headers,\n    })\n\n    return {\n      messageId: result.messageId,\n      accepted: (result.accepted?.length ?? 0) > 0,\n      raw: result,\n    }\n  }\n\n  async shutdown(): Promise<void> {\n    if (this.transporter) {\n      this.transporter.close()\n    }\n  }\n}\n\nfunction formatAddress(addr: any): string | undefined {\n  if (!addr) return undefined\n  if (typeof addr === 'string') return addr\n  return addr.name ? `\"${addr.name}\" <${addr.address}>` : addr.address\n}\n\nfunction formatRecipients(recipients: any): string {\n  if (!recipients) return ''\n  if (typeof recipients === 'string') return recipients\n  if (Array.isArray(recipients)) {\n    return recipients.map((r: any) => formatAddress(r)).join(', ')\n  }\n  return formatAddress(recipients) ?? ''\n}\n","import { Logger } from '@forinda/kickjs-core'\nimport type { MailProvider, MailMessage, MailResult } from '../types'\n\nconst log = Logger.for('ConsoleMail')\n\nlet counter = 0\n\n/**\n * Console mail provider — logs emails instead of sending them.\n * Perfect for development and testing.\n *\n * @example\n * ```ts\n * new MailerAdapter({\n *   provider: new ConsoleProvider(),\n *   defaultFrom: 'dev@localhost',\n * })\n * ```\n */\nexport class ConsoleProvider implements MailProvider {\n  name = 'console'\n\n  async send(message: MailMessage): Promise<MailResult> {\n    const id = `console-${++counter}`\n    const to = Array.isArray(message.to)\n      ? message.to.map((r) => (typeof r === 'string' ? r : r.address)).join(', ')\n      : typeof message.to === 'string'\n        ? message.to\n        : message.to.address\n\n    log.info(`────────────────────────────────────────`)\n    log.info(`From:    ${formatAddr(message.from)}`)\n    log.info(`To:      ${to}`)\n    if (message.cc) log.info(`CC:      ${formatAddr(message.cc)}`)\n    if (message.bcc) log.info(`BCC:     ${formatAddr(message.bcc)}`)\n    log.info(`Subject: ${message.subject}`)\n    if (message.text)\n      log.info(`Text:    ${message.text.slice(0, 200)}${message.text.length > 200 ? '...' : ''}`)\n    if (message.html)\n      log.info(`HTML:    ${message.html.slice(0, 200)}${message.html.length > 200 ? '...' : ''}`)\n    if (message.attachments?.length) {\n      log.info(`Attach:  ${message.attachments.map((a) => a.filename).join(', ')}`)\n    }\n    log.info(`ID:      ${id}`)\n    log.info(`────────────────────────────────────────`)\n\n    return { messageId: id, accepted: true }\n  }\n}\n\nfunction formatAddr(addr: any): string {\n  if (!addr) return '(none)'\n  if (typeof addr === 'string') return addr\n  if (Array.isArray(addr)) return addr.map(formatAddr).join(', ')\n  return addr.name ? `\"${addr.name}\" <${addr.address}>` : addr.address\n}\n"],"mappings":"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","names":["Logger","log","Logger","for","MAILER","Symbol","MailerService","provider","defaultFrom","templateEngine","enabled","options","send","message","msg","from","info","formatRecipient","to","subject","messageId","accepted","result","err","error","sendTemplate","template","data","Error","html","render","getProvider","shutdown","Array","isArray","map","r","address","join","Logger","log","Logger","for","MailerAdapter","name","mailer","options","MailerService","afterStart","_server","container","registerInstance","MAILER","info","provider","enabled","shutdown","SmtpProvider","name","transporter","options","ensureTransporter","nodemailer","createTransport","default","host","port","secure","auth","connectionTimeout","Error","send","message","result","sendMail","from","formatAddress","to","formatRecipients","cc","undefined","bcc","replyTo","subject","text","html","attachments","headers","messageId","accepted","length","raw","shutdown","close","addr","address","recipients","Array","isArray","map","r","join","Logger","log","Logger","for","counter","ConsoleProvider","name","send","message","id","to","Array","isArray","map","r","address","join","info","formatAddr","from","cc","bcc","subject","text","slice","length","html","attachments","a","filename","messageId","accepted","addr"]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@forinda/kickjs-mailer",
+  "version": "1.1.0",
+  "description": "Pluggable email sending for KickJS — nodemailer, Resend, SES, and custom providers",
+  "keywords": [
+    "kickjs",
+    "mailer",
+    "email",
+    "nodemailer",
+    "resend",
+    "ses",
+    "smtp",
+    "templates",
+    "typescript",
+    "adapter"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "@forinda/kickjs-core": "1.1.0"
+  },
+  "peerDependencies": {
+    "nodemailer": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "nodemailer": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@types/nodemailer": "^6.4.17",
+    "nodemailer": "^6.10.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Felix Orinda",
+  "engines": {
+    "node": ">=20.0"
+  },
+  "homepage": "https://forinda.github.io/kick-js/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forinda/kick-js.git",
+    "directory": "packages/mailer"
+  },
+  "bugs": {
+    "url": "https://github.com/forinda/kick-js/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}