typedmailer 1.0.1 → 1.1.0

package/CODE_OF_CONDUCT.md

@@ -17,4 +17,4 @@ Harassment, insults, discriminatory language, intimidation, unwelcome sexual att
 
 ## Enforcement
 
-Report conduct concerns privately through GitHub's contact/reporting tools for the repository owner. Reports will be reviewed and handled as fairly and promptly as possible. Maintainers may remove content or restrict participation for behavior that violates this code.
+Report conduct concerns privately using [GitHub's contact and reporting tools](https://github.com/contact) for the repository owner. Reports will be reviewed and handled as fairly and promptly as possible. Maintainers may remove content or restrict participation for behavior that violates this code.

package/README.md

@@ -17,6 +17,8 @@ TypedMailer is a type-safe email library for Node.js and TypeScript applications
 
 Use TypedMailer when you want to switch email providers without coupling application code to a provider SDK. Provider SDKs are optional peer dependencies, and only the selected adapter is loaded.
 
+The separate `typedmailer/webhooks` entry point verifies and normalizes inbound provider events. It does not provide HTTP routing, persistence, or event processing.
+
 ## Install
 
 Install the `typedmailer` npm package with the provider SDK you plan to use:
@@ -45,6 +47,8 @@ TypedMailer is for trusted server-side Node.js runtimes. It is not intended for
 
 ## Quick start
 
+Want to try TypedMailer without provider credentials? Follow the [local Mailpit quick start](docs/quickstart.md).
+
 ```ts
 import { createMailer } from 'typedmailer';
 
@@ -54,15 +58,18 @@ const mailer = createMailer({
   from: 'Example App <noreply@example.com>',
 });
 
-const result = await mailer.send({
-  to: 'person@example.com',
-  subject: 'Welcome',
-  text: 'Your account is ready.',
-  html: '<p>Your account is ready.</p>',
-});
-
-console.log(result.messageId);
-await mailer.close();
+try {
+  const result = await mailer.send({
+    to: 'person@example.com',
+    subject: 'Welcome',
+    text: 'Your account is ready.',
+    html: '<p>Your account is ready.</p>',
+  });
+
+  console.log(result.messageId);
+} finally {
+  await mailer.close();
+}
 ```
 
 ## Providers
@@ -195,6 +202,10 @@ console.log(mailer.sent[0]);
 
 Messages captured by `createTestMailer` return `provider: 'test'` so test results are not mistaken for SMTP deliveries.
 
+## Verify provider webhooks
+
+Use `verifyWebhook` from `typedmailer/webhooks` to authenticate a raw request and receive normalized events. Your HTTP route remains responsible for preserving the raw body, responding to the provider, deduplicating events durably, and applying application changes. See [Webhook verification](docs/webhooks.md) for provider-specific configuration and security requirements.
+
 ## Runnable examples
 
 The repository includes complete Resend, Amazon SES, and local SMTP/Mailpit examples in [`examples/`](examples/). From a clone, copy `examples/.env.example` to `.env`, replace the example sender and recipient with addresses valid for your account, then install the SDK for the chosen provider:
@@ -221,7 +232,7 @@ Provider and transport failures are normalized as `MailError`, with `code`, `pro
 
 `retryable` is guidance from the normalized failure: recognized network failures and rate limits are retryable; API provider 5xx failures are retryable; authentication, configuration, unsupported, and SMTP 5xx failures are not. `deliveryUnknown` is separate: it is true when a send timeout/socket interruption, a provider 5xx, or an accepted response without a message ID means the provider may have accepted the message without returning a clear result. It stays false for verification failures, DNS lookup failures, authentication errors, rate limits, and SMTP response errors. This does not guarantee that retrying is safe. Use provider-supported idempotency where available and apply retry policy in your application. `cause` retains the original SDK error for diagnostics and can contain provider details; avoid logging it without reviewing your data handling policy.
 
-A successful `send()` means the provider accepted the request; it does not confirm inbox delivery. Delivery, bounce, and complaint events require provider webhooks and are outside this package's current scope.
+A successful `send()` means the provider accepted the request; it does not confirm inbox delivery. Verify delivery, bounce, and complaint callbacks with [`typedmailer/webhooks`](docs/webhooks.md).
 
 `verifyConnection()` currently supports SMTP. API provider adapters report `unsupported` because they do not expose a side-effect-free credential check through this API; verify credentials with a controlled provider test message.
 
@@ -238,6 +249,8 @@ A successful `send()` means the provider accepted the request; it does not confi
 
 Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for development and contribution guidelines.
 
+Contributors are expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
 After cloning, run `npm ci` to install dependencies and enable the local Git hooks. Commits run staged-file lint and format checks plus unit tests. Pushes run the full `npm run check` quality gate, including an isolated npm tarball consumer smoke test; GitHub Actions runs it on Node.js 22 and 24 and audits dependencies before merge and publish.
 
 ## License

package/SECURITY.md

@@ -6,4 +6,4 @@ Only the latest published version is currently supported.
 
 ## Reporting a vulnerability
 
-Please do not report security vulnerabilities in public issues. Use GitHub's private vulnerability reporting for this repository. Include the affected version, impact, and a minimal reproduction. Do not include real credentials, recipient data, or message contents.
+Please do not report security vulnerabilities in public issues. Use [GitHub's private vulnerability reporting](https://github.com/erolsenol/typedmailer/security/advisories/new) for this repository. Include the affected version, impact, and a minimal reproduction. Do not include real credentials, recipient data, or message contents.

package/SUPPORT.md

@@ -2,7 +2,7 @@
 
 ## Runtime support
 
-TypedMailer requires Node.js 22 or newer. CI tests Node.js 22 and 24. We support the latest patch release of each Node.js major that is still in its official maintenance or active LTS period; end-of-life Node.js releases are unsupported even when they satisfy the package engine range.
+TypedMailer requires Node.js 22 or newer. CI tests Node.js 22 and 24; Node.js 26 runs as a non-blocking compatibility canary while it is Current. We support the latest patch release of each Node.js major that is in its official maintenance or active LTS period; end-of-life Node.js releases are unsupported even when they satisfy the package engine range.
 
 Install the provider SDK required by your selected adapter. Provider SDKs are optional peer dependencies; see the [provider contracts](docs/provider-contracts.md) and README compatibility table.
 

package/dist/webhooks.d.ts

@@ -0,0 +1,44 @@
+import type { ProviderName } from './types.js';
+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');
+}
+/** Authenticates a provider webhook before returning normalized, typed email events. */
+export declare function verifyWebhook(input: VerifyWebhookInput): Promise<readonly EmailWebhookEvent[]>;
+export {};

package/dist/webhooks.js

@@ -0,0 +1,417 @@
+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;
+/** 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));
+    }
+}
+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/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/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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedmailer",
-  "version": "1.0.1",
+  "version": "1.1.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",
@@ -19,6 +19,10 @@
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
     },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "import": "./dist/webhooks.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -30,6 +34,8 @@
     "SUPPORT.md",
     "docs/provider-contracts.md",
     "docs/integration-testing.md",
+    "docs/quickstart.md",
+    "docs/webhooks.md",
     "CODE_OF_CONDUCT.md"
   ],
   "scripts": {
@@ -99,8 +105,8 @@
     "@aws-sdk/client-sesv2": ">=3.0.0 <4",
     "@getbrevo/brevo": ">=6.0.1 <7",
     "@sendgrid/mail": ">=8.0.0 <9",
-    "@types/node": "^24.5.2",
-    "@types/nodemailer": "^7.0.1",
+    "@types/node": "^26.6.3",
+    "@types/nodemailer": "^8.0.2",
     "eslint": "^10.11.0",
     "form-data": ">=4.0.0 <5",
     "husky": "^9.1.7",