@hogsend/engine 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -35,13 +35,14 @@
     "papaparse": "^5.5.3",
     "picocolors": "^1.1.1",
     "resend": "^6.12.3",
+    "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.7.0",
-    "@hogsend/db": "^0.7.0",
-    "@hogsend/email": "^0.7.0",
-    "@hogsend/plugin-posthog": "^0.7.0",
-    "@hogsend/plugin-resend": "^0.7.0"
+    "@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"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/app.ts

@@ -15,6 +15,7 @@ import { errorHandler } from "./middleware/error-handler.js";
 import { requestLogger } from "./middleware/request-logger.js";
 import { registerRoutes } from "./routes/index.js";
 import type { DefinedWebhookSource } from "./webhook-sources/define-webhook-source.js";
+import { presetsFromEnv } from "./webhook-sources/presets/index.js";
 
 type AuthSession = Awaited<ReturnType<Auth["api"]["getSession"]>>;
 
@@ -35,10 +36,32 @@ export interface CreateAppOptions {
   middleware?: MiddlewareHandler[];
   /** Webhook sources served at `/v1/webhooks/:sourceId`. */
   webhookSources?: DefinedWebhookSource[];
+  /**
+   * Auto-enable the shipped integration presets (Clerk, Supabase, Stripe,
+   * Segment) for every preset whose env secret is configured (gated further by
+   * `ENABLED_WEBHOOK_PRESETS`). Consumer-supplied `webhookSources` always win on
+   * an id collision. Set `false` to opt out entirely. Default `true`.
+   */
+  enablePresets?: boolean;
   /** Override the default error handler. */
   onError?: ErrorHandler<AppEnv>;
 }
 
+/**
+ * Merge env-enabled presets with the consumer's explicit sources. The
+ * consumer-supplied source WINS on an id collision (so a hand-tuned override of
+ * a preset replaces the shipped one rather than registering a duplicate route).
+ */
+function dedupeById(sources: DefinedWebhookSource[]): DefinedWebhookSource[] {
+  const byId = new Map<string, DefinedWebhookSource>();
+  for (const source of sources) {
+    // Last write wins; callers order presets BEFORE consumer sources so the
+    // consumer override lands last.
+    byId.set(source.meta.id, source);
+  }
+  return [...byId.values()];
+}
+
 export function createApp(
   container: HogsendClient,
   opts: CreateAppOptions = {},
@@ -96,7 +119,19 @@ export function createApp(
     return c.json({ needsSetup: existing.length === 0 });
   });
 
-  registerRoutes(app, { webhookSources: opts.webhookSources ?? [] });
+  // Merge env-enabled presets ahead of the consumer's explicit sources so a
+  // consumer override of a preset id wins (decision #13). `enablePresets`
+  // defaults true; setting only `STRIPE_WEBHOOK_SECRET` auto-mounts Stripe at
+  // `POST /v1/webhooks/stripe` and nothing else.
+  const enablePresets = opts.enablePresets ?? true;
+  const webhookSources = enablePresets
+    ? dedupeById([
+        ...presetsFromEnv(container.env),
+        ...(opts.webhookSources ?? []),
+      ])
+    : (opts.webhookSources ?? []);
+
+  registerRoutes(app, { webhookSources });
 
   // Serve the Studio SPA at /studio/* (static layer, no auth — the SPA gates
   // itself via /v1/auth/status + login; data endpoints stay behind requireAdmin).

package/src/env.ts

