@hogsend/engine 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -38,11 +38,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.9.0",
-    "@hogsend/db": "^0.9.0",
-    "@hogsend/email": "^0.9.0",
-    "@hogsend/plugin-posthog": "^0.9.0",
-    "@hogsend/plugin-resend": "^0.9.0"
+    "@hogsend/core": "^0.10.0",
+    "@hogsend/db": "^0.10.0",
+    "@hogsend/email": "^0.10.0",
+    "@hogsend/plugin-posthog": "^0.10.0",
+    "@hogsend/plugin-resend": "^0.10.0"
+  },
+  "optionalDependencies": {
+    "@hogsend/plugin-postmark": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/container.ts

@@ -9,11 +9,6 @@ import {
   type JournalShape,
 } from "@hogsend/db";
 import type { TemplateRegistry } from "@hogsend/email";
-import {
-  createResendClient,
-  createResendProvider,
-} from "@hogsend/plugin-resend";
-import type { Resend } from "resend";
 import { createBucketAccessor } from "./buckets/bucket-access.js";
 import type { DefinedBucket } from "./buckets/define-bucket.js";
 import {
@@ -33,6 +28,8 @@ import { buildJourneyRegistry } from "./journeys/registry.js";
 import { setAnalytics } from "./lib/analytics-singleton.js";
 import { type Auth, createAuth } from "./lib/auth.js";
 import { setEmailService } from "./lib/email.js";
+import { EmailProviderRegistry } from "./lib/email-provider-registry.js";
+import { emailProvidersFromEnv } from "./lib/email-providers-from-env.js";
 import type {
   EmailService,
   FrequencyCapConfig,
@@ -61,8 +58,19 @@ export interface HogsendClient {
   db: Database;
   dbClient: DatabaseClient;
   auth: Auth;
-  email: Resend;
   emailService: EmailService;
+  /**
+   * The container-held registry of email providers, keyed by `meta.id`. The
+   * `POST /v1/webhooks/email/:providerId` route resolves the verifying provider
+   * out of this. Holds at least the resolved active provider.
+   */
+  emailProviders: EmailProviderRegistry;
+  /**
+   * The single resolved active email provider (the one the mailer sends
+   * through). Resolved from `opts.email.defaultProvider` / `EMAIL_PROVIDER`,
+   * defaulting to the env-built Resend provider for byte-for-byte parity.
+   */
+  emailProvider: EmailProvider;
   /**
    * The app's template registry (key → component + subject + category +
    * optional preview/examples). Same object threaded into the engine mailer;
@@ -121,10 +129,18 @@ export interface HogsendClientOptions {
    * (templates → render → preference checks → tracking → `email_sends` write),
    * and the {@link EmailProvider} is only the swappable wire under it.
    *
-   * - `provider` — the swappable email provider (Resend, Postmark, SES…).
-   *   Defaults to a Resend provider built from env (`RESEND_API_KEY` /
-   *   `RESEND_WEBHOOK_SECRET`). Tracking/rendering/preferences come along for
-   *   free regardless of which provider you supply.
+   * - `provider` — a single swappable email provider (Resend, Postmark, SES…),
+   *   the back-compat one-provider seam. MERGED LAST (after env presets and
+   *   `providers`), so it wins on id collision. Tracking/rendering/preferences
+   *   come along for free regardless of which provider you supply.
+   * - `providers` — register MANY providers into the {@link EmailProviderRegistry}
+   *   (e.g. Resend + Postmark) so the `POST /v1/webhooks/email/:providerId`
+   *   route can verify each one's webhooks. Merged AFTER the env presets and
+   *   BEFORE `provider`.
+   * - `defaultProvider` — the active provider id the mailer sends through.
+   *   Resolves as `defaultProvider ?? EMAIL_PROVIDER ?? "resend"`. If it names a
+   *   provider that isn't registered, the container throws at boot with the list
+   *   of registered ids.
    * - `templates` — the app's template registry (key → component + subject +
    *   category), threaded into the engine mailer and onward to
    *   `getTemplate(..., { registry })`. The engine bakes in no business
@@ -136,6 +152,8 @@ export interface HogsendClientOptions {
    */
   email?: {
     provider?: EmailProvider;
+    providers?: EmailProvider[];
+    defaultProvider?: string;
     templates?: TemplateRegistry;
   };
   /**
@@ -249,8 +267,6 @@ export function createHogsendClient(
       ),
     });
 
-  const email = createResendClient({ apiKey: env.RESEND_API_KEY });
-
   const registry = buildJourneyRegistry(
     opts.journeys ?? [],
     opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
@@ -301,12 +317,51 @@ export function createHogsendClient(
     opts.enabledLists ?? env.ENABLED_LISTS,
   );
 
-  const provider =
-    opts.email?.provider ??
-    createResendProvider({
-      apiKey: env.RESEND_API_KEY,
-      webhookSecret: env.RESEND_WEBHOOK_SECRET,
-    });
+  // Build the email provider registry, then resolve the single active provider
+  // the mailer sends through. Merge order is load-bearing (consumer last/wins,
+  // mirroring the destinations merge): env presets FIRST, then
+  // `opts.email.providers`, then the single back-compat `opts.email.provider`
+  // LAST — so a consumer-supplied provider overrides an env preset of the same
+  // id (last-writer-wins on the registry). The registry is what the
+  // `POST /v1/webhooks/email/:providerId` route dispatches by id.
+  const emailProviders = new EmailProviderRegistry([
+    ...emailProvidersFromEnv(env),
+    ...(opts.email?.providers ?? []),
+    ...(opts.email?.provider ? [opts.email.provider] : []),
+  ]);
+
+  // The active provider id the mailer sends through:
+  // `defaultProvider ?? EMAIL_PROVIDER ?? "resend"`. The default Resend provider
+  // is built (when RESEND_API_KEY is set) by `emailProvidersFromEnv` above — the
+  // SINGLE place Resend is constructed from env — so resolution is just a
+  // registry lookup that throws if the active id resolves to nothing. NEVER
+  // silently fall back for a non-resend id.
+  const activeId =
+    opts.email?.defaultProvider ?? env.EMAIL_PROVIDER ?? "resend";
+  const provider = emailProviders.get(activeId);
+
+  if (!provider) {
+    throw new Error(
+      `email provider "${activeId}" is not registered (registered: ${emailProviders
+        .getAll()
+        .map((p) => p.meta?.id ?? "resend")
+        .join(", ")})`,
+    );
+  }
+
+  // Tracking sovereignty: first-party open/click tracking is the single source
+  // of truth. A provider that can't force its OWN tracking off per-send (an
+  // account-level toggle — e.g. Resend) declares `nativeTracking: true`. We
+  // can't reach that toggle, so we WARN at boot. The outbound-echo suppression
+  // in `dispatchWebhook` is the defence: a native open/click webhook only
+  // touches DB status, never re-emits outbound.
+  if (provider.capabilities?.nativeTracking === true) {
+    logger.warn(
+      `provider ${
+        provider.meta?.id ?? "resend"
+      } reports account-level native tracking ON; disable it in the dashboard — first-party tracking is Hogsend's source of truth.`,
+    );
+  }
 
   const defaults: HogsendDefaults = {
     timezone: opts.defaults?.timezone ?? "UTC",
@@ -327,10 +382,9 @@ export function createHogsendClient(
     opts.overrides?.mailer ??
     createTrackedMailer(
       {
-        defaultFrom: env.RESEND_FROM_EMAIL,
+        defaultFrom: env.EMAIL_FROM ?? env.RESEND_FROM_EMAIL,
         templates,
         db,
-        webhookSecret: env.RESEND_WEBHOOK_SECRET,
         bounceThreshold: 3,
         baseUrl: env.API_PUBLIC_URL,
         frequencyCap: defaults.frequencyCap,
@@ -404,8 +458,9 @@ export function createHogsendClient(
     db,
     dbClient: created.client,
     auth,
-    email,
     emailService,
+    emailProviders,
+    emailProvider: provider,
     templates,
     analytics,
     registry,

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

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,
@@ -149,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,
@@ -205,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/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;
+}