@hogsend/email 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,131 @@
+# @hogsend/email
+
+Email **machinery** for Hogsend, built on [React Email](https://react.email):
+template rendering, a typed template registry, and unsubscribe token/URL helpers.
+
+> **No concrete business templates live here.** As of the boundary revision,
+> your `.tsx` templates are content you own in your app's `src/emails/`. And
+> **sending isn't here either** — that moved to the engine. This package is just
+> the typed plumbing both of those build on.
+
+## Where the rest went
+
+| You want to… | Use | Lives in |
+| --- | --- | --- |
+| Render a template to HTML/text | `renderToHtml` / `renderToPlainText` | `@hogsend/email` (here) |
+| Resolve a template by key | `getTemplate(..., { registry })` | `@hogsend/email` (here) |
+| Build / merge a template registry | `createRegistry` | `@hogsend/email` (here) |
+| Generate unsubscribe links/tokens | `generateUnsubscribeUrl`, `generateUnsubscribeToken`, … | `@hogsend/email` (here) |
+| **Send** a tracked email | `createTrackedMailer` / `sendEmail()` | `@hogsend/engine` |
+| Talk to the email provider | `createResendProvider` (the `EmailProvider` contract) | `@hogsend/plugin-resend` |
+| **Own** your email designs | `welcome.tsx`, `registry.ts`, `templates.d.ts` | **your app** `src/emails/` |
+
+Link rewriting, the open pixel, preference/suppression checks, the `email_sends`
+write, and webhook status updates all live in the engine's `createTrackedMailer`,
+so they come along regardless of which `EmailProvider` you supply.
+
+## Public API
+
+```ts
+import {
+  // rendering
+  renderToHtml,
+  renderToPlainText,
+  // registry
+  createRegistry,
+  getTemplate,
+  getTemplateDefinition,
+  getPreviewText,
+  getTemplateNames,
+  // unsubscribe
+  generateUnsubscribeUrl,
+  generatePreferenceCenterUrl,
+  generateUnsubscribeToken,
+  validateUnsubscribeToken,
+  // errors
+  EmailSendError,
+  EmailSuppressionError,
+  WebhookVerificationError,
+  InvalidTokenError,
+} from "@hogsend/email";
+
+import type {
+  TemplateRegistry,
+  TemplateRegistryMap,
+  TemplateDefinition,
+  TemplateName,
+} from "@hogsend/email";
+```
+
+## Owning your templates (Option B — module augmentation)
+
+Templates are your content. Put the `.tsx` files in your app's `src/emails/`,
+build a registry, and augment `TemplateRegistryMap` so the engine's `sendEmail`
+is fully type-checked against *your* templates.
+
+**`src/emails/welcome.tsx`** — a normal React Email component you design freely.
+
+**`src/emails/registry.ts`** — map each key to its component, subject, category:
+
+```ts
+import { createRegistry } from "@hogsend/email";
+import { WelcomeEmail } from "./welcome.js";
+
+export const templates = createRegistry({
+  welcome: {
+    component: WelcomeEmail,
+    defaultSubject: "Welcome to Acme",
+    category: "transactional",
+    preview: (props) => `Welcome, ${props.name}!`,
+  },
+});
+```
+
+**`src/emails/templates.d.ts`** — the augmentation that gives you type safety:
+
+```ts
+import type { WelcomeEmailProps } from "./welcome.js";
+
+declare module "@hogsend/email" {
+  interface TemplateRegistryMap {
+    welcome: WelcomeEmailProps;
+    // add a line per template; key ↔ props are enforced everywhere
+  }
+}
+```
+
+Pass the registry to the client: `createHogsendClient({ journeys, email: { templates } })`.
+Now `sendEmail({ template: "welcome", props: { name: "Doug" } })` is checked —
+an unknown key or wrong props is a compile error.
+
+> `create-hogsend` scaffolds a starter `src/emails/` (a couple of templates +
+> `registry.ts` + `templates.d.ts`) so this is wired from the first commit.
+
+## Rendering directly
+
+```ts
+import { getTemplate, renderToHtml } from "@hogsend/email";
+
+const { element, subject, category } = getTemplate({
+  key: "welcome",
+  props: { name: "Jane" },
+  registry, // your TemplateRegistry
+});
+const html = await renderToHtml(element);
+```
+
+## Scripts
+
+```bash
+pnpm build         # tsup build to dist/
+pnpm test          # vitest run
+pnpm check-types   # tsc --noEmit
+```
+
+Preview your designs from your **app** (where the `.tsx` files live) with the
+React Email dev server, not from this package.
+
+## Peer dependencies
+
+`react` / `react-dom` (peer). This package no longer depends on `@hogsend/db`
+or a mail provider — it's pure rendering + typing machinery.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@hogsend/email",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dougwithseismic/hogsend.git",
+    "directory": "packages/email"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@react-email/ui": "^6.3.2",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-email": "^6.3.2",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.7",
+    "@repo/typescript-config": "^0.0.0"
+  },
+  "scripts": {
+    "dev": "email dev --port 3003",
+    "build": "tsup",
+    "preview": "email export --outDir out --pretty",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  }
+}

