@hogsend/engine 0.8.0 → 0.10.0

package/src/destinations/presets/slack.ts

@@ -0,0 +1,66 @@
+import { WEBHOOK_EVENT_TYPES } from "../../lib/webhook-signing.js";
+import { defineDestination } from "../define-destination.js";
+
+/** Slack destination config read off `endpoint.config`. */
+interface SlackConfig {
+  /**
+   * The Slack INCOMING WEBHOOK url (`https://hooks.slack.com/services/…`). When
+   * set it overrides `endpoint.url`; either may carry it (the column `url` is the
+   * natural home, `config.url` the explicit one).
+   */
+  url?: string;
+  /** Optional username override for the posted message. */
+  username?: string;
+  /** Optional emoji icon (e.g. `:email:`) for the posted message. */
+  iconEmoji?: string;
+}
+
+/** A compact, human-readable line per catalog event for the Slack text block. */
+function formatLine(type: string, data: Record<string, unknown>): string {
+  const to = typeof data.to === "string" ? data.to : undefined;
+  const email = typeof data.userEmail === "string" ? data.userEmail : undefined;
+  const template =
+    typeof data.templateKey === "string" ? data.templateKey : undefined;
+  const who = to ?? email;
+  const parts = [`*${type}*`];
+  if (who) parts.push(`for \`${who}\``);
+  if (template) parts.push(`(template \`${template}\`)`);
+  return parts.join(" ");
+}
+
+/**
+ * Slack incoming-webhook destination — posts a formatted text block per catalog
+ * event to a Slack channel. The webhook url comes from `config.url` (preferred)
+ * or the endpoint `url`; a missing url is a CONFIG error (thrown → DLQ).
+ *
+ * Slack returns `200` with a plain `ok` body on success and a non-2xx on a bad
+ * payload, so the default 2xx success rule is correct (no `isSuccess` override).
+ */
+export const slackDestination = defineDestination({
+  meta: {
+    id: "slack",
+    name: "Slack",
+    description:
+      "Post a formatted message per email-lifecycle event to a Slack channel.",
+  },
+  events: [...WEBHOOK_EVENT_TYPES],
+  transform(envelope, ctx) {
+    const config = (ctx.endpoint.config ?? {}) as SlackConfig;
+    const url = config.url ?? ctx.endpoint.url;
+    if (!url || url.length === 0) {
+      throw new Error(
+        "slack destination is missing config.url / endpoint.url (non-retryable config error)",
+      );
+    }
+    return {
+      url,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        text: formatLine(envelope.type, envelope.data),
+        ...(config.username ? { username: config.username } : {}),
+        ...(config.iconEmoji ? { icon_emoji: config.iconEmoji } : {}),
+      }),
+    };
+  },
+});

package/src/destinations/presets/webhook.ts

@@ -0,0 +1,37 @@
+import { signWebhook, WEBHOOK_EVENT_TYPES } from "../../lib/webhook-signing.js";
+import { defineDestination } from "../define-destination.js";
+
+/**
+ * The DEFAULT destination — the signed Standard-Webhooks POST every existing
+ * subscriber receives. BYTE-IDENTICAL to the pre-destination delivery: the same
+ * `signWebhook` arguments (id = the envelope id, timestamp = current epoch
+ * seconds, payload = the frozen envelope, secret = the live endpoint secret) and
+ * the exact signed bytes + headers, POSTed to the raw `endpoint.url`.
+ *
+ * Its `meta.id` is `"webhook"`, so an endpoint with `kind = "webhook"` (the
+ * column default) resolves here. This preset is ALWAYS registered, so the
+ * critical no-regression invariant holds even when a consumer wires no
+ * destinations of their own.
+ */
+export const webhookDestination = defineDestination({
+  meta: {
+    id: "webhook",
+    name: "Signed webhook",
+    description:
+      "The default Standard-Webhooks signed POST to a subscriber URL (Svix HMAC).",
+  },
+  // The default signed webhook fans out the WHOLE outbound catalog — it is the
+  // generic subscriber transport, not a per-vendor projection.
+  events: [...WEBHOOK_EVENT_TYPES],
+  transform(envelope, ctx) {
+    const { headers, body } = signWebhook({
+      id: envelope.id,
+      // Same expression the pre-destination delivery task used, so the signature
+      // matches the body the task sends.
+      timestamp: Math.floor(Date.now() / 1000),
+      payload: envelope,
+      secret: ctx.endpoint.secret ?? "",
+    });
+    return { url: ctx.endpoint.url, headers, body };
+  },
+});