@@ -71,6 +71,31 @@ export const env = createEnv({
     ENABLED_LISTS: z.string().default("*"),
     // Cadence for the engine-owned bucket reconcile cron (time-based leaves).
     BUCKET_RECONCILE_CRON: z.string().default("*/5 * * * *"),
+    // --- Outbound webhooks (Section 1.5/1.8) ---
+    // Cadence for the engine-owned outbound-delivery reaper cron (the retry
+    // scheduler + orphan-`sending` recovery). Declared for parity with
+    // BUCKET_RECONCILE_CRON; the delivery task also reads it raw off process.env.
+    OUTBOUND_WEBHOOK_REAPER_CRON: z.string().optional(),
+    // Delivery tunables — read raw off process.env inside the durable task;
+    // declared here so they are part of the validated env contract. All optional
+    // with task-internal defaults (MAX_ATTEMPTS 8, TIMEOUT 15s, BASE 5s,
+    // MAX_DELAY 6h, STUCK_AFTER 5min).
+    OUTBOUND_WEBHOOK_MAX_ATTEMPTS: z.coerce.number().optional(),
+    OUTBOUND_WEBHOOK_TIMEOUT_MS: z.coerce.number().optional(),
+    OUTBOUND_WEBHOOK_BASE_DELAY_MS: z.coerce.number().optional(),
+    OUTBOUND_WEBHOOK_MAX_DELAY_MS: z.coerce.number().optional(),
+    OUTBOUND_WEBHOOK_STUCK_AFTER_MS: z.coerce.number().optional(),
+    // --- Integration presets (Section 2.2) ---
+    // Signature-source secrets. The webhook route resolves a preset's secret via
+    // env[source.auth.envKey]; a signature source FAILS CLOSED when its secret is
+    // unset. Setting one auto-enables that preset at POST /v1/webhooks/<id>.
+    CLERK_WEBHOOK_SECRET: z.string().min(1).optional(),
+    SUPABASE_WEBHOOK_SECRET: z.string().min(1).optional(),
+    STRIPE_WEBHOOK_SECRET: z.string().min(1).optional(),
+    SEGMENT_WEBHOOK_SECRET: z.string().min(1).optional(),
+    // 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(),
   },
   runtimeEnv: process.env,
   emptyStringAsUndefined: true,

package/src/index.ts

@@ -16,7 +16,6 @@ export type {
   PostHogService,
   SendResult,
   WebhookEvent,
-  WebhookEventType,
   WebhookHandlerMap,
 } from "@hogsend/core";
 // Core helpers used by content journeys (days/hours/minutes, condition + journey
@@ -150,6 +149,13 @@ export {
 // --- Logging ---
 export { createLogger, type Logger } from "./lib/logger.js";
 export { createTrackedMailer } from "./lib/mailer.js";
+// --- Outbound webhooks: emit spine (Section 1.4) ---
+export {
+  emitOutbound,
+  OUTBOUND_EVENTS,
+  type OutboundEventName,
+  type OutboundPayloads,
+} from "./lib/outbound.js";
 export { getPostHog } from "./lib/posthog.js";
 export { getRedisIfConnected } from "./lib/redis.js";
 export { type MountStudioResult, mountStudio } from "./lib/studio.js";
@@ -174,7 +180,17 @@ export {
 export {
   pushTrackingEvent,
   resolveEmailSendContext,
+  resolveEmailSendContextByResendId,
 } from "./lib/tracking-events.js";
+// --- Outbound webhooks: signing core (Section 1.2) ---
+export {
+  generateWebhookSecret,
+  type SignedWebhook,
+  signWebhook,
+  verifyWebhookSignature,
+  WEBHOOK_EVENT_TYPES,
+  type WebhookEventType,
+} from "./lib/webhook-signing.js";
 // --- Lists (D3) ---
 export {
   type DefinedList,
@@ -191,9 +207,21 @@ export {
 export {
   type DefinedWebhookSource,
   defineWebhookSource,
+  verifySignature,
+  type WebhookSourceAuth,
   type WebhookSourceCtx,
   type WebhookSourceMeta,
 } from "./webhook-sources/define-webhook-source.js";
+// --- Integration presets (Section 2.3/2.4) ---
+export {
+  clerkSource,
+  PRESET_SOURCES,
+  type PresetId,
+  presetsFromEnv,
+  segmentSource,
+  stripeSource,
+  supabaseSource,
+} from "./webhook-sources/presets/index.js";
 export {
   type CreateWorkerOptions,
   createWorker,
@@ -211,6 +239,11 @@ export {
   bucketReconcileTask,
 } from "./workflows/bucket-reconcile.js";
 export { checkAlertsTask } from "./workflows/check-alerts.js";
+// --- Outbound webhooks: durable delivery task + reaper (Section 1.5) ---
+export {
+  deliverWebhookTask,
+  reapDueWebhookDeliveriesTask,
+} from "./workflows/deliver-webhook.js";
 export { importContactsTask } from "./workflows/import-contacts.js";
 export { sendCampaignTask } from "./workflows/send-campaign.js";
 // --- Built-in Hatchet workflow tasks ---

package/src/journeys/define-journey.ts

@@ -15,6 +15,7 @@ import {
 } from "../lib/enrollment-guards.js";
 import { hatchet } from "../lib/hatchet.js";
 import { createLogger } from "../lib/logger.js";
+import { emitOutbound } from "../lib/outbound.js";
 import { resolveTimezoneWithSource } from "../lib/timezone.js";
 import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
 import { JOURNEY_EXECUTION_TIMEOUT } from "./constants.js";
@@ -190,12 +191,13 @@ export function defineJourney(options: {
       try {
         await options.run(user, ctx);
 
+        const completedAt = new Date();
         await db
           .update(journeyStates)
           .set({
             status: "completed",
-            completedAt: new Date(),
-            updatedAt: new Date(),
+            completedAt,
+            updatedAt: completedAt,
           })
           .where(eq(journeyStates.id, stateId));
 
@@ -205,6 +207,28 @@ export function defineJourney(options: {
           userId,
         });
 
+        // OUTBOUND `journey.completed` — fired alongside the internal
+        // `journey:completed` push. Runs in the WORKER (this durable task), so it
+        // uses the engine `db`/`hatchet`/`logger` singletons. `dedupeKey` =
+        // `journey.completed:<stateId>`: a Hatchet re-execution recomputes the
+        // identical key and the unique `(endpointId, dedupeKey)` index absorbs the
+        // duplicate (risk 3). `journey:failed` is NOT in the catalog → no emit.
+        void emitOutbound({
+          db,
+          hatchet,
+          logger,
+          event: "journey.completed",
+          dedupeKey: `journey.completed:${stateId}`,
+          payload: {
+            journeyId: meta.id,
+            journeyName: meta.name,
+            stateId,
+            userId,
+            userEmail,
+            completedAt: completedAt.toISOString(),
+          },
+        }).catch(logger.warn);
+
         return { stateId, status: "completed" };
       } catch (err) {
         // The journey reached a terminal state (exitOn / cancel) while suspended

package/src/lib/bucket-emit.ts

@@ -6,6 +6,7 @@ import type { BucketLeaveReason } from "../buckets/bucket-reactions.js";
 import { syncBucketToPostHog } from "./bucket-posthog-sync.js";
 import { ingestEvent } from "./ingestion.js";
 import type { Logger } from "./logger.js";
+import { emitOutbound } from "./outbound.js";
 
 export type BucketTransitionKind = "entered" | "left" | "dwell";
 
@@ -146,4 +147,48 @@ export async function emitBucketTransition(opts: {
       },
     });
   }
+
+  // OUTBOUND `bucket.entered` / `bucket.left` — this is the SINGLE producer for
+  // all three transition origins (real-time / reconcile / fast-expiry), so the
+  // emit lives here once. GATED to enter/leave (dwell is a recurring membership
+  // tick, not in the catalog — same gate as the PostHog mirror above). The
+  // `dedupeKey` is the SAME deterministic `idempotencyKey` all three producers
+  // compute, so a Hatchet re-execution converges to ONE emission via the unique
+  // `(endpointId, dedupeKey)` index (risk 3). Fire-and-forget.
+  if (kind === "entered") {
+    void emitOutbound({
+      db,
+      hatchet,
+      logger,
+      event: "bucket.entered",
+      dedupeKey: idempotencyKey,
+      payload: {
+        bucketId: bucket.id,
+        bucketName: bucket.name,
+        userId,
+        userEmail,
+        transition: "entered",
+        entryCount: epoch,
+        source,
+      },
+    }).catch(logger.warn);
+  } else if (kind === "left") {
+    void emitOutbound({
+      db,
+      hatchet,
+      logger,
+      event: "bucket.left",
+      dedupeKey: idempotencyKey,
+      payload: {
+        bucketId: bucket.id,
+        bucketName: bucket.name,
+        userId,
+        userEmail,
+        transition: "left",
+        entryCount: epoch,
+        source,
+        ...(reason != null ? { reason } : {}),
+      },
+    }).catch(logger.warn);
+  }
 }

package/src/lib/contacts.ts

@@ -38,7 +38,7 @@ export async function resolveContact(opts: { db: Database; id: string }) {
   return rows[0] ?? null;
 }
 
-interface SerializedContact {
+export interface SerializedContact {
   id: string;
   externalId: string | null;
   email: string | null;
@@ -1007,13 +1007,23 @@ export async function findContacts(opts: {
 
 /**
  * Soft-delete a contact resolved by email or external id (sets `deletedAt`).
- * Returns true iff a live row was found and soft-deleted.
+ *
+ * Returns `{ deleted }` plus the soft-deleted row's identity (`id`,
+ * `externalId`, `email`) so the delete route can both make its 404 decision
+ * (`deleted`) AND emit the `contact.deleted` outbound webhook with the real
+ * identity — without a second read-back. `deleted` is false (and the identity
+ * fields absent) when no live row matched.
  */
 export async function softDeleteContact(opts: {
   db: Database;
   email?: string;
   userId?: string;
-}): Promise<boolean> {
+}): Promise<{
+  deleted: boolean;
+  id?: string;
+  externalId?: string | null;
+  email?: string | null;
+}> {
   const { db } = opts;
   const email = opts.email ? normalizeEmail(opts.email) : undefined;
   const userId = opts.userId?.trim() || undefined;
@@ -1021,15 +1031,27 @@ export async function softDeleteContact(opts: {
   const clauses = [];
   if (email) clauses.push(eq(contacts.email, email));
   if (userId) clauses.push(eq(contacts.externalId, userId));
-  if (clauses.length === 0) return false;
+  if (clauses.length === 0) return { deleted: false };
 
   const updated = await db
     .update(contacts)
     .set({ deletedAt: new Date(), updatedAt: new Date() })
     .where(and(or(...clauses), isNull(contacts.deletedAt)))
-    .returning({ id: contacts.id });
+    .returning({
+      id: contacts.id,
+      externalId: contacts.externalId,
+      email: contacts.email,
+    });
+
+  const row = updated[0];
+  if (!row) return { deleted: false };
 
-  return updated.length > 0;
+  return {
+    deleted: true,
+    id: row.id,
+    externalId: row.externalId,
+    email: row.email,
+  };
 }
 
 /**

package/src/lib/mailer.ts

@@ -24,8 +24,17 @@ import type {
   SendResult,
   TrackedSendResult,
 } from "./email-service-types.js";
+import { hatchet } from "./hatchet.js";
+import { createLogger } from "./logger.js";
+import { emitOutbound } from "./outbound.js";
 import type { PrepareTrackedHtmlFn } from "./tracked.js";
 import { sendTrackedEmail } from "./tracked.js";
+import { resolveEmailSendContextByResendId } from "./tracking-events.js";
+
+// Fallback logger for the provider-webhook outbound emit — `config.logger` is
+// optional, but `emitOutbound` requires one. Mirrors the engine-lib singleton
+// pattern (define-journey, preferences, tracked).
+const emitLogger = createLogger(process.env.LOG_LEVEL);
 
 const WEBHOOK_TO_STATUS_FIELD: Partial<
   Record<WebhookEventType, keyof typeof emailSends.$inferSelect>
@@ -187,9 +196,23 @@ export function createTrackedMailer(
   ): Promise<boolean> {
     switch (event.type) {
       case "email.sent":
+        // `email.sent` is emitted FIRST-PARTY from the tracked mailer's
+        // provider-accepted branch (lib/tracked.ts) with the rich payload — the
+        // provider-webhook echo only updates the DB status, it does NOT emit.
+        await updateEmailStatus(event.type, event.data.email_id);
+        break;
       case "email.delivered":
+        await updateEmailStatus(event.type, event.data.email_id);
+        // OUTBOUND `email.delivered` — the provider webhook is the SINGLE source
+        // for delivered/bounced (these have no first-party signal).
+        await emitProviderEmailEvent("email.delivered", event.data.email_id);
+        break;
       case "email.opened":
       case "email.clicked":
+        // First-party pixel/redirect is the SINGLE outbound emitter for
+        // open/click (gated on the first-touch null→set UPDATE in the tracking
+        // routes — risk 4). The provider-webhook echo is SUPPRESSED here: it only
+        // updates the DB status, it does NOT emit outbound (no double-source).
         await updateEmailStatus(event.type, event.data.email_id);
         break;
       case "email.bounced":
@@ -197,6 +220,11 @@ export function createTrackedMailer(
           bounceType: event.data.bounce?.type,
           bounceReason: event.data.bounce?.message,
         });
+        // OUTBOUND `email.bounced` with the bounce detail.
+        await emitProviderEmailEvent("email.bounced", event.data.email_id, {
+          bounceType: event.data.bounce?.type,
+          bounceReason: event.data.bounce?.message,
+        });
         await handleBounce(event.data.to);
         break;
       case "email.complained":
@@ -250,6 +278,65 @@ export function createTrackedMailer(
       .where(eq(emailPreferences.email, email));
   }
 
+  /**
+   * Emit the provider-funnel outbound event (`email.delivered` / `email.bounced`)
+   * for a Resend `email_id`. Enriches via {@link resolveEmailSendContextByResendId}
+   * (the only handle a provider webhook holds is the Resend id). Fire-and-forget:
+   * a missing context (webhook racing the send-row commit) or a transient outbound
+   * error is logged and swallowed — never failing the webhook handler. No
+   * `dedupeKey`: the provider path is not a Hatchet-retryable producer, and the
+   * shared `Webhook-Id` is the subscriber-side dedup for any provider redelivery.
+   */
+  function emitProviderEmailEvent(
+    event: "email.delivered" | "email.bounced",
+    resendId: string,
+    bounce?: { bounceType?: string; bounceReason?: string },
+  ): void {
+    if (!db) return;
+    const log = config.logger ?? emitLogger;
+    const database = db;
+    void resolveEmailSendContextByResendId(database, resendId)
+      .then((ctx) => {
+        if (!ctx) return;
+        const base = {
+          emailSendId: ctx.emailSendId,
+          resendId,
+          templateKey: ctx.templateKey,
+          userId: ctx.userId,
+          to: ctx.to,
+          at: new Date().toISOString(),
+        };
+        if (event === "email.bounced") {
+          return emitOutbound({
+            db: database,
+            hatchet,
+            logger: log,
+            event: "email.bounced",
+            payload: {
+              ...base,
+              ...(bounce?.bounceType ? { bounceType: bounce.bounceType } : {}),
+              ...(bounce?.bounceReason
+                ? { bounceReason: bounce.bounceReason }
+                : {}),
+            },
+          });
+        }
+        return emitOutbound({
+          db: database,
+          hatchet,
+          logger: log,
+          event: "email.delivered",
+          payload: base,
+        });
+      })
+      .catch((err: unknown) => {
+        log.warn(`emitOutbound ${event} failed`, {
+          resendId,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
+  }
+
   async function updateEmailStatus(
     eventType: WebhookEventType,
     resendId: string,