@wild-framework/mail-smtp 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wild Framework contributors
+
+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/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @wild-framework/mail-smtp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SMTP mail driver for [Wild Framework](https://github.com/KhandaSoftware/wild-framework)'s mail package, backed by [nodemailer](https://nodemailer.com/).
+
+## Install
+
+```bash
+pnpm add @wild-framework/mail-smtp
+```
+
+## Usage
+
+```ts
+import { SmtpMailProvider } from "@wild-framework/mail-smtp";
+
+SmtpMailProvider.host = process.env.SMTP_HOST;
+SmtpMailProvider.port = Number(process.env.SMTP_PORT ?? 587);
+SmtpMailProvider.user = process.env.SMTP_USER;
+SmtpMailProvider.pass = process.env.SMTP_PASS;
+SmtpMailProvider.from = process.env.MAIL_FROM;
+
+app.register(SmtpMailProvider);
+// … mail is now SMTP-backed, resolved via app.resolve(Mail)
+```
+
+Works with any SMTP server — Postmark, Resend, SendGrid, SES, Mailgun, self-hosted — or Mailpit/MailHog for local development.
+
+## Integration test
+
+Point it at Mailpit and assert delivery via its HTTP API:
+
+```bash
+SMTP_HOST=localhost SMTP_PORT=1025 MAILPIT_URL=http://localhost:8025 \
+  pnpm --filter @wild-framework/mail-smtp test
+```
+
+Skips automatically when `SMTP_HOST` is not set.
+
+## License
+
+MIT

package/dist/driver.d.ts

@@ -0,0 +1,37 @@
+import type { MailDriver, MailMessage } from "@wild-framework/mail";
+import { type Transporter } from "nodemailer";
+/**
+ * Configuration for the SMTP mail driver.
+ */
+export interface SmtpMailConfig {
+    /** SMTP server host, e.g. `smtp.resend.com` or `localhost` (Mailpit). */
+    host: string;
+    /** SMTP server port. Defaults to `587` (or `465` when `secure` is true). */
+    port?: number;
+    /** Use TLS. Set `true` for port 465 (implicit TLS). */
+    secure?: boolean;
+    /** SMTP username. */
+    user?: string;
+    /** SMTP password. */
+    pass?: string;
+    /** Default `from` address when the message omits one. */
+    from?: string;
+    /** A pre-built transporter — for advanced use or tests. */
+    transporter?: Transporter;
+}
+/**
+ * SMTP mail driver implementing `MailDriver`.
+ *
+ * Backed by `nodemailer`. Works with any SMTP server — Postmark, Resend,
+ * SendGrid, SES, Mailgun, self-hosted, or Mailpit/MailHog for local testing.
+ */
+export declare class SmtpMailDriver implements MailDriver {
+    private config;
+    private transporter;
+    constructor(config: SmtpMailConfig);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    send(message: MailMessage): Promise<void>;
+    private requireTransporter;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAmB,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,WAAW,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,UAAU;IAGjC,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,WAAW,CAA4B;gBAE3B,MAAM,EAAE,cAAc;IAMpC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQtB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C,OAAO,CAAC,kBAAkB;CAgB7B"}

package/dist/driver.js

@@ -0,0 +1,54 @@
+import nodemailer, {} from "nodemailer";
+/**
+ * SMTP mail driver implementing `MailDriver`.
+ *
+ * Backed by `nodemailer`. Works with any SMTP server — Postmark, Resend,
+ * SendGrid, SES, Mailgun, self-hosted, or Mailpit/MailHog for local testing.
+ */
+export class SmtpMailDriver {
+    config;
+    transporter = null;
+    constructor(config) {
+        this.config = config;
+        if (!config.host && !config.transporter) {
+            throw new Error("SmtpMailDriver requires a host (or an injected transporter).");
+        }
+    }
+    async connect() {
+        this.requireTransporter(); // materialise so config errors surface at boot
+    }
+    async close() {
+        // Only close transporters we created — an injected one is the caller's.
+        if (this.transporter && !this.config.transporter) {
+            this.transporter.close();
+        }
+        this.transporter = null;
+    }
+    async send(message) {
+        await this.requireTransporter().sendMail({
+            from: message.from ?? this.config.from,
+            to: message.to,
+            cc: message.cc,
+            bcc: message.bcc,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+        });
+    }
+    requireTransporter() {
+        if (!this.transporter) {
+            this.transporter =
+                this.config.transporter ??
+                    nodemailer.createTransport({
+                        host: this.config.host,
+                        port: this.config.port ?? (this.config.secure ? 465 : 587),
+                        secure: this.config.secure ?? false,
+                        auth: this.config.user || this.config.pass
+                            ? { user: this.config.user, pass: this.config.pass }
+                            : undefined,
+                    });
+        }
+        return this.transporter;
+    }
+}
+//# sourceMappingURL=driver.js.map

package/dist/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AACA,OAAO,UAAU,EAAE,EAAoB,MAAM,YAAY,CAAC;AAsB1D;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IAGH;IAFZ,WAAW,GAAuB,IAAI,CAAC;IAE/C,YAAoB,MAAsB;QAAtB,WAAM,GAAN,MAAM,CAAgB;QACtC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;QACpF,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO;QACT,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC,+CAA+C;IAC9E,CAAC;IAED,KAAK,CAAC,KAAK;QACP,wEAAwE;QACxE,IAAI,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAC/C,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QAC7B,CAAC;QACD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,OAAoB;QAC3B,MAAM,IAAI,CAAC,kBAAkB,EAAE,CAAC,QAAQ,CAAC;YACrC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI;YACtC,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,IAAI,EAAE,OAAO,CAAC,IAAI;SACrB,CAAC,CAAC;IACP,CAAC;IAEO,kBAAkB;QACtB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACpB,IAAI,CAAC,WAAW;gBACZ,IAAI,CAAC,MAAM,CAAC,WAAW;oBACvB,UAAU,CAAC,eAAe,CAAC;wBACvB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;wBACtB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;wBAC1D,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,KAAK;wBACnC,IAAI,EACA,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI;4BAChC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;4BACpD,CAAC,CAAC,SAAS;qBACtB,CAAC,CAAC;QACX,CAAC;QACD,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { SmtpMailDriver } from "./driver.js";
+export type { SmtpMailConfig } from "./driver.js";
+export { SmtpMailProvider } from "./provider.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,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SmtpMailDriver } from "./driver.js";
+export { SmtpMailProvider } from "./provider.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,36 @@
+import type { Provider, Application } from "@wild-framework/core";
+/**
+ * Registers an SMTP-backed mail system with the application.
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * SmtpMailProvider.host = process.env.SMTP_HOST!;
+ * SmtpMailProvider.port = Number(process.env.SMTP_PORT ?? 587);
+ * SmtpMailProvider.user = process.env.SMTP_USER;
+ * SmtpMailProvider.pass = process.env.SMTP_PASS;
+ * SmtpMailProvider.from = process.env.MAIL_FROM;
+ * ```
+ *
+ * Materialises the transporter on boot (fail-fast on bad config) and closes
+ * it on shutdown.
+ */
+export declare class SmtpMailProvider implements Provider {
+    /** SMTP host. */
+    static host: string | undefined;
+    /** SMTP port. Defaults to 587 (465 when secure). */
+    static port: number | undefined;
+    /** Use implicit TLS (port 465). */
+    static secure: boolean;
+    /** SMTP username. */
+    static user: string | undefined;
+    /** SMTP password. */
+    static pass: string | undefined;
+    /** Default from address. */
+    static from: string | undefined;
+    private driver;
+    register(app: Application): void;
+    boot(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAKlE;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC7C,iBAAiB;IACjB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,oDAAoD;IACpD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,mCAAmC;IACnC,MAAM,CAAC,MAAM,UAAS;IACtB,qBAAqB;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,qBAAqB;IACrB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4BAA4B;IAC5B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAEhC,OAAO,CAAC,MAAM,CAA6B;IAE3C,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAgB1B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

package/dist/provider.js

@@ -0,0 +1,54 @@
+import { Container } from "@wild-framework/container";
+import { Mail } from "@wild-framework/mail";
+import { SmtpMailDriver } from "./driver.js";
+/**
+ * Registers an SMTP-backed mail system with the application.
+ *
+ * Static configuration (no-arg constructor requirement):
+ *
+ * ```ts
+ * SmtpMailProvider.host = process.env.SMTP_HOST!;
+ * SmtpMailProvider.port = Number(process.env.SMTP_PORT ?? 587);
+ * SmtpMailProvider.user = process.env.SMTP_USER;
+ * SmtpMailProvider.pass = process.env.SMTP_PASS;
+ * SmtpMailProvider.from = process.env.MAIL_FROM;
+ * ```
+ *
+ * Materialises the transporter on boot (fail-fast on bad config) and closes
+ * it on shutdown.
+ */
+export class SmtpMailProvider {
+    /** SMTP host. */
+    static host;
+    /** SMTP port. Defaults to 587 (465 when secure). */
+    static port;
+    /** Use implicit TLS (port 465). */
+    static secure = false;
+    /** SMTP username. */
+    static user;
+    /** SMTP password. */
+    static pass;
+    /** Default from address. */
+    static from;
+    driver;
+    register(app) {
+        const container = app.resolve(Container);
+        const driver = new SmtpMailDriver({
+            host: SmtpMailProvider.host ?? "",
+            port: SmtpMailProvider.port,
+            secure: SmtpMailProvider.secure,
+            user: SmtpMailProvider.user,
+            pass: SmtpMailProvider.pass,
+            from: SmtpMailProvider.from,
+        });
+        this.driver = driver;
+        container.singleton(Mail, () => new Mail(driver));
+    }
+    async boot() {
+        await this.driver?.connect();
+    }
+    async shutdown() {
+        await this.driver?.close();
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,gBAAgB;IACzB,iBAAiB;IACjB,MAAM,CAAC,IAAI,CAAqB;IAChC,oDAAoD;IACpD,MAAM,CAAC,IAAI,CAAqB;IAChC,mCAAmC;IACnC,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,qBAAqB;IACrB,MAAM,CAAC,IAAI,CAAqB;IAChC,qBAAqB;IACrB,MAAM,CAAC,IAAI,CAAqB;IAChC,4BAA4B;IAC5B,MAAM,CAAC,IAAI,CAAqB;IAExB,MAAM,CAA6B;IAE3C,QAAQ,CAAC,GAAgB;QACrB,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAEzC,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;YAC9B,IAAI,EAAE,gBAAgB,CAAC,IAAI,IAAI,EAAE;YACjC,IAAI,EAAE,gBAAgB,CAAC,IAAI;YAC3B,MAAM,EAAE,gBAAgB,CAAC,MAAM;YAC/B,IAAI,EAAE,gBAAgB,CAAC,IAAI;YAC3B,IAAI,EAAE,gBAAgB,CAAC,IAAI;YAC3B,IAAI,EAAE,gBAAgB,CAAC,IAAI;SAC9B,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,SAAS,CAAC,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,IAAI;QACN,MAAM,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,QAAQ;QACV,MAAM,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC"}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@wild-framework/mail-smtp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.2",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Sphah",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Khandasoftware/wild-framework.git"
+  },
+  "description": "SMTP mail driver for Wild Framework's mail package (nodemailer).",
+  "keywords": [
+    "wild",
+    "framework",
+    "mail",
+    "email",
+    "smtp",
+    "nodemailer"
+  ],
+  "dependencies": {
+    "nodemailer": "^6.9.0",
+    "@wild-framework/core": "0.2.2",
+    "@wild-framework/container": "0.2.2",
+    "@wild-framework/mail": "0.2.2"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^6.4.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
 }