typedmailer 1.0.1 → 1.2.0

package/CODE_OF_CONDUCT.md

@@ -17,4 +17,4 @@ Harassment, insults, discriminatory language, intimidation, unwelcome sexual att
 
 ## Enforcement
 
-Report conduct concerns privately through GitHub's contact/reporting tools for the repository owner. Reports will be reviewed and handled as fairly and promptly as possible. Maintainers may remove content or restrict participation for behavior that violates this code.
+Report conduct concerns privately using [GitHub's contact and reporting tools](https://github.com/contact) for the repository owner. Reports will be reviewed and handled as fairly and promptly as possible. Maintainers may remove content or restrict participation for behavior that violates this code.

package/README.md

@@ -17,6 +17,8 @@ TypedMailer is a type-safe email library for Node.js and TypeScript applications
 
 Use TypedMailer when you want to switch email providers without coupling application code to a provider SDK. Provider SDKs are optional peer dependencies, and only the selected adapter is loaded.
 
+The separate `typedmailer/webhooks` entry point verifies and normalizes inbound provider events. It does not provide HTTP routing, persistence, or event processing.
+
 ## Install
 
 Install the `typedmailer` npm package with the provider SDK you plan to use:
@@ -45,6 +47,8 @@ TypedMailer is for trusted server-side Node.js runtimes. It is not intended for
 
 ## Quick start
 
+Want to try TypedMailer without provider credentials? Follow the [local Mailpit quick start](docs/quickstart.md).
+
 ```ts
 import { createMailer } from 'typedmailer';
 
@@ -54,15 +58,18 @@ const mailer = createMailer({
   from: 'Example App <noreply@example.com>',
 });
 
-const result = await mailer.send({
-  to: 'person@example.com',
-  subject: 'Welcome',
-  text: 'Your account is ready.',
-  html: '<p>Your account is ready.</p>',
-});
-
-console.log(result.messageId);
-await mailer.close();
+try {
+  const result = await mailer.send({
+    to: 'person@example.com',
+    subject: 'Welcome',
+    text: 'Your account is ready.',
+    html: '<p>Your account is ready.</p>',
+  });
+
+  console.log(result.messageId);
+} finally {
+  await mailer.close();
+}
 ```
 
 ## Providers
@@ -153,7 +160,7 @@ For local development, start Mailpit with `docker run --rm -p 1025:1025 -p 8025:
 
 ## Message options
 
-`to` accepts an email string, a `{ email, name }` object, or an array. Provide `text` or `html` (or both). Optional fields include `from`, `replyTo`, `cc`, `bcc`, `headers`, `attachments`, `metadata`, and `idempotencyKey`; `messageId` is SMTP-only. Attachments may include `contentId` for inline images with Resend, Postmark, SendGrid, Mailgun, Amazon SES, and SMTP. Attachment content accepts strings or `Uint8Array`; the provider adapters buffer it for SDK requests, so use an application-managed upload or streaming workflow for large files.
+`to` accepts an email string, a `{ email, name }` object, or an array. Provide `text` or `html` (or both). Optional fields include `from`, `replyTo`, `cc`, `bcc`, `headers`, `attachments`, `metadata`, and `idempotencyKey`; `messageId` is SMTP-only. Attachments may include `contentId` for inline images with Resend, Postmark, SendGrid, Mailgun, Amazon SES, and SMTP. Attachment content accepts strings or `Uint8Array`; the provider adapters buffer it for SDK requests, so use an application-managed upload or streaming workflow for large files. Set `maxAttachmentBytes` on `createMailer()` to reject a message before loading or calling the provider when the combined UTF-8 and binary attachment content exceeds your application's memory budget. It is unset by default for backward compatibility.
 
 Subjects and attachment filenames cannot be blank. Supplied content types and inline content IDs must be non-empty. The library does not impose a fixed attachment-size limit.
 
@@ -195,6 +202,10 @@ console.log(mailer.sent[0]);
 
 Messages captured by `createTestMailer` return `provider: 'test'` so test results are not mistaken for SMTP deliveries.
 
+## Verify provider webhooks
+
+Use `verifyWebhook` from `typedmailer/webhooks` to authenticate a raw request and receive normalized events. Your HTTP route remains responsible for preserving the raw body, responding to the provider, deduplicating events durably, and applying application changes. See [Webhook verification](docs/webhooks.md) for provider-specific configuration and security requirements.
+
 ## Runnable examples
 
 The repository includes complete Resend, Amazon SES, and local SMTP/Mailpit examples in [`examples/`](examples/). From a clone, copy `examples/.env.example` to `.env`, replace the example sender and recipient with addresses valid for your account, then install the SDK for the chosen provider:
@@ -221,7 +232,7 @@ Provider and transport failures are normalized as `MailError`, with `code`, `pro
 
 `retryable` is guidance from the normalized failure: recognized network failures and rate limits are retryable; API provider 5xx failures are retryable; authentication, configuration, unsupported, and SMTP 5xx failures are not. `deliveryUnknown` is separate: it is true when a send timeout/socket interruption, a provider 5xx, or an accepted response without a message ID means the provider may have accepted the message without returning a clear result. It stays false for verification failures, DNS lookup failures, authentication errors, rate limits, and SMTP response errors. This does not guarantee that retrying is safe. Use provider-supported idempotency where available and apply retry policy in your application. `cause` retains the original SDK error for diagnostics and can contain provider details; avoid logging it without reviewing your data handling policy.
 
-A successful `send()` means the provider accepted the request; it does not confirm inbox delivery. Delivery, bounce, and complaint events require provider webhooks and are outside this package's current scope.
+A successful `send()` means the provider accepted the request; it does not confirm inbox delivery. Verify delivery, bounce, and complaint callbacks with [`typedmailer/webhooks`](docs/webhooks.md).
 
 `verifyConnection()` currently supports SMTP. API provider adapters report `unsupported` because they do not expose a side-effect-free credential check through this API; verify credentials with a controlled provider test message.
 
@@ -238,6 +249,8 @@ A successful `send()` means the provider accepted the request; it does not confi
 
 Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for development and contribution guidelines.
 
+Contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
 After cloning, run `npm ci` to install dependencies and enable the local Git hooks. Commits run staged-file lint and format checks plus unit tests. Pushes run the full `npm run check` quality gate, including an isolated npm tarball consumer smoke test; GitHub Actions runs it on Node.js 22 and 24 and audits dependencies before merge and publish.
 
 ## License

package/SECURITY.md

@@ -6,4 +6,4 @@ Only the latest published version is currently supported.
 
 ## Reporting a vulnerability
 
-Please do not report security vulnerabilities in public issues. Use GitHub's private vulnerability reporting for this repository. Include the affected version, impact, and a minimal reproduction. Do not include real credentials, recipient data, or message contents.
+Please do not report security vulnerabilities in public issues. Use [GitHub's private vulnerability reporting](https://github.com/erolsenol/typedmailer/security/advisories/new) for this repository. Include the affected version, impact, and a minimal reproduction. Do not include real credentials, recipient data, or message contents.

package/SUPPORT.md

@@ -2,7 +2,7 @@
 
 ## Runtime support
 
-TypedMailer requires Node.js 22 or newer. CI tests Node.js 22 and 24. We support the latest patch release of each Node.js major that is still in its official maintenance or active LTS period; end-of-life Node.js releases are unsupported even when they satisfy the package engine range.
+TypedMailer requires Node.js 22 or newer. CI tests Node.js 22 and 24; Node.js 26 runs as a non-blocking compatibility canary while it is Current. We support the latest patch release of each Node.js major that is in its official maintenance or active LTS period; end-of-life Node.js releases are unsupported even when they satisfy the package engine range.
 
 Install the provider SDK required by your selected adapter. Provider SDKs are optional peer dependencies; see the [provider contracts](docs/provider-contracts.md) and README compatibility table.
 

package/dist/index.d.ts

@@ -1,76 +1,6 @@
-import { z } from 'zod';
+import { type MailerOptions } from './providers/registry.js';
 import type { Mailer } from './types.js';
-declare const providerOptions: {
-    readonly resend: z.ZodObject<{
-        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
-            email: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        provider: z.ZodLiteral<"resend">;
-        apiKey: z.ZodString;
-    }, z.core.$strip>;
-    readonly brevo: z.ZodObject<{
-        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
-            email: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        provider: z.ZodLiteral<"brevo">;
-        apiKey: z.ZodString;
-    }, z.core.$strip>;
-    readonly postmark: z.ZodObject<{
-        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
-            email: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        provider: z.ZodLiteral<"postmark">;
-        apiKey: z.ZodString;
-    }, z.core.$strip>;
-    readonly sendgrid: z.ZodObject<{
-        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
-            email: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        provider: z.ZodLiteral<"sendgrid">;
-        apiKey: z.ZodString;
-    }, z.core.$strip>;
-    readonly mailgun: z.ZodObject<{
-        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
-            email: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        provider: z.ZodLiteral<"mailgun">;
-        apiKey: z.ZodString;
-        domain: z.ZodString;
-        region: z.ZodDefault<z.ZodEnum<{
-            us: "us";
-            eu: "eu";
-        }>>;
-    }, z.core.$strip>;
-    readonly ses: z.ZodObject<{
-        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
-            email: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        provider: z.ZodLiteral<"ses">;
-        region: z.ZodString;
-    }, z.core.$strip>;
-    readonly smtp: z.ZodObject<{
-        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
-            email: z.ZodString;
-            name: z.ZodOptional<z.ZodString>;
-        }, z.core.$strict>]>;
-        provider: z.ZodLiteral<"smtp">;
-        host: z.ZodString;
-        port: z.ZodNumber;
-        secure: z.ZodBoolean;
-        user: z.ZodOptional<z.ZodString>;
-        password: z.ZodOptional<z.ZodString>;
-        connectionTimeout: z.ZodDefault<z.ZodNumber>;
-        greetingTimeout: z.ZodDefault<z.ZodNumber>;
-        socketTimeout: z.ZodDefault<z.ZodNumber>;
-    }, z.core.$strip>;
-};
-export type MailerOptions = z.input<typeof providerOptions.resend> | z.input<typeof providerOptions.brevo> | z.input<typeof providerOptions.postmark> | z.input<typeof providerOptions.sendgrid> | z.input<typeof providerOptions.mailgun> | z.input<typeof providerOptions.ses> | z.input<typeof providerOptions.smtp>;
+export type { MailerOptions };
 export declare function createMailer(input: MailerOptions): Mailer;
 export { MailError } from './errors.js';
 export type { MailErrorCode, MailErrorOperation, MailErrorOptions } from './errors.js';