package/src/__tests__/registry.test.ts

@@ -0,0 +1,81 @@
+import { createElement } from "react";
+import { describe, expect, it } from "vitest";
+import {
+  createRegistry,
+  getPreviewText,
+  getTemplate,
+  getTemplateDefinition,
+  getTemplateNames,
+} from "../registry.js";
+import type { TemplateRegistry } from "../types.js";
+
+// The package ships no business templates; these tests exercise the registry
+// machinery against a tiny self-contained fixture registry (the same shape a
+// client app builds in `src/emails/registry.ts`).
+function Hello(props: { name: string }) {
+  return createElement("div", null, `Hello ${props.name}`);
+}
+
+const fixture = {
+  hello: {
+    component: Hello,
+    defaultSubject: "Hello there",
+    category: "transactional",
+    preview: (props: { name: string }) => `Hi ${props.name}!`,
+  },
+} as unknown as TemplateRegistry;
+
+describe("template registry", () => {
+  it("returns the registered template names", () => {
+    const names = getTemplateNames(fixture);
+    expect(names).toEqual(["hello"]);
+  });
+
+  it("gets a template definition by key", () => {
+    const def = getTemplateDefinition({
+      key: "hello" as never,
+      registry: fixture,
+    });
+    expect(def.component).toBeTypeOf("function");
+    expect(def.defaultSubject).toBe("Hello there");
+    expect(def.category).toBe("transactional");
+  });
+
+  it("resolves a template with props", () => {
+    const result = getTemplate({
+      key: "hello" as never,
+      props: { name: "Doug" } as never,
+      registry: fixture,
+    });
+    expect(result.element).toBeDefined();
+    expect(result.subject).toBe("Hello there");
+    expect(result.category).toBe("transactional");
+  });
+
+  it("generates preview text", () => {
+    const preview = getPreviewText({
+      key: "hello" as never,
+      props: { name: "Doug" } as never,
+      registry: fixture,
+    });
+    expect(preview).toBe("Hi Doug!");
+  });
+
+  it("merges overrides over a base registry", () => {
+    const override = {
+      hello: {
+        component: Hello,
+        defaultSubject: "Hey!",
+        category: "transactional",
+      },
+    } as unknown as Partial<TemplateRegistry>;
+    const custom = createRegistry(fixture, override);
+
+    const result = getTemplate({
+      key: "hello" as never,
+      props: { name: "Doug" } as never,
+      registry: custom,
+    });
+    expect(result.subject).toBe("Hey!");
+  });
+});

package/src/__tests__/render.test.ts

