@beignet/provider-mail-smtp 0.0.30 → 0.0.32

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @beignet/provider-mail-smtp
 
+## 0.0.32
+
+### Patch Changes
+
+- f759611: Provider factory options now resolve through one framework-owned rule:
+  `ProviderConfigDef` gains an `overrides` map that merges defined values over
+  env-derived input before validation, and every first-party provider factory
+  uses it instead of hand-rolled schema defaults and setup-time fallbacks. The
+  precedence is now uniform — defined factory options win over environment
+  variables in all thirteen providers. This flips the previous env-wins
+  behavior of `provider-cache-redis`, `provider-locks-redis`, and the storage,
+  search, and blob providers; set the env var (or drop the option) if you
+  relied on env winning. `installProviderForTest(...)` gains an `env` option
+  that resolves config through the same loader, and unreachable missing-config
+  guards in the pino and inngest factories are gone.
+- eb680ef: Provider naming now follows one implementation-first order matching the
+  factories. `@beignet/provider-redis` is renamed `@beignet/provider-cache-redis`
+  (the package fills the cache port; the raw client stays as the
+  `ctx.ports.redis` escape hatch) with `redisCacheProvider`,
+  `createRedisCacheProvider`, and provider name `cache-redis` matching
+  `locks-redis`. Default consts flip to implementation-first:
+  `loggerPinoProvider` is now `pinoLoggerProvider`, `mailResendProvider` is now
+  `resendMailProvider`, and `mailSmtpProvider` is now `smtpMailProvider`.
+  CLI starter templates and the `redis-cache` provider preset wire the new
+  names. No aliases are kept.
+- 671b986: Every provider package now exposes a `createXProvider(options)` factory, so
+  env-only configuration is a convenience rather than the only path. New
+  factories: `createPinoLoggerProvider`, `createResendMailProvider`,
+  `createSmtpMailProvider`, `createStripePaymentsProvider`,
+  `createUpstashRateLimitProvider`, and `createInngestJobsProvider`. Options
+  mirror each provider's env config fields and override env-derived values; the
+  default consts keep their behavior and now simply call their factory. (The
+  consts themselves are renamed to implementation-first order —
+  `pinoLoggerProvider`, `resendMailProvider`, `smtpMailProvider` — in this
+  release's provider naming normalization; `stripePaymentsProvider`,
+  `upstashRateLimitProvider`, and `inngestJobsProvider` already followed it.)
+- f759611: Provider resilience baseline. The S3 storage provider now surfaces the AWS
+  SDK's built-in retry configuration: pass `maxAttempts` and `retryMode`
+  (`"standard"` or `"adaptive"`) as provider options or set
+  `STORAGE_S3_MAX_ATTEMPTS` and `STORAGE_S3_RETRY_MODE` env vars; the SDK
+  default stays `standard` mode with 3 attempts. Mail providers deliberately do
+  not retry — mail delivery is not idempotent — and now throw `MailDeliveryError`
+  messages that include the provider name and recipient count while preserving
+  the original vendor error as `cause`; dispatch mail from jobs or the outbox
+  when retries are needed.
+
+## 0.0.31
+
 ## 0.0.30
 
 ### Patch Changes

package/README.md

@@ -19,12 +19,12 @@ bun add @beignet/provider-mail-smtp @beignet/core nodemailer
 ## Setup
 
 ```typescript
-import { mailSmtpProvider } from "@beignet/provider-mail-smtp";
+import { smtpMailProvider } from "@beignet/provider-mail-smtp";
 import { createServer } from "@beignet/core/server";
 
 const server = await createServer({
   ports: basePorts,
-  providers: [mailSmtpProvider],
+  providers: [smtpMailProvider],
   context: ({ ports }) => ({ ports }),
   routes,
 });
@@ -44,6 +44,26 @@ Required environment variables:
 registered in `server/providers.ts` and that all required `MAIL_*` env vars are
 present in app env examples or config.
 
+Use `createSmtpMailProvider(...)` when you want to pass config directly
+instead of reading `MAIL_*` env vars. Options override env-derived values:
+
+```typescript
+import { createSmtpMailProvider } from "@beignet/provider-mail-smtp";
+
+export const providers = [
+  createSmtpMailProvider({
+    host: "smtp.example.com",
+    port: 465,
+    user: secrets.smtpUser,
+    pass: secrets.smtpPass,
+    from: "My App <no-reply@example.com>",
+  }),
+];
+```
+
+`smtpMailProvider` is the default env-backed provider, equivalent to
+`createSmtpMailProvider()`.
+
 ## Use in application code
 
 ```typescript
