@hogsend/engine 0.0.1

package/src/routes/admin/timeline.ts

@@ -0,0 +1,221 @@
+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";
+
+const timelineEntrySchema = z.object({
+  type: z.enum(["event", "journey", "email"]),
+  timestamp: z.string(),
+  data: z.record(z.string(), z.unknown()),
+});
+
+import { errorSchema } from "../../lib/schemas.js";
+
+const listRoute = createRoute({
+  method: "get",
+  path: "/{id}/timeline",
+  tags: ["Admin — Timeline"],
+  summary: "Get contact activity timeline",
+  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),
+      type: z.enum(["event", "journey", "email"]).optional(),
+    }),
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({
+            timeline: z.array(timelineEntrySchema),
+            total: z.number(),
+            limit: z.number(),
+            offset: z.number(),
+          }),
+        },
+      },
+      description: "Chronological activity timeline",
+    },
+    404: {
+      content: { "application/json": { schema: errorSchema } },
+      description: "Contact not found",
+    },
+  },
+});
+
+type TimelineEntry = {
+  type: "event" | "journey" | "email";
+  timestamp: string;
+  data: Record<string, unknown>;
+};
+
+export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
+  listRoute,
+  async (c) => {
+    const { db } = c.get("container");
+    const { id } = c.req.valid("param");
+    const { limit, offset, type } = c.req.valid("query");
+
+    const contact = await resolveContact({ db, id });
+    if (!contact) {
+      return c.json({ error: "Contact not found" }, 404);
+    }
+
+    const externalId = contact.externalId;
+    const entries: TimelineEntry[] = [];
+
+    const shouldFetch = (t: string) => !type || type === t;
+    const fetchLimit = limit + offset;
+
+    const [
+      eventRows,
+      journeyRows,
+      emailRows,
+      eventCount,
+      journeyCount,
+      emailCount,
+    ] = await Promise.all([
+      shouldFetch("event")
+        ? db
+            .select()
+            .from(userEvents)
+            .where(eq(userEvents.userId, externalId))
+            .orderBy(desc(userEvents.occurredAt))
+            .limit(fetchLimit)
+        : Promise.resolve([]),
+      shouldFetch("journey")
+        ? db
+            .select()
+            .from(journeyStates)
+            .where(
+              and(
+                eq(journeyStates.userId, externalId),
+                isNull(journeyStates.deletedAt),
+              ),
+            )
+            .orderBy(desc(journeyStates.createdAt))
+            .limit(fetchLimit)
+        : Promise.resolve([]),
+      shouldFetch("email")
+        ? db
+            .select({
+              id: emailSends.id,
+              templateKey: emailSends.templateKey,
+              subject: emailSends.subject,
+              status: emailSends.status,
+              toEmail: emailSends.toEmail,
+              fromEmail: emailSends.fromEmail,
+              sentAt: emailSends.sentAt,
+              deliveredAt: emailSends.deliveredAt,
+              openedAt: emailSends.openedAt,
+              createdAt: emailSends.createdAt,
+            })
+            .from(emailSends)
+            .innerJoin(
+              journeyStates,
+              eq(emailSends.journeyStateId, journeyStates.id),
+            )
+            .where(
+              and(
+                eq(journeyStates.userId, externalId),
+                isNull(journeyStates.deletedAt),
+              ),
+            )
+            .orderBy(desc(emailSends.createdAt))
+            .limit(fetchLimit)
+        : Promise.resolve([]),
+      shouldFetch("event")
+        ? db
+            .select({ count: count() })
+            .from(userEvents)
+            .where(eq(userEvents.userId, externalId))
+            .then((r) => r[0]?.count ?? 0)
+        : Promise.resolve(0),
+      shouldFetch("journey")
+        ? db
+            .select({ count: count() })
+            .from(journeyStates)
+            .where(
+              and(
+                eq(journeyStates.userId, externalId),
+                isNull(journeyStates.deletedAt),
+              ),
+            )
+            .then((r) => r[0]?.count ?? 0)
+        : Promise.resolve(0),
+      shouldFetch("email")
+        ? db
+            .select({ count: count() })
+            .from(emailSends)
+            .innerJoin(
+              journeyStates,
+              eq(emailSends.journeyStateId, journeyStates.id),
+            )
+            .where(
+              and(
+                eq(journeyStates.userId, externalId),
+                isNull(journeyStates.deletedAt),
+              ),
+            )
+            .then((r) => r[0]?.count ?? 0)
+        : Promise.resolve(0),
+    ]);
+
+    for (const row of eventRows) {
+      entries.push({
+        type: "event",
+        timestamp: row.occurredAt.toISOString(),
+        data: {
+          id: row.id,
+          event: row.event,
+          properties: row.properties ?? {},
+        },
+      });
+    }
+
+    for (const row of journeyRows) {
+      entries.push({
+        type: "journey",
+        timestamp: row.createdAt.toISOString(),
+        data: {
+          id: row.id,
+          journeyId: row.journeyId,
+          status: row.status,
+          currentNodeId: row.currentNodeId,
+          completedAt: row.completedAt?.toISOString() ?? null,
+          exitedAt: row.exitedAt?.toISOString() ?? null,
+        },
+      });
+    }
+
+    for (const row of emailRows) {
+      entries.push({
+        type: "email",
+        timestamp: row.createdAt.toISOString(),
+        data: {
+          id: row.id,
+          templateKey: row.templateKey,
+          subject: row.subject,
+          status: row.status,
+          toEmail: row.toEmail,
+          sentAt: row.sentAt?.toISOString() ?? null,
+          deliveredAt: row.deliveredAt?.toISOString() ?? null,
+          openedAt: row.openedAt?.toISOString() ?? null,
+        },
+      });
+    }
+
+    entries.sort(
+      (a, b) =>
+        new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime(),
+    );
+
+    const total = eventCount + journeyCount + emailCount;
+    const paged = entries.slice(offset, offset + limit);
+
+    return c.json({ timeline: paged, total, limit, offset }, 200);
+  },
+);

