@hogsend/engine 0.0.1

package/src/journeys/define-journey.ts

@@ -0,0 +1,188 @@
+import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
+import { evaluatePropertyConditions } from "@hogsend/core";
+import type {
+  JourneyMeta,
+  JourneyRunFn,
+  JourneyUser,
+} from "@hogsend/core/types";
+import { journeyConfigs, journeyStates } from "@hogsend/db";
+import { and, eq, inArray } from "drizzle-orm";
+import { getDb } from "../lib/db.js";
+import {
+  checkEmailPreferences,
+  checkEntryLimit,
+} from "../lib/enrollment-guards.js";
+import { hatchet } from "../lib/hatchet.js";
+import { createLogger } from "../lib/logger.js";
+import { getPostHog } from "../lib/posthog.js";
+import { createJourneyContext } from "./journey-context.js";
+import { getJourneyRegistrySingleton } from "./registry-singleton.js";
+
+const logger = createLogger(process.env.LOG_LEVEL);
+
+interface EventPayloadInput {
+  userId: JsonValue;
+  userEmail: JsonValue;
+  properties: JsonValue;
+  [key: string]: JsonValue;
+}
+
+export interface DefinedJourney {
+  meta: JourneyMeta;
+  task: ReturnType<typeof hatchet.durableTask>;
+}
+
+export function defineJourney(options: {
+  meta: JourneyMeta;
+  run: JourneyRunFn;
+}): DefinedJourney {
+  const { meta } = options;
+
+  const task = hatchet.durableTask({
+    name: `journey-${meta.id}`,
+    onEvents: [meta.trigger.event],
+    executionTimeout: "720h",
+    retries: 0,
+    fn: async (input: EventPayloadInput, hatchetCtx) => {
+      const db = getDb();
+      const userId = input.userId as string;
+      const userEmail = input.userEmail as string;
+      const properties = (input.properties ?? {}) as Record<
+        string,
+        string | number | boolean | null
+      >;
+
+      if (!meta.enabled) {
+        return { status: "skipped", reason: "journey_disabled" };
+      }
+
+      const configOverride = await db.query.journeyConfigs.findFirst({
+        where: eq(journeyConfigs.journeyId, meta.id),
+      });
+      if (configOverride && !configOverride.enabled) {
+        return { status: "skipped", reason: "journey_disabled_by_admin" };
+      }
+
+      if (meta.trigger.where?.length) {
+        if (
+          !evaluatePropertyConditions({
+            conditions: meta.trigger.where,
+            properties,
+          })
+        ) {
+          return { status: "skipped", reason: "trigger_conditions_not_met" };
+        }
+      }
+
+      const entryAllowed = await checkEntryLimit({
+        db,
+        journey: meta,
+        userId,
+      });
+      if (!entryAllowed.allowed) {
+        return { status: "skipped", reason: entryAllowed.reason };
+      }
+
+      const prefs = await checkEmailPreferences({ db, userId });
+      if (prefs.unsubscribed) {
+        return { status: "skipped", reason: "user_unsubscribed" };
+      }
+
+      const activeState = await db.query.journeyStates.findFirst({
+        where: and(
+          eq(journeyStates.userId, userId),
+          eq(journeyStates.journeyId, meta.id),
+          inArray(journeyStates.status, ["active", "waiting"]),
+        ),
+      });
+      if (activeState) {
+        return { status: "skipped", reason: "already_active" };
+      }
+
+      const [state] = await db
+        .insert(journeyStates)
+        .values({
+          userId,
+          userEmail,
+          journeyId: meta.id,
+          currentNodeId: "start",
+          status: "active",
+          context: properties,
+          hatchetRunId: hatchetCtx.workflowRunId(),
+        })
+        .returning();
+
+      if (!state) {
+        return { status: "skipped", reason: "state_creation_failed" };
+      }
+
+      const stateId = state.id;
+
+      const user: JourneyUser = {
+        id: userId,
+        email: userEmail,
+        properties,
+        stateId,
+        journeyId: meta.id,
+        journeyName: meta.name,
+      };
+
+      const ctx = createJourneyContext({
+        db,
+        hatchet,
+        hatchetCtx,
+        registry: getJourneyRegistrySingleton(),
+        logger,
+        posthog: getPostHog(),
+        stateId,
+        userId,
+        userEmail,
+        journeyContext: { ...properties },
+      });
+
+      try {
+        await options.run(user, ctx);
+
+        await db
+          .update(journeyStates)
+          .set({
+            status: "completed",
+            completedAt: new Date(),
+            updatedAt: new Date(),
+          })
+          .where(eq(journeyStates.id, stateId));
+
+        await hatchet.events.push("journey:completed", {
+          journeyId: meta.id,
+          stateId,
+          userId,
+        });
+
+        return { stateId, status: "completed" };
+      } catch (err) {
+        const message =
+          err instanceof Error ? err.message : "Unknown error during journey";
+
+        await db
+          .update(journeyStates)
+          .set({
+            status: "failed",
+            errorMessage: message,
+            updatedAt: new Date(),
+          })
+          .where(eq(journeyStates.id, stateId));
+
+        await hatchet.events.push("journey:failed", {
+          journeyId: meta.id,
+          stateId,
+          userId,
+          error: message,
+        });
+
+        throw err;
+      }
+    },
+  });
+
+  return { meta, task };
+}