@@ -0,0 +1,32 @@
+import { createElement } from "react";
+import { Body, Html, Text } from "react-email";
+import { describe, expect, it } from "vitest";
+import { renderToHtml, renderToPlainText } from "../render.js";
+
+// Render is template-agnostic machinery: it turns any react-email element into
+// HTML / plain text. Use a minimal inline element rather than a baked template.
+function fixtureElement(name: string) {
+  return createElement(
+    Html,
+    null,
+    createElement(Body, null, createElement(Text, null, `Welcome ${name}`)),
+  );
+}
+
+describe("renderToHtml", () => {
+  it("renders a react-email element to HTML", async () => {
+    const html = await renderToHtml(fixtureElement("Doug"));
+    expect(html).toContain("Welcome");
+    expect(html).toContain("Doug");
+    expect(html).toContain("<html");
+  });
+});
+
+describe("renderToPlainText", () => {
+  it("renders a react-email element to plain text", async () => {
+    const text = await renderToPlainText(fixtureElement("Doug"));
+    expect(text).toContain("Welcome");
+    expect(text).toContain("Doug");
+    expect(text).not.toContain("<html");
+  });
+});

package/src/__tests__/types.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import {
+  EmailSendError,
+  EmailSuppressionError,
+  WebhookVerificationError,
+} from "../types.js";
+
+describe("EmailSendError", () => {
+  it("has retryable flag", () => {
+    const err = new EmailSendError("rate limited", {
+      retryable: true,
+      statusCode: 429,
+    });
+    expect(err.retryable).toBe(true);
+    expect(err.statusCode).toBe(429);
+    expect(err.name).toBe("EmailSendError");
+    expect(err.message).toBe("rate limited");
+  });
+
+  it("supports non-retryable errors", () => {
+    const err = new EmailSendError("bad address", {
+      retryable: false,
+      statusCode: 422,
+    });
+    expect(err.retryable).toBe(false);
+  });
+
+  it("preserves cause", () => {
+    const cause = new Error("original");
+    const err = new EmailSendError("wrapped", {
+      retryable: false,
+      cause,
+    });
+    expect(err.cause).toBe(cause);
+  });
+});
+
+describe("EmailSuppressionError", () => {
+  it("formats message with reason and email", () => {
+    const err = new EmailSuppressionError("unsubscribed", "user@example.com");
+    expect(err.message).toContain("unsubscribed");
+    expect(err.message).toContain("user@example.com");
+    expect(err.reason).toBe("unsubscribed");
+    expect(err.name).toBe("EmailSuppressionError");
+  });
+});
+
+describe("WebhookVerificationError", () => {
+  it("sets name and message", () => {
+    const err = new WebhookVerificationError("bad sig");
+    expect(err.name).toBe("WebhookVerificationError");
+    expect(err.message).toBe("bad sig");
+  });
+});