package/src/routes/email/index.ts

@@ -0,0 +1,8 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import { preferencesRouter } from "./preferences.js";
+import { unsubscribeRouter } from "./unsubscribe.js";
+
+export const emailRouter = new OpenAPIHono<AppEnv>();
+emailRouter.route("/", unsubscribeRouter);
+emailRouter.route("/", preferencesRouter);

package/src/routes/email/preferences.ts

@@ -0,0 +1,144 @@
+import { emailPreferences } from "@hogsend/db";
+import type { UnsubscribeTokenPayload } from "@hogsend/email";
+import {
+  generateUnsubscribeToken,
+  InvalidTokenError,
+  validateUnsubscribeToken,
+} from "@hogsend/email";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { and, eq } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { htmlPage } from "../../lib/html.js";
+
+const EMAIL_CATEGORIES = [
+  { id: "journey", label: "Journey & lifecycle emails" },
+] as const;
+
+const preferencesRoute = createRoute({
+  method: "get",
+  path: "/preferences",
+  tags: ["Email"],
+  summary: "Email preference center",
+  request: {
+    query: z.object({
+      token: z.string().min(1),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "text/html": { schema: z.string() } },
+      description: "Preference center page",
+    },
+    400: {
+      content: { "text/html": { schema: z.string() } },
+      description: "Invalid or expired token",
+    },
+  },
+});
+
+export const preferencesRouter = new OpenAPIHono<AppEnv>().openapi(
+  preferencesRoute,
+  async (c) => {
+    const { token } = c.req.valid("query");
+    const { env, db } = c.get("container");
+
+    let payload: UnsubscribeTokenPayload;
+    try {
+      payload = validateUnsubscribeToken({
+        token,
+        secret: env.BETTER_AUTH_SECRET,
+      });
+    } catch (err) {
+      const message =
+        err instanceof InvalidTokenError ? err.message : "Invalid token";
+      return c.html(
+        htmlPage({
+          title: "Invalid Link",
+          body: `<h1>This link is no longer valid</h1><p>${message}. Please check your email for a newer link.</p>`,
+        }),
+        400,
+      );
+    }
+
+    const { externalId, email } = payload;
+
+    const rows = await db
+      .select()
+      .from(emailPreferences)
+      .where(
+        and(
+          eq(emailPreferences.userId, externalId),
+          eq(emailPreferences.email, email),
+        ),
+      )
+      .limit(1);
+
+    const prefs = rows[0];
+    const categories = (prefs?.categories ?? {}) as Record<string, boolean>;
+    const globalUnsub = prefs?.unsubscribedAll ?? false;
+
+    function makeActionUrl(
+      action: "unsubscribe" | "resubscribe",
+      category?: string,
+    ): string {
+      const actionToken = generateUnsubscribeToken({
+        secret: env.BETTER_AUTH_SECRET,
+        externalId,
+        email,
+        action,
+        category,
+      });
+      return `${env.API_PUBLIC_URL}/v1/email/unsubscribe?token=${encodeURIComponent(actionToken)}`;
+    }
+
+    let categoryRows = "";
+    for (const cat of EMAIL_CATEGORIES) {
+      const isSubscribed = categories[cat.id] !== false && !globalUnsub;
+      const statusClass = isSubscribed ? "subscribed" : "unsubscribed";
+      const statusText = isSubscribed ? "Subscribed" : "Unsubscribed";
+      const actionLabel = isSubscribed ? "Unsubscribe" : "Resubscribe";
+      const actionUrl = isSubscribed
+        ? makeActionUrl("unsubscribe", cat.id)
+        : makeActionUrl("resubscribe", cat.id);
+
+      categoryRows += `
+        <div class="pref-row">
+          <div>
+            <div class="pref-label">${cat.label}</div>
+            <div class="pref-status ${statusClass}">${statusText}</div>
+          </div>
+          <a href="${actionUrl}">${actionLabel}</a>
+        </div>`;
+    }
+
+    const globalStatusClass = globalUnsub ? "unsubscribed" : "subscribed";
+    const globalStatusText = globalUnsub
+      ? "Unsubscribed from all"
+      : "Receiving emails";
+    const globalActionLabel = globalUnsub
+      ? "Resubscribe to all"
+      : "Unsubscribe from all";
+    const globalActionUrl = globalUnsub
+      ? makeActionUrl("resubscribe")
+      : makeActionUrl("unsubscribe");
+
+    return c.html(
+      htmlPage({
+        title: "Email Preferences",
+        body: `<h1>Email Preferences</h1>
+        <p>Manage which emails you receive at <strong>${email}</strong>.</p>
+        ${categoryRows}
+        <div class="global-row">
+          <div class="pref-row" style="border-bottom: none;">
+            <div>
+              <div class="pref-label">All emails</div>
+              <div class="pref-status ${globalStatusClass}">${globalStatusText}</div>
+            </div>
+            <a href="${globalActionUrl}">${globalActionLabel}</a>
+          </div>
+        </div>`,
+      }),
+      200,
+    );
+  },
+);

