typedmailer 1.0.1 → 1.2.0

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;

package/dist/webhooks/shared.js

@@ -0,0 +1,69 @@
+import { timingSafeEqual } from 'node:crypto';
+import { WebhookVerificationError, defaultTimestampToleranceSeconds } from './types.js';
+export 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');
+}
+export 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;
+}
+export function safeEqual(left, right) {
+    return left.byteLength === right.byteLength && timingSafeEqual(left, right);
+}
+export function decodeBase64(value) {
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(value))
+        return Buffer.alloc(0);
+    return Buffer.from(value, 'base64');
+}
+export function decodeHex(value) {
+    if (!/^(?:[a-fA-F0-9]{2})+$/.test(value))
+        return Buffer.alloc(0);
+    return Buffer.from(value, 'hex');
+}
+export 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;
+}
+export function asRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new WebhookVerificationError('invalid_payload');
+    }
+    return value;
+}
+export function asOptionalRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+export function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export function asId(value) {
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : undefined;
+}
+export function isString(value) {
+    return typeof value === 'string';
+}
+export function asStringArray(value) {
+    return Array.isArray(value) ? value.filter(isString) : [];
+}
+export function firstString(value) {
+    return asString(value) ?? asStringArray(value)[0];
+}

package/dist/webhooks/signatures.d.ts

@@ -0,0 +1,16 @@
+import type { VerifyWebhookInput } from './types.js';
+export declare function verifyResend(input: Extract<VerifyWebhookInput, {
+    provider: 'resend';
+}>, rawBody: Uint8Array): void;
+export declare function verifyMailgun(input: Extract<VerifyWebhookInput, {
+    provider: 'mailgun';
+}>, payload: unknown): void;
+export declare function verifySendGrid(input: Extract<VerifyWebhookInput, {
+    provider: 'sendgrid';
+}>, rawBody: Uint8Array): void;
+export declare function verifyAuthorization(input: Extract<VerifyWebhookInput, {
+    provider: 'brevo' | 'postmark';
+}>, headerName: string): void;
+export declare function verifySnsNotification(input: Extract<VerifyWebhookInput, {
+    provider: 'ses';
+}>, payload: unknown): Promise<unknown>;

package/dist/webhooks/signatures.js

@@ -0,0 +1,159 @@
+import { createHmac, createVerify, X509Certificate } from 'node:crypto';
+import { WebhookVerificationError } from './types.js';
+import { asRecord, asString, assertRecentTimestamp, decodeBase64, decodeHex, getHeader, safeEqual } from './shared.js';
+export 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');
+}
+export 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');
+    }
+}
+export 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');
+    }
+}
+export 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');
+    }
+}
+export 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('');
+}

package/dist/webhooks/types.d.ts

@@ -0,0 +1,43 @@
+export type ProviderName = import('../types.js').ProviderName;
+export type EmailWebhookEventType = 'accepted' | 'delivered' | 'bounced' | 'complained' | 'delayed' | 'opened' | 'clicked' | 'unsubscribed' | 'rejected' | 'failed' | 'other';
+export interface EmailWebhookEvent {
+    readonly provider: Exclude<ProviderName, 'smtp'>;
+    readonly id?: string;
+    readonly type: EmailWebhookEventType;
+    readonly eventType: string;
+    readonly messageId?: string;
+    readonly recipient?: string;
+    readonly occurredAt?: Date;
+    /** Original provider data. It can contain message metadata and personal information. */
+    readonly raw: unknown;
+}
+export type WebhookHeaders = Readonly<Record<string, string | readonly string[] | undefined>>;
+interface RawWebhookInput {
+    readonly rawBody: string | Uint8Array;
+    readonly headers: WebhookHeaders;
+    readonly now?: Date;
+    readonly toleranceSeconds?: number;
+}
+export type VerifyWebhookInput = (RawWebhookInput & {
+    readonly provider: 'resend';
+    readonly webhookSecret: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'mailgun';
+    readonly signingKey: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'sendgrid';
+    readonly publicKey: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'brevo' | 'postmark';
+    readonly authorization: string;
+    readonly authorizationHeader?: string;
+}) | (RawWebhookInput & {
+    readonly provider: 'ses';
+    readonly topicArn: string;
+});
+export declare class WebhookVerificationError extends Error {
+    readonly code: 'invalid_signature' | 'invalid_payload' | 'unsupported_event';
+    constructor(code: 'invalid_signature' | 'invalid_payload' | 'unsupported_event');
+}
+export declare const defaultTimestampToleranceSeconds = 300;
+export {};

