@hogsend/engine 0.0.1

package/src/lib/backfill.ts

@@ -0,0 +1,84 @@
+import type { Database } from "@hogsend/db";
+
+interface BackfillLogger {
+  info: (message: string) => unknown;
+  warn: (message: string) => unknown;
+}
+
+export interface BatchedBackfillOptions {
+  db: Database;
+  logger: BackfillLogger;
+  /** Human label for logs, e.g. `contacts.normalized_email`. */
+  label: string;
+  /**
+   * Run one batch. MUST be idempotent and self-bounding — it should only touch
+   * rows that still need the change (e.g. `WHERE new_col IS NULL ... LIMIT n`)
+   * and return the number of rows affected. Return 0 when nothing is left.
+   */
+  runBatch: (db: Database, batchSize: number) => Promise<number>;
+  /** Rows per batch. Small enough that each statement holds locks briefly. */
+  batchSize?: number;
+  /** Pause between batches (ms) to relieve pressure on a live database. */
+  pauseMs?: number;
+  /** Safety cap on total batches; logs and stops rather than looping forever. */
+  maxBatches?: number;
+}
+
+export interface BatchedBackfillResult {
+  batches: number;
+  rows: number;
+  /** True if the backfill ran to completion (a batch returned 0). */
+  exhausted: boolean;
+}
+
+/**
+ * Run a long data migration in small, idempotent, lock-friendly batches.
+ *
+ * This is the supported home for bulk data changes — they must NOT live inside
+ * a schema migration, which would hold locks and run unbounded against a live
+ * database. Drive it from a Hatchet task so it's resumable and observable; if
+ * the process dies, re-running continues from where it left off because each
+ * batch only selects rows that still need work. See docs/UPGRADING.md.
+ */
+export async function runBatchedBackfill(
+  opts: BatchedBackfillOptions,
+): Promise<BatchedBackfillResult> {
+  const {
+    db,
+    logger,
+    label,
+    runBatch,
+    batchSize = 500,
+    pauseMs = 0,
+    maxBatches = 100_000,
+  } = opts;
+
+  let batches = 0;
+  let rows = 0;
+  logger.info(`[backfill:${label}] starting (batchSize=${batchSize})`);
+
+  while (batches < maxBatches) {
+    const affected = await runBatch(db, batchSize);
+    if (affected === 0) {
+      logger.info(
+        `[backfill:${label}] complete — ${rows} row(s) across ${batches} batch(es)`,
+      );
+      return { batches, rows, exhausted: true };
+    }
+    batches += 1;
+    rows += affected;
+    if (batches % 20 === 0) {
+      logger.info(
+        `[backfill:${label}] progress — ${rows} row(s) across ${batches} batch(es)`,
+      );
+    }
+    if (pauseMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, pauseMs));
+    }
+  }
+
+  logger.warn(
+    `[backfill:${label}] reached maxBatches=${maxBatches} — stopping. Re-run to continue.`,
+  );
+  return { batches, rows, exhausted: false };
+}

package/src/lib/contacts.ts

@@ -0,0 +1,68 @@
+import { contacts, type Database, type emailPreferences } from "@hogsend/db";
+import { and, eq, ilike, isNull, or, sql } from "drizzle-orm";
+
+const UUID_REGEX =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function contactWhereClause(id: string) {
+  return UUID_REGEX.test(id)
+    ? eq(contacts.id, id)
+    : eq(contacts.externalId, id);
+}
+
+export async function resolveContact(opts: { db: Database; id: string }) {
+  const { db, id } = opts;
+  const rows = await db
+    .select()
+    .from(contacts)
+    .where(and(contactWhereClause(id), isNull(contacts.deletedAt)))
+    .limit(1);
+  return rows[0] ?? null;
+}
+
+export function serializePrefs(row: typeof emailPreferences.$inferSelect) {
+  return {
+    id: row.id,
+    userId: row.userId,
+    email: row.email,
+    unsubscribedAll: row.unsubscribedAll,
+    suppressed: row.suppressed,
+    bounceCount: row.bounceCount,
+    categories: (row.categories ?? {}) as Record<string, boolean>,
+    suppressedAt: row.suppressedAt?.toISOString() ?? null,
+    lastBounceAt: row.lastBounceAt?.toISOString() ?? null,
+  };
+}
+
+export function contactSearchFilter(search: string) {
+  return or(
+    ilike(contacts.email, `%${search}%`),
+    ilike(contacts.externalId, `%${search}%`),
+  );
+}
+
+export async function upsertContact(opts: {
+  db: Database;
+  externalId: string;
+  email?: string;
+  properties?: Record<string, unknown>;
+}): Promise<void> {
+  const { db, externalId, email, properties } = opts;
+
+  await db
+    .insert(contacts)
+    .values({
+      externalId,
+      email: email || null,
+      properties: properties ?? {},
+    })
+    .onConflictDoUpdate({
+      target: contacts.externalId,
+      set: {
+        ...(email ? { email } : {}),
+        properties: sql`COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(properties ?? {})}::jsonb`,
+        lastSeenAt: new Date(),
+        updatedAt: new Date(),
+      },
+    });
+}

