@hogsend/engine 0.9.0 → 0.11.0

package/src/lib/tracked.ts

@@ -14,10 +14,11 @@ import {
 } from "@hogsend/email";
 import { eq } from "drizzle-orm";
 import { getListRegistry } from "../lists/registry-singleton.js";
-import type {
-  FrequencyCapConfig,
-  SendTrackedEmailOptions,
-  TrackedSendResult,
+import {
+  type FrequencyCapConfig,
+  type SendTrackedEmailOptions,
+  type TrackedSendResult,
+  trackedSendResult,
 } from "./email-service-types.js";
 import { isFrequencyCapped } from "./frequency-cap.js";
 import { hatchet } from "./hatchet.js";
@@ -71,12 +72,12 @@ export async function sendTrackedEmail<K extends TemplateName>(
     id: string;
     status: string;
   }): TrackedSendResult =>
-    ({
+    trackedSendResult({
       emailSendId: prior.id,
-      resendId: "",
+      messageId: "",
       status: prior.status === "sent" ? "sent" : "skipped",
       ...(prior.status === "sent" ? {} : { reason: "frequency_capped" }),
-    }) as TrackedSendResult;
+    } as Omit<TrackedSendResult, "resendId">);
 
   // Idempotency short-circuit (POST /v1/emails): a retry with the same key
   // returns the prior send instead of dispatching a duplicate provider call /
@@ -135,15 +136,15 @@ export async function sendTrackedEmail<K extends TemplateName>(
       const suppressedRow = rows[0];
       if (!suppressedRow) throw new Error("Failed to insert email_sends row");
 
-      return {
+      return trackedSendResult({
         emailSendId: suppressedRow.id,
-        resendId: "",
+        messageId: "",
         status:
           suppression === "unsubscribed" ||
           suppression === "category_unsubscribed"
             ? "unsubscribed"
             : "suppressed",
-      };
+      });
     }
 
     // Frequency cap — consulted only for non-system sends (system mail sets
@@ -165,12 +166,12 @@ export async function sendTrackedEmail<K extends TemplateName>(
           to: options.to,
           category: options.category,
         });
-        return {
+        return trackedSendResult({
           emailSendId: "",
-          resendId: "",
+          messageId: "",
           status: "skipped",
           reason: "frequency_capped",
-        };
+        });
       }
     }
   }
