typedmailer 1.1.0 → 1.3.0

package/dist/webhooks.js

@@ -1,19 +1,14 @@
-import { createHmac, createVerify, timingSafeEqual, X509Certificate } from 'node:crypto';
-export class WebhookVerificationError extends Error {
-    code;
-    constructor(code) {
-        super(code === 'invalid_signature'
-            ? 'The webhook request could not be authenticated.'
-            : code === 'unsupported_event'
-                ? 'The provider webhook event is not supported.'
-                : 'The provider webhook payload is invalid.');
-        this.code = code;
-        this.name = 'WebhookVerificationError';
-    }
-}
-const defaultTimestampToleranceSeconds = 300;
+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';
+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)) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
     const rawBody = Buffer.from(input.rawBody);
     let payload;
     try {
@@ -40,378 +35,3 @@ export async function verifyWebhook(input) {
             return normalizeSes(await verifySnsNotification(input, payload));
     }
 }
-function verifyResend(input, rawBody) {
-    const messageId = getHeader(input.headers, 'svix-id');
-    const timestamp = getHeader(input.headers, 'svix-timestamp');
-    const signatures = getHeader(input.headers, 'svix-signature');
-    assertRecentTimestamp(timestamp, input.now, input.toleranceSeconds);
-    if (!messageId || !signatures || !input.webhookSecret.startsWith('whsec_')) {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    let key;
-    try {
-        key = Buffer.from(input.webhookSecret.slice('whsec_'.length), 'base64');
-    }
-    catch {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    if (key.length === 0)
-        throw new WebhookVerificationError('invalid_signature');
-    const expected = createHmac('sha256', key).update(`${messageId}.${timestamp}.`).update(rawBody).digest();
-    const matches = signatures
-        .split(' ')
-        .some((item) => item.startsWith('v1,') && safeEqual(expected, decodeBase64(item.slice(3))));
-    if (!matches)
-        throw new WebhookVerificationError('invalid_signature');
-}
-function verifyMailgun(input, payload) {
-    const root = asRecord(payload);
-    const signature = asRecord(root.signature);
-    const timestamp = asString(signature.timestamp);
-    const token = asString(signature.token);
-    const received = asString(signature.signature);
-    assertRecentTimestamp(timestamp, input.now, input.toleranceSeconds);
-    if (!timestamp || !token || !received || !input.signingKey) {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    const expected = createHmac('sha256', input.signingKey).update(`${timestamp}${token}`).digest('hex');
-    if (!safeEqual(Buffer.from(expected, 'hex'), decodeHex(received))) {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-}
-function verifySendGrid(input, rawBody) {
-    const timestamp = getHeader(input.headers, 'x-twilio-email-event-webhook-timestamp');
-    const signature = getHeader(input.headers, 'x-twilio-email-event-webhook-signature');
-    assertRecentTimestamp(timestamp, input.now, input.toleranceSeconds);
-    if (!timestamp || !signature || !input.publicKey)
-        throw new WebhookVerificationError('invalid_signature');
-    try {
-        const verifier = createVerify('sha256');
-        verifier.update(timestamp);
-        verifier.update(rawBody);
-        verifier.end();
-        if (!verifier.verify(input.publicKey, signature, 'base64')) {
-            throw new WebhookVerificationError('invalid_signature');
-        }
-    }
-    catch (error) {
-        if (error instanceof WebhookVerificationError)
-            throw error;
-        throw new WebhookVerificationError('invalid_signature');
-    }
-}
-function verifyAuthorization(input, headerName) {
-    const received = getHeader(input.headers, headerName);
-    if (!received || !input.authorization || !safeEqual(Buffer.from(received), Buffer.from(input.authorization))) {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-}
-async function verifySnsNotification(input, payload) {
-    const envelope = asRecord(payload);
-    const topicArn = asString(envelope.TopicArn);
-    const signingCertUrl = asString(envelope.SigningCertURL);
-    const signature = asString(envelope.Signature);
-    const signatureVersion = asString(envelope.SignatureVersion);
-    if (envelope.Type !== 'Notification' ||
-        topicArn !== input.topicArn ||
-        !signingCertUrl ||
-        !signature ||
-        (signatureVersion !== '1' && signatureVersion !== '2')) {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    let certificateUrl;
-    try {
-        certificateUrl = new URL(signingCertUrl);
-    }
-    catch {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    const topicMatch = /^arn:(aws|aws-us-gov|aws-cn):sns:([a-z0-9-]+):\d{12}:[^:]+$/.exec(input.topicArn);
-    const expectedHost = topicMatch
-        ? topicMatch[1] === 'aws-cn'
-            ? `sns.${topicMatch[2]}.amazonaws.com.cn`
-            : `sns.${topicMatch[2]}.amazonaws.com`
-        : undefined;
-    if (certificateUrl.protocol !== 'https:' ||
-        certificateUrl.username ||
-        certificateUrl.password ||
-        certificateUrl.port ||
-        certificateUrl.search ||
-        certificateUrl.hash ||
-        certificateUrl.hostname !== expectedHost ||
-        !/^\/SimpleNotificationService-[A-Za-z0-9_-]+\.pem$/.test(certificateUrl.pathname)) {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    let response;
-    try {
-        response = await fetch(certificateUrl, { redirect: 'error', signal: AbortSignal.timeout(5_000) });
-    }
-    catch {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    if (!response.ok)
-        throw new WebhookVerificationError('invalid_signature');
-    let certificateBody;
-    try {
-        certificateBody = await response.text();
-    }
-    catch {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    if (certificateBody.length > 32_768)
-        throw new WebhookVerificationError('invalid_signature');
-    try {
-        const certificate = new X509Certificate(certificateBody);
-        const now = input.now ?? new Date();
-        if (!certificate.subject.split('\n').some((line) => line === 'CN=Amazon SNS') ||
-            now < new Date(certificate.validFrom) ||
-            now > new Date(certificate.validTo)) {
-            throw new WebhookVerificationError('invalid_signature');
-        }
-        const fields = snsFields(envelope);
-        const verifier = createVerify(signatureVersion === '2' ? 'sha256' : 'sha1');
-        verifier.update(fields);
-        verifier.end();
-        if (!verifier.verify(certificate.publicKey, signature, 'base64')) {
-            throw new WebhookVerificationError('invalid_signature');
-        }
-    }
-    catch (error) {
-        if (error instanceof WebhookVerificationError)
-            throw error;
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    try {
-        const message = JSON.parse(asString(envelope.Message) ?? '');
-        return message;
-    }
-    catch {
-        throw new WebhookVerificationError('invalid_payload');
-    }
-}
-function snsFields(envelope) {
-    const fields = ['Message', 'MessageId'];
-    if (envelope.Subject !== undefined)
-        fields.push('Subject');
-    fields.push('Timestamp', 'TopicArn', 'Type');
-    return fields.map((field) => `${field}\n${asString(envelope[field]) ?? ''}\n`).join('');
-}
-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),
-        }),
-    ];
-}
-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),
-        }),
-    ];
-}
-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),
-        });
-    });
-}
-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),
-            }),
-        ];
-}
-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';
-}
-function assertRecentTimestamp(value, now, toleranceSeconds) {
-    if (!value || !/^\d+$/.test(value))
-        throw new WebhookVerificationError('invalid_signature');
-    const timestamp = Number(value);
-    const tolerance = toleranceSeconds ?? defaultTimestampToleranceSeconds;
-    if (!Number.isSafeInteger(timestamp) || !Number.isSafeInteger(tolerance) || tolerance < 1) {
-        throw new WebhookVerificationError('invalid_signature');
-    }
-    const seconds = Math.floor((now ?? new Date()).getTime() / 1000);
-    if (Math.abs(seconds - timestamp) > tolerance)
-        throw new WebhookVerificationError('invalid_signature');
-}
-function getHeader(headers, name) {
-    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
-    return typeof entry === 'string' ? entry : Array.isArray(entry) ? entry.join(' ') : undefined;
-}
-function safeEqual(left, right) {
-    return left.byteLength === right.byteLength && timingSafeEqual(left, right);
-}
-function decodeBase64(value) {
-    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value))
-        return Buffer.alloc(0);
-    return Buffer.from(value, 'base64');
-}
-function decodeHex(value) {
-    if (!/^(?:[a-fA-F0-9]{2})+$/.test(value))
-        return Buffer.alloc(0);
-    return Buffer.from(value, 'hex');
-}
-function parseDate(value) {
-    if (typeof value === 'number' && Number.isFinite(value)) {
-        const milliseconds = value < 10_000_000_000 ? value * 1000 : value;
-        const result = new Date(milliseconds);
-        return Number.isNaN(result.getTime()) ? undefined : result;
-    }
-    if (typeof value === 'string' && value.length > 0) {
-        const result = new Date(value);
-        return Number.isNaN(result.getTime()) ? undefined : result;
-    }
-    return undefined;
-}
-function asRecord(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        throw new WebhookVerificationError('invalid_payload');
-    }
-    return value;
-}
-function asOptionalRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value)
-        ? value
-        : undefined;
-}
-function asString(value) {
-    return typeof value === 'string' && value.length > 0 ? value : undefined;
-}
-function asId(value) {
-    return typeof value === 'string' || typeof value === 'number' ? String(value) : undefined;
-}
-function isString(value) {
-    return typeof value === 'string';
-}
-function asStringArray(value) {
-    return Array.isArray(value) ? value.filter(isString) : [];
-}
-function firstString(value) {
-    return asString(value) ?? asStringArray(value)[0];
-}

