typedmailer 1.3.0 → 1.4.0

package/README.md

@@ -41,6 +41,8 @@ npm install typedmailer @aws-sdk/client-sesv2
 
 Requires Node.js 22 or newer. Provider SDKs are optional peers and are loaded only when their adapter is selected.
 
+For SMTP, use `secure: true` with implicit TLS (commonly port 465), or use STARTTLS with `secure: false` and `requireTLS: true`. Port 587 requires STARTTLS by default; other ports use opportunistic TLS unless `requireTLS` is set.
+
 Supported runtime and release guarantees are documented in [`SUPPORT.md`](SUPPORT.md). Provider behavior guarantees and their test coverage are described in [`docs/provider-contracts.md`](docs/provider-contracts.md). The scheduled and manual provider smoke workflow is documented in [`docs/integration-testing.md`](docs/integration-testing.md).
 
 TypedMailer is for trusted server-side Node.js runtimes. It is not intended for browser or mobile client bundles.

package/dist/providers/brevo.js

@@ -44,7 +44,7 @@ export function createBrevoProvider(options) {
                 return { messageId: result.messageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'brevo');
+                throw normalizeProviderError(error, 'brevo', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/mailgun.js

@@ -62,7 +62,7 @@ export function createMailgunProvider(options) {
                 return { messageId: response.id };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'mailgun');
+                throw normalizeProviderError(error, 'mailgun', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/postmark.js

@@ -42,7 +42,7 @@ export function createPostmarkProvider(options) {
                 return { messageId: response.MessageID };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'postmark');
+                throw normalizeProviderError(error, 'postmark', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/registry.d.ts

@@ -77,6 +77,7 @@ export declare const providerOptions: {
         host: z.ZodString;
         port: z.ZodNumber;
         secure: z.ZodBoolean;
+        requireTLS: z.ZodOptional<z.ZodBoolean>;
         user: z.ZodOptional<z.ZodString>;
         password: z.ZodOptional<z.ZodString>;
         connectionTimeout: z.ZodDefault<z.ZodNumber>;
@@ -147,6 +148,7 @@ export declare const mailerOptionsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     host: z.ZodString;
     port: z.ZodNumber;
     secure: z.ZodBoolean;
+    requireTLS: z.ZodOptional<z.ZodBoolean>;
     user: z.ZodOptional<z.ZodString>;
     password: z.ZodOptional<z.ZodString>;
     connectionTimeout: z.ZodDefault<z.ZodNumber>;

package/dist/providers/registry.js

@@ -27,6 +27,7 @@ export const providerOptions = {
         host: z.string().min(1),
         port: z.number().int().min(1).max(65535),
         secure: z.boolean(),
+        requireTLS: z.boolean().optional(),
         user: z.string().min(1).optional(),
         password: z.string().min(1).optional(),
         connectionTimeout: z.number().int().positive().default(8_000),
@@ -80,6 +81,7 @@ export async function loadProvider(options) {
                     host: options.host,
                     port: options.port,
                     secure: options.secure,
+                    ...(options.requireTLS !== undefined ? { requireTLS: options.requireTLS } : {}),
                     ...(options.user ? { user: options.user } : {}),
                     ...(options.password ? { password: options.password } : {}),
                     connectionTimeout: options.connectionTimeout,

package/dist/providers/sendgrid.js

@@ -50,7 +50,7 @@ export function createSendGridProvider(options) {
                 return { messageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'sendgrid');
+                throw normalizeProviderError(error, 'sendgrid', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/ses.js

@@ -55,7 +55,7 @@ export function createSesProvider(options) {
                 return { messageId: response.MessageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'ses');
+                throw normalizeProviderError(error, 'ses', 'send');
             }
         },
         async verifyConnection() {

package/dist/providers/smtp.d.ts

@@ -3,6 +3,7 @@ interface SmtpOptions {
     host: string;
     port: number;
     secure: boolean;
+    requireTLS?: boolean;
     user?: string;
     password?: string;
     connectionTimeout: number;

package/dist/providers/smtp.js

@@ -11,7 +11,7 @@ export function createSmtpProvider(options) {
         host: options.host,
         port: options.port,
         secure: options.secure,
-        ...(options.port === 587 && !options.secure ? { requireTLS: true } : {}),
+        requireTLS: options.requireTLS ?? (options.port === 587 && !options.secure),
         connectionTimeout: options.connectionTimeout,
         greetingTimeout: options.greetingTimeout,
         socketTimeout: options.socketTimeout,
@@ -53,7 +53,7 @@ export function createSmtpProvider(options) {
                 return { messageId: result.messageId };
             }
             catch (error) {
-                throw normalizeProviderError(error, 'smtp');
+                throw normalizeProviderError(error, 'smtp', 'send');
             }
         },
         async verifyConnection() {

package/dist/webhooks/normalize.d.ts

@@ -1,6 +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[];
+export declare function normalizeSendGrid(payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];
+export declare function normalizeSes(payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];
+export declare function normalizeProviderEvents(provider: 'brevo' | 'postmark', payload: unknown, maxEvents: number): readonly EmailWebhookEvent[];

package/dist/webhooks/normalize.js

@@ -31,9 +31,10 @@ export function normalizeMailgun(payload) {
         }),
     ];
 }
-export function normalizeSendGrid(payload) {
-    if (!Array.isArray(payload))
+export function normalizeSendGrid(payload, maxEvents) {
+    if (!Array.isArray(payload) || payload.length > maxEvents) {
         throw new WebhookVerificationError('invalid_payload');
+    }
     return payload.map((item) => {
         const event = asRecord(item);
         const eventName = asString(event.event);
@@ -47,7 +48,7 @@ export function normalizeSendGrid(payload) {
         });
     });
 }
-export function normalizeSes(payload) {
+export function normalizeSes(payload, maxEvents) {
     const message = asRecord(payload);
     const eventName = asString(message.eventType) ?? asString(message.notificationType);
     const mail = asRecord(message.mail);
@@ -59,6 +60,10 @@ export function normalizeSes(payload) {
         : Array.isArray(complaint?.complainedRecipients)
             ? complaint.complainedRecipients
             : [];
+    if (recipients.length > maxEvents ||
+        (!recipients.length && Array.isArray(mail.destination) && mail.destination.length > maxEvents)) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
     const to = recipients.map((recipient) => asString(asRecord(recipient).emailAddress)).filter(isString);
     const emails = to.length > 0 ? to : asStringArray(mail.destination);
     return emails.length > 0
@@ -80,8 +85,10 @@ export function normalizeSes(payload) {
             }),
         ];
 }
-export function normalizeProviderEvents(provider, payload) {
+export function normalizeProviderEvents(provider, payload, maxEvents) {
     const items = Array.isArray(payload) ? payload : [payload];
+    if (items.length > maxEvents)
+        throw new WebhookVerificationError('invalid_payload');
     return items.map((item) => {
         const event = asRecord(item);
         const eventName = provider === 'brevo' ? asString(event.event) : asString(event.RecordType);

package/dist/webhooks/types.d.ts

@@ -16,6 +16,7 @@ interface RawWebhookInput {
     readonly rawBody: string | Uint8Array;
     readonly headers: WebhookHeaders;
     readonly maxBodyBytes?: number;
+    readonly maxEvents?: number;
     readonly now?: Date;
     readonly toleranceSeconds?: number;
 }

package/dist/webhooks.js

@@ -1,12 +1,18 @@
 import { WebhookVerificationError } from './webhooks/types.js';
 import { verifyAuthorization, verifyMailgun, verifyResend, verifySendGrid, verifySnsNotification, } from './webhooks/signatures.js';
 import { normalizeMailgun, normalizeProviderEvents, normalizeResend, normalizeSendGrid, normalizeSes, } from './webhooks/normalize.js';
+const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+const DEFAULT_MAX_EVENTS = 1_000;
 export { WebhookVerificationError } from './webhooks/types.js';
 /** Authenticates a provider webhook before returning normalized, typed email events. */
 export async function verifyWebhook(input) {
     const rawBodyByteLength = typeof input.rawBody === 'string' ? Buffer.byteLength(input.rawBody) : input.rawBody.byteLength;
-    if (input.maxBodyBytes !== undefined &&
-        (!Number.isSafeInteger(input.maxBodyBytes) || input.maxBodyBytes < 1 || rawBodyByteLength > input.maxBodyBytes)) {
+    const maxBodyBytes = input.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1 || rawBodyByteLength > maxBodyBytes) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
+    const maxEvents = input.maxEvents ?? DEFAULT_MAX_EVENTS;
+    if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) {
         throw new WebhookVerificationError('invalid_payload');
     }
     const rawBody = Buffer.from(input.rawBody);
@@ -26,12 +32,12 @@ export async function verifyWebhook(input) {
             return normalizeMailgun(payload);
         case 'sendgrid':
             verifySendGrid(input, rawBody);
-            return normalizeSendGrid(payload);
+            return normalizeSendGrid(payload, maxEvents);
         case 'brevo':
         case 'postmark':
             verifyAuthorization(input, input.authorizationHeader ?? 'authorization');
-            return normalizeProviderEvents(input.provider, payload);
+            return normalizeProviderEvents(input.provider, payload, maxEvents);
         case 'ses':
-            return normalizeSes(await verifySnsNotification(input, payload));
+            return normalizeSes(await verifySnsNotification(input, payload), maxEvents);
     }
 }

package/docs/webhooks.md

@@ -4,7 +4,7 @@ TypedMailer exposes `verifyWebhook()` from `typedmailer/webhooks`. It authentica
 
 ## Raw request bodies
 
-Pass the exact bytes received by your HTTP framework. Parsing JSON and serializing it again changes the signed input and causes verification to fail. `rawBody` accepts a string or `Uint8Array`; `headers` is a case-insensitive record of request header names and values. If the framework parses request bodies automatically, configure a raw-body capture before its JSON parser. Apply an HTTP request-body size limit before buffering the body. You can also set `maxBodyBytes` on `verifyWebhook()` to reject an oversized payload before JSON parsing; it has no default because provider event batches vary in size.
+Pass the exact bytes received by your HTTP framework. Parsing JSON and serializing it again changes the signed input and causes verification to fail. `rawBody` accepts a string or `Uint8Array`; `headers` is a case-insensitive record of request header names and values. If the framework parses request bodies automatically, configure a raw-body capture before its JSON parser. Apply an HTTP request-body size limit before buffering the body. `verifyWebhook()` also rejects bodies larger than 1 MiB by default; set `maxBodyBytes` to a suitable positive value for your provider and expected batch size. Normalized event batches are limited to 1,000 events by default; set `maxEvents` to adjust that limit. Keep both limits finite and consistent with the upstream request limit.
 
 ## Authentication configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedmailer",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "A type-safe Node.js email library with one API for Resend, Brevo, Postmark, SendGrid, Mailgun, Amazon SES, or SMTP.",
   "author": "Erol Senol",
   "license": "MIT",