package/src/journeys/journey-context.ts

@@ -0,0 +1,179 @@
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { DurationObject } from "@hogsend/core";
+import { evaluateEventCondition } from "@hogsend/core";
+import type { JourneyRegistry } from "@hogsend/core/registry";
+import type { JourneyContext } from "@hogsend/core/types";
+import { type Database, emailSends, journeyStates } from "@hogsend/db";
+import type { PostHogService } from "@hogsend/plugin-posthog";
+import { and, count, eq, max } from "drizzle-orm";
+import { checkEmailPreferences } from "../lib/enrollment-guards.js";
+import { ingestEvent } from "../lib/ingestion.js";
+import type { Logger } from "../lib/logger.js";
+
+interface JourneyContextConfig {
+  db: Database;
+  hatchet: HatchetClient;
+  hatchetCtx: { sleepFor: (duration: DurationObject) => Promise<unknown> };
+  registry: JourneyRegistry;
+  logger: Logger;
+  posthog?: PostHogService;
+  stateId: string;
+  userId: string;
+  userEmail: string;
+  journeyContext: Record<string, unknown>;
+}
+
+export function createJourneyContext(
+  config: JourneyContextConfig,
+): JourneyContext {
+  const {
+    db,
+    hatchet,
+    hatchetCtx,
+    registry,
+    logger,
+    posthog,
+    stateId,
+    userId,
+    userEmail,
+    journeyContext,
+  } = config;
+
+  return {
+    async sleep({ duration, label }) {
+      const sleptAt = new Date().toISOString();
+
+      await db
+        .update(journeyStates)
+        .set({
+          status: "waiting",
+          currentNodeId: label ?? `wait:${JSON.stringify(duration)}`,
+          updatedAt: new Date(),
+        })
+        .where(eq(journeyStates.id, stateId));
+
+      await hatchetCtx.sleepFor(duration);
+
+      const resumedAt = new Date().toISOString();
+
+      await db
+        .update(journeyStates)
+        .set({ status: "active", updatedAt: new Date() })
+        .where(eq(journeyStates.id, stateId));
+
+      return { sleptAt, resumedAt };
+    },
+
+    async checkpoint(label) {
+      await db
+        .update(journeyStates)
+        .set({ currentNodeId: label, updatedAt: new Date() })
+        .where(eq(journeyStates.id, stateId));
+    },
+
+    async trigger({
+      event,
+      userId: targetUserId,
+      userEmail: targetEmail,
+      properties,
+    }) {
+      await ingestEvent({
+        db,
+        registry,
+        hatchet,
+        logger,
+        event: {
+          event,
+          userId: targetUserId,
+          userEmail: targetEmail ?? userEmail,
+          properties: properties ?? {},
+        },
+      });
+    },
+
+    identify(properties) {
+      posthog?.identify(userId, properties);
+    },
+
+    guard: {
+      async isSubscribed() {
+        const prefs = await checkEmailPreferences({ db, userId });
+        return !prefs.unsubscribed;
+      },
+    },
+
+    history: {
+      async hasEvent({ userId: targetUserId, event, within }) {
+        const result = await evaluateEventCondition({
+          condition: {
+            type: "event",
+            eventName: event,
+            check: "exists",
+            within,
+          },
+          ctx: { db, userId: targetUserId, journeyContext },
+        });
+        return { found: result.matched, count: result.count };
+      },
+
+      async journey({ userId: targetUserId, journeyId: targetJourneyId }) {
+        const [result] = await db
+          .select({
+            entryCount: count(),
+            lastCompletedAt: max(journeyStates.completedAt),
+          })
+          .from(journeyStates)
+          .where(
+            and(
+              eq(journeyStates.userId, targetUserId),
+              eq(journeyStates.journeyId, targetJourneyId),
+            ),
+          );
+
+        return {
+          completed: result?.lastCompletedAt !== null,
+          lastCompletedAt:
+            result?.lastCompletedAt instanceof Date
+              ? result.lastCompletedAt.toISOString()
+              : null,
+          entryCount: result?.entryCount ?? 0,
+        };
+      },
+
+      async email({ email: targetEmail, template }) {
+        const [result] = await db
+          .select({
+            count: count(),
+            lastSentAt: max(emailSends.sentAt),
+          })
+          .from(emailSends)
+          .where(
+            and(
+              eq(emailSends.toEmail, targetEmail),
+              eq(emailSends.templateKey, template),
+            ),
+          );
+
+        const total = result?.count ?? 0;
+        return {
+          sent: total > 0,
+          lastSentAt:
+            result?.lastSentAt instanceof Date
+              ? result.lastSentAt.toISOString()
+              : null,
+          count: total,
+        };
+      },
+    },
+
+    posthog: {
+      capture({ event, properties }) {
+        posthog?.captureEvent({
+          distinctId: userId,
+          event,
+          properties,
+        });
+      },
+    },
+  };
+}

