@hogsend/engine 0.0.1

package/src/routes/admin/emails.ts

@@ -0,0 +1,269 @@
+import {
+  type Database,
+  emailSends,
+  journeyStates,
+  linkClicks,
+  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 type { AppEnv } from "../../app.js";
+
+const emailSchema = z.object({
+  id: z.string(),
+  journeyStateId: z.string().nullable(),
+  templateKey: z.string().nullable(),
+  resendId: z.string().nullable(),
+  fromEmail: z.string(),
+  toEmail: z.string(),
+  subject: z.string(),
+  category: z.string().nullable(),
+  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(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const trackedLinkSchema = z.object({
+  id: z.string(),
+  originalUrl: z.string(),
+  clickCount: z.number(),
+  clicks: z.array(
+    z.object({
+      id: z.string(),
+      clickedAt: z.string(),
+      ipAddress: z.string().nullable(),
+      userAgent: z.string().nullable(),
+    }),
+  ),
+});
+
+const journeyContextSchema = z
+  .object({
+    journeyId: z.string(),
+    userId: z.string(),
+    status: z.string(),
+    currentNodeId: z.string(),
+  })
+  .nullable();
+
+import { errorSchema } from "../../lib/schemas.js";
+
+function serializeEmail(row: typeof emailSends.$inferSelect) {
+  return {
+    id: row.id,
+    journeyStateId: row.journeyStateId,
+    templateKey: row.templateKey,
+    resendId: row.resendId,
+    fromEmail: row.fromEmail,
+    toEmail: row.toEmail,
+    subject: row.subject,
+    category: row.category,
+    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,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+const listRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Emails"],
+  summary: "List email sends",
+  request: {
+    query: z.object({
+      limit: z.coerce.number().min(1).max(100).default(50),
+      offset: z.coerce.number().min(0).default(0),
+      toEmail: z.string().optional(),
+      templateKey: z.string().optional(),
+      status: z
+        .enum([
+          "queued",
+          "rendered",
+          "sent",
+          "delivered",
+          "opened",
+          "clicked",
+          "bounced",
+          "complained",
+          "failed",
+        ])
+        .optional(),
+      from: z.string().datetime().optional(),
+      to: z.string().datetime().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            emails: z.array(emailSchema),
+            total: z.number(),
+            limit: z.number(),
+            offset: z.number(),
+          }),
+        },
+      },
+      description: "Paginated email send list",
+    },
+  },
+});
+
+const getRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Admin — Emails"],
+  summary: "Get email detail with delivery timeline and link clicks",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            email: emailSchema,
+            trackedLinks: z.array(trackedLinkSchema),
+            journeyContext: journeyContextSchema,
+          }),
+        },
+      },
+      description: "Email detail with tracked links and journey context",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Email not found",
+    },
+  },
+});
+
+async function fetchTrackedLinksWithClicks(db: Database, emailSendId: string) {
+  const links = await db
+    .select()
+    .from(trackedLinks)
+    .where(eq(trackedLinks.emailSendId, emailSendId))
+    .orderBy(trackedLinks.createdAt);
+
+  if (links.length === 0) return [];
+
+  const linkIds = links.map((l) => l.id);
+  const clicks = await db
+    .select()
+    .from(linkClicks)
+    .where(inArray(linkClicks.trackedLinkId, linkIds))
+    .orderBy(linkClicks.clickedAt);
+
+  const clicksByLink = new Map<string, (typeof clicks)[number][]>();
+  for (const click of clicks) {
+    const arr = clicksByLink.get(click.trackedLinkId) ?? [];
+    arr.push(click);
+    clicksByLink.set(click.trackedLinkId, arr);
+  }
+
+  return links.map((link) => ({
+    id: link.id,
+    originalUrl: link.originalUrl,
+    clickCount: link.clickCount,
+    clicks: (clicksByLink.get(link.id) ?? []).map((click) => ({
+      id: click.id,
+      clickedAt: click.clickedAt.toISOString(),
+      ipAddress: click.ipAddress,
+      userAgent: click.userAgent,
+    })),
+  }));
+}
+
+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 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 (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, 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(
+      {
+        emails: rows.map(serializeEmail),
+        total: totalRows[0]?.count ?? 0,
+        limit,
+        offset,
+      },
+      200,
+    );
+  })
+  .openapi(getRoute, async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    const rows = await db
+      .select()
+      .from(emailSends)
+      .where(eq(emailSends.id, id))
+      .limit(1);
+
+    const row = rows[0];
+    if (!row) {
+      return c.json({ error: "Email not found" }, 404);
+    }
+
+    const [links, journeyContext] = await Promise.all([
+      fetchTrackedLinksWithClicks(db, id),
+      row.journeyStateId
+        ? db
+            .select({
+              journeyId: journeyStates.journeyId,
+              userId: journeyStates.userId,
+              status: journeyStates.status,
+              currentNodeId: journeyStates.currentNodeId,
+            })
+            .from(journeyStates)
+            .where(
+              and(
+                eq(journeyStates.id, row.journeyStateId),
+                isNull(journeyStates.deletedAt),
+              ),
+            )
+            .limit(1)
+            .then((rows) => rows[0] ?? null)
+        : Promise.resolve(null),
+    ]);
+
+    return c.json(
+      {
+        email: serializeEmail(row),
+        trackedLinks: links,
+        journeyContext,
+      },
+      200,
+    );
+  });

