@hogsend/engine 0.8.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.8.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.8.0",
-    "@hogsend/email": "^0.8.0",
-    "@hogsend/plugin-posthog": "^0.8.0",
-    "@hogsend/plugin-resend": "^0.8.0",
-    "@hogsend/db": "^0.8.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,17 +9,18 @@ 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 {
   buildBucketRegistry,
   collectBucketReactionJourneys,
 } from "./buckets/registry.js";
+import type { DefinedDestination } from "./destinations/define-destination.js";
+import { destinationsFromEnv } from "./destinations/presets/index.js";
+import {
+  DestinationRegistry,
+  setDestinationRegistry,
+} from "./destinations/registry-singleton.js";
 import { env } from "./env.js";
 import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
@@ -27,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,
@@ -35,6 +38,7 @@ import { hatchet } from "./lib/hatchet.js";
 import { createLogger, type Logger } from "./lib/logger.js";
 import { createTrackedMailer } from "./lib/mailer.js";
 import { getPostHog } from "./lib/posthog.js";
+import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
 import { prepareTrackedHtml } from "./lib/tracking.js";
 import type { DefinedList } from "./lists/define-list.js";
 import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
@@ -54,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;
@@ -114,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
@@ -129,15 +152,43 @@ export interface HogsendClientOptions {
    */
   email?: {
     provider?: EmailProvider;
+    providers?: EmailProvider[];
+    defaultProvider?: string;
     templates?: TemplateRegistry;
   };
   /**
-   * The PostHog-style analytics service used for person properties + event
-   * capture. Lives at the top level (not under `email`) because the engine
-   * itself uses it — tracking routes and ingestion fire captures. Defaults to
-   * {@link getPostHog} (a no-op when `POSTHOG_API_KEY` is unset).
+   * The PostHog-style analytics service. As of the destinations spine its role
+   * is deliberately NARROW — it is NOT the outbound-catalog firing path (the
+   * email/contact/journey/bucket lifecycle now fans out durably via
+   * DESTINATIONS on the webhook spine, keyed by `webhook_endpoints.kind`). It
+   * remains for exactly two things:
+   *
+   * 1. The identity PULL — `getPersonProperties` for per-user timezone
+   *    resolution at journey enrollment (`define-journey` / `lib/timezone.ts`).
+   *    This read role is UNCHANGED and load-bearing.
+   * 2. The opt-in `bucket.syncToPostHog` person-property mirror — `$set`/`$unset`
+   *    of a boolean cohort property on bucket transitions (`bucket-posthog-sync`).
+   *    Off by default; PostHog `$set`/`$unset` identity semantics have no
+   *    vendor-neutral envelope, so this stays a PostHog-direct write.
+   *
+   * Lives at the top level (not under `email`) because the engine itself uses
+   * it for the PULL. Defaults to {@link getPostHog} (a no-op when
+   * `POSTHOG_API_KEY` is unset).
    */
   analytics?: PostHogService;
+  /**
+   * Code-defined outbound DESTINATIONS (Phase 3). Each is a
+   * `defineDestination()` delivery-time transform keyed by its `meta.id`, which
+   * the delivery task resolves by `webhook_endpoints.kind`. They are MERGED with
+   * the env-enabled presets ({@link destinationsFromEnv}): a consumer
+   * destination WINS over a preset of the same id (so you can override the
+   * shipped `posthog`/`segment`/`slack` shapes). The `webhook` + `posthog`
+   * presets are always present, so the no-regression signed-POST path can never
+   * be turned off here. Installed as the process registry the self-booting
+   * delivery task reads — and `createHogsendClient` runs in BOTH the API and
+   * worker, so it is wired in both. Defaults to none (presets only).
+   */
+  destinations?: DefinedDestination[];
   /**
    * Comma-separated ids (or `*`) controlling which journeys load. Defaults to
    * `env.ENABLED_JOURNEYS`.
@@ -216,8 +267,6 @@ export function createHogsendClient(
       ),
     });
 
-  const email = createResendClient({ apiKey: env.RESEND_API_KEY });
-
   const registry = buildJourneyRegistry(
     opts.journeys ?? [],
     opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
@@ -268,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",
@@ -294,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,
@@ -314,17 +401,56 @@ export function createHogsendClient(
   const analytics = opts.analytics ?? getPostHog();
 
   // Expose the resolved analytics instance to the module-level task-execution
-  // sites that have no client reference (the journey durable task in
-  // define-journey, the bucket PostHog sync). `createHogsendClient` runs in both
-  // the API and worker, so this is installed before any worker task runs. May be
-  // undefined (no POSTHOG_API_KEY) — the reads stay no-ops.
+  // sites that have no client reference. Its role is NARROW (see the
+  // `analytics?` option doc): the identity PULL (`getPersonProperties` for tz
+  // resolution in the journey durable task) plus the opt-in
+  // `bucket.syncToPostHog` person-property mirror — NOT the outbound catalog
+  // firing path (that is the destinations spine). `createHogsendClient` runs in
+  // both the API and worker, so this is installed before any worker task runs.
+  // May be undefined (no POSTHOG_API_KEY) — the reads stay no-ops.
   setAnalytics(analytics);
 
+  // Build + install the outbound DESTINATION registry (Phase 3) the
+  // self-booting delivery task resolves by `webhook_endpoints.kind`. Order is
+  // load-bearing: the env-enabled presets come FIRST and the consumer's
+  // `opts.destinations` LAST, so the DestinationRegistry's last-writer-wins map
+  // lets a consumer destination override a shipped preset of the same id. Runs
+  // in BOTH the API and worker (both call createHogsendClient), so the registry
+  // is present before any worker delivery task executes.
+  const destinations = [
+    ...destinationsFromEnv(env),
+    ...(opts.destinations ?? []),
+  ];
+  const destinationRegistry = new DestinationRegistry(destinations);
+  setDestinationRegistry(destinationRegistry);
+
+  // Optional: auto-seed a PostHog DESTINATION on the outbound spine so the email
+  // lifecycle fans out to PostHog durably. Default OFF (ENABLE_POSTHOG_DESTINATION)
+  // to avoid double-emit alongside the fire-and-forget capture path. Idempotent +
+  // fire-and-forget — a seed failure must never block boot. Runs in BOTH the API
+  // and worker (both call createHogsendClient); the dup guard makes the second a
+  // no-op.
+  if (env.ENABLE_POSTHOG_DESTINATION && env.POSTHOG_API_KEY) {
+    void seedPostHogDestination({
+      db,
+      logger,
+      apiKey: env.POSTHOG_API_KEY,
+      host: env.POSTHOG_HOST,
+    }).catch((error: unknown) => {
+      logger.warn("seedPostHogDestination failed", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  }
+
   // Counts are surfaced by the boot banner / structured ready log (lib/boot.ts);
   // keep these at debug for non-boot contexts (tests, REPL, library use).
   logger.debug(`Journey registry loaded: ${registry.count()} journeys`);
   logger.debug(`Bucket registry loaded: ${bucketRegistry.count()} buckets`);
   logger.debug(`List registry loaded: ${listRegistry.count()} lists`);
+  logger.debug(
+    `Destination registry loaded: ${destinationRegistry.count()} destinations`,
+  );
 
   return {
     env,
@@ -332,8 +458,9 @@ export function createHogsendClient(
     db,
     dbClient: created.client,
     auth,
-    email,
     emailService,
+    emailProviders,
+    emailProvider: provider,
     templates,
     analytics,
     registry,

package/src/destinations/define-destination.ts

@@ -0,0 +1,104 @@
+import type { webhookEndpoints } from "@hogsend/db";
+import type { Logger } from "../lib/logger.js";
+import type { OutboundEventName } from "../lib/outbound.js";
+
+/**
+ * Public, code-first authoring layer for OUTBOUND destinations — the symmetric
+ * twin of {@link defineWebhookSource} on the inbound side.
+ *
+ * A destination is a delivery-time TRANSFORM keyed by `webhook_endpoints.kind`.
+ * It receives the FROZEN vendor-neutral envelope (`{ id, type, timestamp, data }`)
+ * `emitOutbound` wrote to `webhook_deliveries.payload`, plus the LIVE endpoint
+ * row read at delivery time, and returns the concrete HTTP request to make. All
+ * of the durable delivery machinery (retry / backoff / DLQ / reaper / CAS /
+ * idempotency) is unchanged — it operates on the delivery ROW, never on the wire
+ * — so a code-defined destination inherits every bit of it for free.
+ *
+ * Like `defineWebhookSource`, this is an identity / validating function: it
+ * returns its argument unchanged so the call site reads declaratively and a typo
+ * in the shape is a compile error. The real wiring happens when the destination
+ * is registered (via `createHogsendClient({ destinations })` or an env preset)
+ * into the process {@link getDestinationRegistry} the delivery task reads.
+ *
+ * NOTE: `defineDestination` is for event FAN-OUT to product/data tools
+ * (PostHog, Segment, Slack, a CRM, a warehouse). It is NOT the home for
+ * ad-platform conversion forwarding (CAPI) — that stays deferred to PostHog CDP;
+ * Hogsend just fires the events.
+ */
+
+/** A live `webhook_endpoints` row, as read by the delivery task. */
+export type WebhookEndpointRow = typeof webhookEndpoints.$inferSelect;
+
+/**
+ * The frozen envelope stored on `webhook_deliveries.payload` and passed to a
+ * destination transform verbatim. Identical to the shape `emitOutbound` writes.
+ */
+export interface DestinationEnvelope {
+  id: string;
+  type: string;
+  timestamp: string;
+  data: Record<string, unknown>;
+}
+
+/**
+ * Side context handed to a transform. Deliberately tiny — a transform derives
+ * its request from the envelope + the endpoint's `config`/`secret`. `logger` is
+ * provided for diagnostics; mutating external state from a transform is a
+ * mistake (it runs once per delivery attempt, including retries).
+ */
+export interface DestinationCtx {
+  endpoint: WebhookEndpointRow;
+  logger: Logger;
+}
+
+/**
+ * The concrete HTTP request a transform resolves the envelope + endpoint into —
+ * the same contract the internal P1 adapters returned.
+ */
+export interface DestinationTransformResult {
+  url: string;
+  method?: string;
+  headers: Record<string, string>;
+  /**
+   * EXACT bytes to send. For the `webhook` preset these are the SIGNED bytes —
+   * never re-stringify them between sign and send (the signature covers them).
+   */
+  body: string;
+  /**
+   * Optional success classifier. When absent, the delivery task uses the
+   * default 2xx rule (`status >= 200 && status < 300`). A destination whose 2xx
+   * body still encodes a logical error can override this.
+   */
+  isSuccess?: (status: number, bodySnippet: string) => boolean;
+}
+
+export interface DestinationMeta {
+  /**
+   * The stable id — also the value stored in `webhook_endpoints.kind`. An
+   * endpoint with `kind === meta.id` is delivered through this destination's
+   * transform. `"webhook"` and `"posthog"` are the shipped preset ids.
+   */
+  id: string;
+  name: string;
+  description?: string;
+}
+
+export interface DefinedDestination {
+  meta: DestinationMeta;
+  /** The outbound catalog events this destination accepts. */
+  events: OutboundEventName[];
+  /**
+   * Resolve the frozen envelope + live endpoint into a concrete HTTP request.
+   * Return `null` to SKIP delivery for that envelope (the delivery task treats a
+   * skip as a successful no-op — the row is marked delivered without a POST).
+   * A THROW is a non-retryable config error (straight to the DLQ).
+   */
+  transform(
+    envelope: DestinationEnvelope,
+    ctx: DestinationCtx,
+  ): DestinationTransformResult | null;
+}
+
+export function defineDestination(def: DefinedDestination): DefinedDestination {
+  return def;
+}

package/src/destinations/presets/index.ts

@@ -0,0 +1,94 @@
+import type { env as engineEnv } from "../../env.js";
+import type { DefinedDestination } from "../define-destination.js";
+import { posthogDestination } from "./posthog.js";
+import { segmentDestination } from "./segment.js";
+import { slackDestination } from "./slack.js";
+import { webhookDestination } from "./webhook.js";
+
+export { posthogDestination } from "./posthog.js";
+export { segmentDestination } from "./segment.js";
+export { slackDestination } from "./slack.js";
+export { webhookDestination } from "./webhook.js";
+
+/**
+ * All shipped destination presets, keyed by their `kind` id. The id is also the
+ * value stored in `webhook_endpoints.kind`: `PRESET_DESTINATIONS.posthog`
+ * delivers every endpoint with `kind = "posthog"`.
+ */
+export const PRESET_DESTINATIONS = {
+  webhook: webhookDestination,
+  posthog: posthogDestination,
+  segment: segmentDestination,
+  slack: slackDestination,
+} satisfies Record<string, DefinedDestination>;
+
+/** The stable id of a shipped destination preset. */
+export type DestinationPresetId = keyof typeof PRESET_DESTINATIONS;
+
+/**
+ * The preset ids that are ALWAYS registered, regardless of
+ * `ENABLED_DESTINATION_PRESETS`:
+ *  - `webhook` — the default signed POST every existing subscriber receives
+ *    (turning it off would silently break all outbound webhooks).
+ *  - `posthog` — the auto-seeded `ENABLE_POSTHOG_DESTINATION` endpoint resolves
+ *    here; it must stay deliverable even when the env override names only other
+ *    presets.
+ */
+const ALWAYS_ON: readonly DestinationPresetId[] = ["webhook", "posthog"];
+
+/** The slice of the validated env `destinationsFromEnv` reads. */
+type DestinationPresetEnv = Pick<
+  typeof engineEnv,
+  "ENABLED_DESTINATION_PRESETS"
+>;
+
+/**
+ * Resolve which destination PRESETS to register into the process registry from
+ * the validated env (mirrors `presetsFromEnv` for inbound sources).
+ *
+ * Resolution order:
+ *  1. `ENABLED_DESTINATION_PRESETS === "none"` → ONLY the always-on set
+ *     (`webhook` + `posthog`). "none" disables the OPTIONAL presets, never the
+ *     no-regression ones.
+ *  2. `ENABLED_DESTINATION_PRESETS` is a csv of ids → exactly those (unknown ids
+ *     ignored), UNIONED with the always-on set.
+ *  3. `ENABLED_DESTINATION_PRESETS === "*"` → every preset.
+ *  4. absent → the DEFAULT set (the always-on set only).
+ *
+ * Unlike inbound presets, destinations carry NO env secret to gate on — their
+ * credentials live per-endpoint in `webhook_endpoints.config`. The env only
+ * decides which transforms are RESOLVABLE; an endpoint with a `kind` whose
+ * transform is not registered fails its delivery as a config error (DLQ), which
+ * is the right signal that the preset was not enabled.
+ */
+export function destinationsFromEnv(
+  env: DestinationPresetEnv,
+): DefinedDestination[] {
+  const override = env.ENABLED_DESTINATION_PRESETS?.trim();
+
+  const byId = (id: DestinationPresetId): DefinedDestination =>
+    PRESET_DESTINATIONS[id];
+
+  // (3) "*" — every preset.
+  if (override === "*") {
+    return Object.values(PRESET_DESTINATIONS);
+  }
+
+  // (2) explicit csv allow-list (anything other than "*"/"none"/empty), UNIONed
+  // with the always-on set so webhook/posthog can never be dropped.
+  if (override && override !== "none") {
+    const ids = new Set<string>([
+      ...ALWAYS_ON,
+      ...override
+        .split(",")
+        .map((id) => id.trim().toLowerCase())
+        .filter((id) => id.length > 0),
+    ]);
+    return (Object.keys(PRESET_DESTINATIONS) as DestinationPresetId[])
+      .filter((id) => ids.has(id))
+      .map(byId);
+  }
+
+  // (1) "none" and (4) absent → the always-on set only.
+  return ALWAYS_ON.map(byId);
+}

package/src/destinations/presets/posthog.ts

@@ -0,0 +1,71 @@
+import { WEBHOOK_EVENT_TYPES } from "../../lib/webhook-signing.js";
+import { defineDestination } from "../define-destination.js";
+
+/** PostHog destination config read off `endpoint.config`. */
+interface PostHogConfig {
+  apiKey?: string;
+  host?: string;
+  /**
+   * OPTIONAL per-destination event-name remap, applied to `envelope.type` before
+   * building the capture body. Defaults to identity (no remap).
+   *
+   * `email.clicked` is the CANONICAL spine event name. The legacy fire-and-forget
+   * PostHog path captured clicks as `email.link_clicked`, so to preserve existing
+   * PostHog insights built on that name, set
+   * `eventNames: { "email.clicked": "email.link_clicked" }`. Any catalog event can
+   * be remapped this way; absent or unmapped keys pass through unchanged.
+   */
+  eventNames?: Record<string, string>;
+}
+
+/**
+ * PostHog capture destination. Credentials live in `endpoint.config`
+ * (`{ apiKey, host?, eventNames? }`), not a fake `whsec_`. A missing
+ * `config.apiKey` is a CONFIG error — the delivery task treats a thrown
+ * transform as a non-retryable permanent failure (straight to the DLQ).
+ *
+ * Byte-for-byte identical to the P1 internal `posthog` adapter: same capture
+ * URL, same `{ api_key, event, distinct_id, timestamp, properties }` body, same
+ * `$lib: "hogsend"` marker, same `userId ?? to ?? userEmail` distinct-id chain.
+ */
+export const posthogDestination = defineDestination({
+  meta: {
+    id: "posthog",
+    name: "PostHog",
+    description:
+      "Fan email-lifecycle events out to a PostHog project (capture endpoint).",
+  },
+  // PostHog mirrors the whole catalog; the email funnel is the headline use but
+  // any catalog event can be captured. Subscription is still scoped per-endpoint
+  // via `event_types`, so an endpoint only receives what it subscribed to.
+  events: [...WEBHOOK_EVENT_TYPES],
+  transform(envelope, ctx) {
+    const config = (ctx.endpoint.config ?? {}) as PostHogConfig;
+    if (!config.apiKey) {
+      throw new Error(
+        "posthog destination is missing config.apiKey (non-retryable config error)",
+      );
+    }
+    const host = config.host ?? "https://us.i.posthog.com";
+    const data = envelope.data as {
+      userId?: string | null;
+      to?: string | null;
+      userEmail?: string | null;
+    };
+    const distinctId = data.userId ?? data.to ?? data.userEmail ?? undefined;
+    // Optional event-name remap (identity by default).
+    const eventName = config.eventNames?.[envelope.type] ?? envelope.type;
+    return {
+      url: `${host}/capture/`,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        api_key: config.apiKey,
+        event: eventName,
+        distinct_id: distinctId,
+        timestamp: envelope.timestamp,
+        properties: { ...envelope.data, $lib: "hogsend" },
+      }),
+    };
+  },
+});