package/src/journeys/registry-singleton.ts

@@ -0,0 +1,21 @@
+import type { JourneyRegistry } from "@hogsend/core/registry";
+
+let _registry: JourneyRegistry | undefined;
+
+export function setJourneyRegistry(registry: JourneyRegistry): void {
+  _registry = registry;
+}
+
+export function getJourneyRegistrySingleton(): JourneyRegistry {
+  if (!_registry) {
+    throw new Error(
+      "Journey registry not initialized. Call setJourneyRegistry() at startup.",
+    );
+  }
+  return _registry;
+}
+
+/** Reset the singleton — only for test cleanup. */
+export function resetJourneyRegistry(): void {
+  _registry = undefined;
+}

package/src/journeys/registry.ts

@@ -0,0 +1,53 @@
+import { JourneyRegistry } from "@hogsend/core/registry";
+import type { DefinedJourney } from "./define-journey.js";
+import { setJourneyRegistry } from "./registry-singleton.js";
+
+/**
+ * Parse the `ENABLED_JOURNEYS` filter. Returns `"*"` to enable all journeys, or
+ * a `Set` of journey ids to enable. An empty/whitespace/`*` value means all.
+ */
+export function parseEnabledFilter(filter?: string): "*" | Set<string> {
+  if (!filter || filter.trim() === "*") return "*";
+  return new Set(
+    filter
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Build a {@link JourneyRegistry} from an injected array of journeys, applying
+ * the enabled filter, and install it as the process singleton (so durable tasks
+ * can resolve it). Returns the registry.
+ */
+export function buildJourneyRegistry(
+  journeys: DefinedJourney[],
+  enabledFilter?: string,
+): JourneyRegistry {
+  const registry = new JourneyRegistry();
+  const enabled = parseEnabledFilter(enabledFilter);
+
+  for (const journey of journeys) {
+    if (enabled === "*" || enabled.has(journey.meta.id)) {
+      registry.register(journey.meta);
+    }
+  }
+
+  setJourneyRegistry(registry);
+  return registry;
+}
+
+/**
+ * Select the Hatchet durable tasks for the enabled journeys from an injected
+ * array of journeys.
+ */
+export function selectJourneyTasks(
+  journeys: DefinedJourney[],
+  enabledFilter?: string,
+) {
+  const enabled = parseEnabledFilter(enabledFilter);
+  return journeys
+    .filter((j) => enabled === "*" || enabled.has(j.meta.id))
+    .map((j) => j.task);
+}

package/src/lib/alerting.ts

@@ -0,0 +1,205 @@
+import {
+  alertHistory,
+  alertRules,
+  type Database,
+  journeyStates,
+} from "@hogsend/db";
+import { and, count, eq, gte } from "drizzle-orm";
+import { getEmailStats } from "./email-stats.js";
+import type { Logger } from "./logger.js";
+import {
+  sendEmailNotification,
+  sendSlackNotification,
+  sendWebhook,
+} from "./notifications.js";
+
+async function dispatchAlert(opts: {
+  rule: typeof alertRules.$inferSelect;
+  message: string;
+  payload: Record<string, unknown>;
+  resendApiKey?: string;
+}): Promise<{ deliveryStatus: string; error?: string }> {
+  const config = opts.rule.channelConfig as Record<string, string>;
+  switch (opts.rule.channel) {
+    case "webhook": {
+      const result = await sendWebhook(config.url ?? "", {
+        rule: opts.rule.name,
+        type: opts.rule.type,
+        ...opts.payload,
+      });
+      return result.ok
+        ? { deliveryStatus: "sent" }
+        : { deliveryStatus: "failed", error: result.error };
+    }
+    case "slack": {
+      const result = await sendSlackNotification(
+        config.webhookUrl ?? "",
+        opts.message,
+      );
+      return result.ok
+        ? { deliveryStatus: "sent" }
+        : { deliveryStatus: "failed", error: result.error };
+    }
+    case "email": {
+      const result = await sendEmailNotification({
+        to: config.to ?? "",
+        subject: `[Hogsend Alert] ${opts.rule.name}`,
+        body: `<p>${opts.message}</p><pre>${JSON.stringify(opts.payload, null, 2)}</pre>`,
+        resendApiKey: opts.resendApiKey ?? "",
+      });
+      return result.ok
+        ? { deliveryStatus: "sent" }
+        : { deliveryStatus: "failed", error: result.error };
+    }
+    default:
+      return {
+        deliveryStatus: "failed",
+        error: `Unknown channel: ${opts.rule.channel}`,
+      };
+  }
+}
+
+export async function checkAlertRules(opts: {
+  db: Database;
+  logger: Logger;
+  resendApiKey?: string;
+}): Promise<void> {
+  const { db, logger } = opts;
+
+  const rules = await db
+    .select()
+    .from(alertRules)
+    .where(eq(alertRules.enabled, true));
+
+  for (const rule of rules) {
+    try {
+      if (rule.lastFiredAt) {
+        const cooldownMs = rule.cooldownMinutes * 60 * 1000;
+        if (Date.now() - rule.lastFiredAt.getTime() < cooldownMs) {
+          continue;
+        }
+      }
+
+      const threshold = rule.threshold as Record<string, number>;
+      let triggered = false;
+      let payload: Record<string, unknown> = {};
+
+      switch (rule.type) {
+        case "bounce_rate_exceeded": {
+          const windowMinutes = threshold.windowMinutes ?? 60;
+          const since = new Date(Date.now() - windowMinutes * 60 * 1000);
+          const stats = await getEmailStats({ db, since });
+          const rate = stats.total > 0 ? stats.bounced / stats.total : 0;
+          const maxRate = threshold.rate ?? 0.05;
+          if (rate > maxRate && stats.total >= 10) {
+            triggered = true;
+            payload = {
+              bounced: stats.bounced,
+              total: stats.total,
+              rate,
+              threshold: maxRate,
+            };
+          }
+          break;
+        }
+
+        case "journey_failure_spike": {
+          const windowMinutes = threshold.windowMinutes ?? 60;
+          const maxFailures = threshold.count ?? 5;
+          const since = new Date(Date.now() - windowMinutes * 60 * 1000);
+          const failures = await db
+            .select({ count: count() })
+            .from(journeyStates)
+            .where(
+              and(
+                eq(journeyStates.status, "failed"),
+                gte(journeyStates.createdAt, since),
+              ),
+            )
+            .then((r) => r[0]?.count ?? 0);
+          if (failures >= maxFailures) {
+            triggered = true;
+            payload = {
+              failures,
+              threshold: maxFailures,
+              windowMinutes,
+            };
+          }
+          break;
+        }
+
+        case "delivery_issue": {
+          const windowMinutes = threshold.windowMinutes ?? 60;
+          const since = new Date(Date.now() - windowMinutes * 60 * 1000);
+          const stats = await getEmailStats({ db, since });
+          const deliveryRate =
+            stats.total > 0 ? stats.delivered / stats.total : 1;
+          const minRate = threshold.minDeliveryRate ?? 0.9;
+          if (deliveryRate < minRate && stats.total >= 10) {
+            triggered = true;
+            payload = {
+              delivered: stats.delivered,
+              total: stats.total,
+              deliveryRate,
+              threshold: minRate,
+            };
+          }
+          break;
+        }
+
+        case "high_complaint_rate": {
+          const windowMinutes = threshold.windowMinutes ?? 60;
+          const since = new Date(Date.now() - windowMinutes * 60 * 1000);
+          const stats = await getEmailStats({ db, since });
+          const rate = stats.total > 0 ? stats.complained / stats.total : 0;
+          const maxRate = threshold.rate ?? 0.01;
+          if (rate > maxRate && stats.total >= 10) {
+            triggered = true;
+            payload = {
+              complained: stats.complained,
+              total: stats.total,
+              rate,
+              threshold: maxRate,
+            };
+          }
+          break;
+        }
+      }
+
+      if (!triggered) continue;
+
+      const message = `[Hogsend Alert] ${rule.name}: ${rule.type} triggered — ${JSON.stringify(payload)}`;
+
+      const { deliveryStatus, error } = await dispatchAlert({
+        rule,
+        message,
+        payload,
+        resendApiKey: opts.resendApiKey,
+      });
+
+      await Promise.all([
+        db.insert(alertHistory).values({
+          alertRuleId: rule.id,
+          payload,
+          deliveryStatus,
+          error: error ?? null,
+        }),
+        db
+          .update(alertRules)
+          .set({ lastFiredAt: new Date(), updatedAt: new Date() })
+          .where(eq(alertRules.id, rule.id)),
+      ]);
+
+      logger.info("Alert fired", {
+        rule: rule.name,
+        type: rule.type,
+        deliveryStatus,
+      });
+    } catch (err) {
+      logger.error("Alert evaluation failed", {
+        ruleId: rule.id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+}

package/src/lib/api-key-hash.ts

@@ -0,0 +1,19 @@
+import { createHash, randomBytes } from "node:crypto";
+
+const PREFIX_LENGTH = 8;
+
+export function generateApiKey(): {
+  key: string;
+  prefix: string;
+  hash: string;
+} {
+  const raw = randomBytes(32).toString("base64url");
+  const key = `hsk_${raw}`;
+  const prefix = key.slice(0, PREFIX_LENGTH);
+  const hash = hashApiKey(key);
+  return { key, prefix, hash };
+}
+
+export function hashApiKey(key: string): string {
+  return createHash("sha256").update(key).digest("hex");
+}

package/src/lib/auth.ts

@@ -0,0 +1,39 @@
+import type { Database } from "@hogsend/db";
+import * as schema from "@hogsend/db/schema";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { organization } from "better-auth/plugins/organization";
+
+export function createAuth(opts: {
+  db: Database;
+  secret: string;
+  baseURL: string;
+}) {
+  const { db, secret, baseURL } = opts;
+  return betterAuth({
+    basePath: "/api/auth",
+    secret,
+    baseURL,
+    database: drizzleAdapter(db, {
+      provider: "pg",
+      schema,
+    }),
+    emailAndPassword: {
+      enabled: true,
+      minPasswordLength: 8,
+      maxPasswordLength: 128,
+    },
+    session: {
+      expiresIn: 60 * 60 * 24 * 7,
+      updateAge: 60 * 60 * 24,
+    },
+    plugins: [
+      organization({
+        organizationLimit: 5,
+        membershipLimit: 100,
+      }),
+    ],
+  });
+}
+
+export type Auth = ReturnType<typeof createAuth>;