package/src/routes/admin/events.ts

@@ -0,0 +1,132 @@
+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";
+
+const eventSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  event: z.string(),
+  properties: z.record(z.string(), z.unknown()).nullable(),
+  occurredAt: z.string(),
+});
+
+const errorSchema = z.object({ error: z.string() });
+
+function serializeEvent(row: typeof userEvents.$inferSelect) {
+  return {
+    id: row.id,
+    userId: row.userId,
+    event: row.event,
+    properties: (row.properties ?? null) as Record<string, unknown> | null,
+    occurredAt: row.occurredAt.toISOString(),
+  };
+}
+
+const listRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Admin — Events"],
+  summary: "List events",
+  request: {
+    query: z.object({
+      limit: z.coerce.number().min(1).max(100).default(50),
+      offset: z.coerce.number().min(0).default(0),
+      userId: z.string().optional(),
+      event: z.string().optional(),
+      from: z.string().datetime().optional(),
+      to: z.string().datetime().optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            events: z.array(eventSchema),
+            total: z.number(),
+            limit: z.number(),
+            offset: z.number(),
+          }),
+        },
+      },
+      description: "Paginated event list",
+    },
+  },
+});
+
+const getRoute = createRoute({
+  method: "get",
+  path: "/{id}",
+  tags: ["Admin — Events"],
+  summary: "Get event detail",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ event: eventSchema }),
+        },
+      },
+      description: "Event detail",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Event not found",
+    },
+  },
+});
+
+export const eventsRouter = new OpenAPIHono<AppEnv>()
+  .openapi(listRoute, async (c) => {
+    const { db } = c.get("container");
+    const { limit, offset, userId, event, from, to } = c.req.valid("query");
+
+    const conditions = [];
+    if (userId) conditions.push(eq(userEvents.userId, userId));
+    if (event) conditions.push(eq(userEvents.event, event));
+    if (from) conditions.push(gte(userEvents.occurredAt, new Date(from)));
+    if (to) conditions.push(lte(userEvents.occurredAt, new Date(to)));
+
+    const where = conditions.length > 0 ? and(...conditions) : undefined;
+
+    const [rows, totalRows] = await Promise.all([
+      db
+        .select()
+        .from(userEvents)
+        .where(where)
+        .orderBy(desc(userEvents.occurredAt))
+        .limit(limit)
+        .offset(offset),
+      db.select({ count: count() }).from(userEvents).where(where),
+    ]);
+
+    return c.json(
+      {
+        events: rows.map(serializeEvent),
+        total: totalRows[0]?.count ?? 0,
+        limit,
+        offset,
+      },
+      200,
+    );
+  })
+  .openapi(getRoute, async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+
+    const rows = await db
+      .select()
+      .from(userEvents)
+      .where(eq(userEvents.id, id))
+      .limit(1);
+
+    const row = rows[0];
+    if (!row) {
+      return c.json({ error: "Event not found" }, 404);
+    }
+
+    return c.json({ event: serializeEvent(row) }, 200);
+  });

package/src/routes/admin/index.ts