package/dist/index.js

@@ -1,119 +1,14 @@
-import { z } from 'zod';
+import { Buffer } from 'node:buffer';
 import { MailError, normalizeProviderError } from './errors.js';
 import { mailInputSchema, normalizeAddresses } from './config.js';
-const baseOptions = z.object({
-    from: z.union([
-        z.string().email(),
-        z.string().regex(/^.+ <[^<>\s]+@[^<>\s]+>$/, 'Use a valid email address or "Name <email@example.com>".'),
-        z.object({ email: z.string().email(), name: z.string().optional() }).strict(),
-    ]),
-});
-const providerOptions = {
-    resend: baseOptions.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
-    brevo: baseOptions.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),
-    postmark: baseOptions.extend({ provider: z.literal('postmark'), apiKey: z.string().min(1) }),
-    sendgrid: baseOptions.extend({ provider: z.literal('sendgrid'), apiKey: z.string().min(1) }),
-    mailgun: baseOptions.extend({
-        provider: z.literal('mailgun'),
-        apiKey: z.string().min(1),
-        domain: z.string().min(1),
-        region: z.enum(['us', 'eu']).default('us'),
-    }),
-    ses: baseOptions.extend({ provider: z.literal('ses'), region: z.string().min(1) }),
-    smtp: baseOptions
-        .extend({
-        provider: z.literal('smtp'),
-        host: z.string().min(1),
-        port: z.number().int().min(1).max(65535),
-        secure: z.boolean(),
-        user: z.string().min(1).optional(),
-        password: z.string().min(1).optional(),
-        connectionTimeout: z.number().int().positive().default(8_000),
-        greetingTimeout: z.number().int().positive().default(8_000),
-        socketTimeout: z.number().int().positive().default(15_000),
-    })
-        .refine((options) => Boolean(options.user) === Boolean(options.password), {
-        message: 'SMTP user and password must be configured together.',
-        path: ['user'],
-    }),
-};
-async function loadProvider(options) {
-    try {
-        switch (options.provider) {
-            case 'resend': {
-                const { createResendProvider } = await import('./providers/resend.js');
-                return createResendProvider(options);
-            }
-            case 'brevo': {
-                const { createBrevoProvider } = await import('./providers/brevo.js');
-                return createBrevoProvider(options);
-            }
-            case 'postmark': {
-                const { createPostmarkProvider } = await import('./providers/postmark.js');
-                return createPostmarkProvider(options);
-            }
-            case 'sendgrid': {
-                const { createSendGridProvider } = await import('./providers/sendgrid.js');
-                return createSendGridProvider(options);
-            }
-            case 'mailgun': {
-                const { createMailgunProvider } = await import('./providers/mailgun.js');
-                return createMailgunProvider(options);
-            }
-            case 'ses': {
-                const { createSesProvider } = await import('./providers/ses.js');
-                return createSesProvider(options);
-            }
-            case 'smtp': {
-                const { createSmtpProvider } = await import('./providers/smtp.js');
-                return createSmtpProvider({
-                    host: options.host,
-                    port: options.port,
-                    secure: options.secure,
-                    ...(options.user ? { user: options.user } : {}),
-                    ...(options.password ? { password: options.password } : {}),
-                    connectionTimeout: options.connectionTimeout,
-                    greetingTimeout: options.greetingTimeout,
-                    socketTimeout: options.socketTimeout,
-                });
-            }
-        }
-    }
-    catch (error) {
-        const moduleNotFound = error;
-        if (moduleNotFound?.code === 'ERR_MODULE_NOT_FOUND') {
-            const dependencies = {
-                brevo: '@getbrevo/brevo',
-                mailgun: 'mailgun.js and form-data',
-                postmark: 'postmark',
-                resend: 'resend',
-                sendgrid: '@sendgrid/mail',
-                ses: '@aws-sdk/client-sesv2',
-                smtp: 'nodemailer',
-            };
-            const dependency = dependencies[options.provider];
-            throw new MailError(`Install the optional provider package "${dependency}" to use ${options.provider}.`, 'configuration', options.provider, false, { cause: error });
-        }
-        throw error;
-    }
-}
+import { loadProvider, mailerOptionsSchema } from './providers/registry.js';
 export function createMailer(input) {
     let providerPromise;
     let closed = false;
     let closePromise;
     let activeOperations = 0;
     let resolveOperationsIdle;
-    const parsedOptions = z
-        .discriminatedUnion('provider', [
-        providerOptions.resend,
-        providerOptions.brevo,
-        providerOptions.postmark,
-        providerOptions.sendgrid,
-        providerOptions.mailgun,
-        providerOptions.ses,
-        providerOptions.smtp,
-    ])
-        .parse(input);
+    const parsedOptions = mailerOptionsSchema.parse(input);
     const assertOpen = () => {
         if (closed)
             throw new MailError('Mailer has been closed.', 'configuration', parsedOptions.provider, false);
@@ -141,6 +36,13 @@ export function createMailer(input) {
         async send(input) {
             assertOpen();
             const parsed = mailInputSchema.parse(input);
+            const attachmentBytes = parsed.attachments?.reduce((total, attachment) => total +
+                (typeof attachment.content === 'string'
+                    ? Buffer.byteLength(attachment.content)
+                    : attachment.content.byteLength), 0) ?? 0;
+            if (parsedOptions.maxAttachmentBytes !== undefined && attachmentBytes > parsedOptions.maxAttachmentBytes) {
+                throw new MailError(`Attachment content exceeds the configured limit of ${parsedOptions.maxAttachmentBytes} bytes.`, 'configuration', parsedOptions.provider, false);
+            }
             const normalized = {
                 from: (parsed.from ?? parsedOptions.from),
                 to: (normalizeAddresses(parsed.to) ?? []),

package/dist/providers/registry.d.ts

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+import type { MailProvider } from '../types.js';
+export declare const providerOptions: {
+    readonly resend: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        provider: z.ZodLiteral<"resend">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly brevo: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        provider: z.ZodLiteral<"brevo">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly postmark: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        provider: z.ZodLiteral<"postmark">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly sendgrid: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        provider: z.ZodLiteral<"sendgrid">;
+        apiKey: z.ZodString;
+    }, z.core.$strip>;
+    readonly mailgun: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        provider: z.ZodLiteral<"mailgun">;
+        apiKey: z.ZodString;
+        domain: z.ZodString;
+        region: z.ZodDefault<z.ZodEnum<{
+            us: "us";
+            eu: "eu";
+        }>>;
+    }, z.core.$strip>;
+    readonly ses: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        provider: z.ZodLiteral<"ses">;
+        region: z.ZodString;
+    }, z.core.$strip>;
+    readonly smtp: z.ZodObject<{
+        from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+            email: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>;
+        maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+        provider: z.ZodLiteral<"smtp">;
+        host: z.ZodString;
+        port: z.ZodNumber;
+        secure: z.ZodBoolean;
+        user: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        connectionTimeout: z.ZodDefault<z.ZodNumber>;
+        greetingTimeout: z.ZodDefault<z.ZodNumber>;
+        socketTimeout: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+};
+export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodLiteral<"resend">;
+    apiKey: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodLiteral<"brevo">;
+    apiKey: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodLiteral<"postmark">;
+    apiKey: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodLiteral<"sendgrid">;
+    apiKey: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodLiteral<"mailgun">;
+    apiKey: z.ZodString;
+    domain: z.ZodString;
+    region: z.ZodDefault<z.ZodEnum<{
+        us: "us";
+        eu: "eu";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodLiteral<"ses">;
+    region: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    from: z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
+        email: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>;
+    maxAttachmentBytes: z.ZodOptional<z.ZodNumber>;
+    provider: z.ZodLiteral<"smtp">;
+    host: z.ZodString;
+    port: z.ZodNumber;
+    secure: z.ZodBoolean;
+    user: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    connectionTimeout: z.ZodDefault<z.ZodNumber>;
+    greetingTimeout: z.ZodDefault<z.ZodNumber>;
+    socketTimeout: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>], "provider">;
+export type MailerOptions = z.input<typeof mailerOptionsSchema>;
+export type ParsedMailerOptions = z.output<typeof mailerOptionsSchema>;
+export declare function loadProvider(options: ParsedMailerOptions): Promise<MailProvider>;

package/dist/providers/registry.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { MailError } from '../errors.js';
+const baseOptions = z.object({
+    from: z.union([
+        z.string().email(),
+        z.string().regex(/^.+ <[^<>\s]+@[^<>\s]+>$/, 'Use a valid email address or "Name <email@example.com>".'),
+        z.object({ email: z.string().email(), name: z.string().optional() }).strict(),
+    ]),
+    /** Optional aggregate in-memory attachment cap. No default preserves existing behavior. */
+    maxAttachmentBytes: z.number().int().positive().optional(),
+});
+export const providerOptions = {
+    resend: baseOptions.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
+    brevo: baseOptions.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),
+    postmark: baseOptions.extend({ provider: z.literal('postmark'), apiKey: z.string().min(1) }),
+    sendgrid: baseOptions.extend({ provider: z.literal('sendgrid'), apiKey: z.string().min(1) }),
+    mailgun: baseOptions.extend({
+        provider: z.literal('mailgun'),
+        apiKey: z.string().min(1),
+        domain: z.string().min(1),
+        region: z.enum(['us', 'eu']).default('us'),
+    }),
+    ses: baseOptions.extend({ provider: z.literal('ses'), region: z.string().min(1) }),
+    smtp: baseOptions
+        .extend({
+        provider: z.literal('smtp'),
+        host: z.string().min(1),
+        port: z.number().int().min(1).max(65535),
+        secure: z.boolean(),
+        user: z.string().min(1).optional(),
+        password: z.string().min(1).optional(),
+        connectionTimeout: z.number().int().positive().default(8_000),
+        greetingTimeout: z.number().int().positive().default(8_000),
+        socketTimeout: z.number().int().positive().default(15_000),
+    })
+        .refine((options) => Boolean(options.user) === Boolean(options.password), {
+        message: 'SMTP user and password must be configured together.',
+        path: ['user'],
+    }),
+};
+export const mailerOptionsSchema = z.discriminatedUnion('provider', [
+    providerOptions.resend,
+    providerOptions.brevo,
+    providerOptions.postmark,
+    providerOptions.sendgrid,
+    providerOptions.mailgun,
+    providerOptions.ses,
+    providerOptions.smtp,
+]);
+export async function loadProvider(options) {
+    try {
+        switch (options.provider) {
+            case 'resend': {
+                const { createResendProvider } = await import('./resend.js');
+                return createResendProvider(options);
+            }
+            case 'brevo': {
+                const { createBrevoProvider } = await import('./brevo.js');
+                return createBrevoProvider(options);
+            }
+            case 'postmark': {
+                const { createPostmarkProvider } = await import('./postmark.js');
+                return createPostmarkProvider(options);
+            }
+            case 'sendgrid': {
+                const { createSendGridProvider } = await import('./sendgrid.js');
+                return createSendGridProvider(options);
+            }
+            case 'mailgun': {
+                const { createMailgunProvider } = await import('./mailgun.js');
+                return createMailgunProvider(options);
+            }
+            case 'ses': {
+                const { createSesProvider } = await import('./ses.js');
+                return createSesProvider(options);
+            }
+            case 'smtp': {
+                const { createSmtpProvider } = await import('./smtp.js');
+                return createSmtpProvider({
+                    host: options.host,
+                    port: options.port,
+                    secure: options.secure,
+                    ...(options.user ? { user: options.user } : {}),
+                    ...(options.password ? { password: options.password } : {}),
+                    connectionTimeout: options.connectionTimeout,
+                    greetingTimeout: options.greetingTimeout,
+                    socketTimeout: options.socketTimeout,
+                });
+            }
+        }
+    }
+    catch (error) {
+        const moduleNotFound = error;
+        if (moduleNotFound?.code === 'ERR_MODULE_NOT_FOUND') {
+            const dependencies = {
+                brevo: '@getbrevo/brevo',
+                mailgun: 'mailgun.js and form-data',
+                postmark: 'postmark',
+                resend: 'resend',
+                sendgrid: '@sendgrid/mail',
+                ses: '@aws-sdk/client-sesv2',
+                smtp: 'nodemailer',
+            };
+            const dependency = dependencies[options.provider];
+            throw new MailError(`Install the optional provider package "${dependency}" to use ${options.provider}.`, 'configuration', options.provider, false, { cause: error });
+        }
+        throw error;
+    }
+}

package/dist/webhooks/normalize.d.ts

@@ -0,0 +1,6 @@
+import type { EmailWebhookEvent } from './types.js';
+export declare function normalizeResend(payload: unknown): readonly EmailWebhookEvent[];
+export declare function normalizeMailgun(payload: unknown): readonly EmailWebhookEvent[];
+export declare function normalizeSendGrid(payload: unknown): readonly EmailWebhookEvent[];
+export declare function normalizeSes(payload: unknown): readonly EmailWebhookEvent[];
+export declare function normalizeProviderEvents(provider: 'brevo' | 'postmark', payload: unknown): readonly EmailWebhookEvent[];