package/src/routes/email/unsubscribe.ts

@@ -0,0 +1,161 @@
+import type { Database } from "@hogsend/db";
+import { emailPreferences } from "@hogsend/db";
+import type { UnsubscribeTokenPayload } from "@hogsend/email";
+import {
+  generatePreferenceCenterUrl,
+  InvalidTokenError,
+  validateUnsubscribeToken,
+} from "@hogsend/email";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { sql } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { htmlPage } from "../../lib/html.js";
+
+const unsubscribeRoute = createRoute({
+  method: "get",
+  path: "/unsubscribe",
+  tags: ["Email"],
+  summary: "Unsubscribe from emails",
+  request: {
+    query: z.object({
+      token: z.string().min(1),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "text/html": { schema: z.string() } },
+      description: "Unsubscribe confirmation",
+    },
+    400: {
+      content: { "text/html": { schema: z.string() } },
+      description: "Invalid or expired token",
+    },
+  },
+});
+
+async function upsertPreference(
+  db: Database,
+  externalId: string,
+  email: string,
+  update: {
+    unsubscribedAll?: boolean;
+    categoryKey?: string;
+    categoryValue?: boolean;
+  },
+) {
+  const setClause: Record<string, unknown> = { updatedAt: new Date() };
+
+  if (update.unsubscribedAll !== undefined) {
+    setClause.unsubscribedAll = update.unsubscribedAll;
+  }
+  if (update.categoryKey !== undefined) {
+    const jsonValue = update.categoryValue ? "true" : "false";
+    setClause.categories = sql`jsonb_set(COALESCE(${emailPreferences.categories}, '{}'::jsonb), ${`{${update.categoryKey}}`}, ${jsonValue}::jsonb)`;
+  }
+
+  await db
+    .insert(emailPreferences)
+    .values({
+      userId: externalId,
+      email,
+      ...(update.unsubscribedAll !== undefined
+        ? { unsubscribedAll: update.unsubscribedAll }
+        : {}),
+      ...(update.categoryKey !== undefined
+        ? {
+            categories: { [update.categoryKey]: update.categoryValue ?? false },
+          }
+        : {}),
+    })
+    .onConflictDoUpdate({
+      target: [emailPreferences.userId, emailPreferences.email],
+      set: setClause,
+    });
+}
+
+export const unsubscribeRouter = new OpenAPIHono<AppEnv>().openapi(
+  unsubscribeRoute,
+  async (c) => {
+    const { token } = c.req.valid("query");
+    const { env, db } = c.get("container");
+
+    let payload: UnsubscribeTokenPayload;
+    try {
+      payload = validateUnsubscribeToken({
+        token,
+        secret: env.BETTER_AUTH_SECRET,
+      });
+    } catch (err) {
+      const message =
+        err instanceof InvalidTokenError ? err.message : "Invalid token";
+      return c.html(
+        htmlPage({
+          title: "Invalid Link",
+          body: `<h1>This link is no longer valid</h1><p>${message}. Please check your email for a newer link.</p>`,
+        }),
+        400,
+      );
+    }
+
+    const { externalId, email, category, action } = payload;
+
+    if (category && !/^[a-z0-9_-]+$/i.test(category)) {
+      return c.html(
+        htmlPage({
+          title: "Invalid Link",
+          body: "<h1>Invalid category</h1><p>This link is malformed.</p>",
+        }),
+        400,
+      );
+    }
+
+    if (action === "resubscribe") {
+      await upsertPreference(
+        db,
+        externalId,
+        email,
+        category
+          ? {
+              categoryKey: category,
+              categoryValue: true,
+              unsubscribedAll: false,
+            }
+          : { unsubscribedAll: false },
+      );
+
+      return c.html(
+        htmlPage({
+          title: "Resubscribed",
+          body: `<h1>You're back!</h1><p>You've been resubscribed${category ? ` to <strong>${category}</strong> emails` : ""}.</p>`,
+        }),
+        200,
+      );
+    }
+
+    await upsertPreference(
+      db,
+      externalId,
+      email,
+      category
+        ? { categoryKey: category, categoryValue: false }
+        : { unsubscribedAll: true },
+    );
+
+    const preferenceCenterUrl = generatePreferenceCenterUrl({
+      baseUrl: env.API_PUBLIC_URL,
+      secret: env.BETTER_AUTH_SECRET,
+      externalId,
+      email,
+    });
+
+    return c.html(
+      htmlPage({
+        title: "Unsubscribed",
+        body: `<h1>You've been unsubscribed</h1>
+        <p>You won't receive ${category ? `<strong>${category}</strong>` : "any more"} emails from us.</p>
+        <p><a href="${preferenceCenterUrl}">Manage your email preferences</a></p>`,
+      }),
+      200,
+    );
+  },
+);