package/src/lib/db.ts

@@ -0,0 +1,13 @@
+import { createDatabase, type Database } from "@hogsend/db";
+
+let _db: Database | undefined;
+
+export function getDb(): Database {
+  if (!_db) {
+    const url = process.env.DATABASE_URL;
+    if (!url) throw new Error("DATABASE_URL is required");
+    const { db } = createDatabase({ url });
+    _db = db;
+  }
+  return _db;
+}

package/src/lib/email-service-types.ts

@@ -0,0 +1,115 @@
+import type {
+  EmailServiceRenderOptions,
+  EmailServiceRenderResult,
+  RetryOptions,
+  TemplateName,
+  TemplateRegistry,
+  TemplateRegistryMap,
+} from "@hogsend/email";
+import type {
+  BatchEmailItem,
+  SendEmailOptions,
+  SendResult,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "@hogsend/plugin-resend";
+
+export type {
+  BatchEmailItem,
+  SendEmailOptions,
+  SendResult,
+} from "@hogsend/plugin-resend";
+
+// ---------------------------------------------------------------------------
+// Tracked email (high-level API)
+// ---------------------------------------------------------------------------
+
+export interface SendTrackedEmailOptions<
+  K extends TemplateName = TemplateName,
+> {
+  templateKey: K;
+  props: TemplateRegistryMap[K];
+  from: string;
+  to: string;
+  subject?: string;
+  journeyStateId?: string;
+  category?: string;
+  tags?: Array<{ name: string; value: string }>;
+  headers?: Record<string, string>;
+  replyTo?: string | string[];
+  skipPreferenceCheck?: boolean;
+  baseUrl?: string;
+}
+
+export interface TrackedSendResult {
+  emailSendId: string;
+  resendId: string;
+  status: "sent" | "suppressed" | "unsubscribed";
+}
+
+// ---------------------------------------------------------------------------
+// Email service (high-level DX) — engine-owned tracked mailer
+// ---------------------------------------------------------------------------
+
+export interface EmailServiceConfig {
+  defaultFrom: string;
+  /**
+   * The client app's template registry (key → component + subject + category).
+   * Threaded into `getTemplate(..., { registry })` at send + render time so the
+   * engine never bakes in concrete business templates. Required to send/render
+   * any template; an empty registry simply has no sendable keys.
+   */
+  templates: TemplateRegistry;
+  db?: unknown;
+  webhookSecret?: string;
+  webhookHandlers?: WebhookHandlerMap;
+  retryOptions?: RetryOptions;
+  bounceThreshold?: number;
+  baseUrl?: string;
+}
+
+export interface EmailServiceSendOptions<
+  K extends TemplateName = TemplateName,
+> {
+  template: K;
+  props: TemplateRegistryMap[K];
+  to: string;
+  from?: string;
+  subject?: string;
+  journeyStateId?: string;
+  category?: string;
+  tags?: Array<{ name: string; value: string }>;
+  headers?: Record<string, string>;
+  replyTo?: string | string[];
+  skipPreferenceCheck?: boolean;
+}
+
+export interface EmailServiceWebhookOptions {
+  payload: string;
+  headers: Record<string, string>;
+}
+
+export interface EmailServiceWebhookResult {
+  type: WebhookEventType;
+  handled: boolean;
+}
+
+export interface EmailService {
+  send<K extends TemplateName>(
+    options: EmailServiceSendOptions<K>,
+  ): Promise<TrackedSendResult>;
+
+  sendRaw(options: SendEmailOptions): Promise<SendResult>;
+
+  sendBatch(options: { emails: BatchEmailItem[] }): Promise<{
+    results: SendResult[];
+  }>;
+
+  render<K extends TemplateName>(
+    options: EmailServiceRenderOptions<K>,
+  ): Promise<EmailServiceRenderResult>;
+
+  handleWebhook(
+    options: EmailServiceWebhookOptions,
+  ): Promise<EmailServiceWebhookResult>;
+}

package/src/lib/email-stats.ts

@@ -0,0 +1,33 @@
+import { type Database, emailSends } from "@hogsend/db";
+import { count, gte, sql } from "drizzle-orm";
+
+export interface EmailStatsResult {
+  total: number;
+  delivered: number;
+  bounced: number;
+  complained: number;
+}
+
+export async function getEmailStats(opts: {
+  db: Database;
+  since: Date;
+}): Promise<EmailStatsResult> {
+  const { db, since } = opts;
+  const rows = await db
+    .select({
+      total: count(),
+      delivered: sql<number>`count(*) filter (where ${emailSends.status} = 'delivered')`,
+      bounced: sql<number>`count(*) filter (where ${emailSends.status} = 'bounced')`,
+      complained: sql<number>`count(*) filter (where ${emailSends.status} = 'complained')`,
+    })
+    .from(emailSends)
+    .where(gte(emailSends.createdAt, since));
+
+  const row = rows[0];
+  return {
+    total: row?.total ?? 0,
+    delivered: Number(row?.delivered ?? 0),
+    bounced: Number(row?.bounced ?? 0),
+    complained: Number(row?.complained ?? 0),
+  };
+}

package/src/lib/email.ts

@@ -0,0 +1,94 @@
+import { generateUnsubscribeUrl } from "@hogsend/email";
+import type {
+  EmailService,
+  EmailServiceSendOptions,
+} from "./email-service-types.js";
+
+let _service: EmailService | null = null;
+
+export function setEmailService(service: EmailService): void {
+  _service = service;
+}
+
+function getService(): EmailService {
+  if (!_service) {
+    throw new Error(
+      "Email service not initialized. Call setEmailService() at startup.",
+    );
+  }
+  return _service;
+}
+
+export interface SendEmailOptions {
+  to: string;
+  userId: string;
+  template: string;
+  subject: string;
+  journeyName?: string;
+  journeyStateId?: string;
+  props?: Record<string, unknown>;
+}
+
+export interface SendEmailResult {
+  emailSendId: string;
+  sentAt: string;
+}
+
+export async function sendEmail(
+  opts: SendEmailOptions,
+): Promise<SendEmailResult> {
+  const service = getService();
+
+  let unsubscribeUrl: string | undefined;
+  if (process.env.API_PUBLIC_URL && process.env.BETTER_AUTH_SECRET) {
+    unsubscribeUrl = generateUnsubscribeUrl({
+      baseUrl: process.env.API_PUBLIC_URL,
+      secret: process.env.BETTER_AUTH_SECRET,
+      externalId: opts.userId,
+      email: opts.to,
+    });
+  }
+
+  const headers: Record<string, string> = {};
+  if (unsubscribeUrl) {
+    headers["List-Unsubscribe"] = `<${unsubscribeUrl}>`;
+    headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+  }
+
+  // `sendEmail` is the loose, runtime-string entry point used by journeys: the
+  // template key and props are resolved at runtime, so we build the options
+  // untyped and hand them to the typed `service.send`. Type-safe call sites use
+  // `container.emailService.send({ template, props })` directly.
+  const sendOptions = {
+    template: opts.template,
+    props: {
+      ...opts.props,
+      name:
+        (opts.props?.firstName as string) ??
+        (opts.props?.name as string) ??
+        opts.to.split("@")[0] ??
+        "there",
+      journeyName: opts.journeyName ?? opts.template,
+      eventName: opts.template,
+      body: opts.subject,
+      unsubscribeUrl,
+    },
+    to: opts.to,
+    subject: opts.subject,
+    journeyStateId: opts.journeyStateId,
+    category: "journey",
+    tags: [
+      { name: "journeyId", value: opts.journeyName ?? opts.template },
+      { name: "templateKey", value: opts.template },
+      { name: "userId", value: opts.userId },
+    ],
+    headers,
+  } as unknown as EmailServiceSendOptions;
+
+  const result = await service.send(sendOptions);
+
+  return {
+    emailSendId: result.emailSendId,
+    sentAt: new Date().toISOString(),
+  };
+}

package/src/lib/enrollment-guards.ts

@@ -0,0 +1,56 @@
+import { durationToMs, hours } from "@hogsend/core";
+import type { JourneyMeta } from "@hogsend/core/types";
+import { type Database, emailPreferences, journeyStates } from "@hogsend/db";
+import { and, eq } from "drizzle-orm";
+
+export async function checkEntryLimit(opts: {
+  db: Database;
+  journey: JourneyMeta;
+  userId: string;
+}): Promise<{ allowed: boolean; reason?: string }> {
+  const { db, journey, userId } = opts;
+  if (journey.entryLimit === "unlimited") return { allowed: true };
+
+  if (journey.entryLimit === "once") {
+    const existing = await db.query.journeyStates.findFirst({
+      where: and(
+        eq(journeyStates.userId, userId),
+        eq(journeyStates.journeyId, journey.id),
+      ),
+    });
+    return existing
+      ? { allowed: false, reason: "already_entered_once" }
+      : { allowed: true };
+  }
+
+  if (journey.entryLimit === "once_per_period") {
+    const periodMs = durationToMs(journey.entryPeriod ?? hours(24));
+    const cutoff = new Date(Date.now() - periodMs);
+
+    const existing = await db.query.journeyStates.findFirst({
+      where: and(
+        eq(journeyStates.userId, userId),
+        eq(journeyStates.journeyId, journey.id),
+      ),
+      orderBy: (states, { desc }) => [desc(states.createdAt)],
+    });
+
+    return existing && existing.createdAt > cutoff
+      ? { allowed: false, reason: "period_not_elapsed" }
+      : { allowed: true };
+  }
+
+  return { allowed: true };
+}
+
+export async function checkEmailPreferences(opts: {
+  db: Database;
+  userId: string;
+}): Promise<{ unsubscribed: boolean }> {
+  const { db, userId } = opts;
+  const prefs = await db.query.emailPreferences.findFirst({
+    where: eq(emailPreferences.userId, userId),
+  });
+
+  return { unsubscribed: prefs?.unsubscribedAll ?? false };
+}

package/src/lib/hatchet.ts

@@ -0,0 +1,20 @@
+import { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import { env } from "../env.js";
+
+// Construct the Hatchet client from our validated env contract so host/port and
+// TLS strategy are honoured from a single source of truth, rather than relying on
+// the SDK's independent process.env read. The SDK would read the same vars on its
+// own, but passing them explicitly keeps env.ts authoritative and makes the
+// connection config debuggable.
+//
+// `tls_config.tls_strategy` defaults to `tls` (secure); the local insecure
+// hatchet-lite path sets HATCHET_CLIENT_TLS_STRATEGY=none. `namespace` is the
+// future per-tenant knob (default-empty today).
+export const hatchet = HatchetClient.init({
+  token: env.HATCHET_CLIENT_TOKEN,
+  host_port: env.HATCHET_CLIENT_HOST_PORT,
+  tls_config: { tls_strategy: env.HATCHET_CLIENT_TLS_STRATEGY },
+  ...(env.HATCHET_CLIENT_NAMESPACE
+    ? { namespace: env.HATCHET_CLIENT_NAMESPACE }
+    : {}),
+});

package/src/lib/html.ts

@@ -0,0 +1,25 @@
+export function htmlPage(opts: { title: string; body: string }): string {
+  const { title, body } = opts;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${title}</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; max-width: 480px; margin: 80px auto; padding: 0 20px; color: #1a1a1a; }
+    h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
+    p { color: #555; line-height: 1.6; }
+    a { color: #2563eb; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+    .pref-row { display: flex; justify-content: space-between; align-items: center; padding: 12px 0; border-bottom: 1px solid #e5e7eb; }
+    .pref-label { font-weight: 500; }
+    .pref-status { font-size: 0.875rem; }
+    .subscribed { color: #16a34a; }
+    .unsubscribed { color: #dc2626; }
+    .global-row { margin-top: 24px; padding-top: 16px; border-top: 2px solid #e5e7eb; }
+  </style>
+</head>
+<body>${body}</body>
+</html>`;
+}

package/src/lib/ingestion.ts

@@ -0,0 +1,162 @@
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import { evaluatePropertyConditions } from "@hogsend/core";
+import type { JourneyRegistry } from "@hogsend/core/registry";
+import { type Database, journeyStates, userEvents } from "@hogsend/db";
+import { and, eq, inArray, isNull } from "drizzle-orm";
+import { upsertContact } from "./contacts.js";
+import type { Logger } from "./logger.js";
+
+export interface IngestEvent {
+  event: string;
+  userId: string;
+  userEmail: string;
+  properties: Record<string, unknown>;
+  idempotencyKey?: string;
+}
+
+export interface ExitResult {
+  journeyId: string;
+  stateId: string;
+  exited: boolean;
+}
+
+export interface IngestResult {
+  stored: boolean;
+  exits: ExitResult[];
+}
+
+export async function ingestEvent(opts: {
+  db: Database;
+  registry: JourneyRegistry;
+  hatchet: HatchetClient;
+  logger: Logger;
+  event: IngestEvent;
+}): Promise<IngestResult> {
+  const { db, registry, hatchet, logger, event } = opts;
+
+  if (event.idempotencyKey) {
+    const result = await db
+      .insert(userEvents)
+      .values({
+        userId: event.userId,
+        event: event.event,
+        properties: event.properties,
+        idempotencyKey: event.idempotencyKey,
+      })
+      .onConflictDoNothing({
+        target: userEvents.idempotencyKey,
+      })
+      .returning({ id: userEvents.id });
+
+    if (result.length === 0) {
+      return { stored: false, exits: [] };
+    }
+  } else {
+    await db.insert(userEvents).values({
+      userId: event.userId,
+      event: event.event,
+      properties: event.properties,
+    });
+  }
+
+  const serializableProperties = Object.fromEntries(
+    Object.entries(event.properties).filter(
+      ([, v]) =>
+        typeof v === "string" ||
+        typeof v === "number" ||
+        typeof v === "boolean" ||
+        v === null,
+    ),
+  ) as Record<string, string | number | boolean | null>;
+
+  const [, exits] = await Promise.all([
+    hatchet.events.push(event.event, {
+      userId: event.userId,
+      userEmail: event.userEmail,
+      properties: serializableProperties,
+    }),
+    checkExits(db, registry, {
+      userId: event.userId,
+      eventName: event.event,
+      properties: event.properties,
+    }),
+    upsertContact({
+      db,
+      externalId: event.userId,
+      email: event.userEmail || undefined,
+      properties: event.properties,
+    }).catch((err) => {
+      logger.warn("Contact upsert failed", {
+        userId: event.userId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }),
+  ]);
+
+  logger.info("Event ingested", {
+    event: event.event,
+    userId: event.userId,
+    exits: exits.filter((e) => e.exited).length,
+  });
+
+  return { stored: true, exits };
+}
+
+async function checkExits(
+  db: Database,
+  registry: JourneyRegistry,
+  event: {
+    userId: string;
+    eventName: string;
+    properties: Record<string, unknown>;
+  },
+): Promise<ExitResult[]> {
+  const results: ExitResult[] = [];
+
+  const activeStates = await db.query.journeyStates.findMany({
+    where: and(
+      eq(journeyStates.userId, event.userId),
+      inArray(journeyStates.status, ["active", "waiting"]),
+      isNull(journeyStates.deletedAt),
+    ),
+  });
+
+  const statesToExit: string[] = [];
+
+  for (const state of activeStates) {
+    const journey = registry.get(state.journeyId);
+    if (!journey?.exitOn) continue;
+
+    const shouldExit = journey.exitOn.some((exitCondition) => {
+      if (exitCondition.event !== event.eventName) return false;
+      if (!exitCondition.where?.length) return true;
+      return evaluatePropertyConditions({
+        conditions: exitCondition.where,
+        properties: event.properties,
+      });
+    });
+
+    if (shouldExit) {
+      statesToExit.push(state.id);
+    }
+
+    results.push({
+      journeyId: state.journeyId,
+      stateId: state.id,
+      exited: shouldExit,
+    });
+  }
+
+  if (statesToExit.length > 0) {
+    await db
+      .update(journeyStates)
+      .set({
+        status: "exited",
+        exitedAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(inArray(journeyStates.id, statesToExit));
+  }
+
+  return results;
+}