@hogsend/engine 0.0.1

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0 (ELv2)
+
+Copyright 2025 Doug Silkstone and Hogsend contributors
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising out
+of these terms or the use or nature of the software, under any kind of legal
+claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,18 @@
+# @hogsend/engine
+
+The Hogsend framework: `createApp`, `createHogsendClient`, `createWorker`,
+`defineJourney`, `defineWebhookSource`, the ingestion + tracking pipeline, the
+built-in routes, and the registries. This is the public API surface consumers
+build their lifecycle apps on top of.
+
+Scaffold a consumer app with `pnpm dlx create-hogsend@latest`. The engine line
+(`@hogsend/engine`, `@hogsend/db`, `@hogsend/core`) is versioned in lockstep so a
+new engine migration always bumps the engine and DB together; the boot guard
+asserts the database ledger matches the bundled migrations. See
+[engine-boundary.md](https://github.com/dougwithseismic/hogsend/blob/main/docs/engine-boundary.md)
+for the committed API surface and
+[RELEASING.md](https://github.com/dougwithseismic/hogsend/blob/main/docs/RELEASING.md)
+for semver discipline.
+
+This package ships raw TypeScript source; consumers bundle it via their own build
+(tsup `noExternal`).

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@hogsend/engine",
+  "version": "0.0.1",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dougwithseismic/hogsend.git",
+    "directory": "packages/engine"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./worker": "./src/worker.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hatchet-dev/typescript-sdk": "^1.22.3",
+    "@hono/node-server": "^2.0.4",
+    "@hono/zod-openapi": "^1.4.0",
+    "@scalar/hono-api-reference": "^0.10.19",
+    "@t3-oss/env-core": "^0.13.11",
+    "better-auth": "^1.6.11",
+    "drizzle-orm": "^0.45.2",
+    "hono": "^4.12.22",
+    "ioredis": "^5.10.1",
+    "papaparse": "^5.5.3",
+    "resend": "^6.12.3",
+    "winston": "^3.19.0",
+    "zod": "^4.4.3",
+    "@hogsend/core": "^0.0.1",
+    "@hogsend/db": "^0.0.1",
+    "@hogsend/email": "^0.0.1",
+    "@hogsend/plugin-resend": "^0.0.1",
+    "@hogsend/plugin-posthog": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "@types/papaparse": "^5.5.2",
+    "tsx": "^4.22.3",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "lint": "biome check .",
+    "clean": "rm -rf node_modules .turbo"
+  }
+}

package/src/app.ts