@@ -99,10 +119,24 @@ await ctx.ports.smtp.transporter.sendMail({
 When `ctx.ports.devtools` is installed, this provider records `mail.send`,
 `mail.sent`, and `mail.failed` events under the `mail` watcher.
 
-## Errors
+## Failure and retry semantics
+
+The provider fails fast and does not retry. Mail delivery is not idempotent: a
+timed-out send may still have been delivered, so a blind provider retry risks
+duplicate emails.
+
+Delivery failures throw `MailDeliveryError` from `@beignet/core/mail` with the
+provider name, the recipient count, and the original SMTP error preserved as
+`cause`. Message bodies and credentials are never included.
+
+The provider calls `transporter.verify()` during setup, so an unreachable SMTP
+server or rejected credentials fail server startup immediately instead of
+failing the first send. Startup configuration problems also throw during
+provider setup.
 
-Delivery failures throw `MailDeliveryError` from `@beignet/core/mail`.
-Startup configuration and connection problems throw during provider setup.
+When mail needs retries, dispatch it from a job or an outbox-backed listener
+and own idempotency there, for example by recording one delivery per business
+event before sending.
 
 ## Local and tests
 

package/dist/index.d.ts

@@ -28,7 +28,7 @@ export interface SmtpMailEscapeHatch {
     transporter: Transporter;
 }
 /**
- * Ports contributed by `mailSmtpProvider`.
+ * Ports contributed by `smtpMailProvider`.
  */
 export interface SmtpMailProviderPorts {
     /**
@@ -60,18 +60,60 @@ export interface CreateSmtpMailerOptions {
 /**
  * Create a Beignet mailer port backed by Nodemailer SMTP.
  *
- * Use this directly for custom wiring, or install `mailSmtpProvider` to load
+ * Use this directly for custom wiring, or install `smtpMailProvider` to load
  * config from env and contribute ports during server startup.
  */
 export declare function createSmtpMailer({ transporter, from, instrumentation: instrumentationTarget, }: CreateSmtpMailerOptions): MailerPort;
 /**
- * Env-backed SMTP mail provider.
+ * Options for the SMTP mail provider factory.
+ */
+export interface CreateSmtpMailProviderOptions {
+    /**
+     * SMTP server hostname. Overrides `MAIL_HOST`.
+     */
+    host?: string;
+    /**
+     * SMTP server port. Port 465 uses SSL. Overrides `MAIL_PORT`.
+     */
+    port?: number;
+    /**
+     * SMTP username. Overrides `MAIL_USER`.
+     */
+    user?: string;
+    /**
+     * SMTP password. Overrides `MAIL_PASS`.
+     */
+    pass?: string;
+    /**
+     * Default sender address. Overrides `MAIL_FROM`.
+     */
+    from?: string;
+}
+/**
+ * Create an env-backed SMTP mail provider.
+ *
+ * Options override the corresponding `MAIL_*` env values.
+ */
+export declare function createSmtpMailProvider(options?: CreateSmtpMailProviderOptions): 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/index.js").SentMessageInfo, import("nodemailer/lib/smtp-transport/index.js").Options>;
+    };
+}, unknown, void>;
+/**
+ * Default env-backed SMTP mail provider.
  *
  * Reads `MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_PASS`, and `MAIL_FROM`,
  * verifies the transporter during setup, contributes `ports.mailer`, and
  * exposes `ports.smtp.transporter` as an escape hatch.
  */
-export declare const mailSmtpProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+export declare const smtpMailProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
     HOST: z.ZodString;
     PORT: z.ZodCoercedNumber<unknown>;
     USER: z.ZodString;

package/dist/index.d.ts.map

@@ -1 +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;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;OAEG;IACH,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB;;OAEG;IACH,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAoDD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,WAAW,EACX,IAAI,EACJ,eAAe,EAAE,qBAAqB,GACvC,EAAE,uBAAuB,GAAG,UAAU,CAqEtC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAwD3B,CAAC"}
+{"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;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;OAEG;IACH,IAAI,EAAE,mBAAmB,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,WAAW,EAAE,WAAW,CAAC;IACzB;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB;;OAEG;IACH,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AA0DD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,WAAW,EACX,IAAI,EACJ,eAAe,EAAE,qBAAqB,GACvC,EAAE,uBAAuB,GAAG,UAAU,CAqEtC;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,6BAAkC;;;;;;;;;;;kBA0E5C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;iBAA2B,CAAC"}

package/dist/index.js

@@ -19,6 +19,10 @@ function addOptional(target, key, value) {
         Object.assign(target, { [key]: value });
     }
 }
