@hogsend/engine 0.0.1 → 0.1.1

package/src/routes/admin/emails.ts

@@ -6,7 +6,20 @@ import {
   trackedLinks,
 } from "@hogsend/db";
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
-import { and, count, desc, eq, gte, inArray, isNull, lte } from "drizzle-orm";
+import {
+  and,
+  asc,
+  count,
+  desc,
+  eq,
+  getTableColumns,
+  gte,
+  inArray,
+  isNotNull,
+  isNull,
+  lte,
+  or,
+} from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
 
 const emailSchema = z.object({
@@ -19,6 +32,8 @@ const emailSchema = z.object({
   subject: z.string(),
   category: z.string().nullable(),
   status: z.string(),
+  userId: z.string().nullable(),
+  journeyId: z.string().nullable(),
   sentAt: z.string().nullable(),
   deliveredAt: z.string().nullable(),
   openedAt: z.string().nullable(),
@@ -29,6 +44,14 @@ const emailSchema = z.object({
   updatedAt: z.string(),
 });
 
+const eventSchema = z.object({
+  type: z.string(),
+  timestamp: z.string(),
+  url: z.string().optional(),
+  ipAddress: z.string().nullable().optional(),
+  userAgent: z.string().nullable().optional(),
+});
+
 const trackedLinkSchema = z.object({
   id: z.string(),
   originalUrl: z.string(),
@@ -54,7 +77,13 @@ const journeyContextSchema = z
 
 import { errorSchema } from "../../lib/schemas.js";
 
-function serializeEmail(row: typeof emailSends.$inferSelect) {
+function serializeEmail(
+  row: typeof emailSends.$inferSelect,
+  identity: { userId: string | null; journeyId: string | null } = {
+    userId: null,
+    journeyId: null,
+  },
+) {
   return {
     id: row.id,
     journeyStateId: row.journeyStateId,
@@ -65,6 +94,8 @@ function serializeEmail(row: typeof emailSends.$inferSelect) {
     subject: row.subject,
     category: row.category,
     status: row.status,
+    userId: identity.userId,
+    journeyId: identity.journeyId,
     sentAt: row.sentAt?.toISOString() ?? null,
     deliveredAt: row.deliveredAt?.toISOString() ?? null,
     openedAt: row.openedAt?.toISOString() ?? null,
@@ -100,6 +131,16 @@ const listRoute = createRoute({
           "failed",
         ])
         .optional(),
+      journeyId: z.string().optional(),
+      userId: z.string().optional(),
+      category: z.string().optional(),
+      engagement: z
+        .enum(["opened", "clicked", "bounced", "complained"])
+        .optional(),
+      sort: z
+        .enum(["createdAt", "sentAt", "openedAt", "clickedAt"])
+        .default("createdAt"),
+      order: z.enum(["asc", "desc"]).default("desc"),
       from: z.string().datetime().optional(),
       to: z.string().datetime().optional(),
     }),
@@ -135,6 +176,7 @@ const getRoute = createRoute({
         "application/json": {
           schema: z.object({
             email: emailSchema,
+            events: z.array(eventSchema),
             trackedLinks: z.array(trackedLinkSchema),
             journeyContext: journeyContextSchema,
           }),
@@ -188,32 +230,93 @@ async function fetchTrackedLinksWithClicks(db: Database, emailSendId: string) {
 export const emailsRouter = new OpenAPIHono<AppEnv>()
   .openapi(listRoute, async (c) => {
     const { db } = c.get("container");
-    const { limit, offset, toEmail, templateKey, status, from, to } =
-      c.req.valid("query");
+    const {
+      limit,
+      offset,
+      toEmail,
+      templateKey,
+      status,
+      journeyId,
+      userId,
+      category,
+      engagement,
+      sort,
+      order,
+      from,
+      to,
+    } = c.req.valid("query");
+
+    const engagementColumn = {
+      opened: emailSends.openedAt,
+      clicked: emailSends.clickedAt,
+      bounced: emailSends.bouncedAt,
+      complained: emailSends.complainedAt,
+    } as const;
+
+    const sortColumn = {
+      createdAt: emailSends.createdAt,
+      sentAt: emailSends.sentAt,
+      openedAt: emailSends.openedAt,
+      clickedAt: emailSends.clickedAt,
+    } as const;
 
     const conditions = [];
     if (toEmail) conditions.push(eq(emailSends.toEmail, toEmail));
     if (templateKey) conditions.push(eq(emailSends.templateKey, templateKey));
     if (status) conditions.push(eq(emailSends.status, status));
+    if (category) conditions.push(eq(emailSends.category, category));
+    if (journeyId) conditions.push(eq(journeyStates.journeyId, journeyId));
+    // Match the denormalized identity OR the journey-state join, so journeyless
+    // sends (which only carry the denormalized userId) are still filterable.
+    if (userId) {
+      conditions.push(
+        or(eq(emailSends.userId, userId), eq(journeyStates.userId, userId)),
+      );
+    }
+    if (engagement) conditions.push(isNotNull(engagementColumn[engagement]));
     if (from) conditions.push(gte(emailSends.createdAt, new Date(from)));
     if (to) conditions.push(lte(emailSends.createdAt, new Date(to)));
 
     const where = conditions.length > 0 ? and(...conditions) : undefined;
 
+    const orderBy =
+      order === "asc" ? asc(sortColumn[sort]) : desc(sortColumn[sort]);
+
+    const joinCondition = and(
+      eq(emailSends.journeyStateId, journeyStates.id),
+      isNull(journeyStates.deletedAt),
+    );
+
     const [rows, totalRows] = await Promise.all([
       db
-        .select()
+        .select({
+          ...getTableColumns(emailSends),
+          identityUserId: journeyStates.userId,
+          identityJourneyId: journeyStates.journeyId,
+        })
         .from(emailSends)
+        .leftJoin(journeyStates, joinCondition)
         .where(where)
-        .orderBy(desc(emailSends.createdAt))
+        .orderBy(orderBy)
         .limit(limit)
         .offset(offset),
-      db.select({ count: count() }).from(emailSends).where(where),
+      db
+        .select({ count: count() })
+        .from(emailSends)
+        .leftJoin(journeyStates, joinCondition)
+        .where(where),
     ]);
 
     return c.json(
       {
-        emails: rows.map(serializeEmail),
+        emails: rows.map(({ identityUserId, identityJourneyId, ...row }) =>
+          // Prefer the denormalized identity on the send row; fall back to the
+          // journey-state join (covers rows written before denormalization).
+          serializeEmail(row, {
+            userId: row.userId ?? identityUserId,
+            journeyId: identityJourneyId,
+          }),
+        ),
         total: totalRows[0]?.count ?? 0,
         limit,
         offset,
@@ -258,9 +361,52 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
         : Promise.resolve(null),
     ]);
 
+    const events: z.infer<typeof eventSchema>[] = [];
+    if (row.createdAt)
+      events.push({ type: "queued", timestamp: row.createdAt.toISOString() });
+    if (row.sentAt)
+      events.push({ type: "sent", timestamp: row.sentAt.toISOString() });
+    if (row.deliveredAt)
+      events.push({
+        type: "delivered",
+        timestamp: row.deliveredAt.toISOString(),
+      });
+    if (row.openedAt)
+      events.push({ type: "opened", timestamp: row.openedAt.toISOString() });
+    if (row.bouncedAt)
+      events.push({ type: "bounced", timestamp: row.bouncedAt.toISOString() });
+    if (row.complainedAt)
+      events.push({
+        type: "complained",
+        timestamp: row.complainedAt.toISOString(),
+      });
+    if (row.status === "failed" && row.updatedAt)
+      events.push({ type: "failed", timestamp: row.updatedAt.toISOString() });
+
+    for (const link of links) {
+      for (const click of link.clicks) {
+        events.push({
+          type: "clicked",
+          timestamp: click.clickedAt,
+          url: link.originalUrl,
+          ipAddress: click.ipAddress,
+          userAgent: click.userAgent,
+        });
+      }
+    }
+
+    events.sort(
+      (a, b) =>
+        new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+    );
+
     return c.json(
       {
-        email: serializeEmail(row),
+        email: serializeEmail(row, {
+          userId: row.userId ?? journeyContext?.userId ?? null,
+          journeyId: journeyContext?.journeyId ?? null,
+        }),
+        events,
         trackedLinks: links,
         journeyContext,
       },

package/src/routes/admin/index.ts

@@ -1,8 +1,8 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
-import { requireApiKey } from "../../middleware/api-key.js";
 import { auditMiddleware } from "../../middleware/audit.js";
 import { rateLimit } from "../../middleware/rate-limit.js";
+import { requireAdmin } from "../../middleware/require-admin.js";
 import { alertsRouter } from "./alerts.js";
 import { apiKeysRouter } from "./api-keys.js";
 import { auditLogsRouter } from "./audit-logs.js";
@@ -15,10 +15,13 @@ import { journeyLogsRouter } from "./journey-logs.js";
 import { journeysRouter } from "./journeys.js";
 import { metricsRouter } from "./metrics.js";
 import { preferencesRouter } from "./preferences.js";
+import { reportingRouter } from "./reporting.js";
+import { suppressionsRouter } from "./suppressions.js";
+import { templatesRouter } from "./templates.js";
 import { timelineRouter } from "./timeline.js";
 
 export const adminRouter = new OpenAPIHono<AppEnv>();
-adminRouter.use("*", requireApiKey);
+adminRouter.use("*", requireAdmin);
 adminRouter.use("*", rateLimit);
 adminRouter.use("*", auditMiddleware);
 adminRouter.route("/", bulkRouter);
@@ -30,6 +33,9 @@ adminRouter.route("/events", eventsRouter);
 adminRouter.route("/emails", emailsRouter);
 adminRouter.route("/journey-logs", journeyLogsRouter);
 adminRouter.route("/metrics", metricsRouter);
+adminRouter.route("/reporting", reportingRouter);
+adminRouter.route("/templates", templatesRouter);
+adminRouter.route("/suppressions", suppressionsRouter);
 adminRouter.route("/api-keys", apiKeysRouter);
 adminRouter.route("/audit-logs", auditLogsRouter);
 adminRouter.route("/alerts", alertsRouter);

package/src/routes/admin/metrics.ts

@@ -18,15 +18,9 @@ import {
   sql,
 } from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
+import { rate, TRUNC_SQL } from "../../lib/metrics-sql.js";
 import { errorSchema } from "../../lib/schemas.js";
 
-const TRUNC_SQL = {
-  hour: sql`'hour'`,
-  day: sql`'day'`,
-  week: sql`'week'`,
-  month: sql`'month'`,
-} as const;
-
 const overviewRoute = createRoute({
   method: "get",
   path: "/overview",
@@ -123,6 +117,13 @@ const emailMetricsRoute = createRoute({
   path: "/emails",
   tags: ["Admin — Metrics"],
   summary: "Per-template email metrics",
+  request: {
+    query: z.object({
+      from: z.string().datetime().optional(),
+      to: z.string().datetime().optional(),
+      includeUntemplated: z.enum(["true", "false"]).default("false"),
+    }),
+  },
   responses: {
     200: {
       content: {
@@ -139,6 +140,7 @@ const emailMetricsRoute = createRoute({
                 deliveryRate: z.number(),
                 openRate: z.number(),
                 clickRate: z.number(),
+                clickToDeliveryRate: z.number(),
               }),
             ),
           }),
@@ -284,8 +286,6 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
     ]);
 
     const sent30d = emails30d;
-    const bounceRate30d = sent30d > 0 ? bounced30d / sent30d : 0;
-    const unsubscribeRate = totalPrefs > 0 ? unsubscribed / totalPrefs : 0;
 
     return c.json(
       {
@@ -294,8 +294,8 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
         emailsSent24h: emails24h,
         emailsSent7d: emails7d,
         emailsSent30d: sent30d,
-        bounceRate30d: Math.round(bounceRate30d * 10000) / 10000,
-        unsubscribeRate: Math.round(unsubscribeRate * 10000) / 10000,
+        bounceRate30d: rate(bounced30d, sent30d),
+        unsubscribeRate: rate(unsubscribed, totalPrefs),
       },
       200,
     );
@@ -352,7 +352,6 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
         (counts.failed ?? 0) +
         (counts.exited ?? 0);
       const completed = counts.completed ?? 0;
-      const completionRate = enrolled > 0 ? completed / enrolled : 0;
 
       return {
         journeyId: j.id,
@@ -362,7 +361,7 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
         failed: counts.failed ?? 0,
         exited: counts.exited ?? 0,
         active: (counts.active ?? 0) + (counts.waiting ?? 0),
-        completionRate: Math.round(completionRate * 10000) / 10000,
+        completionRate: rate(completed, enrolled),
         avgDurationSecs: durationMap.has(j.id)
           ? Math.round(durationMap.get(j.id) ?? 0)
           : null,
@@ -437,6 +436,15 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
   })
   .openapi(emailMetricsRoute, async (c) => {
     const { db } = c.get("container");
+    const { from, to, includeUntemplated } = c.req.valid("query");
+
+    const conditions = [];
+    if (includeUntemplated !== "true")
+      conditions.push(isNotNull(emailSends.templateKey));
+    if (from) conditions.push(gte(emailSends.createdAt, new Date(from)));
+    if (to) conditions.push(lte(emailSends.createdAt, new Date(to)));
+
+    const where = conditions.length > 0 ? and(...conditions) : undefined;
 
     const rows = await db
       .select({
@@ -448,7 +456,7 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
         bounced: sql<number>`count(*) filter (where ${emailSends.status} = 'bounced')`,
       })
       .from(emailSends)
-      .where(isNotNull(emailSends.templateKey))
+      .where(where)
       .groupBy(emailSends.templateKey);
 
     const templates = rows.map((row) => {
@@ -456,19 +464,20 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
       const delivered = Number(row.delivered);
       const opened = Number(row.opened);
       const clicked = Number(row.clicked);
+      // Open-rate denominator falls back to sent when delivered-webhooks aren't
+      // firing, so opens aren't silently zeroed.
+      const openDenominator = delivered > 0 ? delivered : sent;
       return {
-        templateKey: row.templateKey ?? "",
+        templateKey: row.templateKey ?? "(none)",
         sent,
         delivered,
         opened,
         clicked,
         bounced: Number(row.bounced),
-        deliveryRate:
-          sent > 0 ? Math.round((delivered / sent) * 10000) / 10000 : 0,
-        openRate:
-          delivered > 0 ? Math.round((opened / delivered) * 10000) / 10000 : 0,
-        clickRate:
-          opened > 0 ? Math.round((clicked / opened) * 10000) / 10000 : 0,
+        deliveryRate: rate(delivered, sent),
+        openRate: rate(opened, openDenominator),
+        clickRate: rate(clicked, opened),
+        clickToDeliveryRate: rate(clicked, delivered),
       };
     });
 
@@ -510,8 +519,7 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
         delivered,
         bounced: Number(row.bounced),
         complained: Number(row.complained),
-        deliveryRate:
-          total > 0 ? Math.round((delivered / total) * 10000) / 10000 : 0,
+        deliveryRate: rate(delivered, total),
       };
     });