@@ -0,0 +1,102 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { apiReference } from "@scalar/hono-api-reference";
+import { compress } from "hono/compress";
+import { cors } from "hono/cors";
+import { requestId } from "hono/request-id";
+import { secureHeaders } from "hono/secure-headers";
+import type { ErrorHandler, MiddlewareHandler } from "hono/types";
+import type { HogsendClient } from "./container.js";
+import { API_VERSION } from "./env.js";
+import type { Auth } from "./lib/auth.js";
+import type { ApiKeyContext } from "./middleware/api-key.js";
+import { errorHandler } from "./middleware/error-handler.js";
+import { requestLogger } from "./middleware/request-logger.js";
+import { registerRoutes } from "./routes/index.js";
+import type { DefinedWebhookSource } from "./webhook-sources/define-webhook-source.js";
+
+type AuthSession = Awaited<ReturnType<Auth["api"]["getSession"]>>;
+
+export type AppEnv = {
+  Variables: {
+    container: HogsendClient;
+    requestId: string;
+    user: NonNullable<AuthSession>["user"] | null;
+    session: NonNullable<AuthSession>["session"] | null;
+    apiKey: ApiKeyContext | undefined;
+  };
+};
+
+export interface CreateAppOptions {
+  /** Mount custom routers after the built-in routes. */
+  routes?: (app: OpenAPIHono<AppEnv>) => void;
+  /** Extra middleware applied after the built-in stack. */
+  middleware?: MiddlewareHandler[];
+  /** Webhook sources served at `/v1/webhooks/:sourceId`. */
+  webhookSources?: DefinedWebhookSource[];
+  /** Override the default error handler. */
+  onError?: ErrorHandler<AppEnv>;
+}
+
+export function createApp(
+  container: HogsendClient,
+  opts: CreateAppOptions = {},
+) {
+  const app = new OpenAPIHono<AppEnv>();
+
+  app.use("*", async (c, next) => {
+    c.set("container", container);
+    await next();
+  });
+
+  app.use("*", secureHeaders());
+  app.use("*", cors());
+  app.use("*", compress());
+  app.use("*", requestId());
+  app.use("*", requestLogger);
+
+  for (const mw of opts.middleware ?? []) {
+    app.use("*", mw);
+  }
+
+  app.onError(opts.onError ?? errorHandler);
+
+  app.notFound((c) => {
+    return c.json({ error: "Not Found" }, 404);
+  });
+
+  app.on(["POST", "GET"], "/api/auth/*", (c) => {
+    const { auth } = c.get("container");
+    return auth.handler(c.req.raw);
+  });
+
+  registerRoutes(app, { webhookSources: opts.webhookSources ?? [] });
+
+  opts.routes?.(app);
+
+  if (container.env.NODE_ENV !== "production") {
+    app.doc("/openapi.json", {
+      openapi: "3.1.0",
+      info: {
+        title: "Hogsend API",
+        version: API_VERSION,
+        description: "Journey orchestration API",
+      },
+      servers: [
+        {
+          url: `http://localhost:${container.env.PORT}`,
+          description: "Local development",
+        },
+      ],
+    });
+
+    app.get(
+      "/docs",
+      apiReference({
+        spec: { url: "/openapi.json" },
+        theme: "kepler",
+      }),
+    );
+  }
+
+  return app;
+}

package/src/container.ts