package/docs/provider-contracts.md

@@ -1,6 +1,6 @@
 # Provider behavior contracts
 
-The adapters provide one `createMailer(...).send(...)` interface, while provider APIs differ. This page records the behavior callers may rely on. The capability table in the README is the quick reference; adapter contract tests in `tests/provider-adapters.test.ts` are the executable mapping checks.
+The adapters provide one `createMailer(...).send(...)` interface, while provider APIs differ. This page records the behavior callers may rely on. The capability table in the README is the quick reference; built-in adapter contract tests are organized by provider under `tests/providers/`.
 
 ## Shared guarantees
 
@@ -23,8 +23,12 @@ The adapters provide one `createMailer(...).send(...)` interface, while provider
 | Amazon SES | No                | No              | Yes      | Yes                | Unsupported             |
 | SMTP       | Yes               | No              | No       | Yes                | SMTP connection check   |
 
-Attachments are buffered for provider SDK requests. Large-file streaming belongs in the application. `contentId` is supported by the providers listed as supporting inline attachments. `verifyConnection()` is only available for SMTP because the API providers do not offer a side-effect-free check through this interface.
+Attachments are buffered for provider SDK requests. Configure `maxAttachmentBytes` on `createMailer()` to enforce an aggregate byte cap over all attachment content; strings are counted as UTF-8 bytes and `Uint8Array` content by `byteLength`. The option has no default cap to preserve existing behavior. Large-file streaming belongs in the application. `contentId` is supported by the providers listed as supporting inline attachments. `verifyConnection()` is only available for SMTP because the API providers do not offer a side-effect-free check through this interface.
 
 ## Updating a provider adapter
 
