@beignet/provider-mail-resend 0.0.30 → 0.0.32

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @beignet/provider-mail-resend
 
+## 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

@@ -21,12 +21,12 @@ the SDK's Node.js 20+ runtime requirement.
 ## Setup
 
 ```typescript
-import { mailResendProvider } from "@beignet/provider-mail-resend";
+import { resendMailProvider } from "@beignet/provider-mail-resend";
 import { createServer } from "@beignet/core/server";
 
 const server = await createServer({
   ports: basePorts,
-  providers: [mailResendProvider],
+  providers: [resendMailProvider],
   context: ({ ports }) => ({ ports }),
   routes,
 });
@@ -43,6 +43,23 @@ Required environment variables:
 registered in `server/providers.ts` and that both required env vars are present
 in app env examples or config.
 
+Use `createResendMailProvider(...)` when you want to pass config directly
+instead of reading `RESEND_*` env vars. Options override env-derived values:
+
+```typescript
+import { createResendMailProvider } from "@beignet/provider-mail-resend";
+
+export const providers = [
+  createResendMailProvider({
+    apiKey: secrets.resendApiKey,
+    from: "My App <no-reply@example.com>",
+  }),
+];
+```
+
+`resendMailProvider` is the default env-backed provider, equivalent to
+`createResendMailProvider()`.
+
 ## Use in application code
 
 ```typescript
@@ -96,10 +113,20 @@ The provider contributes:
 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 Resend error preserved as
+`cause`. Message bodies and credentials are never included. Startup
+configuration problems throw during provider setup.
 
-Delivery failures throw `MailDeliveryError` from `@beignet/core/mail`.
-Startup configuration 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

@@ -25,7 +25,7 @@ export interface ResendMailEscapeHatch {
     client: Resend;
 }
 /**
- * Ports contributed by `mailResendProvider`.
+ * Ports contributed by `resendMailProvider`.
  */
 export interface ResendMailProviderPorts {
     /**
@@ -57,17 +57,45 @@ export interface CreateResendMailerOptions {
 /**
  * Create a Beignet mailer port backed by Resend.
  *
- * Use this directly for custom wiring, or install `mailResendProvider` to load
+ * Use this directly for custom wiring, or install `resendMailProvider` to load
  * config from env and contribute ports during server startup.
  */
 export declare function createResendMailer({ client, from, instrumentation: instrumentationTarget, }: CreateResendMailerOptions): MailerPort;
 /**
- * Env-backed Resend mail provider.
+ * Options for the Resend mail provider factory.
+ */
+export interface CreateResendMailProviderOptions {
+    /**
+     * Resend API key. Overrides `RESEND_API_KEY`.
+     */
+    apiKey?: string;
+    /**
+     * Default sender address, e.g. `My App <no-reply@example.com>`.
+     * Overrides `RESEND_FROM`.
+     */
+    from?: string;
+}
+/**
+ * Create an env-backed Resend mail provider.
+ *
+ * Options override the corresponding `RESEND_*` env values.
+ */
+export declare function createResendMailProvider(options?: CreateResendMailProviderOptions): import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    API_KEY: z.ZodString;
+    FROM: z.ZodString;
+}, z.core.$strip>, {
+    mailer: MailerPort;
+    resend: {
+        client: Resend;
+    };
+}, unknown, void>;
+/**
+ * Default env-backed Resend mail provider.
  *
  * Reads `RESEND_API_KEY` and `RESEND_FROM`, contributes `ports.mailer`, and
  * exposes `ports.resend.client` as an escape hatch.
  */
