@hogsend/core 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,11 +32,10 @@
     "drizzle-orm": "^0.45.2",
     "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.9.0"
+    "@hogsend/db": "^0.11.0"
   },
   "devDependencies": {
     "@types/node": "latest",
-    "@types/react": "^19.2.16",
     "vitest": "^4.1.8",
     "@repo/typescript-config": "0.0.0"
   },

package/src/providers/email.ts

@@ -1,41 +1,141 @@
-import type { ReactElement } from "react";
-
 // ---------------------------------------------------------------------------
-// Send options
+// Send options (HTML-only wire — NO React)
 // ---------------------------------------------------------------------------
 
+/**
+ * The provider send wire. HTML-ONLY: the engine ALWAYS renders React → HTML
+ * itself (via `@hogsend/email` `renderToHtml`) before calling `send`, so no
+ * React ever crosses the provider boundary. React Email stays first-class for
+ * template authoring + Studio preview — only this wire is HTML.
+ */
 export interface SendEmailOptions {
   from: string;
   to: string | string[];
   subject: string;
-  react?: ReactElement;
-  html?: string;
+  /** REQUIRED — the engine always renders React → HTML before the wire. */
+  html: string;
+  /** Optional plain-text alternative. */
+  text?: string;
   replyTo?: string | string[];
   cc?: string | string[];
   bcc?: string | string[];
-  scheduledAt?: string;
+  /**
+   * Neutral `{name,value}[]` tags. Each provider maps them natively: Resend
+   * passes them straight through; Postmark takes the first tag's value as `Tag`
+   * and all of them as `Metadata`; SES emits identical `MessageTag[]`.
+   */
   tags?: Array<{ name: string; value: string }>;
   headers?: Record<string, string>;
+  /** Honored only when `capabilities.scheduledSend`; else logged + ignored. */
+  scheduledAt?: string;
 }
 
-export interface BatchEmailItem {
-  from: string;
-  to: string | string[];
-  subject: string;
-  react: ReactElement;
-  replyTo?: string | string[];
-  cc?: string | string[];
-  bcc?: string | string[];
-  tags?: Array<{ name: string; value: string }>;
-  headers?: Record<string, string>;
-}
+/** A single batch item — the send wire minus the per-message `scheduledAt`. */
+export type BatchEmailItem = Omit<SendEmailOptions, "scheduledAt">;
 
 export interface SendResult {
   id: string;
 }
 
 // ---------------------------------------------------------------------------