package/src/routes/health.ts

@@ -0,0 +1,131 @@
+import { getClientSchemaVersion, getEngineSchemaVersion } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { sql } from "drizzle-orm";
+import type { AppEnv } from "../app.js";
+import { API_VERSION } from "../env.js";
+import { getRedis } from "../lib/redis.js";
+
+const componentSchema = z.object({
+  status: z.enum(["up", "down"]),
+  latencyMs: z.number().optional(),
+});
+
+// Per-track schema version block. Two tracks: `engine` (bundled @hogsend/db
+// migrations) and `client` (the client repo's own migrations). See
+// docs/UPGRADING.md "Two-track migrations".
+const trackSchema = z.object({
+  applied: z.string().nullable(),
+  required: z.string().nullable(),
+  inSync: z.boolean(),
+  pending: z.array(z.string()),
+});
+
+const healthResponseSchema = z.object({
+  status: z.enum(["healthy", "degraded", "migration_pending"]),
+  uptime: z.number(),
+  timestamp: z.string(),
+  version: z.string(),
+  components: z.object({
+    database: componentSchema,
+    redis: componentSchema,
+  }),
+  schema: z.object({
+    engine: trackSchema,
+    client: trackSchema,
+  }),
+});
+
+const healthRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Health"],
+  summary: "Health check with component status",
+  responses: {
+    200: {
+      content: {
+        "application/json": { schema: healthResponseSchema },
+      },
+      description: "Service health status",
+    },
+  },
+});
+
+async function checkComponent(
+  fn: () => Promise<void>,
+): Promise<{ status: "up" | "down"; latencyMs: number }> {
+  const start = performance.now();
+  try {
+    await fn();
+    return {
+      status: "up",
+      latencyMs: Math.round(performance.now() - start),
+    };
+  } catch {
+    return {
+      status: "down",
+      latencyMs: Math.round(performance.now() - start),
+    };
+  }
+}
+
+export const healthRouter = new OpenAPIHono<AppEnv>().openapi(
+  healthRoute,
+  async (c) => {
+    const { db, clientJournal } = c.get("container");
+
+    const [dbCheck, redisCheck, engine, client] = await Promise.all([
+      checkComponent(async () => {
+        await db.execute(sql`SELECT 1`);
+      }),
+      checkComponent(async () => {
+        // Actively probe: getRedis() lazily creates + connects the client (with
+        // family:0 for Railway IPv6). The old getRedisIfConnected() only returned
+        // a client if something had ALREADY created one — which nothing does when
+        // PostHog is disabled — so redis always read "down" even though it was
+        // reachable. ioredis buffers the ping until connected (or rejects if the
+        // host is genuinely unreachable → a truthful "down").
+        await getRedis().ping();
+      }),
+      getEngineSchemaVersion(db),
+      getClientSchemaVersion(db, clientJournal ?? { entries: [] }),
+    ]);
+
+    // `migration_pending` if EITHER track is behind. The engine track also gates
+    // boot (fatal); the client track surfaces here non-fatally (client-owned).
+    const inSync = engine.inSync && client.inSync;
+    const allUp = dbCheck.status === "up" && redisCheck.status === "up";
+    const status = !inSync
+      ? ("migration_pending" as const)
+      : allUp
+        ? ("healthy" as const)
+        : ("degraded" as const);
+
+    return c.json(
+      {
+        status,
+        schema: {
+          engine: {
+            applied: engine.applied,
+            required: engine.required,
+            inSync: engine.inSync,
+            pending: engine.pending,
+          },
+          client: {
+            applied: client.applied,
+            required: client.required,
+            inSync: client.inSync,
+            pending: client.pending,
+          },
+        },
+        uptime: process.uptime(),
+        timestamp: new Date().toISOString(),
+        version: API_VERSION,
+        components: {
+          database: dbCheck,
+          redis: redisCheck,
+        },
+      },
+      200,
+    );
+  },
+);

package/src/routes/index.ts

@@ -0,0 +1,32 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { AppEnv } from "../app.js";
+import type { DefinedWebhookSource } from "../webhook-sources/define-webhook-source.js";
+import { adminRouter } from "./admin/index.js";
+import { emailRouter } from "./email/index.js";
+import { healthRouter } from "./health.js";
+import { ingestRouter } from "./ingest.js";
+import { trackingRouter } from "./tracking/index.js";
+import { registerWebhookRoutes } from "./webhooks/index.js";
+
+export interface RegisterRoutesOptions {
+  webhookSources: DefinedWebhookSource[];
+}
+
+export function registerRoutes(
+  app: OpenAPIHono<AppEnv>,
+  opts: RegisterRoutesOptions,
+) {
+  const v1 = new OpenAPIHono<AppEnv>();
+
+  v1.route("/health", healthRouter);
+  v1.route("/ingest", ingestRouter);
+  v1.route("/email", emailRouter);
+  v1.route("/admin", adminRouter);
+  v1.route("/t", trackingRouter);
+
+  app.route("/v1", v1);
+
+  // Webhooks (built-in Resend + injected content sources) are registered on the
+  // app at absolute paths.
+  registerWebhookRoutes(app, { webhookSources: opts.webhookSources });
+}