@hogsend/plugin-resend 0.0.1

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2025 Doug Silkstone and Hogsend contributors
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,9 @@
+# @hogsend/plugin-resend
+
+Resend email delivery for [Hogsend](https://github.com/dougwithseismic/hogsend):
+single + batch sends, tracked sends, webhook parsing/verification, and an email
+service with bounce tracking.
+
+This package ships raw TypeScript source; consumers bundle it via their own build
+(tsup `noExternal`). See the
+[release model](https://github.com/dougwithseismic/hogsend/blob/main/docs/RELEASING.md).

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@hogsend/plugin-resend",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dougwithseismic/hogsend.git",
+    "directory": "packages/plugin-resend"
+  },
+  "sideEffects": false,
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "resend": "^6.12.3",
+    "svix": "^1.94.0",
+    "@hogsend/email": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.7",
+    "@repo/typescript-config": "^0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  }
+}

package/src/__tests__/send.test.ts

@@ -0,0 +1,198 @@
+import { EmailSendError } from "@hogsend/email";
+import { createElement } from "react";
+import type { Resend } from "resend";
+import { describe, expect, it, vi } from "vitest";
+import { sendBatchEmails, sendEmail } from "../send.js";
+
+function mockResendClient(overrides?: {
+  sendFn?: () => Promise<unknown>;
+  batchFn?: () => Promise<unknown>;
+}) {
+  return {
+    emails: {
+      send:
+        overrides?.sendFn ??
+        vi.fn().mockResolvedValue({
+          data: { id: "resend_123" },
+          error: null,
+        }),
+    },
+    batch: {
+      send:
+        overrides?.batchFn ??
+        vi.fn().mockResolvedValue({
+          data: { data: [{ id: "batch_1" }, { id: "batch_2" }] },
+          error: null,
+        }),
+    },
+  } as unknown as Resend;
+}
+
+function dummyElement() {
+  return createElement("div", null, "test");
+}
+
+describe("sendEmail", () => {
+  it("sends successfully and returns id", async () => {
+    const client = mockResendClient();
+    const result = await sendEmail({
+      client,
+      options: {
+        from: "test@hogsend.com",
+        to: "user@example.com",
+        subject: "Test",
+        react: dummyElement(),
+      },
+    });
+    expect(result.id).toBe("resend_123");
+  });
+
+  it("normalizes string recipient to array", async () => {
+    const sendFn = vi.fn().mockResolvedValue({
+      data: { id: "resend_123" },
+      error: null,
+    });
+    const client = mockResendClient({ sendFn });
+
+    await sendEmail({
+      client,
+      options: {
+        from: "test@hogsend.com",
+        to: "user@example.com",
+        subject: "Test",
+        react: dummyElement(),
+      },
+    });
+
+    expect(sendFn).toHaveBeenCalledWith(
+      expect.objectContaining({ to: ["user@example.com"] }),
+    );
+  });
+
+  it("throws EmailSendError on API error", async () => {
+    const client = mockResendClient({
+      sendFn: vi.fn().mockResolvedValue({
+        data: null,
+        error: { message: "Invalid API key" },
+      }),
+    });
+
+    await expect(
+      sendEmail({
+        client,
+        options: {
+          from: "test@hogsend.com",
+          to: "user@example.com",
+          subject: "Test",
+          react: dummyElement(),
+        },
+        retryOptions: { maxRetries: 0 },
+      }),
+    ).rejects.toThrow(EmailSendError);
+  });
+
+  it("retries on transient errors", async () => {
+    let attempt = 0;
+    const sendFn = vi.fn().mockImplementation(async () => {
+      attempt++;
+      if (attempt < 3) {
+        return {
+          data: null,
+          error: { message: "rate limit exceeded", statusCode: 429 },
+        };
+      }
+      return { data: { id: "resend_success" }, error: null };
+    });
+    const client = mockResendClient({ sendFn });
+
+    const result = await sendEmail({
+      client,
+      options: {
+        from: "test@hogsend.com",
+        to: "user@example.com",
+        subject: "Test",
+        react: dummyElement(),
+      },
+      retryOptions: { maxRetries: 3, baseDelayMs: 10, maxDelayMs: 50 },
+    });
+
+    expect(result.id).toBe("resend_success");
+    expect(sendFn).toHaveBeenCalledTimes(3);
+  });
+
+  it("does not retry non-retryable errors", async () => {
+    const sendFn = vi.fn().mockResolvedValue({
+      data: null,
+      error: { message: "Invalid email address", statusCode: 422 },
+    });
+    const client = mockResendClient({ sendFn });
+
+    await expect(
+      sendEmail({
+        client,
+        options: {
+          from: "test@hogsend.com",
+          to: "user@example.com",
+          subject: "Test",
+          react: dummyElement(),
+        },
+        retryOptions: { maxRetries: 3, baseDelayMs: 10 },
+      }),
+    ).rejects.toThrow(EmailSendError);
+
+    expect(sendFn).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("sendBatchEmails", () => {
+  it("returns empty array for empty input", async () => {
+    const client = mockResendClient();
+    const result = await sendBatchEmails({ client, emails: [] });
+    expect(result).toEqual([]);
+  });
+
+  it("sends a batch and returns ids", async () => {
+    const client = mockResendClient();
+    const result = await sendBatchEmails({
+      client,
+      emails: [
+        {
+          from: "a@hogsend.com",
+          to: "b@example.com",
+          subject: "A",
+          react: dummyElement(),
+        },
+        {
+          from: "a@hogsend.com",
+          to: "c@example.com",
+          subject: "B",
+          react: dummyElement(),
+        },
+      ],
+    });
+    expect(result).toEqual([{ id: "batch_1" }, { id: "batch_2" }]);
+  });
+
+  it("auto-chunks lists larger than 100", async () => {
+    const batchFn = vi.fn().mockResolvedValue({
+      data: { data: Array.from({ length: 50 }, (_, i) => ({ id: `id_${i}` })) },
+      error: null,
+    });
+    const client = mockResendClient({ batchFn });
+
+    const emails = Array.from({ length: 150 }, (_, i) => ({
+      from: "a@hogsend.com",
+      to: `user${i}@example.com`,
+      subject: `Email ${i}`,
+      react: dummyElement(),
+    }));
+
+    await sendBatchEmails({ client, emails });
+
+    expect(batchFn).toHaveBeenCalledTimes(2);
+    const firstCallArgs = batchFn.mock.calls[0]?.[0] as unknown[];
+    const secondCallArgs = batchFn.mock.calls[1]?.[0] as unknown[];
+    expect(firstCallArgs).toHaveLength(100);
+    expect(secondCallArgs).toHaveLength(50);
+  });
+});

package/src/__tests__/webhooks.test.ts

@@ -0,0 +1,79 @@
+import { WebhookVerificationError } from "@hogsend/email";
+import { describe, expect, it } from "vitest";
+import type { EmailSentEvent } from "../types.js";
+import { createWebhookHandler, parseWebhookEvent } from "../webhooks.js";
+
+function makeSentEvent(): EmailSentEvent {
+  return {
+    type: "email.sent",
+    created_at: "2024-01-01T00:00:00Z",
+    data: {
+      email_id: "email_123",
+      from: "test@hogsend.com",
+      to: ["user@example.com"],
+      subject: "Test",
+      created_at: "2024-01-01T00:00:00Z",
+    },
+  };
+}
+
+describe("parseWebhookEvent", () => {
+  it("parses a valid sent event", () => {
+    const event = makeSentEvent();
+    const parsed = parseWebhookEvent(JSON.stringify(event));
+    expect(parsed.type).toBe("email.sent");
+    expect(parsed.data.email_id).toBe("email_123");
+  });
+
+  it("parses a valid bounced event", () => {
+    const event = {
+      type: "email.bounced",
+      created_at: "2024-01-01T00:00:00Z",
+      data: {
+        email_id: "email_456",
+        from: "test@hogsend.com",
+        to: ["user@example.com"],
+        subject: "Test",
+        created_at: "2024-01-01T00:00:00Z",
+        bounce: { message: "Mailbox not found", type: "hard" },
+      },
+    };
+    const parsed = parseWebhookEvent(JSON.stringify(event));
+    expect(parsed.type).toBe("email.bounced");
+  });
+
+  it("throws on unknown event type", () => {
+    const event = { type: "email.unknown", data: {} };
+    expect(() => parseWebhookEvent(JSON.stringify(event))).toThrow(
+      WebhookVerificationError,
+    );
+  });
+
+  it("throws on invalid JSON", () => {
+    expect(() => parseWebhookEvent("not json")).toThrow();
+  });
+});
+
+describe("createWebhookHandler", () => {
+  it("requires valid svix headers", async () => {
+    const handler = createWebhookHandler({
+      signingSecret: "whsec_test",
+      handlers: {},
+    });
+    await expect(handler(JSON.stringify(makeSentEvent()), {})).rejects.toThrow(
+      WebhookVerificationError,
+    );
+  });
+
+  it("requires svix headers to be present", async () => {
+    const handler = createWebhookHandler({
+      signingSecret: "whsec_test",
+      handlers: {},
+    });
+    await expect(
+      handler(JSON.stringify(makeSentEvent()), {
+        "svix-id": "msg_123",
+      }),
+    ).rejects.toThrow("Missing required Svix headers");
+  });
+});

package/src/client.ts

@@ -0,0 +1,5 @@
+import { Resend } from "resend";
+
+export function createResendClient(opts: { apiKey: string }): Resend {
+  return new Resend(opts.apiKey);
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// Client
+export { createResendClient } from "./client.js";
+// EmailProvider (the provider contract + Resend implementation)
+export {
+  createResendProvider,
+  type ResendProviderConfig,
+} from "./provider.js";
+// Sending (with retry + auto-chunking)
+export { sendBatchEmails, sendEmail } from "./send.js";
+// Types
+export type {
+  BatchEmailItem,
+  EmailBouncedEvent,
+  EmailClickedEvent,
+  EmailComplainedEvent,
+  EmailDeliveredEvent,
+  EmailDeliveryDelayedEvent,
+  EmailOpenedEvent,
+  EmailProvider,
+  EmailSentEvent,
+  SendEmailOptions,
+  SendResult,
+  WebhookEvent,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "./types.js";
+// Webhooks
+export {
+  createWebhookHandler,
+  parseWebhookEvent,
+  verifyWebhook,
+} from "./webhooks.js";

package/src/provider.ts

@@ -0,0 +1,62 @@
+import type { RetryOptions } from "@hogsend/email";
+import { createResendClient } from "./client.js";
+import { sendBatchEmails, sendEmail } from "./send.js";
+import type {
+  BatchEmailItem,
+  EmailProvider,
+  SendEmailOptions,
+  SendResult,
+  WebhookEvent,
+} from "./types.js";
+import { parseWebhookEvent, verifyWebhook } from "./webhooks.js";
+
+export interface ResendProviderConfig {
+  apiKey: string;
+  webhookSecret?: string;
+  retryOptions?: RetryOptions;
+}
+
+/**
+ * The Resend implementation of the engine's {@link EmailProvider} contract: a dumb
+ * delivery + webhook parse/verify layer. All tracking, DB, preference, and
+ * render logic lives in the engine's `createTrackedMailer`, not here.
+ */
+export function createResendProvider(
+  config: ResendProviderConfig,
+): EmailProvider {
+  const client = createResendClient({ apiKey: config.apiKey });
+  const retryOptions = config.retryOptions;
+
+  return {
+    async send(options: SendEmailOptions): Promise<SendResult> {
+      return sendEmail({ client, options, retryOptions });
+    },
+
+    async sendBatch(
+      emails: BatchEmailItem[],
+    ): Promise<{ results: SendResult[] }> {
+      const results = await sendBatchEmails({ client, emails, retryOptions });
+      return { results };
+    },
+
+    verifyWebhook(opts: {
+      payload: string;
+      headers: Record<string, string>;
+    }): WebhookEvent {
+      if (!config.webhookSecret) {
+        throw new Error(
+          "webhookSecret is required on the provider to verify webhooks",
+        );
+      }
+      return verifyWebhook({
+        payload: opts.payload,
+        headers: opts.headers,
+        signingSecret: config.webhookSecret,
+      });
+    },
+
+    parseWebhook(payload: string): WebhookEvent {
+      return parseWebhookEvent(payload);
+    },
+  };
+}

package/src/send.ts

@@ -0,0 +1,215 @@
+import {
+  DEFAULT_RETRY_OPTIONS,
+  EmailSendError,
+  type RetryOptions,
+} from "@hogsend/email";
+import type { Resend } from "resend";
+import type { BatchEmailItem, SendEmailOptions, SendResult } from "./types.js";
+
+const BATCH_CHUNK_SIZE = 100;
+
+function normalizeRecipients(to: string | string[]): string[] {
+  return Array.isArray(to) ? to : [to];
+}
+
+function isRetryableStatusCode(statusCode: number): boolean {
+  return statusCode === 429 || statusCode >= 500;
+}
+
+function classifyError(error: unknown): EmailSendError {
+  if (error instanceof EmailSendError) return error;
+
+  const message =
+    error instanceof Error ? error.message : "Unknown email send error";
+
+  if (
+    typeof error === "object" &&
+    error !== null &&
+    "statusCode" in error &&
+    typeof (error as { statusCode: unknown }).statusCode === "number"
+  ) {
+    const statusCode = (error as { statusCode: number }).statusCode;
+    return new EmailSendError(message, {
+      retryable: isRetryableStatusCode(statusCode),
+      statusCode,
+      cause: error,
+    });
+  }
+
+  const lowerMessage = message.toLowerCase();
+  const retryable =
+    lowerMessage.includes("rate limit") ||
+    lowerMessage.includes("timeout") ||
+    lowerMessage.includes("econnreset") ||
+    lowerMessage.includes("econnrefused") ||
+    lowerMessage.includes("network");
+
+  return new EmailSendError(message, { retryable, cause: error });
+}
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function getBackoffDelay(
+  attempt: number,
+  baseDelayMs: number,
+  maxDelayMs: number,
+): number {
+  const exponentialDelay = baseDelayMs * 2 ** attempt;
+  const jitter = Math.random() * baseDelayMs;
+  return Math.min(exponentialDelay + jitter, maxDelayMs);
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: Required<RetryOptions>,
+): Promise<T> {
+  let lastError: EmailSendError | undefined;
+
+  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = classifyError(error);
+
+      if (!lastError.retryable || attempt === options.maxRetries) {
+        throw lastError;
+      }
+
+      const delay = getBackoffDelay(
+        attempt,
+        options.baseDelayMs,
+        options.maxDelayMs,
+      );
+      await sleep(delay);
+    }
+  }
+
+  throw (
+    lastError ?? new EmailSendError("Retry exhausted", { retryable: false })
+  );
+}
+
+export async function sendEmail(args: {
+  client: Resend;
+  options: SendEmailOptions;
+  retryOptions?: RetryOptions;
+}): Promise<SendResult> {
+  const { client, options, retryOptions } = args;
+  const opts = { ...DEFAULT_RETRY_OPTIONS, ...retryOptions };
+
+  return withRetry(async () => {
+    const { data, error } = await client.emails.send({
+      from: options.from,
+      to: normalizeRecipients(options.to),
+      subject: options.subject,
+      ...(options.html ? { html: options.html } : { react: options.react }),
+      replyTo: options.replyTo,
+      cc: options.cc,
+      bcc: options.bcc,
+      scheduledAt: options.scheduledAt,
+      tags: options.tags,
+      headers: options.headers,
+    });
+
+    if (error) {
+      throw new EmailSendError(`Failed to send email: ${error.message}`, {
+        retryable:
+          "statusCode" in error &&
+          typeof (error as { statusCode: unknown }).statusCode === "number"
+            ? isRetryableStatusCode(
+                (error as { statusCode: number }).statusCode,
+              )
+            : false,
+        statusCode:
+          "statusCode" in error
+            ? ((error as { statusCode: unknown }).statusCode as number)
+            : undefined,
+      });
+    }
+
+    if (!data) {
+      throw new EmailSendError("Failed to send email: no data returned", {
+        retryable: true,
+      });
+    }
+
+    return { id: data.id };
+  }, opts);
+}
+
+export async function sendBatchEmails(args: {
+  client: Resend;
+  emails: BatchEmailItem[];
+  retryOptions?: RetryOptions;
+}): Promise<SendResult[]> {
+  const { client, emails, retryOptions } = args;
+  if (emails.length === 0) return [];
+
+  const chunks: BatchEmailItem[][] = [];
+  for (let i = 0; i < emails.length; i += BATCH_CHUNK_SIZE) {
+    chunks.push(emails.slice(i, i + BATCH_CHUNK_SIZE));
+  }
+
+  const allResults: SendResult[] = [];
+
+  for (const chunk of chunks) {
+    const results = await sendBatchChunk(client, chunk, retryOptions);
+    allResults.push(...results);
+  }
+
+  return allResults;
+}
+
+async function sendBatchChunk(
+  client: Resend,
+  emails: BatchEmailItem[],
+  retryOptions?: RetryOptions,
+): Promise<SendResult[]> {
+  const opts = { ...DEFAULT_RETRY_OPTIONS, ...retryOptions };
+
+  return withRetry(async () => {
+    const { data, error } = await client.batch.send(
+      emails.map((email) => ({
+        from: email.from,
+        to: normalizeRecipients(email.to),
+        subject: email.subject,
+        react: email.react,
+        replyTo: email.replyTo,
+        cc: email.cc,
+        bcc: email.bcc,
+        tags: email.tags,
+        headers: email.headers,
+      })),
+    );
+
+    if (error) {
+      throw new EmailSendError(
+        `Failed to send batch emails: ${error.message}`,
+        {
+          retryable:
+            "statusCode" in error &&
+            typeof (error as { statusCode: unknown }).statusCode === "number"
+              ? isRetryableStatusCode(
+                  (error as { statusCode: number }).statusCode,
+                )
+              : false,
+          statusCode:
+            "statusCode" in error
+              ? ((error as { statusCode: unknown }).statusCode as number)
+              : undefined,
+        },
+      );
+    }
+
+    if (!data) {
+      throw new EmailSendError(
+        "Failed to send batch emails: no data returned",
+        { retryable: true },
+      );
+    }
+
+    return data.data.map((item: { id: string }) => ({ id: item.id }));
+  }, opts);
+}

package/src/types.ts

@@ -0,0 +1,138 @@
+import type { ReactElement } from "react";
+
+// ---------------------------------------------------------------------------
+// Send options
+// ---------------------------------------------------------------------------
+
+export interface SendEmailOptions {
+  from: string;
+  to: string | string[];
+  subject: string;
+  react?: ReactElement;
+  html?: string;
+  replyTo?: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  scheduledAt?: string;
+  tags?: Array<{ name: string; value: string }>;
+  headers?: Record<string, string>;
+}
+
+export interface BatchEmailItem {
+  from: string;
+  to: string | string[];
+  subject: string;
+  react: ReactElement;
+  replyTo?: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  tags?: Array<{ name: string; value: string }>;
+  headers?: Record<string, string>;
+}
+
+export interface SendResult {
+  id: string;
+}
+
+// ---------------------------------------------------------------------------
+// Webhook events
+// ---------------------------------------------------------------------------
+
+interface WebhookEventBase {
+  created_at: string;
+  data: {
+    email_id: string;
+    from: string;
+    to: string[];
+    subject: string;
+    created_at: string;
+  };
+}
+
+export interface EmailSentEvent extends WebhookEventBase {
+  type: "email.sent";
+}
+
+export interface EmailDeliveredEvent extends WebhookEventBase {
+  type: "email.delivered";
+}
+
+export interface EmailBouncedEvent extends WebhookEventBase {
+  type: "email.bounced";
+  data: WebhookEventBase["data"] & {
+    bounce: {
+      message: string;
+      type: string;
+    };
+  };
+}
+
+export interface EmailComplainedEvent extends WebhookEventBase {
+  type: "email.complained";
+}
+
+export interface EmailDeliveryDelayedEvent extends WebhookEventBase {
+  type: "email.delivery_delayed";
+}
+
+export interface EmailOpenedEvent extends WebhookEventBase {
+  type: "email.opened";
+}
+
+export interface EmailClickedEvent extends WebhookEventBase {
+  type: "email.clicked";
+  data: WebhookEventBase["data"] & {
+    click: {
+      link: string;
+      timestamp: string;
+      ipAddress: string;
+      userAgent: string;
+    };
+  };
+}
+
+export type WebhookEvent =
+  | EmailSentEvent
+  | EmailDeliveredEvent
+  | EmailBouncedEvent
+  | EmailComplainedEvent
+  | EmailDeliveryDelayedEvent
+  | EmailOpenedEvent
+  | EmailClickedEvent;
+
+export type WebhookEventType = WebhookEvent["type"];
+
+export type WebhookHandlerMap = {
+  [K in WebhookEventType]?: (
+    event: Extract<WebhookEvent, { type: K }>,
+  ) => void | Promise<void>;
+};
+
+// ---------------------------------------------------------------------------
+// EmailProvider contract (the entire provider surface)
+// ---------------------------------------------------------------------------
+
+/**
+ * The dumb delivery + webhook parse/verify contract every email provider
+ * implements (Resend, Postmark, SES, …). All tracking, DB, preference, and
+ * render logic lives in the engine's `createTrackedMailer`, never here.
+ */
+export interface EmailProvider {
+  /** Deliver a single message. Returns the provider message id. */
+  send(options: SendEmailOptions): Promise<SendResult>;
+
+  /** Deliver a batch of messages. */
+  sendBatch(emails: BatchEmailItem[]): Promise<{ results: SendResult[] }>;
+
+  /**
+   * Verify a provider webhook signature and return the parsed event. Throws
+   * if the signature is missing/invalid.
+   */
+  verifyWebhook(opts: {
+    payload: string;
+    headers: Record<string, string>;
+  }): WebhookEvent;
+
+  /** Parse an unsigned webhook payload (used in trusted contexts/tests). */
+  parseWebhook(payload: string): WebhookEvent;
+}

package/src/webhooks.ts

@@ -0,0 +1,86 @@
+import { WebhookVerificationError } from "@hogsend/email";
+import { Webhook } from "svix";
+import type {
+  WebhookEvent,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "./types.js";
+
+export function verifyWebhook(opts: {
+  payload: string;
+  headers: Record<string, string>;
+  signingSecret: string;
+}): WebhookEvent {
+  const svixId = opts.headers["svix-id"];
+  const svixTimestamp = opts.headers["svix-timestamp"];
+  const svixSignature = opts.headers["svix-signature"];
+
+  if (!svixId || !svixTimestamp || !svixSignature) {
+    throw new WebhookVerificationError(
+      "Missing required Svix headers: svix-id, svix-timestamp, svix-signature",
+    );
+  }
+
+  try {
+    const wh = new Webhook(opts.signingSecret);
+    const event = wh.verify(opts.payload, {
+      "svix-id": svixId,
+      "svix-timestamp": svixTimestamp,
+      "svix-signature": svixSignature,
+    }) as WebhookEvent;
+
+    return event;
+  } catch (error) {
+    throw new WebhookVerificationError(
+      `Webhook verification failed: ${error instanceof Error ? error.message : "unknown error"}`,
+    );
+  }
+}
+
+export function createWebhookHandler(opts: {
+  signingSecret: string;
+  handlers: WebhookHandlerMap;
+}) {
+  return async (
+    payload: string,
+    headers: Record<string, string>,
+  ): Promise<{ type: WebhookEventType; handled: boolean }> => {
+    const event = verifyWebhook({
+      payload,
+      headers,
+      signingSecret: opts.signingSecret,
+    });
+    const handler = opts.handlers[event.type] as
+      | ((event: WebhookEvent) => void | Promise<void>)
+      | undefined;
+
+    if (handler) {
+      await handler(event);
+      return { type: event.type, handled: true };
+    }
+
+    return { type: event.type, handled: false };
+  };
+}
+
+export function parseWebhookEvent(payload: string): WebhookEvent {
+  const parsed = JSON.parse(payload) as WebhookEvent;
+
+  const validTypes: WebhookEventType[] = [
+    "email.sent",
+    "email.delivered",
+    "email.bounced",
+    "email.complained",
+    "email.delivery_delayed",
+    "email.opened",
+    "email.clicked",
+  ];
+
+  if (!validTypes.includes(parsed.type)) {
+    throw new WebhookVerificationError(
+      `Unknown webhook event type: ${parsed.type}`,
+    );
+  }
+
+  return parsed;
+}