package/dist/webhooks/types.js

@@ -0,0 +1,13 @@
+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';
+    }
+}
+export const defaultTimestampToleranceSeconds = 300;

package/dist/webhooks.d.ts

@@ -0,0 +1,5 @@
+import type { EmailWebhookEvent, VerifyWebhookInput } from './webhooks/types.js';
+export type { EmailWebhookEvent, EmailWebhookEventType, VerifyWebhookInput, WebhookHeaders } from './webhooks/types.js';
+export { WebhookVerificationError } from './webhooks/types.js';
+/** Authenticates a provider webhook before returning normalized, typed email events. */
+export declare function verifyWebhook(input: VerifyWebhookInput): Promise<readonly EmailWebhookEvent[]>;

package/dist/webhooks.js

@@ -0,0 +1,32 @@
+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 rawBody = Buffer.from(input.rawBody);
+    let payload;
+    try {
+        payload = JSON.parse(rawBody.toString('utf8'));
+    }
+    catch {
+        throw new WebhookVerificationError('invalid_payload');
+    }
+    switch (input.provider) {
+        case 'resend':
+            verifyResend(input, rawBody);
+            return normalizeResend(payload);
+        case 'mailgun':
+            verifyMailgun(input, payload);
+            return normalizeMailgun(payload);
+        case 'sendgrid':
+            verifySendGrid(input, rawBody);
+            return normalizeSendGrid(payload);
+        case 'brevo':
+        case 'postmark':
+            verifyAuthorization(input, input.authorizationHeader ?? 'authorization');
+            return normalizeProviderEvents(input.provider, payload);
+        case 'ses':
+            return normalizeSes(await verifySnsNotification(input, payload));
+    }
+}

package/docs/integration-testing.md

@@ -1,6 +1,6 @@
 # Integration smoke workflow
 
-The `Provider integration smoke` workflow runs weekly or manually. It is intentionally separate from pull request CI. It always sends one message to an isolated Mailpit service; this does not contact a real mailbox.
+Pull request CI runs a Mailpit integration job with a pinned service image. It verifies SMTP acceptance and then checks Mailpit's REST API for the unique message, recipient, subject, and body. This does not contact a real mailbox. The separate `Provider integration smoke` workflow also runs weekly or manually and always sends one message to an isolated Mailpit service.
 
 The workflow can also send controlled live messages through Resend or Amazon SES. To enable one, set the repository variable `TYPEDMAILER_INTEGRATION_PROVIDERS` to a comma-separated list such as `mailpit,resend` or `mailpit,ses`, then configure the following values:
 

package/docs/provider-contracts.md

@@ -23,8 +23,8 @@ 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.

package/docs/quickstart.md