@@ -0,0 +1,172 @@
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { JourneyRegistry } from "@hogsend/core/registry";
+import {
+  createDatabase,
+  type Database,
+  type DatabaseClient,
+  type JournalShape,
+} from "@hogsend/db";
+import type { TemplateRegistry } from "@hogsend/email";
+import type { PostHogService } from "@hogsend/plugin-posthog";
+import {
+  createResendClient,
+  createResendProvider,
+  type EmailProvider,
+} from "@hogsend/plugin-resend";
+import type { Resend } from "resend";
+import { env } from "./env.js";
+import type { DefinedJourney } from "./journeys/define-journey.js";
+import { buildJourneyRegistry } from "./journeys/registry.js";
+import { type Auth, createAuth } from "./lib/auth.js";
+import { setEmailService } from "./lib/email.js";
+import type { EmailService } from "./lib/email-service-types.js";
+import { hatchet } from "./lib/hatchet.js";
+import { createLogger, type Logger } from "./lib/logger.js";
+import { createTrackedMailer } from "./lib/mailer.js";
+import { getPostHog } from "./lib/posthog.js";
+import { prepareTrackedHtml } from "./lib/tracking.js";
+
+export interface HogsendClient {
+  env: typeof env;
+  logger: Logger;
+  db: Database;
+  dbClient: DatabaseClient;
+  auth: Auth;
+  email: Resend;
+  emailService: EmailService;
+  analytics?: PostHogService;
+  registry: JourneyRegistry;
+  hatchet: HatchetClient;
+  /**
+   * The client repo's migration journal (`migrations/meta/_journal.json`),
+   * powering the `schema.client` block of `GET /v1/health`. Defaults to an
+   * empty journal — a client that injects none has a trivially-in-sync client
+   * track. The CLIENT track never gates boot (client-owned); engine does.
+   */
+  clientJournal: JournalShape;
+}
+
+export interface HogsendClientOptions {
+  /** Journeys to register in the {@link JourneyRegistry}. Defaults to none. */
+  journeys?: DefinedJourney[];
+  /**
+   * Email is a first-class channel. Its config is grouped here rather than
+   * spread across top-level args — the engine owns the cohesive email pipeline
+   * (templates → render → preference checks → tracking → `email_sends` write),
+   * and the {@link EmailProvider} is only the swappable wire under it.
+   *
+   * - `provider` — the swappable email provider (Resend, Postmark, SES…).
+   *   Defaults to a Resend provider built from env (`RESEND_API_KEY` /
+   *   `RESEND_WEBHOOK_SECRET`). Tracking/rendering/preferences come along for
+   *   free regardless of which provider you supply.
+   * - `templates` — the app's template registry (key → component + subject +
+   *   category), threaded into the engine mailer and onward to
+   *   `getTemplate(..., { registry })`. The engine bakes in no business
+   *   templates; clients own their `.tsx` files + registry. Defaults to an
+   *   empty registry (no sendable template keys).
+   *
+   * Other channels (SMS, push, Slack) are NOT configured here — they're plain
+   * functions a journey imports and calls.
+   */
+  email?: {
+    provider?: EmailProvider;
+    templates?: TemplateRegistry;
+  };
+  /**
+   * The PostHog-style analytics service used for person properties + event
+   * capture. Lives at the top level (not under `email`) because the engine
+   * itself uses it — tracking routes and ingestion fire captures. Defaults to
+   * {@link getPostHog} (a no-op when `POSTHOG_API_KEY` is unset).
+   */
+  analytics?: PostHogService;
+  /**
+   * Comma-separated ids (or `*`) controlling which journeys load. Defaults to
+   * `env.ENABLED_JOURNEYS`.
+   */
+  enabledJourneys?: string;
+  /**
+   * The client repo's migration journal for the `schema.client` health block.
+   * Defaults to `{ entries: [] }` (empty client track ⇒ trivially in sync).
+   */
+  clientJournal?: JournalShape;
+  /**
+   * Genuinely advanced / test-only seams. You probably don't need these —
+   * prefer the first-class `email` / `analytics` args above.
+   * `mailer` replaces the engine-built {@link EmailService} wholesale (used by
+   * tests to inject a mock); `auth`, `hatchet`, and `db` swap their respective
+   * infrastructure singletons.
+   */
+  overrides?: {
+    mailer?: EmailService;
+    auth?: Auth;
+    hatchet?: HatchetClient;
+    db?: Database;
+  };
+}
+
+export function createHogsendClient(
+  opts: HogsendClientOptions = {},
+): HogsendClient {
+  const logger = createLogger(env.LOG_LEVEL);
+  const created = createDatabase({ url: env.DATABASE_URL });
+  const db = opts.overrides?.db ?? created.db;
+
+  const auth =
+    opts.overrides?.auth ??
+    createAuth({
+      db,
+      secret: env.BETTER_AUTH_SECRET,
+      baseURL: env.BETTER_AUTH_URL,
+    });
+
+  const email = createResendClient({ apiKey: env.RESEND_API_KEY });
+
+  const registry = buildJourneyRegistry(
+    opts.journeys ?? [],
+    opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
+  );
+
+  const provider =
+    opts.email?.provider ??
+    createResendProvider({
+      apiKey: env.RESEND_API_KEY,
+      webhookSecret: env.RESEND_WEBHOOK_SECRET,
+    });
+
+  const emailService =
+    opts.overrides?.mailer ??
+    createTrackedMailer(
+      {
+        defaultFrom: env.RESEND_FROM_EMAIL,
+        templates: opts.email?.templates ?? ({} as TemplateRegistry),
+        db,
+        webhookSecret: env.RESEND_WEBHOOK_SECRET,
+        bounceThreshold: 3,
+        baseUrl: env.API_PUBLIC_URL,
+      },
+      {
+        provider,
+        prepareTrackedHtml,
+      },
+    );
+
+  setEmailService(emailService);
+
+  const analytics = opts.analytics ?? getPostHog();
+
+  logger.info(`Journey registry loaded: ${registry.count()} journeys`);
+
+  return {
+    env,
+    logger,
+    db,
+    dbClient: created.client,
+    auth,
+    email,
+    emailService,
+    analytics,
+    registry,
+    hatchet: opts.overrides?.hatchet ?? hatchet,
+    clientJournal: opts.clientJournal ?? { entries: [] },
+  };
+}