package/src/__tests__/unsubscribe-tokens.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, it } from "vitest";
+import {
+  generateUnsubscribeToken,
+  InvalidTokenError,
+  validateUnsubscribeToken,
+} from "../unsubscribe-tokens.js";
+import {
+  generatePreferenceCenterUrl,
+  generateUnsubscribeUrl,
+} from "../unsubscribe-url.js";
+
+const SECRET = "test-secret-minimum-32-characters-long-ok";
+
+describe("unsubscribe tokens", () => {
+  it("round-trips a global unsubscribe token", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+      action: "unsubscribe",
+    });
+
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    expect(payload.externalId).toBe("user-123");
+    expect(payload.email).toBe("user@example.com");
+    expect(payload.action).toBe("unsubscribe");
+    expect(payload.category).toBeUndefined();
+    expect(payload.exp).toBeGreaterThan(Math.floor(Date.now() / 1000));
+  });
+
+  it("round-trips a category unsubscribe token", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-456",
+      email: "user@example.com",
+      category: "journey",
+      action: "unsubscribe",
+    });
+
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    expect(payload.category).toBe("journey");
+    expect(payload.action).toBe("unsubscribe");
+  });
+
+  it("round-trips a resubscribe token", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-789",
+      email: "user@example.com",
+      category: "journey",
+      action: "resubscribe",
+    });
+
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    expect(payload.action).toBe("resubscribe");
+    expect(payload.category).toBe("journey");
+  });
+
+  it("round-trips a manage token", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-abc",
+      email: "user@example.com",
+      action: "manage",
+    });
+
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    expect(payload.action).toBe("manage");
+  });
+
+  it("rejects an expired token", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+      action: "unsubscribe",
+      expiresInSeconds: -1,
+    });
+
+    expect(() => validateUnsubscribeToken({ token, secret: SECRET })).toThrow(
+      InvalidTokenError,
+    );
+    expect(() => validateUnsubscribeToken({ token, secret: SECRET })).toThrow(
+      "Token has expired",
+    );
+  });
+
+  it("rejects a tampered payload", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+      action: "unsubscribe",
+    });
+
+    const [, signature] = token.split(".");
+    const tamperedPayload = Buffer.from(
+      JSON.stringify({
+        externalId: "hacker",
+        email: "hacker@evil.com",
+        action: "unsubscribe",
+        exp: Math.floor(Date.now() / 1000) + 99999,
+      }),
+    ).toString("base64url");
+
+    expect(() =>
+      validateUnsubscribeToken({
+        token: `${tamperedPayload}.${signature}`,
+        secret: SECRET,
+      }),
+    ).toThrow(InvalidTokenError);
+  });
+
+  it("rejects a tampered signature", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+      action: "unsubscribe",
+    });
+
+    const [payload] = token.split(".");
+    const badSig = Buffer.from("not-a-valid-signature").toString("base64url");
+
+    expect(() =>
+      validateUnsubscribeToken({
+        token: `${payload}.${badSig}`,
+        secret: SECRET,
+      }),
+    ).toThrow(InvalidTokenError);
+  });
+
+  it("rejects a wrong secret", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+      action: "unsubscribe",
+    });
+
+    expect(() =>
+      validateUnsubscribeToken({
+        token,
+        secret: "wrong-secret-also-32-characters-long",
+      }),
+    ).toThrow(InvalidTokenError);
+  });
+
+  it("rejects a malformed token without a dot", () => {
+    expect(() =>
+      validateUnsubscribeToken({ token: "nodot", secret: SECRET }),
+    ).toThrow(InvalidTokenError);
+    expect(() =>
+      validateUnsubscribeToken({ token: "nodot", secret: SECRET }),
+    ).toThrow("Malformed token");
+  });
+
+  it("uses 30-day default expiry", () => {
+    const token = generateUnsubscribeToken({
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+      action: "unsubscribe",
+    });
+
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    const expectedExp = Math.floor(Date.now() / 1000) + 30 * 24 * 3600;
+    expect(Math.abs(payload.exp - expectedExp)).toBeLessThan(5);
+  });
+});
+
+describe("unsubscribe URLs", () => {
+  const baseUrl = "https://api.hogsend.com";
+
+  it("generates a global unsubscribe URL", () => {
+    const url = generateUnsubscribeUrl({
+      baseUrl,
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+    });
+
+    expect(url).toMatch(
+      /^https:\/\/api\.hogsend\.com\/v1\/email\/unsubscribe\?token=.+/,
+    );
+
+    const parsed = new URL(url);
+    const token = parsed.searchParams.get("token") as string;
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    expect(payload.action).toBe("unsubscribe");
+    expect(payload.externalId).toBe("user-123");
+  });
+
+  it("generates a category unsubscribe URL", () => {
+    const url = generateUnsubscribeUrl({
+      baseUrl,
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+      category: "journey",
+    });
+
+    const parsed = new URL(url);
+    const token = parsed.searchParams.get("token") as string;
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    expect(payload.category).toBe("journey");
+  });
+
+  it("generates a preference center URL", () => {
+    const url = generatePreferenceCenterUrl({
+      baseUrl,
+      secret: SECRET,
+      externalId: "user-123",
+      email: "user@example.com",
+    });
+
+    expect(url).toMatch(
+      /^https:\/\/api\.hogsend\.com\/v1\/email\/preferences\?token=.+/,
+    );
+
+    const parsed = new URL(url);
+    const token = parsed.searchParams.get("token") as string;
+    const payload = validateUnsubscribeToken({ token, secret: SECRET });
+    expect(payload.action).toBe("manage");
+  });
+});