package/src/destinations/presets/segment.ts

@@ -0,0 +1,75 @@
+import { WEBHOOK_EVENT_TYPES } from "../../lib/webhook-signing.js";
+import { defineDestination } from "../define-destination.js";
+
+/** Segment destination config read off `endpoint.config`. */
+interface SegmentConfig {
+  /** The Segment source WRITE KEY — used as the HTTP Basic username. */
+  writeKey?: string;
+  /**
+   * Override the Segment HTTP Tracking API base (e.g. an EU region or a proxy).
+   * Defaults to `https://api.segment.io`. The `/v1/track` path is appended.
+   */
+  host?: string;
+  /**
+   * OPTIONAL per-destination event-name remap, applied to `envelope.type` before
+   * building the track body (identity by default). Lets a destination project a
+   * canonical spine name onto an existing Segment event name.
+   */
+  eventNames?: Record<string, string>;
+}
+
+/**
+ * Segment HTTP Tracking API destination — posts each catalog event to
+ * `POST /v1/track` as a Segment `track` call. Auth is HTTP Basic with the source
+ * write key as the username and an empty password (Segment's documented scheme).
+ *
+ * Credentials live in `endpoint.config` (`{ writeKey, host?, eventNames? }`). A
+ * missing `config.writeKey` is a CONFIG error — a thrown transform is a
+ * non-retryable permanent failure (straight to the DLQ).
+ *
+ * Identity: `userId` is taken from the envelope's `userId ?? to ?? userEmail`
+ * (the same chain the PostHog destination uses), so an open/click with a known
+ * user is attributed; an anonymous hit falls back to the email address.
+ */
+export const segmentDestination = defineDestination({
+  meta: {
+    id: "segment",
+    name: "Segment",
+    description:
+      "Forward email-lifecycle events to a Segment source via the HTTP Tracking API.",
+  },
+  events: [...WEBHOOK_EVENT_TYPES],
+  transform(envelope, ctx) {
+    const config = (ctx.endpoint.config ?? {}) as SegmentConfig;
+    if (!config.writeKey) {
+      throw new Error(
+        "segment destination is missing config.writeKey (non-retryable config error)",
+      );
+    }
+    const host = config.host ?? "https://api.segment.io";
+    const data = envelope.data as {
+      userId?: string | null;
+      to?: string | null;
+      userEmail?: string | null;
+    };
+    const userId = data.userId ?? data.to ?? data.userEmail ?? undefined;
+    const eventName = config.eventNames?.[envelope.type] ?? envelope.type;
+    // HTTP Basic: base64("<writeKey>:"). Empty password per Segment's docs.
+    const basic = Buffer.from(`${config.writeKey}:`).toString("base64");
+    return {
+      url: `${host}/v1/track`,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${basic}`,
+      },
+      body: JSON.stringify({
+        ...(userId ? { userId } : { anonymousId: envelope.id }),
+        event: eventName,
+        timestamp: envelope.timestamp,
+        messageId: envelope.id,
+        properties: { ...envelope.data, $lib: "hogsend" },
+      }),
+    };
+  },
+});