@hogsend/engine 0.0.1

package/src/lib/logger.ts

@@ -0,0 +1,32 @@
+import winston from "winston";
+
+// Log to stdout only (12-factor): the platform — Railway, Docker, a VPS's
+// systemd/journald — captures the stream. Writing log FILES from inside the app
+// breaks in a non-root container (mkdir EACCES on a root-owned /app) and is
+// pointless on ephemeral container filesystems. If durable file logs are ever
+// needed, add a File transport behind an explicit, writable LOG_DIR opt-in.
+export function createLogger(level: string = "info") {
+  return winston.createLogger({
+    level,
+    format: winston.format.combine(
+      winston.format.timestamp(),
+      winston.format.errors({ stack: true }),
+    ),
+    defaultMeta: { service: "growthhog-api" },
+    transports: [
+      new winston.transports.Console({
+        format: winston.format.combine(
+          winston.format.colorize(),
+          winston.format.printf(({ level, message, timestamp, ...meta }) => {
+            const metaStr = Object.keys(meta).length
+              ? ` ${JSON.stringify(meta)}`
+              : "";
+            return `${timestamp} ${level}: ${message}${metaStr}`;
+          }),
+        ),
+      }),
+    ],
+  });
+}
+
+export type Logger = winston.Logger;

package/src/lib/mailer.ts

