@hogsend/engine 0.0.1

package/src/routes/ingest.ts

@@ -0,0 +1,71 @@
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AppEnv } from "../app.js";
+import { ingestEvent } from "../lib/ingestion.js";
+
+const ingestRequestSchema = z.object({
+  event: z.string().min(1),
+  userId: z.string().min(1),
+  userEmail: z.string().email().optional(),
+  properties: z.record(z.string(), z.unknown()).optional(),
+  idempotencyKey: z.string().optional(),
+  timestamp: z.string().datetime().optional(),
+});
+
+const ingestResponseSchema = z.object({
+  stored: z.boolean(),
+  exits: z.array(
+    z.object({
+      journeyId: z.string(),
+      stateId: z.string(),
+      exited: z.boolean(),
+    }),
+  ),
+});
+
+const ingestRoute = createRoute({
+  method: "post",
+  path: "/",
+  tags: ["Ingestion"],
+  summary: "Ingest an event",
+  description:
+    "Receives events from direct API calls. Stores the event, pushes it to Hatchet for journey routing, and processes exit conditions.",
+  request: {
+    body: {
+      content: {
+        "application/json": { schema: ingestRequestSchema },
+      },
+    },
+  },
+  responses: {
+    202: {
+      content: {
+        "application/json": { schema: ingestResponseSchema },
+      },
+      description: "Event accepted and dispatched",
+    },
+  },
+});
+
+export const ingestRouter = new OpenAPIHono<AppEnv>().openapi(
+  ingestRoute,
+  async (c) => {
+    const body = c.req.valid("json");
+    const { db, registry, hatchet, logger } = c.get("container");
+
+    const result = await ingestEvent({
+      db,
+      registry,
+      hatchet,
+      logger,
+      event: {
+        event: body.event,
+        userId: body.userId,
+        userEmail: body.userEmail ?? "",
+        properties: body.properties ?? {},
+        idempotencyKey: body.idempotencyKey,
+      },
+    });
+
+    return c.json(result, 202);
+  },
+);

package/src/routes/tracking/click.ts