package/src/env.ts

@@ -0,0 +1,56 @@
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+export const API_VERSION = "0.0.1";
+
+export const env = createEnv({
+  server: {
+    NODE_ENV: z
+      .enum(["development", "production", "test"])
+      .default("development"),
+    PORT: z.coerce.number().default(3002),
+    LOG_LEVEL: z
+      .enum(["error", "warn", "info", "http", "debug"])
+      .default("info"),
+    DATABASE_URL: z.string().min(1),
+    REDIS_URL: z.string().min(1).default("redis://localhost:6379"),
+    BETTER_AUTH_SECRET: z.string().min(1),
+    BETTER_AUTH_URL: z.string().url().default("http://localhost:3002"),
+    RESEND_API_KEY: z.string().min(1),
+    RESEND_FROM_EMAIL: z.string().email().default("noreply@hogsend.com"),
+    // Hatchet connection contract. The @hatchet-dev SDK also reads these straight
+    // from process.env via its own config-loader, so this schema is a presence /
+    // shape check that keeps the contract in one place — the values still flow to
+    // the SDK independently. We pass token/host_port/tls/namespace explicitly into
+    // HatchetClient.init() (see lib/hatchet.ts) so env.ts is the source of truth.
+    //
+    // Step 1 of onboarding is "acquire a Hatchet": grab HATCHET_CLIENT_TOKEN from
+    // Hatchet Cloud or the local hatchet-lite dashboard (:8888 → Settings → API
+    // Tokens) and set it yourself. This is the bring-your-own-token contract; there
+    // is no auto-mint.
+    HATCHET_CLIENT_TOKEN: z.string().min(1),
+    HATCHET_CLIENT_HOST_PORT: z.string().min(1).default("localhost:7077"),
+    // Secure by default: `tls` matches the SDK and Hatchet Cloud. The local
+    // insecure hatchet-lite path explicitly overrides to `none` in compose/.env —
+    // we never default to plaintext gRPC.
+    HATCHET_CLIENT_TLS_STRATEGY: z.enum(["none", "tls", "mtls"]).default("tls"),
+    // Future per-tenant isolation knob (one shared Hatchet engine, namespaced
+    // tasks). Default-empty today; documented so it stays part of the contract.
+    HATCHET_CLIENT_NAMESPACE: z.string().optional(),
+    // Emergency boot-guard bypass, read raw in apps/api/src/index.ts. Declared
+    // here so it is part of the validated env contract (single source of truth).
+    SKIP_SCHEMA_CHECK: z.coerce.boolean().default(false),
+    // Client-migration track folder, read raw in @hogsend/db migrate-client.ts
+    // (the db package can't depend on engine). Declared here for contract parity.
+    CLIENT_MIGRATIONS_FOLDER: z.string().min(1).optional(),
+    POSTHOG_API_KEY: z.string().min(1).optional(),
+    POSTHOG_HOST: z.string().url().optional(),
+    POSTHOG_WEBHOOK_SECRET: z.string().min(1).optional(),
+    RESEND_WEBHOOK_SECRET: z.string().min(1).optional(),
+    ADMIN_API_KEY: z.string().min(1).optional(),
+    API_PUBLIC_URL: z.string().url().default("http://localhost:3002"),
+    ENABLED_JOURNEYS: z.string().default("*"),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});

package/src/index.ts

@@ -0,0 +1,114 @@
+// @hogsend/engine — public API surface (the committed semver boundary).
+//
+// Content (journeys, webhook sources, workflows) is injected into these
+// factories by client app code; the engine never imports content.
+
+// Core helpers used by content journeys (days/hours/minutes, condition + journey
+// types) so content can import everything from `@hogsend/engine`.
+export * from "@hogsend/core";
+export { JourneyRegistry } from "@hogsend/core/registry";
+// --- Re-exports for content ---
+// Schema/version helpers used by the boot guard and the /v1/health route.
+export {
+  getBundledMigrations,
+  getClientSchemaVersion,
+  getEngineSchemaVersion,
+  getSchemaVersion,
+  type JournalShape,
+  type SchemaVersion,
+} from "@hogsend/db";
+// --- App / container / worker factories ---
+export { type AppEnv, type CreateAppOptions, createApp } from "./app.js";
+export {
+  createHogsendClient,
+  type HogsendClient,
+  type HogsendClientOptions,
+} from "./container.js";
+// --- Env ---
+export { API_VERSION, env } from "./env.js";
+// --- Journeys ---
+export {
+  type DefinedJourney,
+  defineJourney,
+} from "./journeys/define-journey.js";
+export { createJourneyContext } from "./journeys/journey-context.js";
+export {
+  buildJourneyRegistry,
+  parseEnabledFilter,
+  selectJourneyTasks,
+} from "./journeys/registry.js";
+export {
+  getJourneyRegistrySingleton,
+  setJourneyRegistry,
+} from "./journeys/registry-singleton.js";
+// --- Auth ---
+export { type Auth, createAuth } from "./lib/auth.js";
+// --- Backfill ---
+export {
+  type BatchedBackfillOptions,
+  type BatchedBackfillResult,
+  runBatchedBackfill,
+} from "./lib/backfill.js";
+// --- Infrastructure singletons ---
+export { getDb } from "./lib/db.js";
+// --- Email ---
+export {
+  type SendEmailOptions,
+  type SendEmailResult,
+  sendEmail,
+  setEmailService,
+} from "./lib/email.js";
+// --- Email service (engine-owned tracked mailer) ---
+export type {
+  EmailService,
+  EmailServiceConfig,
+  EmailServiceSendOptions,
+  EmailServiceWebhookOptions,
+  EmailServiceWebhookResult,
+  SendTrackedEmailOptions,
+  TrackedSendResult,
+} from "./lib/email-service-types.js";
+// --- Enrollment guards ---
+export { checkEmailPreferences } from "./lib/enrollment-guards.js";
+export { hatchet } from "./lib/hatchet.js";
+// --- Ingestion pipeline ---
+export {
+  type IngestEvent,
+  type IngestResult,
+  ingestEvent,
+} from "./lib/ingestion.js";
+// --- Logging ---
+export { createLogger, type Logger } from "./lib/logger.js";
+export { createTrackedMailer } from "./lib/mailer.js";
+export { getPostHog } from "./lib/posthog.js";
+export { getRedisIfConnected } from "./lib/redis.js";
+export {
+  type PrepareTrackedHtmlFn,
+  sendTrackedEmail,
+} from "./lib/tracked.js";
+// --- Tracking ---
+export {
+  injectOpenPixel,
+  prepareTrackedHtml,
+  rewriteLinks,
+} from "./lib/tracking.js";
+export {
+  pushTrackingEvent,
+  resolveEmailSendContext,
+} from "./lib/tracking-events.js";
+// --- Webhook sources ---
+export {
+  type DefinedWebhookSource,
+  defineWebhookSource,
+  type WebhookSourceCtx,
+  type WebhookSourceMeta,
+} from "./webhook-sources/define-webhook-source.js";
+export {
+  type CreateWorkerOptions,
+  createWorker,
+  type Worker,
+} from "./worker.js";
+export { checkAlertsTask } from "./workflows/check-alerts.js";
+export { importContactsTask } from "./workflows/import-contacts.js";
+// --- Built-in Hatchet workflow tasks ---
+export { sendEmailTask } from "./workflows/send-email.js";