@hogsend/engine 0.1.0 → 0.1.1

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

package/src/routes/admin/reporting.ts

@@ -0,0 +1,369 @@
+import { emailSends } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import {
+  and,
+  count,
+  desc,
+  eq,
+  gte,
+  isNotNull,
+  lte,
+  or,
+  sql,
+} from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { resolveContact } from "../../lib/contacts.js";
+import { rate, TRUNC_SQL } from "../../lib/metrics-sql.js";
+import { errorSchema } from "../../lib/schemas.js";
+
+// Filtered-count fragments shared by the per-template totals + series queries.
+const COUNTS = {
+  sent: sql<number>`count(*) filter (where ${emailSends.sentAt} is not null)`,
+  delivered: sql<number>`count(*) filter (where ${emailSends.status} = 'delivered' or ${emailSends.deliveredAt} is not null)`,
+  opened: sql<number>`count(*) filter (where ${emailSends.openedAt} is not null)`,
+  clicked: sql<number>`count(*) filter (where ${emailSends.clickedAt} is not null)`,
+  bounced: sql<number>`count(*) filter (where ${emailSends.bouncedAt} is not null)`,
+  complained: sql<number>`count(*) filter (where ${emailSends.complainedAt} is not null)`,
+} as const;
+
+// ---------------------------------------------------------------------------
+// GET /templates/{templateKey} — totals + time-series for one template
+// ---------------------------------------------------------------------------
+
+const templateSeriesRoute = createRoute({
+  method: "get",
+  path: "/templates/{templateKey}",
+  tags: ["Admin — Reporting"],
+  summary: "One template's totals + engagement time-series",
+  request: {
+    params: z.object({ templateKey: z.string() }),
+    query: z.object({
+      from: z.string().datetime().optional(),
+      to: z.string().datetime().optional(),
+      granularity: z.enum(["day", "week", "month"]).default("day"),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            templateKey: z.string(),
+            window: z.object({
+              from: z.string().nullable(),
+              to: z.string().nullable(),
+            }),
+            totals: z.object({
+              sent: z.number(),
+              delivered: z.number(),
+              opened: z.number(),
+              clicked: z.number(),
+              bounced: z.number(),
+              complained: z.number(),
+              deliveryRate: z.number(),
+              openRate: z.number(),
+              clickRate: z.number(),
+              clickToDeliveryRate: z.number(),
+            }),
+            series: z.array(
+              z.object({
+                date: z.string(),
+                sent: z.number(),
+                delivered: z.number(),
+                opened: z.number(),
+                clicked: z.number(),
+                bounced: z.number(),
+              }),
+            ),
+          }),
+        },
+      },
+      description: "Template totals and time-series",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Template has never been sent",
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// GET /contacts/{id}/activity — per-send engagement rows for one contact
+// ---------------------------------------------------------------------------
+
+const contactActivityRoute = createRoute({
+  method: "get",
+  path: "/contacts/{id}/activity",
+  tags: ["Admin — Reporting"],
+  summary: "A contact's email sends with engagement",
+  request: {
+    params: z.object({ id: z.string() }),
+    query: z.object({
+      limit: z.coerce.number().min(1).max(100).default(50),
+      offset: z.coerce.number().min(0).default(0),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            contact: z.object({
+              externalId: z.string(),
+              email: z.string().nullable(),
+            }),
+            sends: z.array(
+              z.object({
+                id: z.string(),
+                templateKey: z.string().nullable(),
+                subject: z.string(),
+                status: z.string(),
+                sentAt: z.string().nullable(),
+                deliveredAt: z.string().nullable(),
+                openedAt: z.string().nullable(),
+                clickedAt: z.string().nullable(),
+                bouncedAt: z.string().nullable(),
+                complainedAt: z.string().nullable(),
+                bounceType: z.string().nullable(),
+                createdAt: z.string(),
+              }),
+            ),
+            total: z.number(),
+            limit: z.number(),
+            offset: z.number(),
+          }),
+        },
+      },
+      description: "Per-contact email send activity",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Contact not found",
+    },
+  },
+});
+
+const MAX_EXPORT_ROWS = 50_000;
+
+function csvCell(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const str = value instanceof Date ? value.toISOString() : String(value);
+  return /[",\n\r]/.test(str) ? `"${str.replace(/"/g, '""')}"` : str;
+}
+
+export const reportingRouter = new OpenAPIHono<AppEnv>()
+  .openapi(templateSeriesRoute, async (c) => {
+    const { db } = c.get("container");
+    const { templateKey } = c.req.valid("param");
+    const { from, to, granularity } = c.req.valid("query");
+
+    const existing = await db
+      .select({ id: emailSends.id })
+      .from(emailSends)
+      .where(eq(emailSends.templateKey, templateKey))
+      .limit(1);
+    if (existing.length === 0) {
+      return c.json({ error: "Template has never been sent" }, 404);
+    }
+
+    const conditions = [eq(emailSends.templateKey, templateKey)];
+    if (from) conditions.push(gte(emailSends.createdAt, new Date(from)));
+    if (to) conditions.push(lte(emailSends.createdAt, new Date(to)));
+    const where = and(...conditions);
+
+    const trunc = sql`date_trunc(${TRUNC_SQL[granularity]}, ${emailSends.createdAt})`;
+
+    const [totalsRows, seriesRows] = await Promise.all([
+      db.select(COUNTS).from(emailSends).where(where),
+      db
+        .select({
+          date: sql<string>`${trunc}::text`,
+          sent: COUNTS.sent,
+          delivered: COUNTS.delivered,
+          opened: COUNTS.opened,
+          clicked: COUNTS.clicked,
+          bounced: COUNTS.bounced,
+        })
+        .from(emailSends)
+        .where(where)
+        .groupBy(trunc)
+        .orderBy(trunc),
+    ]);
+
+    const t = totalsRows[0] ?? {
+      sent: 0,
+      delivered: 0,
+      opened: 0,
+      clicked: 0,
+      bounced: 0,
+      complained: 0,
+    };
+    const sent = Number(t.sent);
+    const delivered = Number(t.delivered);
+    const opened = Number(t.opened);
+    const clicked = Number(t.clicked);
+    const openDenominator = delivered > 0 ? delivered : sent;
+
+    return c.json(
+      {
+        templateKey,
+        window: { from: from ?? null, to: to ?? null },
+        totals: {
+          sent,
+          delivered,
+          opened,
+          clicked,
+          bounced: Number(t.bounced),
+          complained: Number(t.complained),
+          deliveryRate: rate(delivered, sent),
+          openRate: rate(opened, openDenominator),
+          clickRate: rate(clicked, opened),
+          clickToDeliveryRate: rate(clicked, delivered),
+        },
+        series: seriesRows.map((row) => ({
+          date: row.date,
+          sent: Number(row.sent),
+          delivered: Number(row.delivered),
+          opened: Number(row.opened),
+          clicked: Number(row.clicked),
+          bounced: Number(row.bounced),
+        })),
+      },
+      200,
+    );
+  })
+  .openapi(contactActivityRoute, async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+    const { limit, offset } = c.req.valid("query");
+
+    const contact = await resolveContact({ db, id });
+    if (!contact) {
+      return c.json({ error: "Contact not found" }, 404);
+    }
+
+    // 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)];
+    if (contact.email) idConds.push(eq(emailSends.userEmail, contact.email));
+    const where = or(...idConds);
+
+    const [rows, totalRows] = await Promise.all([
+      db
+        .select()
+        .from(emailSends)
+        .where(where)
+        .orderBy(desc(emailSends.createdAt))
+        .limit(limit)
+        .offset(offset),
+      db.select({ count: count() }).from(emailSends).where(where),
+    ]);
+
+    return c.json(
+      {
+        contact: { externalId: contact.externalId, email: contact.email },
+        sends: rows.map((row) => ({
+          id: row.id,
+          templateKey: row.templateKey,
+          subject: row.subject,
+          status: row.status,
+          sentAt: row.sentAt?.toISOString() ?? null,
+          deliveredAt: row.deliveredAt?.toISOString() ?? null,
+          openedAt: row.openedAt?.toISOString() ?? null,
+          clickedAt: row.clickedAt?.toISOString() ?? null,
+          bouncedAt: row.bouncedAt?.toISOString() ?? null,
+          complainedAt: row.complainedAt?.toISOString() ?? null,
+          bounceType: row.bounceType,
+          createdAt: row.createdAt.toISOString(),
+        })),
+        total: totalRows[0]?.count ?? 0,
+        limit,
+        offset,
+      },
+      200,
+    );
+  });
+
+// CSV export — plain route (non-JSON response) under the same auth as the rest
+// of /v1/admin. Bounded to MAX_EXPORT_ROWS; same filters as GET /admin/emails.
+reportingRouter.get("/sends/export", async (c) => {
+  const { db } = c.get("container");
+  const q = c.req.query();
+
+  const engagementColumn = {
+    opened: emailSends.openedAt,
+    clicked: emailSends.clickedAt,
+    bounced: emailSends.bouncedAt,
+    complained: emailSends.complainedAt,
+  } as const;
+
+  const conditions = [];
+  if (q.templateKey) conditions.push(eq(emailSends.templateKey, q.templateKey));
+  if (q.status)
+    conditions.push(
+      eq(emailSends.status, q.status as typeof emailSends.$inferSelect.status),
+    );
+  if (q.category) conditions.push(eq(emailSends.category, q.category));
+  if (q.userId) conditions.push(eq(emailSends.userId, q.userId));
+  if (q.engagement && q.engagement in engagementColumn)
+    conditions.push(
+      isNotNull(
+        engagementColumn[q.engagement as keyof typeof engagementColumn],
+      ),
+    );
+  if (q.from) conditions.push(gte(emailSends.createdAt, new Date(q.from)));
+  if (q.to) conditions.push(lte(emailSends.createdAt, new Date(q.to)));
+  const where = conditions.length > 0 ? and(...conditions) : undefined;
+
+  const rows = await db
+    .select()
+    .from(emailSends)
+    .where(where)
+    .orderBy(desc(emailSends.createdAt))
+    .limit(MAX_EXPORT_ROWS);
+
+  const header = [
+    "id",
+    "createdAt",
+    "templateKey",
+    "status",
+    "toEmail",
+    "userId",
+    "subject",
+    "sentAt",
+    "deliveredAt",
+    "openedAt",
+    "clickedAt",
+    "bouncedAt",
+    "complainedAt",
+    "bounceType",
+  ];
+  const lines = [header.join(",")];
+  for (const r of rows) {
+    lines.push(
+      [
+        r.id,
+        r.createdAt,
+        r.templateKey,
+        r.status,
+        r.toEmail,
+        r.userId,
+        r.subject,
+        r.sentAt,
+        r.deliveredAt,
+        r.openedAt,
+        r.clickedAt,
+        r.bouncedAt,
+        r.complainedAt,
+        r.bounceType,
+      ]
+        .map(csvCell)
+        .join(","),
+    );
+  }
+
+  return c.body(lines.join("\n"), 200, {
+    "Content-Type": "text/csv; charset=utf-8",
+    "Content-Disposition": 'attachment; filename="email-sends.csv"',
+  });
+});

package/src/routes/admin/suppressions.ts

@@ -0,0 +1,99 @@
+import { emailPreferences } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { and, count, desc, eq, gt, type SQL } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { serializePrefs } from "../../lib/contacts.js";
+
+// Maps the requested suppression type to a predicate over email_preferences.
+// `complained` has no dedicated column — a complaint sets `suppressed` without
+// incrementing `bounceCount` (see mailer `handleComplaint`), so we identify it
+// as suppressed-but-not-bounced.
+function typeFilter(
+  type: "bounced" | "unsubscribed" | "complained" | undefined,
+): SQL | undefined {
+  switch (type) {
+    case "bounced":
+      return gt(emailPreferences.bounceCount, 0);
+    case "unsubscribed":
+      return eq(emailPreferences.unsubscribedAll, true);
+    case "complained":
+      return and(
+        eq(emailPreferences.suppressed, true),
+        eq(emailPreferences.bounceCount, 0),
+      );
+    default:
+      return undefined;
+  }
+}
+
+const suppressionSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  email: z.string(),
+  unsubscribedAll: z.boolean(),
+  suppressed: z.boolean(),
+  bounceCount: z.number(),
+  categories: z.record(z.string(), z.boolean()),
+  suppressedAt: z.string().nullable(),
+  lastBounceAt: z.string().nullable(),
+});
+
+const listSuppressionsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Suppressions"],
+  summary: "List suppressed / bounced / unsubscribed recipients",
+  request: {
+    query: z.object({
+      type: z.enum(["bounced", "unsubscribed", "complained"]).optional(),
+      limit: z.coerce.number().min(1).max(200).default(50),
+      offset: z.coerce.number().min(0).default(0),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            suppressions: z.array(suppressionSchema),
+            total: z.number(),
+            limit: z.number(),
+            offset: z.number(),
+          }),
+        },
+      },
+      description: "Suppression list",
+    },
+  },
+});
+
+export const suppressionsRouter = new OpenAPIHono<AppEnv>().openapi(
+  listSuppressionsRoute,
+  async (c) => {
+    const { db } = c.get("container");
+    const { type, limit, offset } = c.req.valid("query");
+
+    const where = typeFilter(type);
+
+    const [rows, totalRows] = await Promise.all([
+      db
+        .select()
+        .from(emailPreferences)
+        .where(where)
+        .orderBy(desc(emailPreferences.updatedAt))
+        .limit(limit)
+        .offset(offset),
+      db.select({ count: count() }).from(emailPreferences).where(where),
+    ]);
+
+    return c.json(
+      {
+        suppressions: rows.map((row) => serializePrefs(row)),
+        total: totalRows[0]?.count ?? 0,
+        limit,
+        offset,
+      },
+      200,
+    );
+  },
+);