@hogsend/engine 0.6.0 → 0.8.0

package/src/routes/admin/events.ts

@@ -2,6 +2,7 @@ import { userEvents } from "@hogsend/db";
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import { and, count, desc, eq, gte, lte } from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
+import { ingestEvent } from "../../lib/ingestion.js";
 
 const eventSchema = z.object({
   id: z.string(),
@@ -79,7 +80,71 @@ const getRoute = createRoute({
   },
 });
 
+const exitSchema = z.object({
+  journeyId: z.string(),
+  stateId: z.string(),
+  exited: z.boolean(),
+});
+
+const ingestRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Admin — Events"],
+  summary: "Ingest a test event",
+  description:
+    "Session-authed ingest for the Studio Debug panel. Runs an event " +
+    "through the full ingest pipeline (stores it, routes it to journeys, " +
+    "evaluates exits). Inherits requireAdmin session auth from the admin " +
+    "mount — does NOT accept an hsk_ API key.",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            event: z.string().min(1),
+            userId: z.string().optional(),
+            userEmail: z.string().optional(),
+            properties: z.record(z.string(), z.unknown()).optional(),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    202: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            stored: z.boolean(),
+            exits: z.array(exitSchema),
+          }),
+        },
+      },
+      description: "Event accepted and ingested",
+    },
+  },
+});
+
 export const eventsRouter = new OpenAPIHono<AppEnv>()
+  .openapi(ingestRoute, async (c) => {
+    const { db, registry, hatchet, logger } = c.get("container");
+    const { event, userId, userEmail, properties } = c.req.valid("json");
+
+    const result = await ingestEvent({
+      db,
+      registry,
+      hatchet,
+      logger,
+      event: {
+        event,
+        userId,
+        userEmail,
+        eventProperties: properties ?? {},
+      },
+    });
+
+    return c.json(result, 202);
+  })
   .openapi(listRoute, async (c) => {
     const { db } = c.get("container");
     const { limit, offset, userId, event, from, to } = c.req.valid("query");

package/src/routes/admin/index.ts

@@ -20,6 +20,7 @@ import { reportingRouter } from "./reporting.js";
 import { suppressionsRouter } from "./suppressions.js";
 import { templatesRouter } from "./templates.js";
 import { timelineRouter } from "./timeline.js";
+import { webhooksRouter } from "./webhooks.js";
 
 export const adminRouter = new OpenAPIHono<AppEnv>();
 adminRouter.use("*", requireAdmin);
@@ -39,6 +40,7 @@ adminRouter.route("/reporting", reportingRouter);
 adminRouter.route("/templates", templatesRouter);
 adminRouter.route("/suppressions", suppressionsRouter);
 adminRouter.route("/api-keys", apiKeysRouter);
+adminRouter.route("/webhooks", webhooksRouter);
 adminRouter.route("/audit-logs", auditLogsRouter);
 adminRouter.route("/alerts", alertsRouter);
 adminRouter.route("/dlq", dlqRouter);

package/src/routes/admin/journeys.ts

@@ -662,7 +662,9 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
         event: meta.trigger.event,
         userId: body.userId,
         userEmail: body.userEmail,
-        properties: body.properties ?? {},
+        // Public request field stays `properties` (decision #14); it maps to
+        // the event-property bag of the IngestEvent (D2 split).
+        eventProperties: body.properties ?? {},
       },
     });
 

package/src/routes/admin/preferences.ts

@@ -104,7 +104,7 @@ export const preferencesRouter = new OpenAPIHono<AppEnv>()
     const rows = await db
       .select()
       .from(emailPreferences)
