@hogsend/engine 0.5.0 → 0.7.0

package/src/buckets/registry.ts

@@ -1,4 +1,5 @@
 import { BucketRegistry } from "@hogsend/core/registry";
+import type { DefinedJourney } from "../journeys/define-journey.js";
 import { parseEnabledFilter } from "../journeys/registry.js";
 import { bucketExpiryTask } from "../workflows/bucket-reconcile.js";
 import type { DefinedBucket } from "./define-bucket.js";
@@ -60,3 +61,83 @@ export function selectBucketTasks(
   // the DefinedBucket task shape — both are `hatchet.durableTask` returns.
   return [bucketExpiryTask as NonNullable<DefinedBucket["task"]>];
 }
+
+/**
+ * Select the Hatchet durable tasks for the reaction journeys generated by
+ * `bucket.on()` across the ENABLED buckets (Section 9). Reactions are
+ * bucket-owned, so they are gated by `ENABLED_BUCKETS` — NOT `ENABLED_JOURNEYS`
+ * (their `bucket-<id>-on-<kind>` ids never appear in a consumer's
+ * `ENABLED_JOURNEYS` csv, so folding them into the journeys[] array would drop
+ * every reaction whenever ENABLED_JOURNEYS is a csv).
+ *
+ * Asserts no reaction-id collision (a build-time loud failure) before returning.
+ */
+export function selectBucketReactionTasks(
+  buckets: DefinedBucket[],
+  enabledFilter?: string,
+  userJourneyIds?: Iterable<string>,
+): NonNullable<DefinedBucket["task"]>[] {
+  const enabled = parseEnabledFilter(enabledFilter);
+  const enabledBuckets = buckets.filter(
+    (b) => enabled === "*" || enabled.has(b.meta.id),
+  );
+  // Loud boot failure on a duplicate reaction id / user-journey collision
+  // instead of a silent register-last-wins drop (Section 9). Pass the consumer
+  // journey ids so a reaction id colliding with a hand-written journey throws.
+  assertNoReactionIdCollisions(enabledBuckets, userJourneyIds);
+  return enabledBuckets.flatMap((b) =>
+    b.reactions.map((r) => r.task),
+  ) as NonNullable<DefinedBucket["task"]>[];
+}
+
+/**
+ * Collect the reaction `DefinedJourney`s across the ENABLED buckets (Section 9).
+ * Bucket-gated by `ENABLED_BUCKETS` for the same reason as
+ * {@link selectBucketReactionTasks}. The container registers their metas into the
+ * journey registry directly (bypassing the ENABLED_JOURNEYS filter) so the admin
+ * `feedsJourneys` and the dwell cron can resolve them.
+ */
+export function collectBucketReactionJourneys(
+  buckets: DefinedBucket[],
+  enabledFilter?: string,
+): DefinedJourney[] {
+  const enabled = parseEnabledFilter(enabledFilter);
+  return buckets
+    .filter((b) => enabled === "*" || enabled.has(b.meta.id))
+    .flatMap((b) => b.reactions);
+}
+
+/**
+ * Reaction tasks register on Hatchet under `journey-${meta.id}`. Two buckets
+ * sharing an id, two reactions colliding on a generated id, or a user journey
+ * named `bucket-<id>-on-<kind>` collide silently (register-last-wins) or throw on
+ * boot. Throw a descriptive build-time error instead (Section 9).
+ *
+ * @param enabledBuckets the already-enabled buckets to scan.
+ * @param userJourneyIds ids of the consumer's hand-written journeys (optional);
+ *   a reaction id colliding with one of these throws.
+ */
+export function assertNoReactionIdCollisions(
+  enabledBuckets: DefinedBucket[],
+  userJourneyIds?: Iterable<string>,
+): void {
+  const seen = new Set<string>();
+  const userIds = new Set(userJourneyIds ?? []);
+
+  for (const bucket of enabledBuckets) {
+    for (const reaction of bucket.reactions) {
+      const id = reaction.meta.id;
+      if (seen.has(id)) {
+        throw new Error(
+          `Bucket reaction id collision: "${id}" is generated by more than one reaction (check for duplicate bucket ids or two reactions of the same kind on bucket "${bucket.meta.id}").`,
+        );
+      }
+      if (userIds.has(id)) {
+        throw new Error(
+          `Bucket reaction id collision: generated reaction "${id}" (bucket "${bucket.meta.id}") collides with a user journey of the same id.`,
+        );
+      }
+      seen.add(id);
+    }
+  }
+}

