typedmailer 1.1.0 → 1.3.0

package/README.md

@@ -160,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.
 
@@ -176,6 +176,32 @@ Provider capabilities differ. Unsupported fields return a `MailError` with code
 | Amazon SES | No                 | No               | Yes      | Yes                | Unsupported          |
 | SMTP       | Yes                | No               | No       | Yes                | Yes                  |
 
+### Custom providers
+
+Use `ProviderAdapter` when your provider is not built in or you need to wrap an existing mail SDK. The adapter receives normalized addresses and the configured default sender; its `send` method must resolve with the provider message ID. Implement `verifyConnection` only when the provider offers a safe connection check, and use `close` to release resources such as pooled clients.
+
+```ts
+import { createMailer, type ProviderAdapter } from 'typedmailer';
+
+const adapter: ProviderAdapter<'acme'> = {
+  name: 'acme',
+  async send(message) {
+    const response = await acmeClient.sendEmail(message);
+    return { messageId: response.id };
+  },
+  async close() {
+    await acmeClient.close();
+  },
+};
+
+const mailer = createMailer({ provider: adapter, from: 'noreply@example.com' });
+const result = await mailer.send({ to: 'person@example.com', subject: 'Hello', text: 'Hi' });
+// result.provider is typed as "acme".
+await mailer.close();
+```
+
+The custom adapter owns provider SDK setup, field support, and error handling. Throwing an error still passes through TypedMailer error normalization. Connection verification is reported as `unsupported` when the adapter does not implement it.
+
 ```ts
 await mailer.send({
   to: [{ email: 'person@example.com', name: 'Sam' }],

package/dist/config.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { MailAddress } from './types.js';
 export declare const mailInputSchema: z.ZodObject<{
     from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodString, z.ZodObject<{
         email: z.ZodString;
@@ -44,14 +45,8 @@ export declare const mailInputSchema: z.ZodObject<{
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strict>;
 export declare function normalizeAddresses<T>(value: T | readonly T[] | undefined): readonly T[] | undefined;
-export declare function emailOf(address: string | {
-    email: string;
-    name?: string;
-}): string;
-export declare function addressWithName(address: string | {
-    email: string;
-    name?: string;
-}): {
+export declare function emailOf(address: MailAddress): string;
+export declare function addressWithName(address: MailAddress): {
     email: string;
     name?: string;
 };

package/dist/config.js

@@ -53,8 +53,9 @@ export function emailOf(address) {
     return namedAddress?.[2] ?? address;
 }
 export function addressWithName(address) {
-    if (typeof address !== 'string')
-        return address;
+    if (typeof address !== 'string') {
+        return { email: address.email, ...(address.name !== undefined ? { name: address.name } : {}) };
+    }
     const namedAddress = address.match(/^(.+) <([^<>\s]+@[^<>\s]+)>$/);
     return namedAddress ? { email: namedAddress[2], name: namedAddress[1] } : { email: address };
 }

package/dist/index.d.ts

@@ -1,77 +1,9 @@
-import { z } from 'zod';
-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 declare function createMailer(input: MailerOptions): Mailer;
+import { type MailerOptions as BuiltInMailerOptions } from './providers/registry.js';
+import type { CustomMailerOptions, Mailer, ProviderName } from './types.js';
+export type MailerOptions = BuiltInMailerOptions | CustomMailerOptions;
+export declare function createMailer<const TProvider extends string>(input: CustomMailerOptions<TProvider>): Mailer<TProvider>;
+export declare function createMailer(input: BuiltInMailerOptions): Mailer<ProviderName | 'test'>;
+export declare function createMailer(input: MailerOptions): Mailer<string>;
 export { MailError } from './errors.js';
 export type { MailErrorCode, MailErrorOperation, MailErrorOptions } from './errors.js';
-export type { MailAddress, MailAttachment, Mailer, NormalizedMailInput, ProviderName, SendMailInput, SendMailResult, } from './types.js';
+export type { CustomMailerOptions, MailAddress, MailAttachment, Mailer, NormalizedMailInput, ProviderAdapter, ProviderName, ProviderSendResult, SendMailInput, SendMailResult, } from './types.js';

package/dist/index.js

@@ -1,101 +1,38 @@
+import { Buffer } from 'node:buffer';
 import { z } from 'zod';
 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,
-                });
+import { loadProvider, mailerBaseOptionsSchema, mailerOptionsSchema, } from './providers/registry.js';
+function isProviderAdapter(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const adapter = value;
+    return (typeof adapter.name === 'string' &&
+        adapter.name.length > 0 &&
+        adapter.name.trim() === adapter.name &&
+        typeof adapter.send === 'function' &&
+        (adapter.verifyConnection === undefined || typeof adapter.verifyConnection === 'function') &&
+        (adapter.close === undefined || typeof adapter.close === 'function'));
+}
+const customMailerOptionsSchema = mailerBaseOptionsSchema
+    .extend({ provider: z.custom(isProviderAdapter, 'Invalid custom provider adapter.') })
+    .strict();
+function isCustomOptions(input) {
+    return typeof input.provider !== 'string';
+}
+function createCustomProvider(adapter) {
+    return {
+        send: (input) => adapter.send(input),
+        async verifyConnection() {
+            if (!adapter.verifyConnection) {
+                throw new MailError(`Connection verification is not supported by the custom provider "${adapter.name}".`, 'unsupported', adapter.name, false);
             }
-        }
-    }
-    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;
-    }
+            await adapter.verifyConnection();
+        },
+        async close() {
+            await adapter.close?.();
+        },
+    };
 }
 export function createMailer(input) {
     let providerPromise;
@@ -103,24 +40,20 @@ export function createMailer(input) {
     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 = isCustomOptions(input)
+        ? customMailerOptionsSchema.parse(input)
+        : mailerOptionsSchema.parse(input);
+    const providerName = typeof parsedOptions.provider === 'string' ? parsedOptions.provider : parsedOptions.provider.name;
     const assertOpen = () => {
         if (closed)
-            throw new MailError('Mailer has been closed.', 'configuration', parsedOptions.provider, false);
+            throw new MailError('Mailer has been closed.', 'configuration', providerName, false);
     };
     const getProvider = () => {
         assertOpen();
-        providerPromise ??= loadProvider(parsedOptions);
+        providerPromise ??=
+            typeof parsedOptions.provider === 'string'
+                ? loadProvider(parsedOptions)
+                : Promise.resolve(createCustomProvider(parsedOptions.provider));
         return providerPromise;
     };
     const runWithProvider = async (operation) => {
@@ -141,9 +74,18 @@ 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', providerName, false);
+            }
+            const cc = normalizeAddresses(parsed.cc);
+            const bcc = normalizeAddresses(parsed.bcc);
             const normalized = {
-                from: (parsed.from ?? parsedOptions.from),
-                to: (normalizeAddresses(parsed.to) ?? []),
+                from: parsed.from ?? parsedOptions.from,
+                to: normalizeAddresses(parsed.to) ?? [],
                 subject: parsed.subject,
                 ...(parsed.messageId ? { messageId: parsed.messageId } : {}),
                 ...(parsed.text !== undefined ? { text: parsed.text } : {}),
@@ -161,24 +103,20 @@ export function createMailer(input) {
                     : {}),
                 ...(parsed.idempotencyKey ? { idempotencyKey: parsed.idempotencyKey } : {}),
                 ...(parsed.metadata ? { metadata: parsed.metadata } : {}),
-                ...(normalizeAddresses(parsed.cc)
-                    ? { cc: normalizeAddresses(parsed.cc) }
-                    : {}),
-                ...(normalizeAddresses(parsed.bcc)
-                    ? { bcc: normalizeAddresses(parsed.bcc) }
-                    : {}),
+                ...(cc ? { cc } : {}),
+                ...(bcc ? { bcc } : {}),
                 ...(parsed.replyTo ? { replyTo: parsed.replyTo } : {}),
             };
             try {
                 const result = await runWithProvider((provider) => provider.send(normalized));
                 return {
-                    provider: parsedOptions.provider,
+                    provider: providerName,
                     messageId: result.messageId,
                     acceptedAt: new Date(),
                 };
             }
             catch (error) {
-                throw normalizeProviderError(error, parsedOptions.provider, 'send');
+                throw normalizeProviderError(error, providerName, 'send');
             }
         },
         async verifyConnection() {
@@ -186,7 +124,7 @@ export function createMailer(input) {
                 await runWithProvider((provider) => provider.verifyConnection());
             }
             catch (error) {
-                throw normalizeProviderError(error, parsedOptions.provider);
+                throw normalizeProviderError(error, providerName);
             }
         },
         async close() {

package/dist/providers/registry.d.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import type { MailProvider } from '../types.js';
+export declare const mailerBaseOptionsSchema: 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>;
+}, z.core.$strip>;
+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';
+export const mailerBaseOptionsSchema = 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: mailerBaseOptionsSchema.extend({ provider: z.literal('resend'), apiKey: z.string().min(1) }),
+    brevo: mailerBaseOptionsSchema.extend({ provider: z.literal('brevo'), apiKey: z.string().min(1) }),
+    postmark: mailerBaseOptionsSchema.extend({ provider: z.literal('postmark'), apiKey: z.string().min(1) }),
+    sendgrid: mailerBaseOptionsSchema.extend({ provider: z.literal('sendgrid'), apiKey: z.string().min(1) }),
+    mailgun: mailerBaseOptionsSchema.extend({
+        provider: z.literal('mailgun'),
+        apiKey: z.string().min(1),
+        domain: z.string().min(1),
+        region: z.enum(['us', 'eu']).default('us'),
+    }),
+    ses: mailerBaseOptionsSchema.extend({ provider: z.literal('ses'), region: z.string().min(1) }),
+    smtp: mailerBaseOptionsSchema
+        .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;
+    }
+}