@@ -0,0 +1,63 @@
+# TypedMailer quick start
+
+Send your first message to a local inbox without provider credentials or a real recipient.
+
+## 1. Install TypedMailer and its SMTP adapter
+
+```sh
+npm install typedmailer nodemailer
+```
+
+## 2. Start Mailpit
+
+With Docker:
+
+```sh
+docker run --rm --name typedmailer-mailpit -p 1025:1025 -p 8025:8025 axllent/mailpit:v1.31.3
+```
+
+Or with Homebrew:
+
+```sh
+brew install mailpit
+mailpit
+```
+
+Mailpit captures messages locally. Open its inbox at <http://127.0.0.1:8025>.
+
+## 3. Create `send.mjs`
+
+```js
+import { createMailer } from 'typedmailer';
+
+const mailer = createMailer({
+  provider: 'smtp',
+  host: '127.0.0.1',
+  port: 1025,
+  secure: false,
+  from: 'TypedMailer Demo <sender@example.test>',
+});
+
+try {
+  await mailer.verifyConnection();
+  const result = await mailer.send({
+    to: 'reader@example.test',
+    subject: 'My first TypedMailer message',
+    text: 'This message was captured by local Mailpit.',
+  });
+
+  console.log(`Mailpit accepted ${result.messageId}`);
+} finally {
+  await mailer.close();
+}
+```
+
+## 4. Run it
+
+```sh
+node send.mjs
+```
+
+Check the captured message in Mailpit. Both addresses use the reserved `.test` domain; this setup sends nothing to the public internet.
+
+To try a real provider, follow the provider-specific setup in the [README](../README.md#providers). To receive delivery, bounce, and complaint events, follow the [webhook guide](webhooks.md).

package/docs/webhooks.md

@@ -0,0 +1,60 @@
+# Verifying and normalizing email webhooks
+
+TypedMailer exposes `verifyWebhook()` from `typedmailer/webhooks`. It authenticates a raw HTTP webhook request before returning normalized event records. It does not start an HTTP server, acknowledge requests, persist event IDs, or perform application actions. Your route owns HTTP responses, durable deduplication, and business logic.
+
+## 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.
+
+## Authentication configuration
+
+| Provider   | Verification input                                 | Provider requirements                                                                                                                                                                 |
+| ---------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Resend     | `webhookSecret`                                    | The endpoint `whsec_...` signing secret; Svix headers are checked and timestamps older than five minutes are rejected by default.                                                     |
+| Mailgun    | `signingKey`                                       | The account webhook signing key; the signed timestamp and token are checked with HMAC-SHA256 and a five-minute default freshness window.                                              |
+| SendGrid   | `publicKey`                                        | The Event Webhook ECDSA public key; signature and timestamp headers are verified against the exact raw body.                                                                          |
+| Brevo      | `authorization` and optional `authorizationHeader` | Configure a custom header or bearer token in Brevo. Brevo does not sign event payloads cryptographically.                                                                             |
+| Postmark   | `authorization` and optional `authorizationHeader` | Configure HTTPS Basic Authentication for the webhook URL. Pass the expected header value, including the `Basic ` prefix, as `authorization`. Postmark does not sign webhook payloads. |
+| Amazon SES | `topicArn`                                         | SNS Notification envelope signatures and expected topic ARN are checked. SNS signing certificates are fetched only from the matching regional SNS HTTPS host.                         |
+
+Resend, Mailgun, and SendGrid reject timestamps outside a five-minute window by default. Set `toleranceSeconds` to change that window or `now` to supply a clock value in deterministic tests. Amazon SNS verification supports `Notification` envelopes; subscription confirmation and unsubscribe envelopes are not handled. SNS verification makes an HTTPS request to retrieve the signing certificate, so account for that outbound request in your network policy.
+
+For providers without signed payloads, protect the endpoint with HTTPS and the provider's configured authentication. For Brevo, `authorization` is the exact value configured for its custom authorization header; pass the same header name through `authorizationHeader` when it is not `authorization`. Do not treat an IP allowlist as the only control unless you can keep it current. SMTP has no provider webhook adapter.
+
+## Example: Resend
+
+```ts
+import { verifyWebhook } from 'typedmailer/webhooks';
+
+const events = await verifyWebhook({
+  provider: 'resend',
+  rawBody: requestBody, // exact bytes or string from the incoming request
+  headers: requestHeaders,
+  webhookSecret: process.env.RESEND_WEBHOOK_SECRET!,
+});
+
+for (const event of events) {
+  if (event.type === 'bounced' && event.messageId) {
+    await markMessageBounced(event.messageId);
+  }
+}
+```
+
+## Normalized event shape
+
+Each event includes `provider`, provider `eventType`, a normalized `type`, and the original provider payload in `raw`. When available, it also includes a provider event ID (`id`), message ID, recipient, and event timestamp (`occurredAt`). `raw` may contain personal data and provider metadata; avoid logging it without review. Unknown provider event names map to `type: 'other'` and retain their original `eventType`.
+
+Normalized types are `accepted`, `delivered`, `bounced`, `complained`, `delayed`, `opened`, `clicked`, `unsubscribed`, `rejected`, `failed`, and `other`.
+
+## Delivery, retries, and deduplication
+
+Providers retry webhook delivery. `verifyWebhook()` verifies authenticity but does not prevent the same authentic event from being processed twice. Persist event IDs (or a stable provider/message/event key when the provider has no event ID) with a unique constraint before applying side effects. Acknowledge only after durable acceptance by your application. Do not log secrets or full event payloads by default.
+
+## Provider references
+
+- [Resend webhook verification](https://resend.com/docs/webhooks/introduction)
+- [Mailgun securing webhooks](https://documentation.mailgun.com/docs/mailgun/user-manual/webhooks/securing-webhooks)
+- [SendGrid signed Event Webhooks](https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features)
+- [Brevo secure webhook calls](https://developers.brevo.com/docs/secured-webhooks)
+- [Postmark webhooks](https://postmarkapp.com/developer/webhooks/webhooks-overview)
+- [Amazon SNS signature verification](https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message.html)