@hogsend/engine 0.9.0 → 0.10.0

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,