-      .where(eq(emailPreferences.userId, contact.externalId))
+      .where(eq(emailPreferences.userId, contact.externalId ?? contact.id))
       .limit(1);
 
     if (rows.length === 0) {
@@ -131,7 +131,7 @@ export const preferencesRouter = new OpenAPIHono<AppEnv>()
     const [upserted] = await db
       .insert(emailPreferences)
       .values({
-        userId: contact.externalId,
+        userId: contact.externalId ?? contact.id,
         email: contact.email,
         unsubscribedAll: body.unsubscribedAll ?? false,
         suppressed: body.suppressed ?? false,

package/src/routes/admin/reporting.ts

@@ -12,7 +12,7 @@ import {
   sql,
 } from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
-import { resolveContact } from "../../lib/contacts.js";
+import { contactKey, resolveContact } from "../../lib/contacts.js";
 import { rate, TRUNC_SQL } from "../../lib/metrics-sql.js";
 import { errorSchema } from "../../lib/schemas.js";
 
@@ -109,7 +109,7 @@ const contactActivityRoute = createRoute({
         "application/json": {
           schema: z.object({
             contact: z.object({
-              externalId: z.string(),
+              externalId: z.string().nullable(),
               email: z.string().nullable(),
             }),
             sends: z.array(
@@ -244,7 +244,7 @@ export const reportingRouter = new OpenAPIHono<AppEnv>()
 
     // Denormalized identity makes this single-table; fall back to the contact's
     // email so journeyless sends still surface.
-    const idConds = [eq(emailSends.userId, contact.externalId)];
+    const idConds = [eq(emailSends.userId, contactKey(contact))];
     if (contact.email) idConds.push(eq(emailSends.userEmail, contact.email));
     const where = or(...idConds);
 

package/src/routes/admin/timeline.ts

@@ -2,7 +2,7 @@ import { emailSends, journeyStates, userEvents } from "@hogsend/db";
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import { and, count, desc, eq, isNull } from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
-import { resolveContact } from "../../lib/contacts.js";
+import { contactKey, resolveContact } from "../../lib/contacts.js";
 
 const timelineEntrySchema = z.object({
   type: z.enum(["event", "journey", "email"]),
@@ -64,7 +64,10 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
       return c.json({ error: "Contact not found" }, 404);
     }
 
-    const externalId = contact.externalId;
+    // Resolved string key the history tables (user_events/journey_states/
+    // email_sends) were written under: external_id, else anonymous_id, else the
+    // contact uuid (matches ingestEvent's resolvedKey).
+    const externalId = contactKey(contact);
     const entries: TimelineEntry[] = [];
 
     const shouldFetch = (t: string) => !type || type === t;

package/src/routes/admin/webhooks.ts

@@ -0,0 +1,466 @@
+import { randomUUID } from "node:crypto";
+import { webhookDeliveries, webhookEndpoints } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { count, desc, eq } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { errorSchema } from "../../lib/schemas.js";
+import {
+  generateWebhookSecret,
+  WEBHOOK_EVENT_TYPES,
+  type WebhookEventType,
+} from "../../lib/webhook-signing.js";
+import { deliverWebhookTask } from "../../workflows/deliver-webhook.js";
+
+/**
+ * Admin outbound-webhook management (Section 1.8). Mounted at
+ * `/v1/admin/webhooks`, it inherits `requireAdmin` + `rateLimit` +
+ * `auditMiddleware` from the admin router root — no per-route auth here.
+ *
+ * Secret-once invariant (LOCKED decision 1): the full `whsec_…` secret is
+ * returned ONLY on create + rotate-secret. `serializeEndpoint` NEVER includes
+ * it; list/get/patch expose `secretPrefix` only. Anything that returns the full
+ * secret is an explicit, audited create/rotate response.
+ */
+
+// The catalog enum for request validation — derived from the SINGLE source of
+// truth in `webhook-signing.ts` (Section 1.3). `z.enum` needs a non-empty tuple,
+// which `WEBHOOK_EVENT_TYPES` (12 strings, `as const`) satisfies.
+const eventTypeEnum = z.enum(
+  WEBHOOK_EVENT_TYPES as unknown as [WebhookEventType, ...WebhookEventType[]],
+);
+
+const webhookEndpointSchema = z.object({
+  id: z.string(),
+  url: z.string(),
+  description: z.string().nullable(),
+  eventTypes: z.array(z.string()),
+  secretPrefix: z.string(),
+  status: z.enum(["enabled", "disabled"]),
+  organizationId: z.string().nullable(),
+  lastDeliveryAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const listRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Webhooks"],
+  summary: "List outbound webhook endpoints",
+  request: {
+    query: z.object({
+      limit: z.coerce.number().min(1).max(100).default(50),
+      offset: z.coerce.number().min(0).default(0),
+      includeDisabled: z.enum(["true", "false"]).default("true"),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            endpoints: z.array(webhookEndpointSchema),
+            total: z.number(),
+            limit: z.number(),
+            offset: z.number(),
+          }),
+        },
+      },
+      description: "Paginated webhook endpoint list (secret never included)",
+    },
+  },
+});
+
+const createEndpointRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Admin — Webhooks"],
+  summary: "Create a webhook endpoint",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            url: z.string().url(),
+            eventTypes: z.array(eventTypeEnum).min(1),
+            description: z.string().max(500).optional(),
+            disabled: z.boolean().optional(),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    201: {
+      content: {
+        "application/json": {
+          schema: webhookEndpointSchema.extend({ secret: z.string() }),
+        },
+      },
+      description: "Endpoint created — signing secret shown only once",
+    },
+  },
+});
+
+const getEndpointRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Admin — Webhooks"],
+  summary: "Get a webhook endpoint",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": { schema: webhookEndpointSchema },
+      },
+      description: "Webhook endpoint (secret never included)",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Endpoint not found",
+    },
+  },
+});
+
+const updateEndpointRoute = createRoute({
+  method: "patch",
+  path: "/{id}",
+  tags: ["Admin — Webhooks"],
+  summary: "Update a webhook endpoint",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            url: z.string().url().optional(),
+            eventTypes: z.array(eventTypeEnum).min(1).optional(),
+            description: z.string().max(500).nullable().optional(),
+            disabled: z.boolean().optional(),
+          }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": { schema: webhookEndpointSchema },
+      },
+      description: "Updated webhook endpoint (secret never included)",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Endpoint not found",
+    },
+  },
+});
+
+const deleteEndpointRoute = createRoute({
+  method: "delete",
+  path: "/{id}",
+  tags: ["Admin — Webhooks"],
+  summary: "Delete a webhook endpoint",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ deleted: z.boolean() }),
+        },
+      },
+      description: "Endpoint hard-deleted (deliveries cascade)",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Endpoint not found",
+    },
+  },
+});
+
+const rotateSecretRoute = createRoute({
+  method: "post",
+  path: "/{id}/rotate-secret",
+  tags: ["Admin — Webhooks"],
+  summary: "Rotate a webhook endpoint's signing secret",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            id: z.string(),
+            secret: z.string(),
+            secretPrefix: z.string(),
+          }),
+        },
+      },
+      description: "New signing secret — shown only once (hard cutover)",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Endpoint not found",
+    },
+  },
+});
+
+const testRoute = createRoute({
+  method: "post",
+  path: "/{id}/test",
+  tags: ["Admin — Webhooks"],
+  summary: "Send a test event to a webhook endpoint",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    202: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            enqueued: z.boolean(),
+            eventType: z.literal("webhook.test"),
+          }),
+        },
+      },
+      description: "Out-of-band test event enqueued for delivery",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Endpoint not found",
+    },
+  },
+});
+
+/**
+ * Serialize an endpoint row for an API response. NEVER includes `secret` — the
+ * full `whsec_…` is surfaced only on create + rotate-secret via the dedicated
+ * response shapes. `status` is derived from the `disabled` boolean.
+ */
+function serializeEndpoint(row: typeof webhookEndpoints.$inferSelect) {
+  return {
+    id: row.id,
+    url: row.url,
+    description: row.description,
+    eventTypes: row.eventTypes as string[],
+    secretPrefix: row.secretPrefix,
+    status: (row.disabled ? "disabled" : "enabled") as "enabled" | "disabled",
+    organizationId: row.organizationId,
+    lastDeliveryAt: row.lastDeliveryAt?.toISOString() ?? null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+export const webhooksRouter = new OpenAPIHono<AppEnv>()
+  .openapi(listRoute, async (c) => {
+    const { db } = c.get("container");
+    const { limit, offset, includeDisabled } = c.req.valid("query");
+
+    const where =
+      includeDisabled === "true"
+        ? undefined
+        : eq(webhookEndpoints.disabled, false);
+
+    const [rows, totalRows] = await Promise.all([
+      db
+        .select()
+        .from(webhookEndpoints)
+        .where(where)
+        .orderBy(desc(webhookEndpoints.createdAt))
+        .limit(limit)
+        .offset(offset),
+      db.select({ count: count() }).from(webhookEndpoints).where(where),
+    ]);
+
+    return c.json(
+      {
+        endpoints: rows.map(serializeEndpoint),
+        total: totalRows[0]?.count ?? 0,
+        limit,
+        offset,
+      },
+      200,
+    );
+  })
+  .openapi(createEndpointRoute, async (c) => {
+    const { db } = c.get("container");
+    const body = c.req.valid("json");
+
+    const { secret, secretPrefix } = generateWebhookSecret();
+
+    const [created] = await db
+      .insert(webhookEndpoints)
+      .values({
+        url: body.url,
+        eventTypes: body.eventTypes,
+        description: body.description ?? null,
+        disabled: body.disabled ?? false,
+        secret,
+        secretPrefix,
+      })
+      .returning();
+
+    if (!created) throw new Error("Failed to create webhook endpoint");
+
+    // The ONLY list/get-shaped response that also carries the full secret.
+    return c.json({ ...serializeEndpoint(created), secret }, 201);
+  })
+  .openapi(getEndpointRoute, async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    const [row] = await db
+      .select()
+      .from(webhookEndpoints)
+      .where(eq(webhookEndpoints.id, id))
+      .limit(1);
+
+    if (!row) {
+      return c.json({ error: "Webhook endpoint not found" }, 404);
+    }
+
+    return c.json(serializeEndpoint(row), 200);
+  })
+  .openapi(updateEndpointRoute, async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+    const body = c.req.valid("json");
+
+    const [existing] = await db
+      .select()
+      .from(webhookEndpoints)
+      .where(eq(webhookEndpoints.id, id))
+      .limit(1);
+
+    if (!existing) {
+      return c.json({ error: "Webhook endpoint not found" }, 404);
+    }
+
+    const patch: Partial<typeof webhookEndpoints.$inferInsert> = {
+      updatedAt: new Date(),
+    };
+    if (body.url !== undefined) patch.url = body.url;
+    if (body.eventTypes !== undefined) patch.eventTypes = body.eventTypes;
+    if (body.description !== undefined) patch.description = body.description;
+    if (body.disabled !== undefined) patch.disabled = body.disabled;
+
+    const [updated] = await db
+      .update(webhookEndpoints)
+      .set(patch)
+      .where(eq(webhookEndpoints.id, id))
+      .returning();
+
+    if (!updated) {
+      return c.json({ error: "Webhook endpoint not found" }, 404);
+    }
+
+    return c.json(serializeEndpoint(updated), 200);
+  })
+  .openapi(deleteEndpointRoute, async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    // Hard delete (LOCKED: no soft-delete column). The FK cascade on
+    // `webhook_deliveries.endpoint_id` drops this endpoint's delivery rows.
+    const deleted = await db
+      .delete(webhookEndpoints)
+      .where(eq(webhookEndpoints.id, id))
+      .returning({ id: webhookEndpoints.id });
+
+    if (deleted.length === 0) {
+      return c.json({ error: "Webhook endpoint not found" }, 404);
+    }
+
+    return c.json({ deleted: true }, 200);
+  })
+  .openapi(rotateSecretRoute, async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    const { secret, secretPrefix } = generateWebhookSecret();
+
+    // Hard cutover (LOCKED decision 10): the old secret is invalid immediately.
+    // The delivery task reads the LIVE endpoint secret, so in-flight deliveries
+    // re-sign with the new secret on their next attempt.
+    const [updated] = await db
+      .update(webhookEndpoints)
+      .set({ secret, secretPrefix, updatedAt: new Date() })
+      .where(eq(webhookEndpoints.id, id))
+      .returning({ id: webhookEndpoints.id });
+
+    if (!updated) {
+      return c.json({ error: "Webhook endpoint not found" }, 404);
+    }
+
+    return c.json({ id: updated.id, secret, secretPrefix }, 200);
+  })
+  .openapi(testRoute, async (c) => {
+    const { db, logger } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    const [endpoint] = await db
+      .select()
+      .from(webhookEndpoints)
+      .where(eq(webhookEndpoints.id, id))
+      .limit(1);
+
+    if (!endpoint) {
+      return c.json({ error: "Webhook endpoint not found" }, 404);
+    }
+
+    // Out-of-band test (LOCKED decision 11): delivered regardless of the
+    // endpoint's `eventTypes`. Build a synthetic delivery row directly — it does
+    // NOT go through `emitOutbound` (which filters by subscription) — then enqueue
+    // the same durable delivery task the live emit path uses.
+    const webhookId = `msg_${randomUUID()}`;
+    const timestamp = new Date();
+    const envelope = {
+      id: webhookId,
+      type: "webhook.test" as const,
+      timestamp: timestamp.toISOString(),
+      data: {
+        message: "Hogsend test event",
+        endpointId: endpoint.id,
+        sentAt: timestamp.toISOString(),
+      },
+    };
+
+    const [delivery] = await db
+      .insert(webhookDeliveries)
+      .values({
+        endpointId: endpoint.id,
+        organizationId: endpoint.organizationId,
+        webhookId,
+        eventType: "webhook.test",
+        dedupeKey: null,
+        payload: envelope,
+        status: "pending",
+        attemptCount: 0,
+        nextRetryAt: timestamp,
+      })
+      .returning({ id: webhookDeliveries.id });
+
+    if (!delivery) throw new Error("Failed to enqueue webhook test delivery");
+
+    // Enqueue-and-202 (LOCKED): tolerate a broker hiccup — the row is already
+    // `pending` with `nextRetryAt <= now`, so the reaper re-drives it. Enqueue
+    // fire-and-forget (mirrors the emit spine) so a slow/unreachable broker never
+    // blocks the 202; a failed enqueue is logged, not surfaced as an error.
+    void deliverWebhookTask
+      .runNoWait({ deliveryId: delivery.id })
+      .catch((error: unknown) => {
+        logger.warn("webhooks/test: deliverWebhookTask enqueue failed", {
+          endpointId: endpoint.id,
+          deliveryId: delivery.id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      });
+
+    return c.json({ enqueued: true, eventType: "webhook.test" as const }, 202);
+  });