@hogsend/engine 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -38,11 +38,11 @@
     "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.9.0",
+    "@hogsend/db": "^0.9.0",
+    "@hogsend/email": "^0.9.0",
+    "@hogsend/plugin-posthog": "^0.9.0",
+    "@hogsend/plugin-resend": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/container.ts

@@ -20,6 +20,12 @@ 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";
@@ -35,6 +41,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";
@@ -132,12 +139,38 @@ export interface HogsendClientOptions {
     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`.
@@ -314,17 +347,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,

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" },
+      }),
+    };
+  },
+});

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 };
+  },
+});