@hogsend/engine 0.1.0 → 0.2.0

package/src/routes/admin/metrics.ts

@@ -1,4 +1,5 @@
 import {
+  bucketMemberships,
   contacts,
   emailPreferences,
   emailSends,
@@ -18,15 +19,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",
@@ -39,6 +34,8 @@ const overviewRoute = createRoute({
           schema: z.object({
             totalContacts: z.number(),
             activeJourneys: z.number(),
+            activeBuckets: z.number(),
+            bucketMembers: z.number(),
             emailsSent24h: z.number(),
             emailsSent7d: z.number(),
             emailsSent30d: z.number(),
@@ -123,6 +120,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 +143,7 @@ const emailMetricsRoute = createRoute({
                 deliveryRate: z.number(),
                 openRate: z.number(),
                 clickRate: z.number(),
+                clickToDeliveryRate: z.number(),
               }),
             ),
           }),
@@ -216,6 +221,75 @@ const eventVolumeRoute = createRoute({
   },
 });
 
+const bucketsMetricsRoute = createRoute({
+  method: "get",
+  path: "/buckets",
+  tags: ["Admin — Metrics"],
+  summary: "Per-bucket membership metrics",
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            buckets: z.array(
+              z.object({
+                bucketId: z.string(),
+                name: z.string(),
+                size: z.number(),
+                entered: z.number(),
+                left: z.number(),
+                avgDwellSecs: z.number().nullable(),
+              }),
+            ),
+          }),
+        },
+      },
+      description: "Per-bucket size, entered/left totals, and average dwell",
+    },
+  },
+});
+
+const bucketTrendRoute = createRoute({
+  method: "get",
+  path: "/buckets/{id}",
+  tags: ["Admin — Metrics"],
+  summary: "Single bucket size-over-time and entered/left trend",
+  request: {
+    params: z.object({ id: z.string() }),
+    query: z.object({
+      period: z.enum(["day", "week", "month"]).default("day"),
+      from: z.string().datetime().optional(),
+      to: z.string().datetime().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            bucketId: z.string(),
+            size: z.number(),
+            points: z.array(
+              z.object({
+                date: z.string(),
+                entered: z.number(),
+                left: z.number(),
+              }),
+            ),
+          }),
+        },
+      },
+      description: "Bucket entered/left time-series with current size",
+    },
+    404: {
+      content: {
+        "application/json": { schema: errorSchema },
+      },
+      description: "Bucket not found",
+    },
+  },
+});
+
 export const metricsRouter = new OpenAPIHono<AppEnv>()
   .openapi(overviewRoute, async (c) => {
     const { db } = c.get("container");
@@ -228,6 +302,8 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
     const [
       contactsTotal,
       activeJourneys,
+      activeBucketsRows,
+      bucketMembers,
       emails24h,
       emails7d,
       emails30d,
@@ -250,6 +326,27 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
           ),
         )
         .then((r) => r[0]?.count ?? 0),
+      // Distinct buckets with at least one active member.
+      db
+        .selectDistinct({ bucketId: bucketMemberships.bucketId })
+        .from(bucketMemberships)
+        .where(
+          and(
+            inArray(bucketMemberships.status, ["active"]),
+            isNull(bucketMemberships.deletedAt),
+          ),
+        ),
+      // Total active memberships across all buckets.
+      db
+        .select({ count: count() })
+        .from(bucketMemberships)
+        .where(
+          and(
+            inArray(bucketMemberships.status, ["active"]),
+            isNull(bucketMemberships.deletedAt),
+          ),
+        )
+        .then((r) => r[0]?.count ?? 0),
       db
         .select({ count: count() })
         .from(emailSends)
@@ -284,18 +381,18 @@ 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(
       {
         totalContacts: contactsTotal,
         activeJourneys,
+        activeBuckets: activeBucketsRows.length,
+        bucketMembers,
         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 +449,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 +458,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 +533,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 +553,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 +561,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 +616,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),
       };
     });
 
@@ -556,4 +661,162 @@ export const metricsRouter = new OpenAPIHono<AppEnv>()
     }));
 
     return c.json({ events }, 200);