package/src/index.ts

@@ -0,0 +1,53 @@
+// @hogsend/email — email machinery only. No concrete business templates are
+// baked in here; clients own their `.tsx` templates + registry and augment the
+// open `TemplateRegistryMap` interface (Option B).
+
+// Template registry
+export {
+  createRegistry,
+  getPreviewText,
+  getTemplate,
+  getTemplateDefinition,
+  getTemplateNames,
+} from "./registry.js";
+
+// Rendering
+export { renderToHtml, renderToPlainText } from "./render.js";
+
+// Types
+export type {
+  EmailServiceRenderOptions,
+  EmailServiceRenderResult,
+  RetryOptions,
+  TemplateDefinition,
+  TemplateName,
+  TemplateRegistry,
+  TemplateRegistryMap,
+} from "./types.js";
+
+// Runtime values & error classes
+export {
+  DEFAULT_RETRY_OPTIONS,
+  EmailSendError,
+  EmailSuppressionError,
+  WebhookVerificationError,
+} from "./types.js";
+
+// Unsubscribe tokens
+export type {
+  TokenAction,
+  TokenOptions,
+  UnsubscribeTokenPayload,
+} from "./unsubscribe-tokens.js";
+export {
+  generateUnsubscribeToken,
+  InvalidTokenError,
+  validateUnsubscribeToken,
+} from "./unsubscribe-tokens.js";
+
+// Unsubscribe URLs
+export type { UnsubscribeUrlOptions } from "./unsubscribe-url.js";
+export {
+  generatePreferenceCenterUrl,
+  generateUnsubscribeUrl,
+} from "./unsubscribe-url.js";

package/src/registry.ts

@@ -0,0 +1,65 @@
+import type { ReactElement } from "react";
+import type {
+  TemplateDefinition,
+  TemplateName,
+  TemplateRegistry,
+  TemplateRegistryMap,
+} from "./types.js";
+
+// The registry holds no baked-in business templates. Client apps build their
+// own `TemplateRegistry` (key → component + subject + category) and pass it to
+// these helpers — see the engine `TrackedMailer`, which threads the
+// container-provided registry through at send + render time.
+
+export function getTemplate<K extends TemplateName>(opts: {
+  key: K;
+  props: TemplateRegistryMap[K];
+  registry: TemplateRegistry;
+}): { element: ReactElement; subject: string; category?: string } {
+  const { key, props, registry } = opts;
+  const definition = registry[key] as TemplateDefinition<
+    TemplateRegistryMap[K]
+  >;
+
+  return {
+    element: definition.component(props) as ReactElement,
+    subject: definition.defaultSubject,
+    category: definition.category,
+  };
+}
+
+export function getTemplateDefinition<K extends TemplateName>(opts: {
+  key: K;
+  registry: TemplateRegistry;
+}): TemplateDefinition<TemplateRegistryMap[K]> {
+  const { key, registry } = opts;
+  return registry[key] as TemplateDefinition<TemplateRegistryMap[K]>;
+}
+
+export function getPreviewText<K extends TemplateName>(opts: {
+  key: K;
+  props: TemplateRegistryMap[K];
+  registry: TemplateRegistry;
+}): string | undefined {
+  const { key, props, registry } = opts;
+  const definition = registry[key] as TemplateDefinition<
+    TemplateRegistryMap[K]
+  >;
+  return definition.preview?.(props);
+}
+
+/**
+ * Merge partial registry overrides over a base registry. Useful for clients
+ * that want to tweak a few templates while inheriting the rest of a starter
+ * set.
+ */
+export function createRegistry(
+  base: TemplateRegistry,
+  overrides: Partial<TemplateRegistry> = {},
+): TemplateRegistry {
+  return { ...base, ...overrides };
+}
+
+export function getTemplateNames(registry: TemplateRegistry): TemplateName[] {
+  return Object.keys(registry) as TemplateName[];
+}

