@beignet/provider-mail-smtp 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-mail-smtp
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,95 @@
+# @beignet/provider-mail-smtp
+
+SMTP-backed mail provider for Beignet, implemented with Nodemailer.
+
+The provider installs the app-facing `ctx.ports.mailer` port and exposes
+`ctx.ports.smtp.transporter` only as an escape hatch for Nodemailer-specific
+features.
+
+## Install
+
+```bash
+bun add @beignet/provider-mail-smtp nodemailer
+```
+
+## Setup
+
+```typescript
+import { mailSmtpProvider } from "@beignet/provider-mail-smtp";
+import { createServer } from "@beignet/core/server";
+
+const server = await createServer({
+  ports: basePorts,
+  providers: [mailSmtpProvider],
+  createContext: ({ ports }) => ({ ports }),
+  routes,
+});
+```
+
+Required environment variables:
+
+| Variable | Description |
+| --- | --- |
+| `MAIL_HOST` | SMTP server hostname |
+| `MAIL_PORT` | SMTP server port. Port `465` uses SSL. |
+| `MAIL_USER` | SMTP username |
+| `MAIL_PASS` | SMTP password |
+| `MAIL_FROM` | Default sender address |
+
+## Use in application code
+
+```typescript
+await ctx.ports.mailer.send({
+  to: "user@example.com",
+  subject: "Welcome",
+  text: "Thanks for joining.",
+});
+```
+
+The same `MailerPort` works with Resend, memory fakes, and other adapters:
+
+```typescript
+await ctx.ports.mailer.send({
+  from: { email: "support@example.com", name: "Support" },
+  to: ["user@example.com", "admin@example.com"],
+  cc: "audit@example.com",
+  replyTo: "support@example.com",
+  subject: "Account updated",
+  text: "Your account was updated.",
+  html: "<p>Your account was updated.</p>",
+});
+```
+
+## Escape hatch
+
+Use the Nodemailer transporter only when you need an SMTP-specific feature not
+covered by `MailerPort`:
+
+```typescript
+await ctx.ports.smtp.transporter.sendMail({
+  from: "sender@example.com",
+  to: "user@example.com",
+  subject: "Invoice",
+  text: "Attached.",
+  attachments: [
+    {
+      filename: "invoice.pdf",
+      path: "/path/to/invoice.pdf",
+    },
+  ],
+});
+```
+
+## Devtools
+
+When `ctx.ports.devtools` is installed, this provider records `mail.send`,
+`mail.sent`, and `mail.failed` events under the `mail` watcher.
+
+## Errors
+
+Delivery failures throw `MailDeliveryError` from `@beignet/core/mail`.
+Startup configuration and connection problems throw during provider setup.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @beignet/provider-mail-smtp
+ *
+ * SMTP-backed mail provider for Beignet.
+ */
+import { type MailAddress, type MailerPort } from "@beignet/core/mail";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import type { Transporter } from "nodemailer";
+import { z } from "zod";
+declare const MailConfigSchema: z.ZodObject<{
+    HOST: z.ZodString;
+    PORT: z.ZodCoercedNumber<unknown>;
+    USER: z.ZodString;
+    PASS: z.ZodString;
+    FROM: z.ZodString;
+}, z.core.$strip>;
+export type MailConfig = z.infer<typeof MailConfigSchema>;
+export interface SmtpMailEscapeHatch {
+    transporter: Transporter;
+}
+export interface SmtpMailProviderPorts {
+    mailer: MailerPort;
+    smtp: SmtpMailEscapeHatch;
+}
+export interface CreateSmtpMailerOptions {
+    transporter: Transporter;
+    from: MailAddress;
+    instrumentation?: ProviderInstrumentationTarget;
+}
+export declare function createSmtpMailer({ transporter, from, instrumentation: instrumentationTarget, }: CreateSmtpMailerOptions): MailerPort;
+export declare const mailSmtpProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    HOST: z.ZodString;
+    PORT: z.ZodCoercedNumber<unknown>;
+    USER: z.ZodString;
+    PASS: z.ZodString;
+    FROM: z.ZodString;
+}, z.core.$strip>, {
+    mailer: MailerPort;
+    smtp: {
+        transporter: Transporter<import("nodemailer/lib/smtp-transport").SentMessageInfo, import("nodemailer/lib/smtp-transport").Options>;
+    };
+}>;
+export {};
+//# 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;;;;GAIG;AAEH,OAAO,EAGL,KAAK,WAAW,EAEhB,KAAK,UAAU,EAIhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGL,KAAK,6BAA6B,EACnC,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAEV,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,gBAAgB;;;;;;iBAMpB,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAoDD,wBAAgB,gBAAgB,CAAC,EAC/B,WAAW,EACX,IAAI,EACJ,eAAe,EAAE,qBAAqB,GACvC,EAAE,uBAAuB,GAAG,UAAU,CAqEtC;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;EAwD3B,CAAC"}