@@ -257,22 +258,26 @@ export async function sendTrackedEmail<K extends TemplateName>(
   const emailSendId = insertedRow.id;
 
   try {
-    let html: string | undefined;
-    if (options.baseUrl && prepareTrackedHtml) {
-      const rawHtml = await renderToHtml(sendElement);
-      html = await prepareTrackedHtml({
-        html: rawHtml,
-        emailSendId,
-        baseUrl: options.baseUrl,
-        db,
-      });
-    }
+    // HTML-ONLY wire — the engine ALWAYS renders React → HTML itself. When
+    // tracking is on (baseUrl + prepareTrackedHtml) we render then rewrite
+    // links/inject the open pixel; otherwise we render plain HTML. React Email
+    // stays first-class for authoring/Studio; it never crosses the wire.
+    const rawHtml = await renderToHtml(sendElement);
+    const html =
+      options.baseUrl && prepareTrackedHtml
+        ? await prepareTrackedHtml({
+            html: rawHtml,
+            emailSendId,
+            baseUrl: options.baseUrl,
+            db,
+          })
+        : rawHtml;
 
     const result = await provider.send({
       from: options.from,
       to: options.to,
       subject,
-      ...(html ? { html } : { react: sendElement }),
+      html,
       tags: options.tags,
       headers: sendHeaders,
       replyTo: options.replyTo,
@@ -282,7 +287,7 @@ export async function sendTrackedEmail<K extends TemplateName>(
     await db
       .update(emailSends)
       .set({
-        resendId: result.id,
+        messageId: result.id,
         status: "sent",
         sentAt,
         updatedAt: sentAt,
@@ -306,7 +311,7 @@ export async function sendTrackedEmail<K extends TemplateName>(
       dedupeKey: `email.sent:${emailSendId}`,
       payload: {
         emailSendId,
-        resendId: result.id,
+        messageId: result.id,
         templateKey: options.templateKey,
         to: options.to,
         userId: options.userId ?? null,
@@ -322,11 +327,11 @@ export async function sendTrackedEmail<K extends TemplateName>(
       });
     });
 
-    return {
+    return trackedSendResult({
       emailSendId,
-      resendId: result.id,
+      messageId: result.id,
       status: "sent",
-    };
+    });
   } catch (error) {
     // A provider send failed (transient SMTP/network/429). Stamp `failed` AND
     // RELEASE the idempotency key (set it null), exactly like the suppression

package/src/lib/tracking-events.ts

@@ -9,7 +9,7 @@ interface EmailSendContext {
   userId: string;
   userEmail: string;
   templateKey: string | null;
-  resendId: string | null;
+  messageId: string | null;
   to: string;
 }
 
@@ -21,7 +21,7 @@ export async function resolveEmailSendContext(
     .select({
       toEmail: emailSends.toEmail,
       templateKey: emailSends.templateKey,
-      resendId: emailSends.resendId,
+      messageId: emailSends.messageId,
       userId: journeyStates.userId,
       userEmail: journeyStates.userEmail,
     })
@@ -37,12 +37,12 @@ export async function resolveEmailSendContext(
     userId: row.userId ?? row.toEmail,
     userEmail: row.userEmail ?? row.toEmail,
     templateKey: row.templateKey,
-    resendId: row.resendId,
+    messageId: row.messageId,
     to: row.toEmail,
   };
 }
 
-export interface ResendEmailSendContext {
+export interface EmailSendContextByMessageId {
   emailSendId: string;
   userId: string;
   userEmail: string;
@@ -50,21 +50,28 @@ export interface ResendEmailSendContext {
   to: string;
 }
 
+/**
+ * @deprecated Renamed to {@link EmailSendContextByMessageId} as part of the
+ * provider-neutral `resendId` → `messageId` rename. Kept as an alias for one
+ * minor; removed the following minor.
+ */
+export type ResendEmailSendContext = EmailSendContextByMessageId;
+
 /**
  * Mirror of {@link resolveEmailSendContext} that resolves by the provider's
- * `resendId` instead of the internal `email_sends.id`. Used by the
+ * `messageId` instead of the internal `email_sends.id`. Used by the
  * provider-webhook enrichment path (`email.delivered`/`email.bounced`) where the
- * only handle we hold is the Resend `email_id`.
+ * only handle we hold is the provider message id.
  *
  * Returns the internal `emailSendId` plus the same denormalized identity
  * (`userId`/`userEmail` fall back to the recipient address, exactly like the
  * id-keyed resolver) and `to` recipient. Returns null when no send row carries
- * that `resendId` yet (e.g. a webhook arriving before the send row is committed).
+ * that `messageId` yet (e.g. a webhook arriving before the send row is committed).
  */
-export async function resolveEmailSendContextByResendId(
+export async function resolveEmailSendContextByMessageId(
   db: Database,
-  resendId: string,
-): Promise<ResendEmailSendContext | null> {
+  messageId: string,
+): Promise<EmailSendContextByMessageId | null> {
   const rows = await db
     .select({
       emailSendId: emailSends.id,
@@ -77,7 +84,7 @@ export async function resolveEmailSendContextByResendId(
     })
     .from(emailSends)
     .leftJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
-    .where(eq(emailSends.resendId, resendId))
+    .where(eq(emailSends.messageId, messageId))
     .limit(1);
 
   const row = rows[0];
@@ -92,6 +99,14 @@ export async function resolveEmailSendContextByResendId(
   };
 }
 
+/**
+ * @deprecated Renamed to {@link resolveEmailSendContextByMessageId} as part of
+ * the provider-neutral `resendId` → `messageId` rename. Kept as an alias for one
+ * minor; removed the following minor.
+ */
+export const resolveEmailSendContextByResendId =
+  resolveEmailSendContextByMessageId;
+
 export interface PushTrackingEventOpts {
   db: Database;
   hatchet: HatchetClient;

package/src/middleware/rate-limit.ts

@@ -1,3 +1,4 @@
+import type { Context } from "hono";
 import { createMiddleware } from "hono/factory";
 import type { AppEnv } from "../app.js";
 import { getRedis } from "../lib/redis.js";
@@ -11,6 +12,38 @@ export interface RateLimitOptions {
   windowMs?: number;
   max?: number;
   prefix?: string;
+  /**
+   * Derive the per-request bucket key. Default keys on the resolved api-key /
+   * user id (falling back to "anonymous") — correct for the authenticated data
+   * plane. Pass `clientIpKey` for UNAUTHENTICATED surfaces (e.g. the first-admin
+   * sign-up gate) where every request would otherwise collapse onto the single
+   * "anonymous" bucket and let one attacker exhaust the budget for everyone.
+   */
+  keyFn?: (c: Context<AppEnv>) => string;
+  /**
+   * The middleware no-ops under `NODE_ENV=test` by default so the suite isn't
+   * throttled. Set `false` to keep it ACTIVE in tests — required to assert the
+   * unauthenticated sign-up limiter actually returns 429 past the threshold.
+   */
+  disableInTest?: boolean;
+}
+
+/**
+ * Best-effort client IP from the proxy headers Railway/Cloudflare set (same
+ * source as `audit.ts` / tracking). Falls back to "unknown" so a request with
+ * no forwarded IP still shares a single bounded bucket rather than bypassing.
+ */
+function clientIp(c: Context<AppEnv>): string {
+  return (
+    c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ||
+    c.req.header("x-real-ip") ||
+    "unknown"
+  );
+}
+
+/** Bucket key for unauthenticated, IP-scoped surfaces (e.g. sign-up). */
+export function clientIpKey(c: Context<AppEnv>): string {
+  return `ip:${clientIp(c)}`;
 }
 
 /**
@@ -25,6 +58,7 @@ export function createRateLimit(opts: RateLimitOptions = {}) {
   const windowMs = opts.windowMs ?? DEFAULT_WINDOW_MS;
   const max = opts.max ?? DEFAULT_MAX_REQUESTS;
   const prefix = opts.prefix ?? DEFAULT_PREFIX;
+  const disableInTest = opts.disableInTest ?? true;
 
   // Per-instance memory store so prefixes stay budget-isolated in the
   // Redis-less fallback path too.
@@ -32,10 +66,11 @@ export function createRateLimit(opts: RateLimitOptions = {}) {
   let cleanupCounter = 0;
 
   return createMiddleware<AppEnv>(async (c, next) => {
-    if (process.env.NODE_ENV === "test") return next();
+    if (disableInTest && process.env.NODE_ENV === "test") return next();
 
-    const apiKey = c.get("apiKey");
-    const keyId = apiKey?.id ?? c.get("user")?.id ?? "anonymous";
+    const keyId = opts.keyFn
+      ? opts.keyFn(c)
+      : (c.get("apiKey")?.id ?? c.get("user")?.id ?? "anonymous");
     const now = Date.now();
 
     let count: number;

package/src/routes/admin/emails.ts

@@ -26,6 +26,8 @@ const emailSchema = z.object({
   id: z.string(),
   journeyStateId: z.string().nullable(),
   templateKey: z.string().nullable(),
+  messageId: z.string().nullable(),
+  /** @deprecated Mirrors `messageId`; kept for one minor, removed thereafter. */
   resendId: z.string().nullable(),
   fromEmail: z.string(),
   toEmail: z.string(),
@@ -88,7 +90,9 @@ function serializeEmail(
     id: row.id,
     journeyStateId: row.journeyStateId,
     templateKey: row.templateKey,
-    resendId: row.resendId,
+    messageId: row.messageId,
+    // @deprecated Mirror of `messageId` for one minor (back-compat).
+    resendId: row.messageId,
     fromEmail: row.fromEmail,
     toEmail: row.toEmail,
     subject: row.subject,

package/src/routes/tracking/click.ts

@@ -121,7 +121,7 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
             event: "email.clicked",
             payload: {
               emailSendId,
-              resendId: ctx.resendId ?? null,
+              messageId: ctx.messageId ?? null,
               templateKey: ctx.templateKey ?? null,
               userId: ctx.userId ?? null,
               to: ctx.to ?? ctx.userEmail ?? "",

package/src/routes/tracking/open.ts

@@ -81,7 +81,7 @@ export const openRouter = new OpenAPIHono<AppEnv>().openapi(
             event: "email.opened",
             payload: {
               emailSendId: id,
-              resendId: ctx.resendId ?? null,
+              messageId: ctx.messageId ?? null,
               templateKey: ctx.templateKey ?? null,
               userId: ctx.userId ?? null,
               to: ctx.to ?? ctx.userEmail ?? "",

package/src/routes/webhooks/email-provider.ts

@@ -0,0 +1,124 @@
+import { WebhookHandshakeSignal } from "@hogsend/core";
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import type { Context } from "hono";
+import type { AppEnv } from "../../app.js";
+import { headersToRecord } from "../../lib/headers.js";
+
+/**
+ * Shared email-provider webhook dispatch used by BOTH the id-dispatched
+ * `POST /v1/webhooks/email/:providerId` route and the thin
+ * `POST /v1/webhooks/resend` alias. Resolves the provider from the container's
+ * {@link EmailProviderRegistry} (404 on unknown id), reads the raw body as the
+ * EXACT received bytes (signature schemes verify over these), verifies +
+ * dispatches the normalized {@link EmailEvent}, 200s a
+ * {@link WebhookHandshakeSignal}, and 401s a verification error.
+ */
+export async function dispatchProviderWebhook(
+  c: Context<AppEnv>,
+  providerId: string,
+) {
+  const { emailProviders, emailService, logger } = c.get("container");
+
+  const provider = emailProviders.get(providerId);
+  if (!provider) {
+    return c.json({ error: "Unknown email provider" }, 404);
+  }
+
+  // Read the body ONCE as the EXACT received bytes — signature schemes verify
+  // over these bytes, so we must not re-stringify.
+  const payload = await c.req.text();
+  const headers = headersToRecord(c.req.raw.headers);
+
+  try {
+    const event = await provider.verifyWebhook({ payload, headers });
+    const result = await emailService.handleWebhook(event, providerId);
+
+    logger.info("Email provider webhook processed", {
+      providerId,
+      type: event.type,
+      handled: result.handled,
+    });
+
+    return c.json({ ok: true }, 200);
+  } catch (err) {
+    if (err instanceof WebhookHandshakeSignal) {
+      // A non-delivery-status handshake (SNS confirm, Postmark subscription
+      // change) the provider already handled — ack with 200.
+      logger.info("Email webhook handshake", {
+        providerId,
+        action: err.action,
+      });
+      return c.json({ ok: true }, 200);
+    }
+    logger.warn("Email provider webhook failed", {
+      providerId,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    return c.json({ error: "Webhook verification failed" }, 401);
+  }
+}
+
+/**
+ * Id-dispatched email-provider webhook receiver:
+ * `POST /v1/webhooks/email/:providerId`.
+ *
+ * Resolves the provider from the container's {@link EmailProviderRegistry} (so
+ * an unknown id is a clean 404), verifies the webhook via that provider (which
+ * owns its OWN secrets), and dispatches the normalized {@link EmailEvent} into
+ * `emailService.handleWebhook`. Registered BEFORE the `:sourceId` catch-all so
+ * Hono matches the static `email/` prefix first.
+ *
+ * The provider's `verifyWebhook` is the ONLY place body-shape knowledge lives —
+ * the route never sniffs the payload. It returns a normalized event, OR throws
+ * {@link WebhookHandshakeSignal} for non-status handshakes (route 200s), OR
+ * throws a verification error (route 401s).
+ */
+const emailProviderWebhookRoute = createRoute({
+  method: "post",
+  path: "/v1/webhooks/email/{providerId}",
+  tags: ["Webhooks"],
+  summary: "Email provider webhook receiver",
+  request: {
+    params: z.object({ providerId: z.string() }),
+    body: {
+      content: {
+        "application/json": {
+          schema: z.record(z.string(), z.unknown()),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ ok: z.boolean() }),
+        },
+      },
+      description: "Webhook processed",
+    },
+    401: {
+      content: {
+        "application/json": {
+          schema: z.object({ error: z.string() }),
+        },
+      },
+      description: "Missing or invalid webhook signature",
+    },
+    404: {
+      content: {
+        "application/json": {
+          schema: z.object({ error: z.string() }),
+        },
+      },
+      description: "Unknown email provider",
+    },
+  },
+});
+
+export function registerEmailProviderRoutes(app: OpenAPIHono<AppEnv>) {
+  app.openapi(emailProviderWebhookRoute, (c) => {
+    const { providerId } = c.req.valid("param");
+    return dispatchProviderWebhook(c, providerId);
+  });
+}

package/src/routes/webhooks/index.ts

@@ -1,6 +1,7 @@
 import type { OpenAPIHono } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
 import type { DefinedWebhookSource } from "../../webhook-sources/define-webhook-source.js";
+import { registerEmailProviderRoutes } from "./email-provider.js";
 import { resendWebhookRouter } from "./resend.js";
 import { registerWebhookSourceRoutes } from "./sources.js";
 
@@ -12,6 +13,12 @@ export function registerWebhookRoutes(
   app: OpenAPIHono<AppEnv>,
   opts: RegisterWebhookRoutesOptions,
 ) {
+  // Order is load-bearing for Hono path matching:
+  //  1. the thin `/v1/webhooks/resend` alias (static),
+  //  2. the `/v1/webhooks/email/:providerId` id-dispatched route (static
+  //     `email/` prefix — MUST come before the catch-all),
+  //  3. the `/v1/webhooks/:sourceId` consumer-source catch-all (LAST).
   app.route("/v1/webhooks", resendWebhookRouter);
+  registerEmailProviderRoutes(app);
   registerWebhookSourceRoutes(app, opts.webhookSources);
 }

package/src/routes/webhooks/resend.ts

@@ -1,11 +1,13 @@
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
+import { dispatchProviderWebhook } from "./email-provider.js";
 
 const resendWebhookRoute = createRoute({
   method: "post",
   path: "/resend",
   tags: ["Webhooks"],
-  summary: "Resend webhook receiver",
+  summary:
+    "Resend webhook receiver (@deprecated — use /v1/webhooks/email/resend)",
   request: {
     body: {
       content: {
@@ -32,37 +34,20 @@ const resendWebhookRoute = createRoute({
       },
       description: "Missing or invalid webhook secret",
     },
+    404: {
+      content: {
+        "application/json": {
+          schema: z.object({ error: z.string() }),
+        },
+      },
+      description: "Resend provider not registered",
+    },
   },
 });
 
 export const resendWebhookRouter = new OpenAPIHono<AppEnv>().openapi(
   resendWebhookRoute,
-  async (c) => {
-    const { emailService, logger } = c.get("container");
-
-    const rawBody = await c.req.text();
-    const headers: Record<string, string> = {};
-    for (const [key, value] of c.req.raw.headers.entries()) {
-      headers[key] = value;
-    }
-
-    try {
-      const result = await emailService.handleWebhook({
-        payload: rawBody,
-        headers,
-      });
-
-      logger.info("Resend webhook processed", {
-        type: result.type,
-        handled: result.handled,
-      });
-
-      return c.json({ ok: true }, 200);
-    } catch (err) {
-      logger.warn("Resend webhook failed", {
-        error: err instanceof Error ? err.message : String(err),
-      });
-      return c.json({ error: "Webhook verification failed" }, 401);
-    }
-  },
+  // Thin deprecated alias for `POST /v1/webhooks/email/resend` — identical
+  // behavior, just the `resend` provider id wired in.
+  (c) => dispatchProviderWebhook(c, "resend"),
 );

package/src/routes/webhooks/sources.ts

@@ -1,5 +1,6 @@
 import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
+import { headersToRecord } from "../../lib/headers.js";
 import { ingestEvent } from "../../lib/ingestion.js";
 import type { DefinedWebhookSource } from "../../webhook-sources/define-webhook-source.js";
 import { verifySignature } from "../../webhook-sources/verify.js";
@@ -8,6 +9,19 @@ export function registerWebhookSourceRoutes(
   app: OpenAPIHono<AppEnv>,
   sources: DefinedWebhookSource[],
 ) {
+  // Reserve `email` for the email-provider route
+  // (`POST /v1/webhooks/email/:providerId`). A source with `meta.id === "email"`
+  // would shadow that prefix, so fail loudly at registration rather than let it
+  // silently break provider webhooks.
+  for (const source of sources) {
+    if (source.meta.id === "email") {
+      throw new Error(
+        'Webhook source id "email" is reserved for the email-provider route ' +
+          "(POST /v1/webhooks/email/:providerId). Rename the source.",
+      );
+    }
+  }
+
   const sourceMap = new Map(sources.map((s) => [s.meta.id, s]));
 
   const webhookRoute = createRoute({
@@ -56,10 +70,7 @@ export function registerWebhookSourceRoutes(
     // Read the body ONCE as the EXACT received bytes — signature schemes verify
     // over these bytes, so we must not re-stringify. JSON.parse only AFTER auth.
     const rawBody = await c.req.text();
-    const headers: Record<string, string> = {};
-    for (const [key, value] of c.req.raw.headers.entries()) {
-      headers[key.toLowerCase()] = value;
-    }
+    const headers = headersToRecord(c.req.raw.headers);
 
     const secret = env[source.auth.envKey as keyof typeof env] as
       | string

package/src/workflows/send-email.ts

@@ -34,7 +34,8 @@ export const sendEmailTask = hatchet.task({
 
     try {
       // `from` is optional: when absent the mailer's `resolveFrom` falls back to
-      // its configured defaultFrom (env.RESEND_FROM_EMAIL).
+      // its configured defaultFrom (env.RESEND_FROM_EMAIL). The neutral
+      // `tags: {name,value}[]` shape passes straight through to the provider wire.
       const result = await emailService.sendRaw({
         from: input.from,
         to: input.to,