typedmailer 1.1.0 → 1.2.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.
 

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[];

package/dist/webhooks/normalize.js

@@ -0,0 +1,154 @@
+import { WebhookVerificationError } from './types.js';
+import { asId, asOptionalRecord, asRecord, asString, asStringArray, firstString, isString, parseDate, } from './shared.js';
+export function normalizeResend(payload) {
+    const root = asRecord(payload);
+    const data = asRecord(root.data);
+    return [
+        makeEvent('resend', root, {
+            id: asString(root.id),
+            eventType: asString(root.type),
+            type: mapEventType(asString(root.type)),
+            messageId: asString(data.email_id),
+            recipient: firstString(data.to),
+            occurredAt: parseDate(root.created_at),
+        }),
+    ];
+}
+export function normalizeMailgun(payload) {
+    const root = asRecord(payload);
+    const event = asRecord(root['event-data']);
+    const message = asRecord(event.message);
+    const headers = asRecord(message.headers);
+    const eventName = asString(event.event);
+    return [
+        makeEvent('mailgun', event, {
+            id: asId(event.id),
+            eventType: eventName,
+            type: mapEventType(eventName),
+            messageId: asString(headers['message-id']),
+            recipient: asString(event.recipient),
+            occurredAt: parseDate(event.timestamp),
+        }),
+    ];
+}
+export function normalizeSendGrid(payload) {
+    if (!Array.isArray(payload))
+        throw new WebhookVerificationError('invalid_payload');
+    return payload.map((item) => {
+        const event = asRecord(item);
+        const eventName = asString(event.event);
+        return makeEvent('sendgrid', event, {
+            id: asString(event.sg_event_id),
+            eventType: eventName,
+            type: mapEventType(eventName),
+            messageId: asString(event.sg_message_id),
+            recipient: asString(event.email),
+            occurredAt: parseDate(event.timestamp),
+        });
+    });
+}
+export function normalizeSes(payload) {
+    const message = asRecord(payload);
+    const eventName = asString(message.eventType) ?? asString(message.notificationType);
+    const mail = asRecord(message.mail);
+    const bounce = asOptionalRecord(message.bounce);
+    const complaint = asOptionalRecord(message.complaint);
+    const delivery = asOptionalRecord(message.delivery);
+    const recipients = Array.isArray(bounce?.bouncedRecipients)
+        ? bounce.bouncedRecipients
+        : Array.isArray(complaint?.complainedRecipients)
+            ? complaint.complainedRecipients
+            : [];
+    const to = recipients.map((recipient) => asString(asRecord(recipient).emailAddress)).filter(isString);
+    const emails = to.length > 0 ? to : asStringArray(mail.destination);
+    return emails.length > 0
+        ? emails.map((recipient) => makeEvent('ses', message, {
+            id: asString(message.messageId),
+            eventType: eventName,
+            type: mapEventType(eventName),
+            messageId: asString(mail.messageId),
+            recipient,
+            occurredAt: parseDate(delivery?.timestamp) ?? parseDate(bounce?.timestamp),
+        }))
+        : [
+            makeEvent('ses', message, {
+                id: asString(message.messageId),
+                eventType: eventName,
+                type: mapEventType(eventName),
+                messageId: asString(mail.messageId),
+                occurredAt: parseDate(asRecord(message.delivery).timestamp),
+            }),
+        ];
+}
+export function normalizeProviderEvents(provider, payload) {
+    const items = Array.isArray(payload) ? payload : [payload];
+    return items.map((item) => {
+        const event = asRecord(item);
+        const eventName = provider === 'brevo' ? asString(event.event) : asString(event.RecordType);
+        return makeEvent(provider, event, {
+            id: provider === 'brevo'
+                ? (asId(event.id) ?? asString(event['message-id']))
+                : (asId(event.ID) ?? asString(event.MessageID)),
+            eventType: eventName,
+            type: mapEventType(eventName),
+            messageId: provider === 'brevo' ? asString(event['message-id']) : asString(event.MessageID),
+            recipient: provider === 'brevo' ? asString(event.email) : asString(event.Recipient),
+            occurredAt: parseDate(provider === 'brevo' ? (event.ts_epoch ?? event.date) : (event.DeliveredAt ?? event.BouncedAt)),
+        });
+    });
+}
+function makeEvent(provider, raw, fields) {
+    if (!fields.eventType)
+        throw new WebhookVerificationError('invalid_payload');
+    return {
+        provider,
+        raw,
+        eventType: fields.eventType,
+        type: fields.type,
+        ...(fields.id ? { id: fields.id } : {}),
+        ...(fields.messageId ? { messageId: fields.messageId } : {}),
+        ...(fields.recipient ? { recipient: fields.recipient } : {}),
+        ...(fields.occurredAt ? { occurredAt: fields.occurredAt } : {}),
+    };
+}
+function mapEventType(eventType) {
+    const event = eventType?.toLowerCase().replaceAll(/[._ -]/g, '') ?? '';
+    const mappings = {
+        accepted: 'accepted',
+        sent: 'accepted',
+        request: 'accepted',
+        emailsent: 'accepted',
+        delivery: 'delivered',
+        delivered: 'delivered',
+        emaildelivered: 'delivered',
+        bounce: 'bounced',
+        bounced: 'bounced',
+        emailbounced: 'bounced',
+        hardbounce: 'bounced',
+        softbounce: 'bounced',
+        spamcomplaint: 'complained',
+        complaint: 'complained',
+        complained: 'complained',
+        emailcomplained: 'complained',
+        spamreport: 'complained',
+        deferred: 'delayed',
+        deliverydelayed: 'delayed',
+        deliverydelay: 'delayed',
+        emaildeliverydelayed: 'delayed',
+        open: 'opened',
+        opened: 'opened',
+        emailopened: 'opened',
+        click: 'clicked',
+        clicked: 'clicked',
+        emailclicked: 'clicked',
+        unsubscribed: 'unsubscribed',
+        groupunsubscribe: 'unsubscribed',
+        reject: 'rejected',
+        rejected: 'rejected',
+        dropped: 'failed',
+        failed: 'failed',
+        emailfailed: 'failed',
+        renderingfailure: 'failed',
+    };
+    return mappings[event] ?? 'other';
+}

package/dist/webhooks/shared.d.ts

@@ -0,0 +1,14 @@
+import type { WebhookHeaders } from './types.js';
+export declare function assertRecentTimestamp(value: string | undefined, now: Date | undefined, toleranceSeconds: number | undefined): void;
+export declare function getHeader(headers: WebhookHeaders, name: string): string | undefined;
+export declare function safeEqual(left: Uint8Array, right: Uint8Array): boolean;
+export declare function decodeBase64(value: string): Buffer;
+export declare function decodeHex(value: string): Buffer;
+export declare function parseDate(value: unknown): Date | undefined;
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function asOptionalRecord(value: unknown): Record<string, unknown> | undefined;
+export declare function asString(value: unknown): string | undefined;
+export declare function asId(value: unknown): string | undefined;
+export declare function isString(value: unknown): value is string;
+export declare function asStringArray(value: unknown): string[];
+export declare function firstString(value: unknown): string | undefined;