@@ -0,0 +1,266 @@
+import type { Database } from "@hogsend/db";
+import { emailPreferences, emailSends } from "@hogsend/db";
+import type {
+  EmailServiceRenderOptions,
+  EmailServiceRenderResult,
+  TemplateName,
+} from "@hogsend/email";
+import { getTemplate, renderToHtml, renderToPlainText } from "@hogsend/email";
+import type {
+  BatchEmailItem,
+  EmailProvider,
+  WebhookEvent,
+  WebhookEventType,
+  WebhookHandlerMap,
+} from "@hogsend/plugin-resend";
+import { eq, sql } from "drizzle-orm";
+import type {
+  EmailService,
+  EmailServiceConfig,
+  EmailServiceSendOptions,
+  EmailServiceWebhookOptions,
+  EmailServiceWebhookResult,
+  SendEmailOptions,
+  SendResult,
+  TrackedSendResult,
+} from "./email-service-types.js";
+import type { PrepareTrackedHtmlFn } from "./tracked.js";
+import { sendTrackedEmail } from "./tracked.js";
+
+const WEBHOOK_TO_STATUS_FIELD: Partial<
+  Record<WebhookEventType, keyof typeof emailSends.$inferSelect>
+> = {
+  "email.sent": "sentAt",
+  "email.delivered": "deliveredAt",
+  "email.opened": "openedAt",
+  "email.clicked": "clickedAt",
+  "email.bounced": "bouncedAt",
+  "email.complained": "complainedAt",
+};
+
+const WEBHOOK_TO_STATUS: Partial<Record<WebhookEventType, string>> = {
+  "email.sent": "sent",
+  "email.delivered": "delivered",
+  "email.opened": "opened",
+  "email.clicked": "clicked",
+  "email.bounced": "bounced",
+  "email.complained": "complained",
+};
+
+/**
+ * The engine-owned high-level mailer. It owns the full send pipeline —
+ * render → preference/suppression check → tracked-html rewrite → `email_sends`
+ * insert → `provider.send(...)` → status record — and delegates only the raw
+ * provider delivery + webhook parse/verify to the injected {@link EmailProvider}.
+ */
+export function createTrackedMailer(
+  config: EmailServiceConfig,
+  deps: {
+    provider: EmailProvider;
+    prepareTrackedHtml?: PrepareTrackedHtmlFn;
+  },
+): EmailService {
+  const { provider } = deps;
+  const db = config.db as Database | undefined;
+  const retryDefaults = config.retryOptions;
+  const registry = config.templates;
+
+  function resolveFrom(overrideFrom?: string): string {
+    return overrideFrom ?? config.defaultFrom;
+  }
+
+  const service: EmailService = {
+    async send<K extends TemplateName>(
+      options: EmailServiceSendOptions<K>,
+    ): Promise<TrackedSendResult> {
+      const from = resolveFrom(options.from);
+
+      if (db) {
+        return sendTrackedEmail({
+          db,
+          provider,
+          registry,
+          retryOptions: retryDefaults,
+          prepareTrackedHtml: deps.prepareTrackedHtml,
+          options: {
+            templateKey: options.template,
+            props: options.props,
+            from,
+            to: options.to,
+            subject: options.subject,
+            journeyStateId: options.journeyStateId,
+            category: options.category,
+            tags: options.tags,
+            headers: options.headers,
+            replyTo: options.replyTo,
+            skipPreferenceCheck: options.skipPreferenceCheck,
+            baseUrl: config.baseUrl,
+          },
+        });
+      }
+
+      const { element, subject: defaultSubject } = getTemplate({
+        key: options.template,
+        props: options.props,
+        registry,
+      });
+      const result = await provider.send({
+        from,
+        to: options.to,
+        subject: options.subject ?? defaultSubject,
+        react: element,
+        tags: options.tags,
+        headers: options.headers,
+        replyTo: options.replyTo,
+      });
+
+      return {
+        emailSendId: "",
+        resendId: result.id,
+        status: "sent",
+      };
+    },
+
+    async sendRaw(options: SendEmailOptions): Promise<SendResult> {
+      return provider.send({ ...options, from: resolveFrom(options.from) });
+    },
+
+    async sendBatch(options: {
+      emails: BatchEmailItem[];
+    }): Promise<{ results: SendResult[] }> {
+      const emails = options.emails.map((e) => ({
+        ...e,
+        from: resolveFrom(e.from),
+      }));
+      return provider.sendBatch(emails);
+    },
+
+    async render<K extends TemplateName>(
+      options: EmailServiceRenderOptions<K>,
+    ): Promise<EmailServiceRenderResult> {
+      const { element, subject, category } = getTemplate({
+        key: options.template,
+        props: options.props,
+        registry,
+      });
+
+      const [html, text] = await Promise.all([
+        renderToHtml(element),
+        renderToPlainText(element),
+      ]);
+
+      return { html, text, subject, category };
+    },
+
+    async handleWebhook(
+      options: EmailServiceWebhookOptions,
+    ): Promise<EmailServiceWebhookResult> {
+      if (!config.webhookSecret) {
+        throw new Error(
+          "webhookSecret is required in EmailServiceConfig to handle webhooks",
+        );
+      }
+
+      const userHandlers: WebhookHandlerMap = config.webhookHandlers ?? {};
+
+      const event = provider.verifyWebhook({
+        payload: options.payload,
+        headers: options.headers,
+      });
+
+      const handled = await dispatchWebhook(event, userHandlers);
+
+      return { type: event.type, handled };
+    },
+  };
+
+  const bounceThreshold = config.bounceThreshold ?? 3;
+
+  async function dispatchWebhook(
+    event: WebhookEvent,
+    userHandlers: WebhookHandlerMap,
+  ): Promise<boolean> {
+    switch (event.type) {
+      case "email.sent":
+      case "email.delivered":
+      case "email.opened":
+      case "email.clicked":
+        await updateEmailStatus(event.type, event.data.email_id);
+        break;
+      case "email.bounced":
+        await updateEmailStatus(event.type, event.data.email_id);
+        await handleBounce(event.data.to);
+        break;
+      case "email.complained":
+        await updateEmailStatus(event.type, event.data.email_id);
+        await handleComplaint(event.data.to);
+        break;
+      case "email.delivery_delayed":
+        break;
+    }
+
+    const userHandler = userHandlers[event.type] as
+      | ((e: WebhookEvent) => void | Promise<void>)
+      | undefined;
+    if (userHandler) {
+      await userHandler(event);
+      return true;
+    }
+
+    return false;
+  }
+
+  async function handleBounce(toAddresses: string[]): Promise<void> {
+    if (!db) return;
+    const email = toAddresses[0];
+    if (!email) return;
+
+    await db
+      .update(emailPreferences)
+      .set({
+        bounceCount: sql`${emailPreferences.bounceCount} + 1`,
+        lastBounceAt: new Date(),
+        suppressed: sql`CASE WHEN ${emailPreferences.bounceCount} + 1 >= ${bounceThreshold} THEN true ELSE ${emailPreferences.suppressed} END`,
+        suppressedAt: sql`CASE WHEN ${emailPreferences.bounceCount} + 1 >= ${bounceThreshold} THEN NOW() ELSE ${emailPreferences.suppressedAt} END`,
+        updatedAt: new Date(),
+      })
+      .where(eq(emailPreferences.email, email));
+  }
+
+  async function handleComplaint(toAddresses: string[]): Promise<void> {
+    if (!db) return;
+    const email = toAddresses[0];
+    if (!email) return;
+
+    await db
+      .update(emailPreferences)
+      .set({
+        suppressed: true,
+        suppressedAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(eq(emailPreferences.email, email));
+  }
+
+  async function updateEmailStatus(
+    eventType: WebhookEventType,
+    resendId: string,
+  ): Promise<void> {
+    if (!db) return;
+
+    const timestampField = WEBHOOK_TO_STATUS_FIELD[eventType];
+    const status = WEBHOOK_TO_STATUS[eventType];
+    if (!timestampField || !status) return;
+
+    await db
+      .update(emailSends)
+      .set({
+        status: status as typeof emailSends.$inferSelect.status,
+        [timestampField]: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(eq(emailSends.resendId, resendId));
+  }
+
+  return service;
+}

package/src/lib/notifications.ts

@@ -0,0 +1,61 @@
+export async function sendWebhook(
+  url: string,
+  payload: Record<string, unknown>,
+): Promise<{ ok: boolean; error?: string }> {
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: `HTTP ${res.status}: ${res.statusText}`,
+      };
+    }
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function sendSlackNotification(
+  webhookUrl: string,
+  text: string,
+): Promise<{ ok: boolean; error?: string }> {
+  return sendWebhook(webhookUrl, { text });
+}
+
+import { createResendClient } from "@hogsend/plugin-resend";
+
+export async function sendEmailNotification(opts: {
+  to: string;
+  subject: string;
+  body: string;
+  resendApiKey: string;
+}): Promise<{ ok: boolean; error?: string }> {
+  try {
+    const client = createResendClient({ apiKey: opts.resendApiKey });
+    const { error } = await client.emails.send({
+      from: "Hogsend Alerts <alerts@hogsend.com>",
+      to: opts.to,
+      subject: opts.subject,
+      html: opts.body,
+    });
+    if (error) {
+      return { ok: false, error: error.message };
+    }
+    return { ok: true };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

package/src/lib/posthog.ts

@@ -0,0 +1,19 @@
+import {
+  createPostHogService,
+  type PostHogService,
+} from "@hogsend/plugin-posthog";
+import { getRedis } from "./redis.js";
+
+let _posthog: PostHogService | undefined;
+
+export function getPostHog(): PostHogService | undefined {
+  if (!process.env.POSTHOG_API_KEY) return undefined;
+  if (!_posthog) {
+    _posthog = createPostHogService({
+      apiKey: process.env.POSTHOG_API_KEY,
+      host: process.env.POSTHOG_HOST,
+      redis: getRedis(),
+    });
+  }
+  return _posthog;
+}

package/src/lib/redis.ts

@@ -0,0 +1,30 @@
+import { Redis } from "ioredis";
+
+let _redis: Redis | undefined;
+
+export function getRedis(): Redis {
+  if (!_redis) {
+    _redis = new Redis(process.env.REDIS_URL ?? "redis://localhost:6379", {
+      // Railway private networking (*.railway.internal) is IPv6-only; without
+      // family: 0, ioredis only tries IPv4 and silently fails to connect —
+      // which is why Postgres (postgres.js does dual-stack) worked but Redis
+      // didn't. family: 0 lets DNS resolve both A and AAAA. Harmless locally.
+      family: 0,
+      // Connect on first command (e.g. the /v1/health probe), not at import.
+      lazyConnect: true,
+      connectTimeout: 5000,
+      maxRetriesPerRequest: 3,
+      // Retry a transient blip a few times, then give up cleanly. Without a cap,
+      // an environment with no redis (tests, self-host without redis) keeps a
+      // socket retrying forever — which hangs vitest and leaks handles. In prod
+      // redis is reachable, so it connects on the first try and never gives up.
+      retryStrategy: (times) =>
+        times > 5 ? null : Math.min(times * 300, 1500),
+    });
+  }
+  return _redis;
+}
+
+export function getRedisIfConnected(): Redis | undefined {
+  return _redis;
+}

package/src/lib/schemas.ts

@@ -0,0 +1,8 @@
+import { z } from "@hono/zod-openapi";
+
+export const errorSchema = z.object({ error: z.string() });
+
+export const paginationQuerySchema = z.object({
+  limit: z.coerce.number().min(1).max(100).default(50),
+  offset: z.coerce.number().min(0).default(0),
+});

package/src/lib/tracked.ts

@@ -0,0 +1,175 @@
+import type { Database } from "@hogsend/db";
+import { emailPreferences, emailSends } from "@hogsend/db";
+import type {
+  EmailSuppressionError,
+  RetryOptions,
+  TemplateName,
+  TemplateRegistry,
+} from "@hogsend/email";
+import { getTemplate, renderToHtml } from "@hogsend/email";
+import type { EmailProvider } from "@hogsend/plugin-resend";
+import { eq } from "drizzle-orm";
+import type {
+  SendTrackedEmailOptions,
+  TrackedSendResult,
+} from "./email-service-types.js";
+
+export type PrepareTrackedHtmlFn = (opts: {
+  html: string;
+  emailSendId: string;
+  baseUrl: string;
+  db: Database;
+}) => Promise<string>;
+
+interface TrackedEmailDeps {
+  db: Database;
+  provider: EmailProvider;
+  /** The client app's template registry, threaded into {@link getTemplate}. */
+  registry: TemplateRegistry;
+  retryOptions?: RetryOptions;
+  prepareTrackedHtml?: PrepareTrackedHtmlFn;
+}
+
+export async function sendTrackedEmail<K extends TemplateName>(
+  opts: TrackedEmailDeps & { options: SendTrackedEmailOptions<K> },
+): Promise<TrackedSendResult> {
+  const { db, provider, registry, prepareTrackedHtml, options } = opts;
+
+  if (!options.skipPreferenceCheck) {
+    const suppression = await checkSuppression(
+      db,
+      options.to,
+      options.category,
+    );
+    if (suppression) {
+      const rows = await db
+        .insert(emailSends)
+        .values({
+          templateKey: options.templateKey,
+          fromEmail: options.from,
+          toEmail: options.to,
+          subject: options.subject ?? "",
+          category: options.category,
+          journeyStateId: options.journeyStateId,
+          status: "failed",
+        })
+        .returning({ id: emailSends.id });
+
+      const suppressedRow = rows[0];
+      if (!suppressedRow) throw new Error("Failed to insert email_sends row");
+
+      return {
+        emailSendId: suppressedRow.id,
+        resendId: "",
+        status:
+          suppression === "unsubscribed" ||
+          suppression === "category_unsubscribed"
+            ? "unsubscribed"
+            : "suppressed",
+      };
+    }
+  }
+
+  const {
+    element,
+    subject: defaultSubject,
+    category,
+  } = getTemplate({ key: options.templateKey, props: options.props, registry });
+
+  const subject = options.subject ?? defaultSubject;
+
+  const insertRows = await db
+    .insert(emailSends)
+    .values({
+      templateKey: options.templateKey,
+      fromEmail: options.from,
+      toEmail: options.to,
+      subject,
+      category: options.category ?? category,
+      journeyStateId: options.journeyStateId,
+      status: "queued",
+    })
+    .returning({ id: emailSends.id });
+
+  const insertedRow = insertRows[0];
+  if (!insertedRow) throw new Error("Failed to insert email_sends row");
+  const emailSendId = insertedRow.id;
+
+  try {
+    let html: string | undefined;
+    if (options.baseUrl && prepareTrackedHtml) {
+      const rawHtml = await renderToHtml(element);
+      html = await prepareTrackedHtml({
+        html: rawHtml,
+        emailSendId,
+        baseUrl: options.baseUrl,
+        db,
+      });
+    }
+
+    const result = await provider.send({
+      from: options.from,
+      to: options.to,
+      subject,
+      ...(html ? { html } : { react: element }),
+      tags: options.tags,
+      headers: options.headers,
+      replyTo: options.replyTo,
+    });
+
+    await db
+      .update(emailSends)
+      .set({
+        resendId: result.id,
+        status: "sent",
+        sentAt: new Date(),
+        updatedAt: new Date(),
+      })
+      .where(eq(emailSends.id, emailSendId));
+
+    return {
+      emailSendId,
+      resendId: result.id,
+      status: "sent",
+    };
+  } catch (error) {
+    await db
+      .update(emailSends)
+      .set({
+        status: "failed",
+        updatedAt: new Date(),
+      })
+      .where(eq(emailSends.id, emailSendId));
+
+    throw error;
+  }
+}
+
+type SuppressionReason = EmailSuppressionError["reason"] | null;
+
+async function checkSuppression(
+  db: Database,
+  email: string,
+  category?: string,
+): Promise<SuppressionReason> {
+  const rows = await db
+    .select()
+    .from(emailPreferences)
+    .where(eq(emailPreferences.email, email))
+    .limit(1);
+
+  if (rows.length === 0) return null;
+
+  const prefs = rows[0];
+  if (!prefs) return null;
+
+  if (prefs.suppressed) return "suppressed";
+  if (prefs.unsubscribedAll) return "unsubscribed";
+
+  if (category && prefs.categories) {
+    const categories = prefs.categories as Record<string, boolean>;
+    if (categories[category] === false) return "category_unsubscribed";
+  }
+
+  return null;
+}

package/src/lib/tracking-event-names.ts

@@ -0,0 +1,5 @@
+// First-party tracking event names emitted by the engine's own tracking
+// endpoints (link click + open pixel). These belong to the engine — they are
+// not journey content — so they live here rather than in app-side constants.
+export const EMAIL_OPENED = "email.opened" as const;
+export const EMAIL_LINK_CLICKED = "email.link_clicked" as const;

package/src/lib/tracking-events.ts

@@ -0,0 +1,84 @@
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { JourneyRegistry } from "@hogsend/core/registry";
+import { type Database, emailSends, journeyStates } from "@hogsend/db";
+import type { PostHogService } from "@hogsend/plugin-posthog";
+import { eq } from "drizzle-orm";
+import { ingestEvent } from "./ingestion.js";
+import type { Logger } from "./logger.js";
+
+interface EmailSendContext {
+  userId: string;
+  userEmail: string;
+  templateKey: string | null;
+}
+
+export async function resolveEmailSendContext(
+  db: Database,
+  emailSendId: string,
+): Promise<EmailSendContext | null> {
+  const rows = await db
+    .select({
+      toEmail: emailSends.toEmail,
+      templateKey: emailSends.templateKey,
+      userId: journeyStates.userId,
+      userEmail: journeyStates.userEmail,
+    })
+    .from(emailSends)
+    .leftJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
+    .where(eq(emailSends.id, emailSendId))
+    .limit(1);
+
+  const row = rows[0];
+  if (!row) return null;
+
+  return {
+    userId: row.userId ?? row.toEmail,
+    userEmail: row.userEmail ?? row.toEmail,
+    templateKey: row.templateKey,
+  };
+}
+
+export interface PushTrackingEventOpts {
+  db: Database;
+  hatchet: HatchetClient;
+  registry: JourneyRegistry;
+  logger: Logger;
+  posthog?: PostHogService;
+  event: string;
+  emailSendId: string;
+  properties?: Record<string, unknown>;
+}
+
+export async function pushTrackingEvent(
+  opts: PushTrackingEventOpts,
+): Promise<void> {
+  const { db, hatchet, registry, logger, posthog, event, emailSendId } = opts;
+
+  const ctx = await resolveEmailSendContext(db, emailSendId);
+  if (!ctx) return;
+
+  const properties: Record<string, unknown> = {
+    emailSendId,
+    templateKey: ctx.templateKey,
+    ...opts.properties,
+  };
+
+  posthog?.captureEvent({
+    distinctId: ctx.userId,
+    event,
+    properties,
+  });
+
+  await ingestEvent({
+    db,
+    registry,
+    hatchet,
+    logger,
+    event: {
+      event,
+      userId: ctx.userId,
+      userEmail: ctx.userEmail,
+      properties,
+    },
+  });
+}