package/src/render.ts

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { render } from "react-email";
+
+export async function renderToHtml(element: ReactElement): Promise<string> {
+  return render(element);
+}
+
+export async function renderToPlainText(
+  element: ReactElement,
+): Promise<string> {
+  return render(element, { plainText: true });
+}

package/src/types.ts

@@ -0,0 +1,107 @@
+import type { ReactElement } from "react";
+
+// ---------------------------------------------------------------------------
+// Template registry (open, augmentable — Option B "module augmentation")
+// ---------------------------------------------------------------------------
+
+/**
+ * The set of template keys known to the type system, and the props each key
+ * expects. This interface ships EMPTY: `@hogsend/email` bakes in no concrete
+ * business templates. Client apps declare their templates by augmenting it:
+ *
+ * ```ts
+ * declare module "@hogsend/email" {
+ *   interface TemplateRegistryMap {
+ *     welcome: { name: string; dashboardUrl?: string };
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, `TemplateName` resolves to the client's keys and
+ * `emailService.send({ template, props })` is fully type-checked.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: intentionally open for client augmentation
+export interface TemplateRegistryMap {}
+
+export type TemplateName = keyof TemplateRegistryMap;
+
+export interface TemplateDefinition<P = Record<string, unknown>> {
+  component: (props: P) => ReactElement;
+  defaultSubject: string;
+  category?: string;
+  preview?: (props: P) => string;
+}
+
+export type TemplateRegistry = {
+  [K in TemplateName]: TemplateDefinition<TemplateRegistryMap[K]>;
+};
+
+// ---------------------------------------------------------------------------
+// Render options
+// ---------------------------------------------------------------------------
+
+export interface EmailServiceRenderOptions<
+  K extends TemplateName = TemplateName,
+> {
+  template: K;
+  props: TemplateRegistryMap[K];
+}
+
+export interface EmailServiceRenderResult {
+  html: string;
+  text: string;
+  subject: string;
+  category?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Retry configuration
+// ---------------------------------------------------------------------------
+
+export interface RetryOptions {
+  maxRetries?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+}
+
+export const DEFAULT_RETRY_OPTIONS: Required<RetryOptions> = {
+  maxRetries: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 30_000,
+};
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class EmailSendError extends Error {
+  readonly retryable: boolean;
+  readonly statusCode?: number;
+
+  constructor(
+    message: string,
+    options: { retryable: boolean; statusCode?: number; cause?: unknown },
+  ) {
+    super(message, { cause: options.cause });
+    this.name = "EmailSendError";
+    this.retryable = options.retryable;
+    this.statusCode = options.statusCode;
+  }
+}
+
+export class EmailSuppressionError extends Error {
+  readonly reason: "unsubscribed" | "suppressed" | "category_unsubscribed";
+
+  constructor(reason: EmailSuppressionError["reason"], email: string) {
+    super(`Email to ${email} suppressed: ${reason}`);
+    this.name = "EmailSuppressionError";
+    this.reason = reason;
+  }
+}
+
+export class WebhookVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WebhookVerificationError";
+  }
+}

package/src/unsubscribe-tokens.ts

@@ -0,0 +1,116 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export type TokenAction = "unsubscribe" | "resubscribe" | "manage";
+
+export interface UnsubscribeTokenPayload {
+  externalId: string;
+  email: string;
+  category?: string;
+  action: TokenAction;
+  exp: number;
+}
+
+export interface TokenOptions {
+  secret: string;
+  externalId: string;
+  email: string;
+  category?: string;
+  action: TokenAction;
+  expiresInSeconds?: number;
+}
+
+export class InvalidTokenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidTokenError";
+  }
+}
+
+const DEFAULT_EXPIRY_SECONDS = 30 * 24 * 3600; // 30 days
+
+function toBase64Url(data: string): string {
+  return Buffer.from(data).toString("base64url");
+}
+
+function fromBase64Url(data: string): string {
+  return Buffer.from(data, "base64url").toString("utf-8");
+}
+
+function sign(payload: string, secret: string): string {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function generateUnsubscribeToken(options: TokenOptions): string {
+  const {
+    secret,
+    externalId,
+    email,
+    category,
+    action,
+    expiresInSeconds = DEFAULT_EXPIRY_SECONDS,
+  } = options;
+
+  const payload: UnsubscribeTokenPayload = {
+    externalId,
+    email,
+    action,
+    exp: Math.floor(Date.now() / 1000) + expiresInSeconds,
+  };
+
+  if (category) {
+    payload.category = category;
+  }
+
+  const encodedPayload = toBase64Url(JSON.stringify(payload));
+  const signature = sign(encodedPayload, secret);
+
+  return `${encodedPayload}.${signature}`;
+}
+
+export function validateUnsubscribeToken(opts: {
+  token: string;
+  secret: string;
+}): UnsubscribeTokenPayload {
+  const { token, secret } = opts;
+  const parts = token.split(".");
+  if (parts.length !== 2) {
+    throw new InvalidTokenError("Malformed token");
+  }
+
+  const [encodedPayload, signature] = parts as [string, string];
+
+  const expectedSignature = sign(encodedPayload, secret);
+
+  const sigBuffer = Buffer.from(signature, "base64url");
+  const expectedBuffer = Buffer.from(expectedSignature, "base64url");
+
+  if (
+    sigBuffer.length !== expectedBuffer.length ||
+    !timingSafeEqual(sigBuffer, expectedBuffer)
+  ) {
+    throw new InvalidTokenError("Invalid token signature");
+  }
+
+  let payload: UnsubscribeTokenPayload;
+  try {
+    payload = JSON.parse(fromBase64Url(encodedPayload));
+  } catch {
+    throw new InvalidTokenError("Malformed token payload");
+  }
+
+  if (
+    !payload.externalId ||
+    !payload.email ||
+    !payload.action ||
+    !payload.exp
+  ) {
+    throw new InvalidTokenError("Incomplete token payload");
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (payload.exp < now) {
+    throw new InvalidTokenError("Token has expired");
+  }
+
+  return payload;
+}

package/src/unsubscribe-url.ts

@@ -0,0 +1,38 @@
+import { generateUnsubscribeToken } from "./unsubscribe-tokens.js";
+
+export interface UnsubscribeUrlOptions {
+  baseUrl: string;
+  secret: string;
+  externalId: string;
+  email: string;
+  category?: string;
+}
+
+export function generateUnsubscribeUrl(options: UnsubscribeUrlOptions): string {
+  const { baseUrl, secret, externalId, email, category } = options;
+
+  const token = generateUnsubscribeToken({
+    secret,
+    externalId,
+    email,
+    category,
+    action: "unsubscribe",
+  });
+
+  return `${baseUrl}/v1/email/unsubscribe?token=${encodeURIComponent(token)}`;
+}
+
+export function generatePreferenceCenterUrl(
+  options: Omit<UnsubscribeUrlOptions, "category">,
+): string {
+  const { baseUrl, secret, externalId, email } = options;
+
+  const token = generateUnsubscribeToken({
+    secret,
+    externalId,
+    email,
+    action: "manage",
+  });
+
+  return `${baseUrl}/v1/email/preferences?token=${encodeURIComponent(token)}`;
+}