@@ -0,0 +1,36 @@
+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 { alertsRouter } from "./alerts.js";
+import { apiKeysRouter } from "./api-keys.js";
+import { auditLogsRouter } from "./audit-logs.js";
+import { bulkRouter } from "./bulk.js";
+import { contactsRouter } from "./contacts.js";
+import { dlqRouter } from "./dlq.js";
+import { emailsRouter } from "./emails.js";
+import { eventsRouter } from "./events.js";
+import { journeyLogsRouter } from "./journey-logs.js";
+import { journeysRouter } from "./journeys.js";
+import { metricsRouter } from "./metrics.js";
+import { preferencesRouter } from "./preferences.js";
+import { timelineRouter } from "./timeline.js";
+
+export const adminRouter = new OpenAPIHono<AppEnv>();
+adminRouter.use("*", requireApiKey);
+adminRouter.use("*", rateLimit);
+adminRouter.use("*", auditMiddleware);
+adminRouter.route("/", bulkRouter);
+adminRouter.route("/contacts", contactsRouter);
+adminRouter.route("/contacts", preferencesRouter);
+adminRouter.route("/contacts", timelineRouter);
+adminRouter.route("/journeys", journeysRouter);
+adminRouter.route("/events", eventsRouter);
+adminRouter.route("/emails", emailsRouter);
+adminRouter.route("/journey-logs", journeyLogsRouter);
+adminRouter.route("/metrics", metricsRouter);
+adminRouter.route("/api-keys", apiKeysRouter);
+adminRouter.route("/audit-logs", auditLogsRouter);
+adminRouter.route("/alerts", alertsRouter);
+adminRouter.route("/dlq", dlqRouter);

package/src/routes/admin/journey-logs.ts

@@ -0,0 +1,117 @@
+import { journeyLogs, journeyStates } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { and, eq, isNull } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+
+const stateSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  userEmail: z.string(),
+  journeyId: z.string(),
+  currentNodeId: z.string(),
+  status: z.string(),
+  hatchetRunId: z.string().nullable(),
+  context: z.record(z.string(), z.unknown()),
+  errorMessage: z.string().nullable(),
+  entryCount: z.number(),
+  completedAt: z.string().nullable(),
+  exitedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const logSchema = z.object({
+  id: z.string(),
+  fromNodeId: z.string().nullable(),
+  toNodeId: z.string().nullable(),
+  action: z.string(),
+  detail: z.record(z.string(), z.unknown()).nullable(),
+  createdAt: z.string(),
+});
+
+import { errorSchema } from "../../lib/schemas.js";
+
+function serializeState(row: typeof journeyStates.$inferSelect) {
+  return {
+    ...row,
+    context: (row.context ?? {}) as Record<string, unknown>,
+    completedAt: row.completedAt?.toISOString() ?? null,
+    exitedAt: row.exitedAt?.toISOString() ?? null,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+function serializeLog(row: typeof journeyLogs.$inferSelect) {
+  return {
+    id: row.id,
+    fromNodeId: row.fromNodeId,
+    toNodeId: row.toNodeId,
+    action: row.action,
+    detail: (row.detail ?? null) as Record<string, unknown> | null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+const getRoute = createRoute({
+  method: "get",
+  path: "/{stateId}",
+  tags: ["Admin — Journey Logs"],
+  summary: "Get full log sequence for a journey instance",
+  request: {
+    params: z.object({ stateId: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            state: stateSchema,
+            logs: z.array(logSchema),
+          }),
+        },
+      },
+      description: "Journey instance with full log sequence",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Journey state not found",
+    },
+  },
+});
+
+export const journeyLogsRouter = new OpenAPIHono<AppEnv>().openapi(
+  getRoute,
+  async (c) => {
+    const { db } = c.get("container");
+    const { stateId } = c.req.valid("param");
+
+    const [stateRows, logs] = await Promise.all([
+      db
+        .select()
+        .from(journeyStates)
+        .where(
+          and(eq(journeyStates.id, stateId), isNull(journeyStates.deletedAt)),
+        )
+        .limit(1),
+      db
+        .select()
+        .from(journeyLogs)
+        .where(eq(journeyLogs.journeyStateId, stateId))
+        .orderBy(journeyLogs.createdAt),
+    ]);
+
+    const state = stateRows[0];
+    if (!state) {
+      return c.json({ error: "Journey state not found" }, 404);
+    }
+
+    return c.json(
+      {
+        state: serializeState(state),
+        logs: logs.map(serializeLog),
+      },
+      200,
+    );
+  },
+);