package/src/destinations/registry-singleton.ts

@@ -0,0 +1,78 @@
+import type { DefinedDestination } from "./define-destination.js";
+import { PRESET_DESTINATIONS } from "./presets/index.js";
+
+/**
+ * The process-wide destination registry, set once by `createHogsendClient` at
+ * startup and read by the delivery task (`workflows/deliver-webhook.ts`) to
+ * resolve a transform by `endpoint.kind`.
+ *
+ * Why a singleton (mirrors `lib/analytics-singleton.ts`): the durable
+ * `deliverWebhookTask` SELF-BOOTS — it opens its own `getDb()` from
+ * `process.env` and has NO client/container reference. So the registered
+ * transforms (presets + the consumer's `defineDestination()` destinations) MUST
+ * be reachable via a process singleton, exactly as analytics / the journey +
+ * bucket registries are. `createHogsendClient` runs in BOTH the API and worker,
+ * so by the time any worker task executes the registry has been installed.
+ *
+ * Resilient default: if a delivery task somehow runs in a process that never
+ * called `createHogsendClient` (a bare reaper re-drive in a test harness), the
+ * getter lazily falls back to the shipped {@link PRESET_DESTINATIONS} so the
+ * no-regression `webhook` + the `posthog` presets still resolve. Installing a
+ * registry via {@link setDestinationRegistry} replaces this fallback.
+ */
+export class DestinationRegistry {
+  private readonly byKind = new Map<string, DefinedDestination>();
+
+  constructor(destinations: DefinedDestination[] = []) {
+    for (const destination of destinations) {
+      // Last-writer-wins on id collision — the caller (container) orders the
+      // array so the consumer's destination wins over a preset of the same id.
+      this.byKind.set(destination.meta.id, destination);
+    }
+  }
+
+  /** Resolve a destination by its `kind` id, or `undefined` when unregistered. */
+  get(kind: string): DefinedDestination | undefined {
+    return this.byKind.get(kind);
+  }
+
+  /** Every registered destination (for diagnostics / catalog enumeration). */
+  getAll(): DefinedDestination[] {
+    return [...this.byKind.values()];
+  }
+
+  /** Number of registered destinations. */
+  count(): number {
+    return this.byKind.size;
+  }
+}
+
+/** The lazily-built fallback registry of just the shipped presets. */
+let fallback: DestinationRegistry | undefined;
+let installed: DestinationRegistry | undefined;
+
+/**
+ * Install the resolved destination registry. Called by `createHogsendClient`
+ * after merging the env presets with the consumer's `opts.destinations`.
+ */
+export function setDestinationRegistry(registry: DestinationRegistry): void {
+  installed = registry;
+}
+
+/**
+ * Read the destination registry. Returns the installed registry, or a lazily
+ * built preset-only fallback so a self-booting task always resolves the
+ * always-on `webhook` + `posthog` presets even before any container ran.
+ */
+export function getDestinationRegistry(): DestinationRegistry {
+  if (installed) return installed;
+  if (!fallback) {
+    fallback = new DestinationRegistry(Object.values(PRESET_DESTINATIONS));
+  }
+  return fallback;
+}
+
+/** Reset the installed registry — only for test cleanup. */
+export function resetDestinationRegistry(): void {
+  installed = undefined;
+}

package/src/env.ts