+function countRecipients(message) {
+    const count = (list) => list === undefined ? 0 : Array.isArray(list) ? list.length : 1;
+    return count(message.to) + count(message.cc) + count(message.bcc);
+}
 function createSmtpPayload(message, defaultFrom) {
     const normalized = normalizeMailMessage(message, { defaultFrom });
     if (!normalized.from) {
@@ -43,7 +47,7 @@ function createSmtpPayload(message, defaultFrom) {
 /**
  * Create a Beignet mailer port backed by Nodemailer SMTP.
  *
- * Use this directly for custom wiring, or install `mailSmtpProvider` to load
+ * Use this directly for custom wiring, or install `smtpMailProvider` to load
  * config from env and contribute ports during server startup.
  */
 export function createSmtpMailer({ transporter, from, instrumentation: instrumentationTarget, }) {
@@ -54,6 +58,7 @@ export function createSmtpMailer({ transporter, from, instrumentation: instrumen
     return {
         async send(message) {
             const payload = createSmtpPayload(message, from);
+            const recipientCount = countRecipients(message);
             instrumentation.custom({
                 name: "mail.send",
                 label: "Mail send",
@@ -102,9 +107,7 @@ export function createSmtpMailer({ transporter, from, instrumentation: instrumen
                 });
                 throw new MailDeliveryError({
                     provider: "smtp",
-                    message: error instanceof Error
-                        ? error.message
-                        : "SMTP failed to send email.",
+                    message: `SMTP failed to send email to ${recipientCount} recipient(s): ${error instanceof Error ? error.message : String(error)}`,
                     cause: error,
                 });
             }
@@ -112,56 +115,73 @@ export function createSmtpMailer({ transporter, from, instrumentation: instrumen
     };
 }
 /**
- * Env-backed SMTP mail provider.
+ * Create an env-backed SMTP mail provider.
+ *
+ * Options override the corresponding `MAIL_*` env values.
+ */
+export function createSmtpMailProvider(options = {}) {
+    return createProvider({
+        name: "mail-smtp",
+        config: {
+            schema: MailConfigSchema,
+            envPrefix: "MAIL_",
+            // Defined options win over env-derived values at config load time.
+            overrides: {
+                HOST: options.host,
+                PORT: options.port,
+                USER: options.user,
+                PASS: options.pass,
+                FROM: options.from,
+            },
+        },
+        async setup({ config, ports }) {
+            if (!config) {
+                throw new Error("[smtpMailProvider] Missing Mail config. " +
+                    "Please set MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, and MAIL_FROM environment variables.");
+            }
+            const { HOST: host, PORT: port, USER: user, PASS: pass, FROM: from, } = config;
+            const transporter = nodemailer.createTransport({
+                host,
+                port,
+                secure: port === 465,
+                auth: {
+                    user,
+                    pass,
+                },
+            });
+            try {
+                await transporter.verify();
+            }
+            catch (error) {
+                throw new Error(`[smtpMailProvider] Failed to connect to mail server at ${host}:${port}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            const instrumentation = createProviderInstrumentation(ports, {
+                providerName: "mail-smtp",
+                watcher: "mail",
+            });
+            const mailer = createSmtpMailer({
+                transporter,
+                from,
+                instrumentation,
+            });
+            return {
+                ports: {
+                    mailer,
+                    smtp: { transporter },
+                },
+                stop() {
+                    transporter.close();
+                },
+            };
+        },
+    });
+}
+/**
+ * Default env-backed SMTP mail provider.
  *
  * Reads `MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_PASS`, and `MAIL_FROM`,
  * verifies the transporter during setup, contributes `ports.mailer`, and
  * exposes `ports.smtp.transporter` as an escape hatch.
  */
-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();
-            },
-        };
-    },
-});
+export const smtpMailProvider = createSmtpMailProvider();
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/provider-mail-smtp",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "type": "module",
   "description": "SMTP mail provider for Beignet - adds mailer port using nodemailer",
   "main": "./dist/index.js",
@@ -102,7 +102,7 @@
       "registration": {
         "required": true,
         "tokens": [
-          "mailSmtpProvider"
+          "smtpMailProvider"
         ]
       }
     }

package/src/index.ts

@@ -50,7 +50,7 @@ export interface SmtpMailEscapeHatch {
 }
 
 /**
- * Ports contributed by `mailSmtpProvider`.
+ * Ports contributed by `smtpMailProvider`.
  */
 export interface SmtpMailProviderPorts {
   /**
@@ -90,6 +90,12 @@ function addOptional<
   }
 }
 
+function countRecipients(message: SendMailOptions): number {
+  const count = (list: SendMailOptions["cc"]): number =>
+    list === undefined ? 0 : Array.isArray(list) ? list.length : 1;
+  return count(message.to) + count(message.cc) + count(message.bcc);
+}
+
 function createSmtpPayload(
   message: SendMailOptions,
   defaultFrom: MailAddress,
@@ -134,7 +140,7 @@ function createSmtpPayload(
 /**
  * Create a Beignet mailer port backed by Nodemailer SMTP.
  *
- * Use this directly for custom wiring, or install `mailSmtpProvider` to load
+ * Use this directly for custom wiring, or install `smtpMailProvider` to load
  * config from env and contribute ports during server startup.
  */
 export function createSmtpMailer({
@@ -150,6 +156,7 @@ export function createSmtpMailer({
   return {
     async send(message): Promise<SendMailResult> {
       const payload = createSmtpPayload(message, from);
+      const recipientCount = countRecipients(message);
       instrumentation.custom({
         name: "mail.send",
         label: "Mail send",
@@ -201,10 +208,9 @@ export function createSmtpMailer({
         });
         throw new MailDeliveryError({
           provider: "smtp",
-          message:
-            error instanceof Error
-              ? error.message
-              : "SMTP failed to send email.",
+          message: `SMTP failed to send email to ${recipientCount} recipient(s): ${
+            error instanceof Error ? error.message : String(error)
+          }`,
           cause: error,
         });
       }
@@ -213,66 +219,118 @@ export function createSmtpMailer({
 }
 
 /**
- * Env-backed SMTP mail provider.
+ * Options for the SMTP mail provider factory.
+ */
+export interface CreateSmtpMailProviderOptions {
+  /**
+   * SMTP server hostname. Overrides `MAIL_HOST`.
+   */
+  host?: string;
+  /**
+   * SMTP server port. Port 465 uses SSL. Overrides `MAIL_PORT`.
+   */
+  port?: number;
+  /**
+   * SMTP username. Overrides `MAIL_USER`.
+   */
+  user?: string;
+  /**
+   * SMTP password. Overrides `MAIL_PASS`.
+   */
+  pass?: string;
+  /**
+   * Default sender address. Overrides `MAIL_FROM`.
+   */
+  from?: string;
+}
+
+/**
+ * Create an env-backed SMTP mail provider.
  *
- * Reads `MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_PASS`, and `MAIL_FROM`,
- * verifies the transporter during setup, contributes `ports.mailer`, and
- * exposes `ports.smtp.transporter` as an escape hatch.
+ * Options override the corresponding `MAIL_*` env values.
  */
-export const mailSmtpProvider = createProvider({
-  name: "mail-smtp",
+export function createSmtpMailProvider(
+  options: CreateSmtpMailProviderOptions = {},
+) {
+  return createProvider({
+    name: "mail-smtp",
 
-  config: {
-    schema: MailConfigSchema,
-    envPrefix: "MAIL_",
-  },
+    config: {
+      schema: MailConfigSchema,
+      envPrefix: "MAIL_",
+      // Defined options win over env-derived values at config load time.
+      overrides: {
+        HOST: options.host,
+        PORT: options.port,
+        USER: options.user,
+        PASS: options.pass,
+        FROM: options.from,
+      },
+    },
 
-  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.",
-      );
-    }
+    async setup({ config, ports }) {
+      if (!config) {
+        throw new Error(
+          "[smtpMailProvider] Missing Mail config. " +
+            "Please set MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS, and MAIL_FROM environment variables.",
+        );
+      }
+      const {
+        HOST: host,
+        PORT: port,
+        USER: user,
+        PASS: pass,
+        FROM: from,
+      } = config;
 
-    const transporter = nodemailer.createTransport({
-      host: config.HOST,
-      port: config.PORT,
-      secure: config.PORT === 465,
-      auth: {
-        user: config.USER,
-        pass: config.PASS,
-      },
-    });
+      const transporter = nodemailer.createTransport({
+        host,
+        port,
+        secure: port === 465,
+        auth: {
+          user,
+          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)
-        }`,
-      );
-    }
+      try {
+        await transporter.verify();
+      } catch (error) {
+        throw new Error(
+          `[smtpMailProvider] Failed to connect to mail server at ${host}:${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,
-    });
+      const instrumentation = createProviderInstrumentation(ports, {
+        providerName: "mail-smtp",
+        watcher: "mail",
+      });
+      const mailer = createSmtpMailer({
+        transporter,
+        from,
+        instrumentation,
+      });
 
-    return {
-      ports: {
-        mailer,
-        smtp: { transporter },
-      } satisfies SmtpMailProviderPorts,
-      stop() {
-        transporter.close();
-      },
-    };
-  },
-});
+      return {
+        ports: {
+          mailer,
+          smtp: { transporter },
+        } satisfies SmtpMailProviderPorts,
+        stop() {
+          transporter.close();
+        },
+      };
+    },
+  });
+}
+
+/**
+ * Default env-backed SMTP mail provider.
+ *
+ * Reads `MAIL_HOST`, `MAIL_PORT`, `MAIL_USER`, `MAIL_PASS`, and `MAIL_FROM`,
+ * verifies the transporter during setup, contributes `ports.mailer`, and
+ * exposes `ports.smtp.transporter` as an escape hatch.
+ */
+export const smtpMailProvider = createSmtpMailProvider();