package/dist/index.js

@@ -0,0 +1,154 @@
+/**
+ * @beignet/provider-mail-smtp
+ *
+ * SMTP-backed mail provider for Beignet.
+ */
+import { formatMailAddress, formatMailAddressList, MailDeliveryError, normalizeMailMessage, } from "@beignet/core/mail";
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import nodemailer from "nodemailer";
+import { z } from "zod";
+const MailConfigSchema = z.object({
+    HOST: z.string(),
+    PORT: z.coerce.number().int().positive(),
+    USER: z.string(),
+    PASS: z.string(),
+    FROM: z.string().min(1),
+});
+function addOptional(target, key, value) {
+    if (value !== undefined) {
+        Object.assign(target, { [key]: value });
+    }
+}
+function createSmtpPayload(message, defaultFrom) {
+    const normalized = normalizeMailMessage(message, { defaultFrom });
+    if (!normalized.from) {
+        throw new MailDeliveryError({
+            provider: "smtp",
+            message: "Cannot send email without a from address.",
+        });
+    }
+    const payload = {
+        from: formatMailAddress(normalized.from),
+        to: formatMailAddressList(normalized.to),
+        subject: normalized.subject,
+    };
+    addOptional(payload, "text", normalized.text);
+    addOptional(payload, "html", normalized.html);
+    addOptional(payload, "cc", normalized.cc ? formatMailAddressList(normalized.cc) : undefined);
+    addOptional(payload, "bcc", normalized.bcc ? formatMailAddressList(normalized.bcc) : undefined);
+    addOptional(payload, "replyTo", normalized.replyTo ? formatMailAddressList(normalized.replyTo) : undefined);
+    addOptional(payload, "headers", normalized.headers);
+    return payload;
+}
+export function createSmtpMailer({ transporter, from, instrumentation: instrumentationTarget, }) {
+    const instrumentation = createProviderInstrumentation(instrumentationTarget, {
+        providerName: "mail-smtp",
+        watcher: "mail",
+    });
+    return {
+        async send(message) {
+            const payload = createSmtpPayload(message, from);
+            instrumentation.custom({
+                name: "mail.send",
+                label: "Mail send",
+                summary: `Sending "${message.subject}"`,
+                details: {
+                    provider: "smtp",
+                    subject: message.subject,
+                    to: payload.to,
+                },
+            });
+            try {
+                const result = await transporter.sendMail(payload);
+                const id = typeof result === "object" &&
+                    result !== null &&
+                    "messageId" in result &&
+                    typeof result.messageId === "string"
+                    ? result.messageId
+                    : undefined;
+                instrumentation.custom({
+                    name: "mail.sent",
+                    label: "Mail sent",
+                    summary: `Sent "${message.subject}"`,
+                    details: {
+                        provider: "smtp",
+                        subject: message.subject,
+                        to: payload.to,
+                        id,
+                    },
+                });
+                return {
+                    id,
+                    provider: "smtp",
+                };
+            }
+            catch (error) {
+                instrumentation.custom({
+                    name: "mail.failed",
+                    label: "Mail failed",
+                    summary: `Failed to send "${message.subject}"`,
+                    details: {
+                        provider: "smtp",
+                        subject: message.subject,
+                        to: payload.to,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                });
+                throw new MailDeliveryError({
+                    provider: "smtp",
+                    message: error instanceof Error
+                        ? error.message
+                        : "SMTP failed to send email.",
+                    cause: error,
+                });
+            }
+        },
+    };
+}
+export const mailSmtpProvider = createProvider({
+    name: "mail-smtp",
+    config: {
+        schema: MailConfigSchema,
+        envPrefix: "MAIL_",
+    },
+    async setup({ config, ports }) {
+        if (!config) {
+            throw new Error("[mailSmtpProvider] Missing Mail config. " +
+                "Please set MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, and MAIL_FROM environment variables.");
+        }
+        const transporter = nodemailer.createTransport({
+            host: config.HOST,
+            port: config.PORT,
+            secure: config.PORT === 465,
+            auth: {
+                user: config.USER,
+                pass: config.PASS,
+            },
+        });
+        try {
+            await transporter.verify();
+        }
+        catch (error) {
+            throw new Error(`[mailSmtpProvider] Failed to connect to mail server at ${config.HOST}:${config.PORT}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const instrumentation = createProviderInstrumentation(ports, {
+            providerName: "mail-smtp",
+            watcher: "mail",
+        });
+        const mailer = createSmtpMailer({
+            transporter,
+            from: config.FROM,
+            instrumentation,
+        });
+        return {
+            ports: {
+                mailer,
+                smtp: { transporter },
+            },
+            stop() {
+                transporter.close();
+            },
+        };
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@beignet/provider-mail-smtp",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "SMTP mail provider for Beignet - adds mailer port using nodemailer",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "mail",
+    "email",
+    "provider",
+    "smtp",
+    "nodemailer",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-mail-smtp"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "nodemailer": "^7.0.7"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "@types/nodemailer": "^6.4.0",
+    "nodemailer": "^7.0.7",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,235 @@
+/**
+ * @beignet/provider-mail-smtp
+ *
+ * SMTP-backed mail provider for Beignet.
+ */
+
+import {
+  formatMailAddress,
+  formatMailAddressList,
+  type MailAddress,
+  MailDeliveryError,
+  type MailerPort,
+  normalizeMailMessage,
+  type SendMailOptions,
+  type SendMailResult,
+} from "@beignet/core/mail";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+import type {
+  SendMailOptions as NodemailerSendMailOptions,
+  Transporter,
+} from "nodemailer";
+import nodemailer from "nodemailer";
+import { z } from "zod";
+
+const MailConfigSchema = z.object({
+  HOST: z.string(),
+  PORT: z.coerce.number().int().positive(),
+  USER: z.string(),
+  PASS: z.string(),
+  FROM: z.string().min(1),
+});
+
+export type MailConfig = z.infer<typeof MailConfigSchema>;
+
+export interface SmtpMailEscapeHatch {
+  transporter: Transporter;
+}
+
+export interface SmtpMailProviderPorts {
+  mailer: MailerPort;
+  smtp: SmtpMailEscapeHatch;
+}
+
+export interface CreateSmtpMailerOptions {
+  transporter: Transporter;
+  from: MailAddress;
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+function addOptional<
+  T extends Record<string, unknown>,
+  K extends keyof NodemailerSendMailOptions,
+>(target: T, key: K, value: NodemailerSendMailOptions[K] | undefined): void {
+  if (value !== undefined) {
+    Object.assign(target, { [key]: value });
+  }
+}
+
+function createSmtpPayload(
+  message: SendMailOptions,
+  defaultFrom: MailAddress,
+): NodemailerSendMailOptions {
+  const normalized = normalizeMailMessage(message, { defaultFrom });
+
+  if (!normalized.from) {
+    throw new MailDeliveryError({
+      provider: "smtp",
+      message: "Cannot send email without a from address.",
+    });
+  }
+
+  const payload = {
+    from: formatMailAddress(normalized.from),
+    to: formatMailAddressList(normalized.to),
+    subject: normalized.subject,
+  } satisfies NodemailerSendMailOptions;
+
+  addOptional(payload, "text", normalized.text);
+  addOptional(payload, "html", normalized.html);
+  addOptional(
+    payload,
+    "cc",
+    normalized.cc ? formatMailAddressList(normalized.cc) : undefined,
+  );
+  addOptional(
+    payload,
+    "bcc",
+    normalized.bcc ? formatMailAddressList(normalized.bcc) : undefined,
+  );
+  addOptional(
+    payload,
+    "replyTo",
+    normalized.replyTo ? formatMailAddressList(normalized.replyTo) : undefined,
+  );
+  addOptional(payload, "headers", normalized.headers);
+
+  return payload;
+}
+
+export function createSmtpMailer({
+  transporter,
+  from,
+  instrumentation: instrumentationTarget,
+}: CreateSmtpMailerOptions): MailerPort {
+  const instrumentation = createProviderInstrumentation(instrumentationTarget, {
+    providerName: "mail-smtp",
+    watcher: "mail",
+  });
+
+  return {
+    async send(message): Promise<SendMailResult> {
+      const payload = createSmtpPayload(message, from);
+      instrumentation.custom({
+        name: "mail.send",
+        label: "Mail send",
+        summary: `Sending "${message.subject}"`,
+        details: {
+          provider: "smtp",
+          subject: message.subject,
+          to: payload.to,
+        },
+      });
+
+      try {
+        const result = await transporter.sendMail(payload);
+        const id =
+          typeof result === "object" &&
+          result !== null &&
+          "messageId" in result &&
+          typeof result.messageId === "string"
+            ? result.messageId
+            : undefined;
+
+        instrumentation.custom({
+          name: "mail.sent",
+          label: "Mail sent",
+          summary: `Sent "${message.subject}"`,
+          details: {
+            provider: "smtp",
+            subject: message.subject,
+            to: payload.to,
+            id,
+          },
+        });
+
+        return {
+          id,
+          provider: "smtp",
+        };
+      } catch (error) {
+        instrumentation.custom({
+          name: "mail.failed",
+          label: "Mail failed",
+          summary: `Failed to send "${message.subject}"`,
+          details: {
+            provider: "smtp",
+            subject: message.subject,
+            to: payload.to,
+            error: error instanceof Error ? error.message : String(error),
+          },
+        });
+        throw new MailDeliveryError({
+          provider: "smtp",
+          message:
+            error instanceof Error
+              ? error.message
+              : "SMTP failed to send email.",
+          cause: error,
+        });
+      }
+    },
+  };
+}
+
+export const mailSmtpProvider = createProvider({
+  name: "mail-smtp",
+
+  config: {
+    schema: MailConfigSchema,
+    envPrefix: "MAIL_",
+  },
+
+  async setup({ config, ports }) {
+    if (!config) {
+      throw new Error(
+        "[mailSmtpProvider] Missing Mail config. " +
+          "Please set MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, and MAIL_FROM environment variables.",
+      );
+    }
+
+    const transporter = nodemailer.createTransport({
+      host: config.HOST,
+      port: config.PORT,
+      secure: config.PORT === 465,
+      auth: {
+        user: config.USER,
+        pass: config.PASS,
+      },
+    });
+
+    try {
+      await transporter.verify();
+    } catch (error) {
+      throw new Error(
+        `[mailSmtpProvider] Failed to connect to mail server at ${config.HOST}:${config.PORT}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+
+    const instrumentation = createProviderInstrumentation(ports, {
+      providerName: "mail-smtp",
+      watcher: "mail",
+    });
+    const mailer = createSmtpMailer({
+      transporter,
+      from: config.FROM,
+      instrumentation,
+    });
+
+    return {
+      ports: {
+        mailer,
+        smtp: { transporter },
+      } satisfies SmtpMailProviderPorts,
+      stop() {
+        transporter.close();
+      },
+    };
+  },
+});