@@ -27,8 +27,30 @@ export const env = createEnv({
     // comma-separated. Needed when the Studio is served from a different origin
     // than the API — e.g. the `hogsend studio` CLI pointing at a remote instance.
     BETTER_AUTH_TRUSTED_ORIGINS: z.string().optional(),
-    RESEND_API_KEY: z.string().min(1),
+    // Optional: a deploy may run a non-Resend provider (Postmark, SES…) and set
+    // no Resend key at all. Read directly ONLY in the lazy-resend default branch
+    // (container.ts) and the future `emailProvidersFromEnv` preset. With this
+    // optional, a Postmark-only deploy boots without a Resend key.
+    RESEND_API_KEY: z.string().min(1).optional(),
     RESEND_FROM_EMAIL: z.string().email().default("noreply@hogsend.com"),
+    // --- Provider-neutral email config (BYO email provider) ---
+    // The active email provider id the container resolves from the
+    // EmailProviderRegistry. Absent → "resend" (today's byte-for-byte default).
+    EMAIL_PROVIDER: z.string().optional(),
+    // Neutral default-from address. The mailer's `defaultFrom` is
+    // `EMAIL_FROM ?? RESEND_FROM_EMAIL`, so an unset EMAIL_FROM keeps today's
+    // Resend-named default.
+    EMAIL_FROM: z.string().email().optional(),
+    // --- Postmark (opt-in BYO provider) ---
+    // Postmark stays OPT-IN: a preset is built only when POSTMARK_SERVER_TOKEN
+    // is present, and it NEVER changes the default active provider — set
+    // EMAIL_PROVIDER=postmark to activate it. Postmark has no HMAC, so webhook
+    // authenticity is HTTP Basic creds in the webhook URL — fail-closed when
+    // unset (status updates rejected).
+    POSTMARK_SERVER_TOKEN: z.string().min(1).optional(),
+    POSTMARK_MESSAGE_STREAM: z.string().min(1).optional(),
+    POSTMARK_WEBHOOK_USER: z.string().min(1).optional(),
+    POSTMARK_WEBHOOK_PASS: z.string().min(1).optional(),
     // Hatchet connection contract. The @hatchet-dev SDK also reads these straight
     // from process.env via its own config-loader, so this schema is a presence /
     // shape check that keeps the contract in one place — the values still flow to
@@ -57,6 +79,12 @@ export const env = createEnv({
     POSTHOG_API_KEY: z.string().min(1).optional(),
     POSTHOG_HOST: z.string().url().optional(),
     POSTHOG_WEBHOOK_SECRET: z.string().min(1).optional(),
+    // When true AND POSTHOG_API_KEY is set, the engine idempotently auto-seeds
+    // ONE kind="posthog" webhook endpoint subscribed to the email funnel so the
+    // full email lifecycle fans out to PostHog DURABLY (on the delivery spine).
+    // Default OFF to avoid a surprise double-emit alongside the existing
+    // fire-and-forget PostHog capture path.
+    ENABLE_POSTHOG_DESTINATION: z.coerce.boolean().default(false),
     RESEND_WEBHOOK_SECRET: z.string().min(1).optional(),
     ADMIN_API_KEY: z.string().min(1).optional(),
     API_PUBLIC_URL: z.string().url().default("http://localhost:3002"),
@@ -96,6 +124,15 @@ export const env = createEnv({
     // Preset enablement override: csv of preset ids, `"*"` (all with a secret),
     // or `"none"`. Absent → auto-enable any preset whose secret is set.
     ENABLED_WEBHOOK_PRESETS: z.string().optional(),
+    // --- Outbound destination presets (Phase 3) ---
+    // Which `defineDestination()` PRESETS are registered into the process
+    // destination registry the delivery task resolves by `endpoint.kind`. csv of
+    // ids (e.g. "segment,slack"), `"*"` (all presets), or `"none"`. Absent → the
+    // DEFAULT set (webhook + posthog). The `webhook` and `posthog` presets are
+    // ALWAYS registered regardless of this value, so the no-regression delivery
+    // path can never be turned off by misconfiguration. Set this to add the
+    // segment/slack presets (credentials still live per-endpoint in `config`).
+    ENABLED_DESTINATION_PRESETS: z.string().optional(),
   },
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,

package/src/index.ts

@@ -3,24 +3,32 @@
 // Content (journeys, webhook sources, workflows) is injected into these
 // factories by client app code; the engine never imports content.
 
-// --- Capability-provider contracts (canonical origin: @hogsend/core) ---
-// Email provider contract + analytics contract, re-exported so consumers can
-// import them from `@hogsend/engine`. (`SendEmailOptions` is intentionally
-// omitted here: the engine's public `SendEmailOptions` is the high-level
-// journey-facing send options from `./lib/email.js`; the provider-contract
-// `SendEmailOptions` remains available via `@hogsend/core`.)
 export type {
   BatchEmailItem,
   CaptureOptions,
+  EmailEvent,
+  EmailEventType,
   EmailProvider,
+  EmailProviderCapabilities,
+  EmailProviderMeta,
+  /** @deprecated Use {@link EmailEvent}. Frozen `event.raw` cast target. */
+  LegacyResendWebhookEvent,
   PostHogService,
   SendResult,
+  /** @deprecated Use {@link EmailEvent}. Kept for one minor. */
   WebhookEvent,
   WebhookHandlerMap,
 } from "@hogsend/core";
 // Core helpers used by content journeys (days/hours/minutes, condition + journey
 // types) so content can import everything from `@hogsend/engine`.
 export * from "@hogsend/core";
+// --- Capability-provider contracts (canonical origin: @hogsend/core) ---
+// Email provider contract + analytics contract, re-exported so consumers can
+// import them from `@hogsend/engine`. (`SendEmailOptions` is intentionally
+// omitted here: the engine's public `SendEmailOptions` is the high-level
+// journey-facing send options from `./lib/email.js`; the provider-contract
+// `SendEmailOptions` remains available via `@hogsend/core`.)
+export { defineEmailProvider, WebhookHandshakeSignal } from "@hogsend/core";
 export {
   BucketRegistry,
   JourneyRegistry,
@@ -76,6 +84,31 @@ export {
   type HogsendClientOptions,
   type HogsendDefaults,
 } from "./container.js";
+// --- Outbound destinations: public authoring layer (Phase 3) ---
+export {
+  type DefinedDestination,
+  type DestinationCtx,
+  type DestinationEnvelope,
+  type DestinationMeta,
+  type DestinationTransformResult,
+  defineDestination,
+  type WebhookEndpointRow,
+} from "./destinations/define-destination.js";
+export {
+  type DestinationPresetId,
+  destinationsFromEnv,
+  PRESET_DESTINATIONS,
+  posthogDestination,
+  segmentDestination,
+  slackDestination,
+  webhookDestination,
+} from "./destinations/presets/index.js";
+export {
+  DestinationRegistry,
+  getDestinationRegistry,
+  resetDestinationRegistry,
+  setDestinationRegistry,
+} from "./destinations/registry-singleton.js";
 // --- Env ---
 export { API_VERSION, env } from "./env.js";
 // --- Journeys ---
@@ -124,6 +157,8 @@ export {
   sendEmail,
   setEmailService,
 } from "./lib/email.js";
+// --- Email provider registry (container-held, keyed by meta.id) ---
+export { EmailProviderRegistry } from "./lib/email-provider-registry.js";
 // --- Email service (engine-owned tracked mailer) ---
 export type {
   EmailService,
@@ -180,6 +215,11 @@ export {
 export {
   pushTrackingEvent,
   resolveEmailSendContext,
+  resolveEmailSendContextByMessageId,
+  /**
+   * @deprecated Kept for one minor; use
+   * {@link resolveEmailSendContextByMessageId}.
+   */
   resolveEmailSendContextByResendId,
 } from "./lib/tracking-events.js";
 // --- Outbound webhooks: signing core (Section 1.2) ---

package/src/journeys/define-journey.ts

@@ -179,7 +179,6 @@ export function defineJourney(options: {
         hatchetCtx,
         registry: getJourneyRegistrySingleton(),
         logger,
-        posthog,
         stateId,
         userId,
         userEmail,

package/src/journeys/journey-context.ts

@@ -7,7 +7,7 @@ import {
   SleepCondition,
   UserEventCondition,
 } from "@hatchet-dev/typescript-sdk/v1/index.js";
-import type { DurationObject, PostHogService } from "@hogsend/core";
+import type { DurationObject } from "@hogsend/core";
 import { durationToMs, evaluateEventCondition } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import {
@@ -69,7 +69,6 @@ interface JourneyContextConfig {
   };
   registry: JourneyRegistry;
   logger: Logger;
-  posthog?: PostHogService;
   stateId: string;
   userId: string;
   userEmail: string;
@@ -140,7 +139,6 @@ export function createJourneyContext(
     hatchetCtx,
     registry,
     logger,
-    posthog,
     stateId,
     userId,
     userEmail,
@@ -316,10 +314,6 @@ export function createJourneyContext(
       });
     },
 
-    identify(properties) {
-      posthog?.identify(userId, properties);
-    },
-
     guard: {
       async isSubscribed() {
         const prefs = await checkEmailPreferences({ db, userId });
@@ -390,15 +384,5 @@ export function createJourneyContext(
         };
       },
     },
-
-    posthog: {
-      capture({ event, properties }) {
-        posthog?.captureEvent({
-          distinctId: userId,
-          event,
-          properties,
-        });
-      },
-    },
   };
 }

package/src/lib/analytics-singleton.ts

@@ -6,6 +6,13 @@ import { createOptionalSingleton } from "./singleton.js";
  * the module-level task-execution sites that have no client reference of their
  * own (the journey durable task in `define-journey`, the bucket PostHog sync).
  *
+ * Its role is deliberately NARROW (see the `analytics?` option doc on
+ * {@link createHogsendClient}): the identity PULL (`getPersonProperties` for
+ * per-user timezone resolution) and the opt-in `bucket.syncToPostHog`
+ * person-property mirror. It is explicitly NOT the outbound-catalog firing
+ * path — the email/contact/journey/bucket lifecycle fans out durably via
+ * DESTINATIONS on the webhook spine, not through this singleton.
+ *
  * Mirrors the journey/bucket-registry + client-schedule-defaults singletons:
  * `createHogsendClient` runs in BOTH the API and worker processes, so by the
  * time any worker task executes, the container has already installed the

package/src/lib/email-provider-registry.ts

@@ -0,0 +1,45 @@
+import type { EmailProvider } from "@hogsend/core";
+
+/**
+ * Container-held registry of email providers, keyed by `provider.meta.id`. The
+ * webhook route (`POST /v1/webhooks/email/:providerId`) resolves the verifying
+ * provider out of this registry via `c.get("container")`, and the container
+ * also picks ONE `active` provider out of it for the mailer.
+ *
+ * Deliberately NOT a process singleton: unlike the `DestinationRegistry`
+ * singleton — which exists only because the self-booting `deliverWebhookTask`
+ * has no container — both readers of this registry (the mailer the container
+ * constructs, and the webhook route which has the container) have a container
+ * reference, so the singleton + lazy-preset fallback would be dead weight.
+ *
+ * Keyed by `meta.id` with last-writer-wins, so a consumer-supplied provider of
+ * the same id overrides an env preset of that id.
+ */
+export class EmailProviderRegistry {
+  private byId = new Map<string, EmailProvider>();
+
+  constructor(providers: EmailProvider[] = []) {
+    for (const provider of providers) this.register(provider);
+  }
+
+  /**
+   * Register (or replace) a provider. Falls back to `"resend"` for a provider
+   * built before `meta` existed (the contract keeps `meta` optional for
+   * back-compat). Last-writer-wins.
+   */
+  register(provider: EmailProvider): void {
+    this.byId.set(provider.meta?.id ?? "resend", provider);
+  }
+
+  get(id: string): EmailProvider | undefined {
+    return this.byId.get(id);
+  }
+
+  getAll(): EmailProvider[] {
+    return [...this.byId.values()];
+  }
+
+  count(): number {
+    return this.byId.size;
+  }
+}

package/src/lib/email-providers-from-env.ts

@@ -0,0 +1,94 @@
+import type { EmailProvider } from "@hogsend/core";
+import { createResendProvider } from "@hogsend/plugin-resend";
+import type { env as envSchema } from "../env.js";
+
+/**
+ * `@hogsend/plugin-postmark` is an OPT-IN, deferred-publish package: it is an
+ * engine `optionalDependency`, NOT a hard one, and it is not on the npm registry
+ * yet. So we MUST NOT statically import it — a static `import` would make the
+ * package mandatory at engine load, and `npm install @hogsend/engine` would fail
+ * with E404 on plugin-postmark for every consumer that doesn't have it.
+ *
+ * Instead we load it lazily, ONCE, behind a top-level guarded dynamic import:
+ * the `import()` only fires when `POSTMARK_SERVER_TOKEN` is present (the same
+ * gate the preset below uses), so a deploy that never sets that var never
+ * touches the package and degrades gracefully when it isn't installed. ESM
+ * top-level await keeps `emailProvidersFromEnv` itself synchronous (it reads the
+ * already-resolved factory), so `createHogsendClient` stays synchronous.
+ *
+ * The specifier is assembled at runtime (not a string literal) ON PURPOSE: a
+ * literal `import("@hogsend/plugin-postmark")` makes `tsc` resolve the module's
+ * types, which fails with TS2307 for any consumer that doesn't have the opt-in
+ * package installed (e.g. a fresh `create-hogsend` app). A computed specifier is
+ * opaque to the type-checker — resolved only at runtime — so the engine
+ * type-checks identically with or without the package present.
+ */
+type CreatePostmarkProvider = (cfg: {
+  serverToken: string;
+  messageStream?: string;
+  webhookBasicAuth?: { user: string; pass: string };
+}) => EmailProvider;
+
+const POSTMARK_PACKAGE = ["@hogsend", "plugin-postmark"].join("/");
+
+let createPostmarkProvider: CreatePostmarkProvider | null = null;
+if (process.env.POSTMARK_SERVER_TOKEN) {
+  try {
+    ({ createPostmarkProvider } = (await import(POSTMARK_PACKAGE)) as {
+      createPostmarkProvider: CreatePostmarkProvider;
+    });
+  } catch {
+    // The token is set but the opt-in package isn't installed. Leave the factory
+    // null — `emailProvidersFromEnv` skips the preset, and if Postmark was the
+    // resolved active provider the container throws a clear "not registered"
+    // error directing the operator to install `@hogsend/plugin-postmark`.
+    createPostmarkProvider = null;
+  }
+}
+
+/**
+ * Build the env-enabled email-provider presets. Mirrors `destinationsFromEnv`:
+ * a preset is constructed ONLY when its credential is present, so a
+ * Postmark-only deploy (no `RESEND_API_KEY`) contributes no Resend provider.
+ *
+ * These presets come FIRST in the container's merge — a consumer-supplied
+ * provider of the same id wins (last-writer-wins on the registry).
+ */
+export function emailProvidersFromEnv(env: typeof envSchema): EmailProvider[] {
+  const providers: EmailProvider[] = [];
+
+  if (env.RESEND_API_KEY) {
+    providers.push(
+      createResendProvider({
+        apiKey: env.RESEND_API_KEY,
+        webhookSecret: env.RESEND_WEBHOOK_SECRET,
+      }),
+    );
+  }
+
+  // Postmark is OPT-IN: built only when its token is present AND the opt-in
+  // package resolved (see the guarded dynamic import above), and it never
+  // changes the default active provider — set EMAIL_PROVIDER=postmark to
+  // activate it. Postmark has no HMAC, so webhook auth is HTTP Basic creds (the
+  // provider fails closed when they're unset).
+  if (env.POSTMARK_SERVER_TOKEN && createPostmarkProvider) {
+    providers.push(
+      createPostmarkProvider({
+        serverToken: env.POSTMARK_SERVER_TOKEN,
+        ...(env.POSTMARK_MESSAGE_STREAM
+          ? { messageStream: env.POSTMARK_MESSAGE_STREAM }
+          : {}),
+        ...(env.POSTMARK_WEBHOOK_USER && env.POSTMARK_WEBHOOK_PASS
+          ? {
+              webhookBasicAuth: {
+                user: env.POSTMARK_WEBHOOK_USER,
+                pass: env.POSTMARK_WEBHOOK_PASS,
+              },
+            }
+          : {}),
+      }),
+    );
+  }
+
+  return providers;
+}

package/src/lib/email-service-types.ts

@@ -1,9 +1,10 @@
 import type {
   BatchEmailItem,
   DurationObject,
+  EmailEvent,
+  EmailEventType,
   SendEmailOptions,
   SendResult,
-  WebhookEventType,
   WebhookHandlerMap,
 } from "@hogsend/core";
 import type {
@@ -63,12 +64,36 @@ export interface SendTrackedEmailOptions<
 
 export interface TrackedSendResult {
   emailSendId: string;
+  /** The provider's neutral message id (Resend email_id / Postmark MessageID). */
+  messageId: string;
+  /**
+   * @deprecated Renamed to {@link TrackedSendResult.messageId}. This read-alias
+   * always mirrors `messageId`; kept for one minor and removed the following
+   * minor. Build results via {@link trackedSendResult} so the alias stays live.
+   */
   resendId: string;
   status: "sent" | "suppressed" | "unsubscribed" | "skipped";
   /** Present only when `status === "skipped"` by the frequency cap. */
   reason?: "frequency_capped";
 }
 
+/**
+ * Build a {@link TrackedSendResult}, attaching a live `@deprecated` `resendId`
+ * read-alias getter that mirrors `messageId`. Lets every send path return a
+ * single canonical `messageId` while public consumers reading the old `resendId`
+ * field keep working for one minor.
+ */
+export function trackedSendResult(
+  result: Omit<TrackedSendResult, "resendId">,
+): TrackedSendResult {
+  return Object.defineProperty({ ...result }, "resendId", {
+    get(this: { messageId: string }) {
+      return this.messageId;
+    },
+    enumerable: true,
+  }) as TrackedSendResult;
+}
+
 // ---------------------------------------------------------------------------
 // Frequency capping (client default config)
 // ---------------------------------------------------------------------------
@@ -102,7 +127,6 @@ export interface EmailServiceConfig {
    */
   templates: TemplateRegistry;
   db?: unknown;
-  webhookSecret?: string;
   webhookHandlers?: WebhookHandlerMap;
   retryOptions?: RetryOptions;
   bounceThreshold?: number;
@@ -138,13 +162,18 @@ export interface EmailServiceSendOptions<
   idempotencyKey?: string;
 }
 
+/**
+ * @deprecated The route now verifies the provider webhook and hands
+ * {@link EmailService.handleWebhook} an already-parsed {@link EmailEvent}. This
+ * raw `{ payload, headers }` shape is no longer the handler input.
+ */
 export interface EmailServiceWebhookOptions {
   payload: string;
   headers: Record<string, string>;
 }
 
 export interface EmailServiceWebhookResult {
-  type: WebhookEventType;
+  type: EmailEventType;
   handled: boolean;
 }
 
@@ -163,7 +192,14 @@ export interface EmailService {
     options: EmailServiceRenderOptions<K>,
   ): Promise<EmailServiceRenderResult>;
 
+  /**
+   * Dispatch an already-verified, provider-neutral {@link EmailEvent} into the
+   * status/suppression/outbound pipeline. The webhook route owns provider
+   * resolution + signature verification and passes the parsed event + the
+   * resolving `providerId` (the latter is informational for now).
+   */
   handleWebhook(
-    options: EmailServiceWebhookOptions,
+    event: EmailEvent,
+    providerId?: string,
   ): Promise<EmailServiceWebhookResult>;
 }

package/src/lib/headers.ts

@@ -0,0 +1,13 @@
+/**
+ * Flatten a `Headers` instance into a plain lowercased `Record<string, string>`.
+ * Webhook routes verify signatures over the EXACT received bytes, so they need a
+ * case-insensitive header lookup — this is the single place that lowercasing
+ * lives. Pass `c.req.raw.headers`.
+ */
+export function headersToRecord(headers: Headers): Record<string, string> {
+  const record: Record<string, string> = {};
+  for (const [key, value] of headers.entries()) {
+    record[key.toLowerCase()] = value;
+  }
+  return record;
+}