-export declare const mailResendProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+export declare const resendMailProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
     API_KEY: z.ZodString;
     FROM: z.ZodString;
 }, z.core.$strip>, {

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,EAA2B,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,sBAAsB;;;iBAG1B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;OAEG;IACH,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB;;OAEG;IACH,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AAqDD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,IAAI,EACJ,eAAe,EAAE,qBAAqB,GACvC,EAAE,yBAAyB,GAAG,UAAU,CAsFxC;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;iBAkC7B,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,EAA2B,MAAM,EAAE,MAAM,QAAQ,CAAC;AACzD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,QAAA,MAAM,sBAAsB;;;iBAG1B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;OAEG;IACH,MAAM,EAAE,qBAAqB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,IAAI,EAAE,WAAW,CAAC;IAClB;;OAEG;IACH,eAAe,CAAC,EAAE,6BAA6B,CAAC;CACjD;AA2DD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,MAAM,EACN,IAAI,EACJ,eAAe,EAAE,qBAAqB,GACvC,EAAE,yBAAyB,GAAG,UAAU,CAwFxC;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,+BAAoC;;;;;;;;kBA2C9C;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;iBAA6B,CAAC"}

package/dist/index.js

@@ -16,6 +16,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 createResendPayload(message, defaultFrom) {
     const normalized = normalizeMailMessage(message, { defaultFrom });
     if (!normalized.from) {
@@ -40,7 +44,7 @@ function createResendPayload(message, defaultFrom) {
 /**
  * Create a Beignet mailer port backed by Resend.
  *
- * Use this directly for custom wiring, or install `mailResendProvider` to load
+ * Use this directly for custom wiring, or install `resendMailProvider` to load
  * config from env and contribute ports during server startup.
  */
 export function createResendMailer({ client, from, instrumentation: instrumentationTarget, }) {
@@ -51,6 +55,7 @@ export function createResendMailer({ client, from, instrumentation: instrumentat
     return {
         async send(message) {
             const payload = createResendPayload(message, from);
+            const recipientCount = countRecipients(message);
             instrumentation.custom({
                 name: "mail.send",
                 label: "Mail send",
@@ -77,7 +82,7 @@ export function createResendMailer({ client, from, instrumentation: instrumentat
                     });
                     throw new MailDeliveryError({
                         provider: "resend",
-                        message: result.error.message || "Resend failed to send email.",
+                        message: `Resend failed to send email to ${recipientCount} recipient(s): ${result.error.message || "unknown Resend error"}`,
                         cause: result.error,
                     });
                 }
@@ -114,9 +119,7 @@ export function createResendMailer({ client, from, instrumentation: instrumentat
                 });
                 throw new MailDeliveryError({
                     provider: "resend",
-                    message: error instanceof Error
-                        ? error.message
-                        : "Resend failed to send email.",
+                    message: `Resend failed to send email to ${recipientCount} recipient(s): ${error instanceof Error ? error.message : String(error)}`,
                     cause: error,
                 });
             }
@@ -124,37 +127,51 @@ export function createResendMailer({ client, from, instrumentation: instrumentat
     };
 }
 /**
- * Env-backed Resend mail provider.
+ * Create an env-backed Resend mail provider.
+ *
+ * Options override the corresponding `RESEND_*` env values.
+ */
+export function createResendMailProvider(options = {}) {
+    return createProvider({
+        name: "mail-resend",
+        config: {
+            schema: ResendMailConfigSchema,
+            envPrefix: "RESEND_",
+            // Defined options win over env-derived values at config load time.
+            overrides: {
+                API_KEY: options.apiKey,
+                FROM: options.from,
+            },
+        },
+        async setup({ config, ports }) {
+            if (!config) {
+                throw new Error("[resendMailProvider] Missing Resend config. " +
+                    "Please set RESEND_API_KEY and RESEND_FROM environment variables.");
+            }
+            const { API_KEY: apiKey, FROM: from } = config;
+            const client = new Resend(apiKey);
+            const instrumentation = createProviderInstrumentation(ports, {
+                providerName: "mail-resend",
+                watcher: "mail",
+            });
+            const mailer = createResendMailer({
+                client,
+                from,
+                instrumentation,
+            });
+            return {
+                ports: {
+                    mailer,
+                    resend: { client },
+                },
+            };
+        },
+    });
+}
+/**
+ * Default env-backed Resend mail provider.
  *
  * Reads `RESEND_API_KEY` and `RESEND_FROM`, contributes `ports.mailer`, and
  * exposes `ports.resend.client` as an escape hatch.
  */
-export const mailResendProvider = createProvider({
-    name: "mail-resend",
-    config: {
-        schema: ResendMailConfigSchema,
-        envPrefix: "RESEND_",
-    },
-    async setup({ config, ports }) {
-        if (!config) {
-            throw new Error("[mailResendProvider] Missing Resend config. " +
-                "Please set RESEND_API_KEY and RESEND_FROM environment variables.");
-        }
-        const client = new Resend(config.API_KEY);
-        const instrumentation = createProviderInstrumentation(ports, {
-            providerName: "mail-resend",
-            watcher: "mail",
-        });
-        const mailer = createResendMailer({
-            client,
-            from: config.FROM,
-            instrumentation,
-        });
-        return {
-            ports: {
-                mailer,
-                resend: { client },
-            },
-        };
-    },
-});
+export const resendMailProvider = createResendMailProvider();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beignet/provider-mail-resend",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "type": "module",
   "description": "Resend mail provider for Beignet - adds mailer port using Resend",
   "main": "./dist/index.js",
@@ -94,7 +94,7 @@
       "registration": {
         "required": true,
         "tokens": [
-          "mailResendProvider"
+          "resendMailProvider"
         ]
       }
     }

package/src/index.ts

@@ -43,7 +43,7 @@ export interface ResendMailEscapeHatch {
 }
 
 /**
- * Ports contributed by `mailResendProvider`.
+ * Ports contributed by `resendMailProvider`.
  */
 export interface ResendMailProviderPorts {
   /**
@@ -84,6 +84,12 @@ function addOptional<T extends Record<string, unknown>, K extends string, V>(
   }
 }
 
+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 createResendPayload(
   message: SendMailOptions,
   defaultFrom: MailAddress,
@@ -128,7 +134,7 @@ function createResendPayload(
 /**
  * Create a Beignet mailer port backed by Resend.
  *
- * Use this directly for custom wiring, or install `mailResendProvider` to load
+ * Use this directly for custom wiring, or install `resendMailProvider` to load
  * config from env and contribute ports during server startup.
  */
 export function createResendMailer({
@@ -144,6 +150,7 @@ export function createResendMailer({
   return {
     async send(message): Promise<SendMailResult> {
       const payload = createResendPayload(message, from);
+      const recipientCount = countRecipients(message);
       instrumentation.custom({
         name: "mail.send",
         label: "Mail send",
@@ -172,7 +179,9 @@ export function createResendMailer({
           });
           throw new MailDeliveryError({
             provider: "resend",
-            message: result.error.message || "Resend failed to send email.",
+            message: `Resend failed to send email to ${recipientCount} recipient(s): ${
+              result.error.message || "unknown Resend error"
+            }`,
             cause: result.error,
           });
         }
@@ -212,10 +221,9 @@ export function createResendMailer({
 
         throw new MailDeliveryError({
           provider: "resend",
-          message:
-            error instanceof Error
-              ? error.message
-              : "Resend failed to send email.",
+          message: `Resend failed to send email to ${recipientCount} recipient(s): ${
+            error instanceof Error ? error.message : String(error)
+          }`,
           cause: error,
         });
       }
@@ -224,43 +232,75 @@ export function createResendMailer({
 }
 
 /**
- * Env-backed Resend mail provider.
+ * Options for the Resend mail provider factory.
+ */
+export interface CreateResendMailProviderOptions {
+  /**
+   * Resend API key. Overrides `RESEND_API_KEY`.
+   */
+  apiKey?: string;
+  /**
+   * Default sender address, e.g. `My App <no-reply@example.com>`.
+   * Overrides `RESEND_FROM`.
+   */
+  from?: string;
+}
+
+/**
+ * Create an env-backed Resend mail provider.
  *
- * Reads `RESEND_API_KEY` and `RESEND_FROM`, contributes `ports.mailer`, and
- * exposes `ports.resend.client` as an escape hatch.
+ * Options override the corresponding `RESEND_*` env values.
  */
-export const mailResendProvider = createProvider({
-  name: "mail-resend",
+export function createResendMailProvider(
+  options: CreateResendMailProviderOptions = {},
+) {
+  return createProvider({
+    name: "mail-resend",
+
+    config: {
+      schema: ResendMailConfigSchema,
+      envPrefix: "RESEND_",
+      // Defined options win over env-derived values at config load time.
+      overrides: {
+        API_KEY: options.apiKey,
+        FROM: options.from,
+      },
+    },
 
-  config: {
-    schema: ResendMailConfigSchema,
-    envPrefix: "RESEND_",
-  },
+    async setup({ config, ports }) {
+      if (!config) {
+        throw new Error(
+          "[resendMailProvider] Missing Resend config. " +
+            "Please set RESEND_API_KEY and RESEND_FROM environment variables.",
+        );
+      }
+      const { API_KEY: apiKey, FROM: from } = config;
 
-  async setup({ config, ports }) {
-    if (!config) {
-      throw new Error(
-        "[mailResendProvider] Missing Resend config. " +
-          "Please set RESEND_API_KEY and RESEND_FROM environment variables.",
-      );
-    }
+      const client = new Resend(apiKey);
+      const instrumentation = createProviderInstrumentation(ports, {
+        providerName: "mail-resend",
+        watcher: "mail",
+      });
+      const mailer = createResendMailer({
+        client,
+        from,
+        instrumentation,
+      });
 
-    const client = new Resend(config.API_KEY);
-    const instrumentation = createProviderInstrumentation(ports, {
-      providerName: "mail-resend",
-      watcher: "mail",
-    });
-    const mailer = createResendMailer({
-      client,
-      from: config.FROM,
-      instrumentation,
-    });
+      return {
+        ports: {
+          mailer,
+          resend: { client },
+        } satisfies ResendMailProviderPorts,
+      };
+    },
+  });
+}
 
-    return {
-      ports: {
-        mailer,
-        resend: { client },
-      } satisfies ResendMailProviderPorts,
-    };
-  },
-});
+/**
+ * Default env-backed Resend mail provider.
+ *
+ * Reads `RESEND_API_KEY` and `RESEND_FROM`, contributes `ports.mailer`, and
+ * exposes `ports.resend.client` as an escape hatch.
+ */
+export const resendMailProvider = createResendMailProvider();