package/src/container.ts

@@ -14,8 +14,12 @@ import {
   createResendProvider,
 } from "@hogsend/plugin-resend";
 import type { Resend } from "resend";
+import { createBucketAccessor } from "./buckets/bucket-access.js";
 import type { DefinedBucket } from "./buckets/define-bucket.js";
-import { buildBucketRegistry } from "./buckets/registry.js";
+import {
+  buildBucketRegistry,
+  collectBucketReactionJourneys,
+} from "./buckets/registry.js";
 import { env } from "./env.js";
 import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
 import type { DefinedJourney } from "./journeys/define-journey.js";
@@ -32,6 +36,8 @@ 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";
+import type { DefinedList } from "./lists/define-list.js";
+import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
 
 export interface HogsendDefaults {
   /** Global fallback IANA timezone for scheduling. Defaults to "UTC". */
@@ -66,6 +72,14 @@ export interface HogsendClient {
    * Empty when no buckets are wired.
    */
   bucketRegistry: BucketRegistry;
+  /**
+   * The email-list registry (D3): code-defined subscription categories layered
+   * on `email_preferences.categories`, with the LOCKED polarity rule that is the
+   * single source of truth for the mailer's suppression check AND the preference
+   * center. Built and installed as the process singleton at client build (read
+   * elsewhere via `getListRegistry()`). Empty when no lists are wired.
+   */
+  listRegistry: ListRegistry;
   hatchet: HatchetClient;
   /**
    * The client repo's migration journal (`migrations/meta/_journal.json`),
@@ -87,6 +101,13 @@ export interface HogsendClientOptions {
   journeys?: DefinedJourney[];
   /** Buckets to register in the {@link BucketRegistry}. Defaults to none. */
   buckets?: DefinedBucket[];
+  /**
+   * Email lists (D3) to register in the {@link ListRegistry}. Each is a
+   * `defineList()` subscription category (id + name + `defaultOptIn`). The
+   * registry drives the mailer's list-aware suppression check and the
+   * preference center. Defaults to none (empty registry ⇒ legacy opt-in).
+   */
+  lists?: DefinedList[];
   /**
    * 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
@@ -127,6 +148,11 @@ export interface HogsendClientOptions {
    * `env.ENABLED_BUCKETS`.
    */
   enabledBuckets?: string;
+  /**
+   * Comma-separated ids (or `*`) controlling which lists load. Defaults to
+   * `env.ENABLED_LISTS`.
+   */
+  enabledLists?: string;
   /**
    * The client repo's migration journal for the `schema.client` health block.
    * Defaults to `{ entries: [] }` (empty client track ⇒ trivially in sync).
@@ -200,9 +226,46 @@ export function createHogsendClient(
   // Installs the bucket registry singleton in BOTH the API and worker processes
   // (both call createHogsendClient); the real-time ingest path reads it via
   // getBucketRegistrySingleton().
-  const bucketRegistry = buildBucketRegistry(
-    opts.buckets ?? [],
-    opts.enabledBuckets ?? env.ENABLED_BUCKETS,
+  const buckets = opts.buckets ?? [];
+  const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
+  const bucketRegistry = buildBucketRegistry(buckets, enabledBuckets);
+
+  // Register the reaction journeys generated by `bucket.on()` into the journey
+  // registry AFTER buildJourneyRegistry, bypassing the ENABLED_JOURNEYS filter:
+  // reactions are bucket-owned and were already gated by ENABLED_BUCKETS
+  // (collectBucketReactionJourneys), so their `bucket-<id>-on-<kind>` ids must NOT
+  // be subject to the journeys csv (Section 9). Both API and worker call
+  // createHogsendClient, so the singleton carries reaction metas in both
+  // processes (needed for admin feedsJourneys + the dwell-cron lookup).
+  for (const reaction of collectBucketReactionJourneys(
+    buckets,
+    enabledBuckets,
+  )) {
+    registry.register(reaction.meta);
+  }
+
+  // Re-bind the member-access accessors on each enabled bucket to THIS
+  // container's db so `overrides.db` flows through (the accessors default to the
+  // getDb() singleton at defineBucket time, before any container exists —
+  // bucket-access.ts dbResolver seam). The enabled set mirrors
+  // buildBucketRegistry's filter.
+  const enabledIds = new Set(bucketRegistry.getAll().map((b) => b.id));
+  for (const bucket of buckets) {
+    if (!enabledIds.has(bucket.meta.id)) continue;
+    const accessor = createBucketAccessor(bucket.meta.id, () => db);
+    bucket.count = accessor.count;
+    bucket.has = accessor.has;
+    bucket.members = accessor.members;
+    bucket.membersIterator = accessor.membersIterator;
+  }
+
+  // Build + install the list registry singleton (D3). Runs in BOTH the API and
+  // worker (both call createHogsendClient), so `getListRegistry()` resolves the
+  // wired lists in the mailer's suppression check and the preference center in
+  // either process. `buildListRegistry` installs the process singleton.
+  const listRegistry = buildListRegistry(
+    opts.lists ?? [],
+    opts.enabledLists ?? env.ENABLED_LISTS,
   );
 
   const provider =
@@ -261,6 +324,7 @@ export function createHogsendClient(
   // keep these at debug for non-boot contexts (tests, REPL, library use).
   logger.debug(`Journey registry loaded: ${registry.count()} journeys`);
   logger.debug(`Bucket registry loaded: ${bucketRegistry.count()} buckets`);
+  logger.debug(`List registry loaded: ${listRegistry.count()} lists`);
 
   return {
     env,
@@ -274,6 +338,7 @@ export function createHogsendClient(
     analytics,
     registry,
     bucketRegistry,
+    listRegistry,
     hatchet: opts.overrides?.hatchet ?? hatchet,
     clientJournal: opts.clientJournal ?? { entries: [] },
     defaults,

package/src/env.ts

@@ -65,6 +65,10 @@ export const env = createEnv({
     // Evaluated at worker boot — a toggle requires a worker restart; only the
     // bucket_configs DB override is hot.
     ENABLED_BUCKETS: z.string().default("*"),
+    // Email lists (D3): same `"*"`-or-csv contract as ENABLED_JOURNEYS /
+    // ENABLED_BUCKETS. Filters which `defineList()` lists are registered into the
+    // process ListRegistry (the suppression-polarity + preference-center source).
+    ENABLED_LISTS: z.string().default("*"),
     // Cadence for the engine-owned bucket reconcile cron (time-based leaves).
     BUCKET_RECONCILE_CRON: z.string().default("*/5 * * * *"),
   },

package/src/index.ts

@@ -39,6 +39,18 @@ export {
 // --- App / container / worker factories ---
 export { type AppEnv, type CreateAppOptions, createApp } from "./app.js";
 // --- Buckets ---
+export {
+  type BucketAccessor,
+  type BucketMemberRow,
+  createBucketAccessor,
+  type MembersResult,
+} from "./buckets/bucket-access.js";
+export type {
+  BucketLeaveReason,
+  DwellOptions,
+  EnterOptions,
+  LeaveOptions,
+} from "./buckets/bucket-reactions.js";
 export {
   type BucketTransition,
   type BucketTransitionKind,
@@ -50,6 +62,8 @@ export {
 } from "./buckets/define-bucket.js";
 export {
   buildBucketRegistry,
+  collectBucketReactionJourneys,
+  selectBucketReactionTasks,
   selectBucketTasks,
 } from "./buckets/registry.js";
 export {
@@ -161,6 +175,18 @@ export {
   pushTrackingEvent,
   resolveEmailSendContext,
 } from "./lib/tracking-events.js";
+// --- Lists (D3) ---
+export {
+  type DefinedList,
+  defineList,
+  type ListMeta,
+} from "./lists/define-list.js";
+export { buildListRegistry, ListRegistry } from "./lists/registry.js";
+export {
+  getListRegistry,
+  resetListRegistry,
+  setListRegistry,
+} from "./lists/registry-singleton.js";
 // --- Webhook sources ---
 export {
   type DefinedWebhookSource,
@@ -186,5 +212,6 @@ export {
 } from "./workflows/bucket-reconcile.js";
 export { checkAlertsTask } from "./workflows/check-alerts.js";
 export { importContactsTask } from "./workflows/import-contacts.js";
+export { sendCampaignTask } from "./workflows/send-campaign.js";
 // --- Built-in Hatchet workflow tasks ---
 export { sendEmailTask } from "./workflows/send-email.js";

package/src/journeys/journey-context.ts

@@ -298,6 +298,10 @@ export function createJourneyContext(
       userEmail: targetEmail,
       properties,
     }) {
+      // Keep the PUBLIC `TriggerOptions.properties` field name (decision #13 —
+      // renaming it would break consumer journeys + scaffold). Map it to the
+      // engine-internal `eventProperties` bag here; no `contactProperties` by
+      // default (a future `TriggerOptions.contactProperties` is deferred).
       await ingestEvent({
         db,
         registry,
@@ -307,7 +311,7 @@ export function createJourneyContext(
           event,
           userId: targetUserId,
           userEmail: targetEmail ?? userEmail,
-          properties: properties ?? {},
+          eventProperties: properties ?? {},
         },
       });
     },

package/src/lib/boot.ts

@@ -125,12 +125,20 @@ export interface WorkerReadyInfo {
   client: HogsendClient;
   journeyTasks: number;
   bucketTasks: number;
+  /** Reaction journey tasks generated by `bucket.on()` (Section 9). */
+  bucketReactionTasks: number;
   builtinTasks: number;
 }
 
 /** Render the worker "ready" output (banner in dev TTY, structured log otherwise). */
 export function reportWorkerReady(info: WorkerReadyInfo): void {
-  const { client, journeyTasks, bucketTasks, builtinTasks } = info;
+  const {
+    client,
+    journeyTasks,
+    bucketTasks,
+    bucketReactionTasks,
+    builtinTasks,
+  } = info;
   const engineVersion = getEngineVersion();
   const hatchetHost = client.env.HATCHET_CLIENT_HOST_PORT;
 
@@ -141,6 +149,7 @@ export function reportWorkerReady(info: WorkerReadyInfo): void {
       namespace: client.env.HATCHET_CLIENT_NAMESPACE || undefined,
       journeyTasks,
       bucketTasks,
+      bucketReactionTasks,
       builtinTasks,
     });
     return;
@@ -151,6 +160,7 @@ export function reportWorkerReady(info: WorkerReadyInfo): void {
   const tasks = [
     plural(journeyTasks, "journey task"),
     plural(bucketTasks, "bucket task"),
+    plural(bucketReactionTasks, "reaction task"),
     plural(builtinTasks, "built-in task"),
   ].join(dim(" · "));
 
@@ -161,6 +171,6 @@ export function reportWorkerReady(info: WorkerReadyInfo): void {
     `  ${ok} ${tasks}`,
     "",
     `  ${dim("Listening — journeys fire as events arrive.")}`,
-    `  ${dim("Send one:")} ${color.cyan("POST /v1/ingest")} ${dim("· or Studio › Debug")}`,
+    `  ${dim("Send one:")} ${color.cyan("POST /v1/events")} ${dim("· or Studio › Debug")}`,
   ]);
 }

package/src/lib/bucket-emit.ts

@@ -2,11 +2,12 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { BucketMeta } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import type { Database } from "@hogsend/db";
+import type { BucketLeaveReason } from "../buckets/bucket-reactions.js";
 import { syncBucketToPostHog } from "./bucket-posthog-sync.js";
 import { ingestEvent } from "./ingestion.js";
 import type { Logger } from "./logger.js";
 
-export type BucketTransitionKind = "entered" | "left";
+export type BucketTransitionKind = "entered" | "left" | "dwell";
 
 /** Where a transition originated — carried on the emitted event properties. */
 export type BucketTransitionSource =
@@ -40,6 +41,16 @@ export async function emitBucketTransition(opts: {
   userEmail: string | null;
   epoch: number;
   source?: BucketTransitionSource;
+  /** Carried on a `left` transition's properties → `ctx.reason`. */
+  reason?: BucketLeaveReason;
+  /** The dwell schedule label (`after-<ms>`/`every-<ms>`) — `dwell` only. */
+  dwellLabel?: string;
+  /**
+   * The deterministic dwell interval ordinal — `dwell` only. Rides the
+   * idempotencyKey so a same-sweep retry recomputes the identical key and is
+   * absorbed by the `userEvents` dedup. Surfaced as `dwellCount`.
+   */
+  dwellOrdinal?: number;
 }): Promise<void> {
   const {
     db,
@@ -52,22 +63,53 @@ export async function emitBucketTransition(opts: {
     userEmail,
     epoch,
     source = "event",
+    reason,
+    dwellLabel,
+    dwellOrdinal,
   } = opts;
 
+  // The dwell transition emits a labelled event so two dwell reactions on one
+  // bucket (one `after`, one `every`) route distinctly; enter/left keep the
+  // canonical `bucket:<kind>:<id>` form. The idempotencyKey is recomputed
+  // identically by a retry: enter/left key on the membership epoch, dwell keys
+  // on the (label, ordinal) so a same-sweep retry rides the userEvents dedup.
+  const eventName =
+    kind === "dwell"
+      ? `bucket:dwell:${bucket.id}:${dwellLabel}`
+      : `bucket:${kind}:${bucket.id}`;
+  const idempotencyKey =
+    kind === "dwell"
+      ? `bucket:${bucket.id}:${userId}:dwell:${dwellLabel}:${dwellOrdinal}`
+      : `bucket:${bucket.id}:${userId}:${kind}:${epoch}`;
+
   const properties: Record<string, unknown> = {
     bucketId: bucket.id,
     bucketName: bucket.name,
     userId,
     transition: kind,
     source,
+    // entryCount is always carried (the membership ordinal); the reaction `run`
+    // derives `isFirstEntry` from it.
+    entryCount: epoch,
   };
+  // reason is carried on a leave so the `leave` reaction can filter on it.
+  if (kind === "left" && reason != null) {
+    properties.reason = reason;
+  }
+  // dwellCount = the interval ordinal, surfaced to the dwell reaction.
+  if (kind === "dwell" && dwellOrdinal != null) {
+    properties.dwellCount = dwellOrdinal;
+  }
 
   // Optional PostHog person-property mirror (Section 12). Off by default; a
   // no-op without POSTHOG_API_KEY. Wired here, the single transition path shared
   // by all three producers (real-time / reconcile / fast-expiry), so the sync
   // fires exactly once per emitted transition. Best-effort — it never blocks the
-  // event emit below.
-  syncBucketToPostHog({ logger, kind, bucket, userId });
+  // event emit below. Dwell is a recurring membership-age tick, not a state
+  // change, so it does NOT mirror a person property.
+  if (kind === "entered" || kind === "left") {
+    syncBucketToPostHog({ logger, kind, bucket, userId });
+  }
 
   // Per-bucket alias — the recommended, narrowly-routed binding. The
   // deterministic idempotencyKey rides the userEvents dedup short-circuit as
@@ -78,11 +120,11 @@ export async function emitBucketTransition(opts: {
     hatchet,
     logger,
     event: {
-      event: `bucket:${kind}:${bucket.id}`,
+      event: eventName,
       userId,
       userEmail: userEmail ?? "",
-      properties,
-      idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}`,
+      eventProperties: properties,
+      idempotencyKey,
     },
   });
 
@@ -99,7 +141,7 @@ export async function emitBucketTransition(opts: {
         event: genericEvent,
         userId,
         userEmail: userEmail ?? "",
-        properties,
+        eventProperties: properties,
         idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}:generic`,
       },
     });