@@ -0,0 +1,103 @@
+import { emailSends, linkClicks, trackedLinks } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { and, eq, isNull, sql } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { EMAIL_LINK_CLICKED } from "../../lib/tracking-event-names.js";
+import { pushTrackingEvent } from "../../lib/tracking-events.js";
+
+const clickRoute = createRoute({
+  method: "get",
+  path: "/c/:id",
+  tags: ["Tracking"],
+  summary: "Track link click and redirect",
+  request: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+  },
+  responses: {
+    302: { description: "Redirect to original URL" },
+    404: { description: "Link not found" },
+  },
+});
+
+export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
+  clickRoute,
+  async (c) => {
+    const { id } = c.req.valid("param");
+    const { db, env } = c.get("container");
+
+    const rows = await db
+      .select({
+        id: trackedLinks.id,
+        originalUrl: trackedLinks.originalUrl,
+        emailSendId: trackedLinks.emailSendId,
+      })
+      .from(trackedLinks)
+      .where(eq(trackedLinks.id, id))
+      .limit(1);
+
+    const link = rows[0];
+    if (!link) {
+      return c.redirect(env.API_PUBLIC_URL, 302);
+    }
+
+    const ip =
+      c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ??
+      c.req.header("x-real-ip") ??
+      null;
+    const userAgent = c.req.header("user-agent") ?? null;
+
+    await Promise.all([
+      db.insert(linkClicks).values({
+        trackedLinkId: link.id,
+        ipAddress: ip,
+        userAgent,
+      }),
+      db
+        .update(trackedLinks)
+        .set({
+          clickCount: sql`${trackedLinks.clickCount} + 1`,
+          updatedAt: new Date(),
+        })
+        .where(eq(trackedLinks.id, link.id)),
+      db
+        .update(emailSends)
+        .set({
+          clickedAt: new Date(),
+          updatedAt: new Date(),
+        })
+        .where(
+          and(
+            eq(emailSends.id, link.emailSendId),
+            isNull(emailSends.clickedAt),
+          ),
+        ),
+    ]);
+
+    const {
+      hatchet,
+      registry,
+      logger,
+      analytics: posthog,
+    } = c.get("container");
+
+    pushTrackingEvent({
+      db,
+      hatchet,
+      registry,
+      logger,
+      posthog,
+      event: EMAIL_LINK_CLICKED,
+      emailSendId: link.emailSendId,
+      properties: { linkUrl: link.originalUrl, linkId: link.id },
+    }).catch((err) => {
+      logger.warn("Failed to push click tracking event", {
+        linkId: link.id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+
+    return c.redirect(link.originalUrl, 302);
+  },
+);

package/src/routes/tracking/index.ts

@@ -0,0 +1,9 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import { clickRouter } from "./click.js";
+import { openRouter } from "./open.js";
+
+export const trackingRouter = new OpenAPIHono<AppEnv>();
+
+trackingRouter.route("/", clickRouter);
+trackingRouter.route("/", openRouter);

package/src/routes/tracking/open.ts

@@ -0,0 +1,71 @@
+import { emailSends } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { and, eq, isNull } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { EMAIL_OPENED } from "../../lib/tracking-event-names.js";
+import { pushTrackingEvent } from "../../lib/tracking-events.js";
+
+const TRANSPARENT_GIF = Buffer.from(
+  "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
+  "base64",
+);
+
+const openRoute = createRoute({
+  method: "get",
+  path: "/o/:id",
+  tags: ["Tracking"],
+  summary: "Track email open",
+  request: {
+    params: z.object({
+      id: z.string().uuid(),
+    }),
+  },
+  responses: {
+    200: { description: "1x1 transparent GIF" },
+  },
+});
+
+export const openRouter = new OpenAPIHono<AppEnv>().openapi(
+  openRoute,
+  async (c) => {
+    const { id } = c.req.valid("param");
+    const { db } = c.get("container");
+
+    await db
+      .update(emailSends)
+      .set({
+        openedAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(and(eq(emailSends.id, id), isNull(emailSends.openedAt)));
+
+    const {
+      hatchet,
+      registry,
+      logger,
+      analytics: posthog,
+    } = c.get("container");
+
+    pushTrackingEvent({
+      db,
+      hatchet,
+      registry,
+      logger,
+      posthog,
+      event: EMAIL_OPENED,
+      emailSendId: id,
+    }).catch((err) => {
+      logger.warn("Failed to push open tracking event", {
+        emailSendId: id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+
+    return c.body(TRANSPARENT_GIF, 200, {
+      "Content-Type": "image/gif",
+      "Cache-Control": "no-store, no-cache, must-revalidate",
+      Pragma: "no-cache",
+      Expires: "0",
+    });
+  },
+);

package/src/routes/webhooks/index.ts

@@ -0,0 +1,17 @@
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import type { DefinedWebhookSource } from "../../webhook-sources/define-webhook-source.js";
+import { resendWebhookRouter } from "./resend.js";
+import { registerWebhookSourceRoutes } from "./sources.js";
+
+export interface RegisterWebhookRoutesOptions {
+  webhookSources: DefinedWebhookSource[];
+}
+
+export function registerWebhookRoutes(
+  app: OpenAPIHono<AppEnv>,
+  opts: RegisterWebhookRoutesOptions,
+) {
+  app.route("/v1/webhooks", resendWebhookRouter);
+  registerWebhookSourceRoutes(app, opts.webhookSources);
+}

package/src/routes/webhooks/resend.ts

@@ -0,0 +1,68 @@
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+
+const resendWebhookRoute = createRoute({
+  method: "post",
+  path: "/resend",
+  tags: ["Webhooks"],
+  summary: "Resend webhook receiver",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.record(z.string(), z.unknown()),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      content: {
+        "application/json": {
+          schema: z.object({ ok: z.boolean() }),
+        },
+      },
+      description: "Webhook processed",
+    },
+    401: {
+      content: {
+        "application/json": {
+          schema: z.object({ error: z.string() }),
+        },
+      },
+      description: "Missing or invalid webhook secret",
+    },
+  },
+});
+
+export const resendWebhookRouter = new OpenAPIHono<AppEnv>().openapi(
+  resendWebhookRoute,
+  async (c) => {
+    const { emailService, logger } = c.get("container");
+
+    const rawBody = await c.req.text();
+    const headers: Record<string, string> = {};
+    for (const [key, value] of c.req.raw.headers.entries()) {
+      headers[key] = value;
+    }
+
+    try {
+      const result = await emailService.handleWebhook({
+        payload: rawBody,
+        headers,
+      });
+
+      logger.info("Resend webhook processed", {
+        type: result.type,
+        handled: result.handled,
+      });
+
+      return c.json({ ok: true }, 200);
+    } catch (err) {
+      logger.warn("Resend webhook failed", {
+        error: err instanceof Error ? err.message : String(err),
+      });
+      return c.json({ error: "Webhook verification failed" }, 401);
+    }
+  },
+);

package/src/routes/webhooks/sources.ts

@@ -0,0 +1,97 @@
+import { createRoute, type OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import { ingestEvent } from "../../lib/ingestion.js";
+import type { DefinedWebhookSource } from "../../webhook-sources/define-webhook-source.js";
+
+export function registerWebhookSourceRoutes(
+  app: OpenAPIHono<AppEnv>,
+  sources: DefinedWebhookSource[],
+) {
+  const sourceMap = new Map(sources.map((s) => [s.meta.id, s]));
+
+  const webhookRoute = createRoute({
+    method: "post",
+    path: "/v1/webhooks/{sourceId}",
+    request: {
+      params: z.object({ sourceId: z.string() }),
+    },
+    responses: {
+      200: {
+        description: "Webhook accepted",
+        content: {
+          "application/json": {
+            schema: z.object({
+              ok: z.boolean(),
+              skipped: z.boolean().optional(),
+              event: z.string().optional(),
+              userId: z.string().optional(),
+              exits: z.number().optional(),
+            }),
+          },
+        },
+      },
+      400: {
+        description: "Invalid payload",
+      },
+      401: {
+        description: "Unauthorized",
+      },
+      404: {
+        description: "Source not found",
+      },
+    },
+  });
+
+  app.openapi(webhookRoute, async (c) => {
+    const { sourceId } = c.req.valid("param");
+    const source = sourceMap.get(sourceId);
+
+    if (!source) {
+      return c.json({ error: "Unknown webhook source" }, 404);
+    }
+
+    const { db, logger, env, registry, hatchet } = c.get("container");
+
+    // Auth is enforced only when the source's secret is configured. An
+    // unconfigured source is treated as open (parity with the pre-engine route).
+    const secret = env[source.auth.envKey as keyof typeof env] as
+      | string
+      | undefined;
+    if (secret) {
+      const provided =
+        c.req.header(source.auth.header) ??
+        c.req.header("authorization")?.replace("Bearer ", "");
+
+      if (provided !== secret) {
+        return c.json({ error: "Invalid webhook secret" }, 401);
+      }
+    }
+
+    let payload: unknown = await c.req.json();
+    if (source.schema) {
+      const parsed = source.schema.safeParse(payload);
+      if (!parsed.success) {
+        return c.json(
+          { error: "Invalid payload", details: parsed.error.flatten() },
+          400,
+        );
+      }
+      payload = parsed.data;
+    }
+
+    const event = await source.transform(payload, { db, logger });
+    if (!event) {
+      logger.info("Webhook event skipped", { source: sourceId });
+      return c.json({ ok: true, skipped: true });
+    }
+
+    const result = await ingestEvent({ db, registry, hatchet, logger, event });
+
+    return c.json({
+      ok: true,
+      event: event.event,
+      userId: event.userId,
+      exits: result.exits,
+    });
+  });
+}

package/src/webhook-sources/define-webhook-source.ts

@@ -0,0 +1,34 @@
+import type { Database } from "@hogsend/db";
+import type { z } from "zod";
+import type { IngestEvent } from "../lib/ingestion.js";
+import type { Logger } from "../lib/logger.js";
+
+export interface WebhookSourceAuth {
+  header: string;
+  envKey: string;
+  type: "match";
+}
+
+export interface WebhookSourceCtx {
+  db: Database;
+  logger: Logger;
+}
+
+export interface WebhookSourceMeta {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+export interface DefinedWebhookSource<T = unknown> {
+  meta: WebhookSourceMeta;
+  auth: WebhookSourceAuth;
+  schema?: z.ZodSchema<T>;
+  transform(payload: T, ctx: WebhookSourceCtx): Promise<IngestEvent | null>;
+}
+
+export function defineWebhookSource<T>(
+  def: DefinedWebhookSource<T>,
+): DefinedWebhookSource<T> {
+  return def;
+}

package/src/worker.ts

@@ -0,0 +1,64 @@
+import type { HogsendClient } from "./container.js";
+import type { DefinedJourney } from "./journeys/define-journey.js";
+import { selectJourneyTasks } from "./journeys/registry.js";
+import { hatchet } from "./lib/hatchet.js";
+import { getPostHog } from "./lib/posthog.js";
+import { getRedisIfConnected } from "./lib/redis.js";
+import { checkAlertsTask } from "./workflows/check-alerts.js";
+import { importContactsTask } from "./workflows/import-contacts.js";
+import { sendEmailTask } from "./workflows/send-email.js";
+
+export interface CreateWorkerOptions {
+  container: HogsendClient;
+  journeys: DefinedJourney[];
+  /** Defaults to `container.env.ENABLED_JOURNEYS`. */
+  enabledJourneys?: string;
+  /** Extra client tasks registered alongside the built-in workflows. */
+  extraWorkflows?: unknown[];
+}
+
+export interface Worker {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+
+export function createWorker(opts: CreateWorkerOptions): Worker {
+  const { container, journeys } = opts;
+  const enabled = opts.enabledJourneys ?? container.env.ENABLED_JOURNEYS;
+  const journeyTasks = selectJourneyTasks(journeys, enabled);
+
+  const baseWorkflows = [
+    sendEmailTask,
+    importContactsTask,
+    checkAlertsTask,
+    ...journeyTasks,
+  ];
+  const workflows = [
+    ...baseWorkflows,
+    ...((opts.extraWorkflows ?? []) as typeof baseWorkflows),
+  ];
+
+  // Hatchet's worker is created lazily on start so signal wiring can own its
+  // lifecycle. `_worker` is captured for stop().
+  let _worker: Awaited<ReturnType<typeof hatchet.worker>> | undefined;
+
+  async function stop(): Promise<void> {
+    await Promise.allSettled([
+      _worker?.stop(),
+      getPostHog()?.shutdown(),
+      getRedisIfConnected()?.quit(),
+    ]);
+  }
+
+  async function start(): Promise<void> {
+    _worker = await hatchet.worker("hogsend-worker", { workflows });
+
+    container.logger.info(
+      `Hogsend worker started with ${journeyTasks.length} journey task(s)`,
+    );
+
+    await _worker.start();
+  }
+
+  return { start, stop };
+}

package/src/workflows/check-alerts.ts

@@ -0,0 +1,24 @@
+import { createDatabase } from "@hogsend/db";
+import { checkAlertRules } from "../lib/alerting.js";
+import { hatchet } from "../lib/hatchet.js";
+import { createLogger } from "../lib/logger.js";
+
+export const checkAlertsTask = hatchet.task({
+  name: "check-alerts",
+  retries: 1,
+  executionTimeout: "60s",
+  fn: async () => {
+    const { db } = createDatabase({
+      url: process.env.DATABASE_URL ?? "",
+    });
+    const logger = createLogger(process.env.LOG_LEVEL ?? "info");
+
+    await checkAlertRules({
+      db,
+      logger,
+      resendApiKey: process.env.RESEND_API_KEY,
+    });
+
+    return { checked: true };
+  },
+});

package/src/workflows/import-contacts.ts

@@ -0,0 +1,134 @@
+import { createDatabase, importJobs } from "@hogsend/db";
+import { eq } from "drizzle-orm";
+import Papa from "papaparse";
+import { upsertContact } from "../lib/contacts.js";
+import { hatchet } from "../lib/hatchet.js";
+
+const BATCH_SIZE = 500;
+
+export const importContactsTask = hatchet.task({
+  name: "import-contacts",
+  retries: 0,
+  executionTimeout: "600s",
+  fn: async (input: { jobId: string; data: string; format: string }) => {
+    const { db } = createDatabase({
+      url: process.env.DATABASE_URL ?? "",
+    });
+
+    await db
+      .update(importJobs)
+      .set({ status: "processing", updatedAt: new Date() })
+      .where(eq(importJobs.id, input.jobId));
+
+    let rows: Array<{
+      externalId: string;
+      email?: string;
+      properties?: Record<string, unknown>;
+    }>;
+
+    try {
+      if (input.format === "json") {
+        rows = JSON.parse(input.data);
+      } else {
+        rows = parseCsv(input.data);
+      }
+    } catch (err) {
+      await db
+        .update(importJobs)
+        .set({
+          status: "failed",
+          errors: [
+            {
+              row: 0,
+              error: `Parse error: ${err instanceof Error ? err.message : String(err)}`,
+            },
+          ],
+          updatedAt: new Date(),
+        })
+        .where(eq(importJobs.id, input.jobId));
+      return { status: "failed" };
+    }
+
+    await db
+      .update(importJobs)
+      .set({ totalRows: rows.length, updatedAt: new Date() })
+      .where(eq(importJobs.id, input.jobId));
+
+    let processed = 0;
+    let failed = 0;
+    const errors: Array<{ row: number; error: string }> = [];
+
+    for (let i = 0; i < rows.length; i += BATCH_SIZE) {
+      const batch = rows.slice(i, i + BATCH_SIZE);
+      const results = await Promise.allSettled(
+        batch.map((row, idx) =>
+          upsertContact({
+            db,
+            externalId: row.externalId,
+            email: row.email,
+            properties: row.properties,
+          }).then(() => ({ index: i + idx, ok: true })),
+        ),
+      );
+
+      results.forEach((result, batchIdx) => {
+        if (result.status === "fulfilled") {
+          processed++;
+        } else {
+          failed++;
+          errors.push({
+            row: i + batchIdx,
+            error: result.reason?.message ?? "Unknown error",
+          });
+        }
+      });
+
+      await db
+        .update(importJobs)
+        .set({
+          processedRows: processed,
+          failedRows: failed,
+          updatedAt: new Date(),
+        })
+        .where(eq(importJobs.id, input.jobId));
+    }
+
+    await db
+      .update(importJobs)
+      .set({
+        status: failed === rows.length ? "failed" : "completed",
+        processedRows: processed,
+        failedRows: failed,
+        errors: errors.length > 0 ? errors.slice(0, 100) : null,
+        updatedAt: new Date(),
+      })
+      .where(eq(importJobs.id, input.jobId));
+
+    return { status: "completed", processed, failed };
+  },
+});
+
+function parseCsv(data: string): Array<{
+  externalId: string;
+  email?: string;
+  properties?: Record<string, unknown>;
+}> {
+  const result = Papa.parse<Record<string, string>>(data, {
+    header: true,
+    skipEmptyLines: true,
+  });
+
+  if (!result.meta.fields?.includes("externalId")) {
+    throw new Error("CSV must have an externalId column");
+  }
+
+  return result.data.map((row) => {
+    const { externalId, email, ...rest } = row;
+    const properties = Object.keys(rest).length > 0 ? rest : undefined;
+    return {
+      externalId: externalId ?? "",
+      email: email || undefined,
+      properties: properties as Record<string, unknown> | undefined,
+    };
+  });
+}