-When changing an adapter, update the README capability table and this contract if caller-visible behavior changes. Add or adjust adapter tests for the provider payload, unsupported fields, returned message ID, and error normalization. Keep provider SDK versions within the declared peer range and verify both the locked SDK and minimum supported SDK set.
+When changing an adapter, add its configuration schema and lazy loader in `src/providers/registry.ts`, keep its implementation in `src/providers/<provider>.ts`, and update the README capability table and this contract if caller-visible behavior changes. Add or adjust adapter tests for the provider payload, unsupported fields, returned message ID, and error normalization. Keep provider SDK versions within the declared peer range and verify both the locked SDK and minimum supported SDK set. CI derives the minimum-version install list from each peer range's explicit lower bound so the support metadata and compatibility check stay aligned.
+
+## Custom adapters
+
+Applications can provide a `ProviderAdapter<TName>` directly to `createMailer()` without adding a built-in provider. Its `send()` method receives `NormalizedMailInput`: `from` is always set, and `to`, `cc`, and `bcc` are arrays when present. Resolve with `{ messageId }` after the SDK accepts the message. `verifyConnection()` and `close()` are optional; verification rejects with `unsupported` when omitted, while close is a no-op. TypedMailer normalizes thrown errors and tags results with the adapter's name. The generic adapter name is preserved in `SendMailResult<TName>` for TypeScript callers. Custom adapters are responsible for documenting and enforcing unsupported message fields.

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.
+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.
 
 ## Authentication configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedmailer",
-  "version": "1.1.0",
+  "version": "1.3.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",
@@ -45,6 +45,7 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "release:check": "node scripts/release-preflight.mjs",
+    "provider:peer-floor": "node scripts/check-provider-peer-floor.mjs",
     "examples:check": "node --check examples/resend.mjs && node --check examples/ses.mjs && node --check examples/smtp-mailpit.mjs",
     "security:audit": "npm audit --audit-level=high",
     "package:smoke": "node scripts/package-smoke.mjs",
@@ -116,7 +117,7 @@
     "postmark": ">=5.0.0 <6",
     "prettier": "^3.9.9",
     "resend": ">=6.0.0 <7",
-    "typescript": "^5.9.2",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.1",
     "vitest": "^5.0.2"
   },