+  })
+  .openapi(bucketsMetricsRoute, async (c) => {
+    const { db, bucketRegistry } = c.get("container");
+
+    const [sizes, totals, dwell] = await Promise.all([
+      // Current size = active, non-deleted memberships per bucket.
+      db
+        .select({
+          bucketId: bucketMemberships.bucketId,
+          size: count(),
+        })
+        .from(bucketMemberships)
+        .where(
+          and(
+            eq(bucketMemberships.status, "active"),
+            isNull(bucketMemberships.deletedAt),
+          ),
+        )
+        .groupBy(bucketMemberships.bucketId),
+      // Total entered = all rows; total left = rows that have flipped to "left".
+      db
+        .select({
+          bucketId: bucketMemberships.bucketId,
+          entered: count(),
+          left: sql<number>`count(*) filter (where ${bucketMemberships.status} = 'left')`,
+        })
+        .from(bucketMemberships)
+        .where(isNull(bucketMemberships.deletedAt))
+        .groupBy(bucketMemberships.bucketId),
+      // Average dwell — seconds between entry and leave (or now, if still active).
+      db
+        .select({
+          bucketId: bucketMemberships.bucketId,
+          avgDwell: sql<number>`avg(extract(epoch from (coalesce(${bucketMemberships.leftAt}, now()) - ${bucketMemberships.enteredAt})))`,
+        })
+        .from(bucketMemberships)
+        .where(isNull(bucketMemberships.deletedAt))
+        .groupBy(bucketMemberships.bucketId),
+    ]);
+
+    const sizeMap = new Map(sizes.map((r) => [r.bucketId, r.size]));
+    const totalsMap = new Map(
+      totals.map((r) => [
+        r.bucketId,
+        { entered: Number(r.entered), left: Number(r.left) },
+      ]),
+    );
+    const dwellMap = new Map<string, number>();
+    for (const row of dwell) {
+      if (row.avgDwell != null) {
+        dwellMap.set(row.bucketId, Number(row.avgDwell));
+      }
+    }
+
+    const buckets = bucketRegistry.getAll().map((b) => {
+      const t = totalsMap.get(b.id) ?? { entered: 0, left: 0 };
+      return {
+        bucketId: b.id,
+        name: b.name,
+        size: sizeMap.get(b.id) ?? 0,
+        entered: t.entered,
+        left: t.left,
+        avgDwellSecs: dwellMap.has(b.id)
+          ? Math.round(dwellMap.get(b.id) ?? 0)
+          : null,
+      };
+    });
+
+    return c.json({ buckets }, 200);
+  })
+  .openapi(bucketTrendRoute, async (c) => {
+    const { db, bucketRegistry } = c.get("container");
+    const { id } = c.req.valid("param");
+    const { period, from, to } = c.req.valid("query");
+
+    if (!bucketRegistry.has(id)) {
+      return c.json({ error: "Bucket not found" }, 404);
+    }
+
+    const now = new Date();
+    const defaultFrom = new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+    const fromDate = from ? new Date(from) : defaultFrom;
+    const toDate = to ? new Date(to) : now;
+
+    const [size, enteredRows, leftRows] = await Promise.all([
+      db
+        .select({ count: count() })
+        .from(bucketMemberships)
+        .where(
+          and(
+            eq(bucketMemberships.bucketId, id),
+            eq(bucketMemberships.status, "active"),
+            isNull(bucketMemberships.deletedAt),
+          ),
+        )
+        .then((r) => r[0]?.count ?? 0),
+      // Joins over time, bucketed on enteredAt.
+      db
+        .select({
+          date: sql<string>`date_trunc(${TRUNC_SQL[period]}, ${bucketMemberships.enteredAt})::text`,
+          count: count(),
+        })
+        .from(bucketMemberships)
+        .where(
+          and(
+            eq(bucketMemberships.bucketId, id),
+            isNull(bucketMemberships.deletedAt),
+            gte(bucketMemberships.enteredAt, fromDate),
+            lte(bucketMemberships.enteredAt, toDate),
+          ),
+        )
+        .groupBy(
+          sql`date_trunc(${TRUNC_SQL[period]}, ${bucketMemberships.enteredAt})`,
+        )
+        .orderBy(
+          sql`date_trunc(${TRUNC_SQL[period]}, ${bucketMemberships.enteredAt})`,
+        ),
+      // Leaves over time, bucketed on leftAt (only flipped rows have a leftAt).
+      db
+        .select({
+          date: sql<string>`date_trunc(${TRUNC_SQL[period]}, ${bucketMemberships.leftAt})::text`,
+          count: count(),
+        })
+        .from(bucketMemberships)
+        .where(
+          and(
+            eq(bucketMemberships.bucketId, id),
+            isNull(bucketMemberships.deletedAt),
+            isNotNull(bucketMemberships.leftAt),
+            gte(bucketMemberships.leftAt, fromDate),
+            lte(bucketMemberships.leftAt, toDate),
+          ),
+        )
+        .groupBy(
+          sql`date_trunc(${TRUNC_SQL[period]}, ${bucketMemberships.leftAt})`,
+        )
+        .orderBy(
+          sql`date_trunc(${TRUNC_SQL[period]}, ${bucketMemberships.leftAt})`,
+        ),
+    ]);
+
+    const pointMap = new Map<string, { entered: number; left: number }>();
+    for (const row of enteredRows) {
+      const entry = pointMap.get(row.date) ?? { entered: 0, left: 0 };
+      entry.entered = row.count;
+      pointMap.set(row.date, entry);
+    }
+    for (const row of leftRows) {
+      const entry = pointMap.get(row.date) ?? { entered: 0, left: 0 };
+      entry.left = row.count;
+      pointMap.set(row.date, entry);
+    }
+
+    const points = Array.from(pointMap.entries())
+      .map(([date, v]) => ({ date, entered: v.entered, left: v.left }))
+      .sort((a, b) => a.date.localeCompare(b.date));
+
+    return c.json({ bucketId: id, size, points }, 200);
   });