-// Webhook events
+// Recipient normalization (shared by every provider's send wire)
+// ---------------------------------------------------------------------------
+
+/** Normalize a `string | string[] | undefined` recipient field to a string[]. */
+export function normalizeRecipients(v?: string | string[]): string[] {
+  if (v === undefined) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+/** Join a recipient field into a single comma-separated string (Postmark wire). */
+export function joinRecipients(v?: string | string[]): string {
+  return normalizeRecipients(v).join(",");
+}
+
+// ---------------------------------------------------------------------------
+// Provider-neutral email events (the normalized webhook shape)
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider-neutral email event types. The `email.` prefix is intentional — it
+ * keeps the `WebhookHandlerMap` keys, `WEBHOOK_TO_STATUS`,
+ * `WEBHOOK_TO_STATUS_FIELD`, and the outbound catalog all UNCHANGED.
+ */
+export type EmailEventType =
+  | "email.sent"
+  | "email.delivered"
+  | "email.bounced"
+  | "email.complained"
+  | "email.delivery_delayed"
+  | "email.opened"
+  | "email.clicked";
+
+/**
+ * Provider-neutral bounce classification. Drives suppression: `permanent`
+ * auto-suppresses (the engine increments `bounceCount`), `complaint` suppresses
+ * immediately, `transient` is recorded but never suppresses, and `unknown` is
+ * the conservative default (recorded, never suppresses). Each provider's
+ * classifier returns this from its own wire-specific bounce shape.
+ */
+export type BounceClass = "permanent" | "transient" | "complaint" | "unknown";
+
+/**
+ * The provider-neutral email event every provider's `verifyWebhook`/
+ * `parseWebhook` normalizes its verbatim webhook into. This is the ONE shape the
+ * engine's `dispatchWebhook` reads — Resend, Postmark, and SES all adapt their
+ * wire payloads into this. The untouched provider payload is preserved in `raw`
+ * as a handler escape hatch (cast to {@link LegacyResendWebhookEvent} for the
+ * old Resend shape during the deprecation window).
+ */
+export interface EmailEvent {
+  type: EmailEventType;
+  /** Resend `email_id` | Postmark `MessageID` | SES `mail.messageId`. */
+  messageId: string;
+  /** ALL recipients (SES bounce/complaint carry many). */
+  recipients: string[];
+  /** ISO 8601 timestamp of the provider event. */
+  occurredAt: string;
+  /** Present on `email.bounced` / `email.complained`. Drives suppression. */
+  bounce?: {
+    class: BounceClass;
+    code: string;
+    reason?: string;
+  };
+  /** Present on `email.clicked` (native-tracking echo only; first-party owns clicks). */
+  click?: { url: string; at?: string; ip?: string; ua?: string };
+  /** The untouched provider payload, for handler escape-hatch + debugging. */
+  raw: unknown;
+}
+
+/**
+ * Per-event handler map. Keys are UNCHANGED `email.*` event types; each handler
+ * now receives the provider-neutral {@link EmailEvent}. Handler bodies that read
+ * the old Resend shape (`event.data.email_id`, `event.data.bounce`) must switch
+ * to `event.messageId` / `event.bounce` OR cast
+ * `event.raw as LegacyResendWebhookEvent` during the deprecation window.
+ */
+export type WebhookHandlerMap = {
+  [K in EmailEventType]?: (
+    event: Extract<EmailEvent, { type: K }>,
+  ) => void | Promise<void>;
+};
+
+/**
+ * Thrown by `verifyWebhook` when the request was a non-delivery-status handshake
+ * (e.g. SNS SubscriptionConfirmation, Postmark SubscriptionChange) that the
+ * provider already handled. The webhook route catches it and returns 200.
+ * Provider-specific body-shape knowledge stays entirely inside the provider —
+ * the engine route NEVER sniffs the body.
+ */
+export class WebhookHandshakeSignal extends Error {
+  constructor(readonly action: string) {
+    super(action);
+    this.name = "WebhookHandshakeSignal";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Legacy Resend-shaped webhook union (frozen escape hatch, one minor)
 // ---------------------------------------------------------------------------
 
 interface WebhookEventBase {
@@ -49,14 +149,17 @@ interface WebhookEventBase {
   };
 }
 
+/** @deprecated Use {@link EmailEvent}. Frozen for one minor as a `raw` cast target. */
 export interface EmailSentEvent extends WebhookEventBase {
   type: "email.sent";
 }
 
+/** @deprecated Use {@link EmailEvent}. Frozen for one minor as a `raw` cast target. */
 export interface EmailDeliveredEvent extends WebhookEventBase {
   type: "email.delivered";
 }
 
+/** @deprecated Use {@link EmailEvent}. Frozen for one minor as a `raw` cast target. */
 export interface EmailBouncedEvent extends WebhookEventBase {
   type: "email.bounced";
   data: WebhookEventBase["data"] & {
@@ -67,18 +170,22 @@ export interface EmailBouncedEvent extends WebhookEventBase {
   };
 }
 
+/** @deprecated Use {@link EmailEvent}. Frozen for one minor as a `raw` cast target. */
 export interface EmailComplainedEvent extends WebhookEventBase {
   type: "email.complained";
 }
 
+/** @deprecated Use {@link EmailEvent}. Frozen for one minor as a `raw` cast target. */
 export interface EmailDeliveryDelayedEvent extends WebhookEventBase {
   type: "email.delivery_delayed";
 }
 
+/** @deprecated Use {@link EmailEvent}. Frozen for one minor as a `raw` cast target. */
 export interface EmailOpenedEvent extends WebhookEventBase {
   type: "email.opened";
 }
 
+/** @deprecated Use {@link EmailEvent}. Frozen for one minor as a `raw` cast target. */
 export interface EmailClickedEvent extends WebhookEventBase {
   type: "email.clicked";
   data: WebhookEventBase["data"] & {
@@ -91,6 +198,14 @@ export interface EmailClickedEvent extends WebhookEventBase {
   };
 }
 
+/**
+ * @deprecated The Resend-shaped webhook union, frozen for one minor. It no
+ * longer flows through `verifyWebhook`/`parseWebhook` — those now return the
+ * provider-neutral {@link EmailEvent}. Cast `event.raw as WebhookEvent` (alias
+ * {@link LegacyResendWebhookEvent}) inside a `webhookHandler` to keep reading the
+ * old nested shape while you migrate to {@link EmailEvent} fields. Removed the
+ * following minor.
+ */
 export type WebhookEvent =
   | EmailSentEvent
   | EmailDeliveredEvent
@@ -100,13 +215,58 @@ export type WebhookEvent =
   | EmailOpenedEvent
   | EmailClickedEvent;
 
+/**
+ * @deprecated The Resend-shaped webhook union, frozen for one minor. Cast
+ * `event.raw as LegacyResendWebhookEvent` inside a `webhookHandler` to keep
+ * reading the old nested shape while you migrate to {@link EmailEvent} fields.
+ * Removed the following minor.
+ */
+export type LegacyResendWebhookEvent = WebhookEvent;
+
+/**
+ * @deprecated Use {@link EmailEventType}. Kept for one minor as the type of the
+ * legacy union's `type` discriminant.
+ */
 export type WebhookEventType = WebhookEvent["type"];
 
-export type WebhookHandlerMap = {
-  [K in WebhookEventType]?: (
-    event: Extract<WebhookEvent, { type: K }>,
-  ) => void | Promise<void>;
-};
+// ---------------------------------------------------------------------------
+// Provider identity & capabilities
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider identity. `id` is the key the {@link EmailProviderRegistry} indexes
+ * by and the `:providerId` the `POST /v1/webhooks/email/:providerId` route
+ * dispatches on. `name` is the human label; `description` is optional prose.
+ */
+export interface EmailProviderMeta {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+/**
+ * What the provider's wire can and can't do. Drives engine-side enforcement
+ * decisions (the tracking-sovereignty boot WARN, the `scheduledAt` capability
+ * gate). All flags are optional — an absent flag is treated conservatively.
+ */
+export interface EmailProviderCapabilities {
+  /**
+   * Whether the provider's OWN open/click tracking is active and the engine
+   * cannot force it off per-send. `false` = the provider disables it per-send
+   * (Postmark TrackOpens:false/TrackLinks:'None'; SES omit from config-set) and
+   * the engine TRUSTS that. `true` = an account-level toggle the engine can't
+   * reach (Resend) → the engine logs a boot WARN. First-party open/click
+   * tracking is always the single source of truth.
+   */
+  nativeTracking?: boolean;
+  /** Honors `SendEmailOptions.scheduledAt` (Resend yes; Postmark/SES no). */
+  scheduledSend?: boolean;
+  /**
+   * Has a crypto signature scheme (Resend svix; SES SNS cert). `false` = the
+   * provider must fail-closed on its own (Postmark basic-auth).
+   */
+  signedWebhooks?: boolean;
+}
 
 // ---------------------------------------------------------------------------
 // EmailProvider contract (the entire provider surface)
@@ -118,6 +278,21 @@ export type WebhookHandlerMap = {
  * render logic lives in the engine's `createTrackedMailer`, never here.
  */
 export interface EmailProvider {
+  /**
+   * Provider identity. `meta.id` is the key the {@link EmailProviderRegistry}
+   * indexes by and the `:providerId` the webhook route dispatches on. Optional
+   * for back-compat with providers built before the registry; the registry
+   * falls back to `"resend"` when absent. Becomes required in a later
+   * (breaking) phase — new providers should always supply it.
+   */
+  readonly meta?: EmailProviderMeta;
+  /**
+   * Optional declaration of what the provider's wire supports. Read by the
+   * engine for the native-tracking boot WARN and the `scheduledAt` gate. Absent
+   * is treated conservatively (no native tracking assumed, no scheduled send).
+   */
+  readonly capabilities?: EmailProviderCapabilities;
+
   /** Deliver a single message. Returns the provider message id. */
   send(options: SendEmailOptions): Promise<SendResult>;
 
@@ -125,14 +300,26 @@ export interface EmailProvider {
   sendBatch(emails: BatchEmailItem[]): Promise<{ results: SendResult[] }>;
 
   /**
-   * Verify a provider webhook signature and return the parsed event. Throws
-   * if the signature is missing/invalid.
+   * Verify the provider's webhook (owns its OWN secrets, constructed-in) and
+   * return a normalized {@link EmailEvent}. Throws on a bad signature. Throws
+   * {@link WebhookHandshakeSignal} for non-status handshakes (the route 200s
+   * those). MAY be async (SES must GET the SNS SubscribeURL).
    */
   verifyWebhook(opts: {
     payload: string;
     headers: Record<string, string>;
-  }): WebhookEvent;
+  }): Promise<EmailEvent> | EmailEvent;
+
+  /** Parse an unsigned webhook payload (trusted contexts/tests). */
+  parseWebhook(payload: string): EmailEvent;
+}
 
-  /** Parse an unsigned webhook payload (used in trusted contexts/tests). */
-  parseWebhook(payload: string): WebhookEvent;
+/**
+ * Identity factory for an {@link EmailProvider}. Mirrors `defineWebhookSource` /
+ * `defineDestination` — it returns its argument unchanged but pins the literal
+ * shape to the {@link EmailProvider} contract, so a typo in `meta` or a missing
+ * method is caught at definition time rather than at the call site.
+ */
+export function defineEmailProvider(provider: EmailProvider): EmailProvider {
+  return provider;
 }