@hogsend/engine 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -37,11 +37,11 @@
     "resend": "^6.12.3",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.6.0",
-    "@hogsend/db": "^0.6.0",
-    "@hogsend/email": "^0.6.0",
-    "@hogsend/plugin-posthog": "^0.6.0",
-    "@hogsend/plugin-resend": "^0.6.0"
+    "@hogsend/core": "^0.7.0",
+    "@hogsend/db": "^0.7.0",
+    "@hogsend/email": "^0.7.0",
+    "@hogsend/plugin-posthog": "^0.7.0",
+    "@hogsend/plugin-resend": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/buckets/check-membership.ts

@@ -51,7 +51,16 @@ export async function checkBucketMembership(opts: {
   userId: string;
   userEmail: string | null;
   event: string;
-  properties: Record<string, unknown>;
+  /**
+   * D2: the event payload — candidate-narrowing ONLY. It NO LONGER participates
+   * in property eval (the raw-payload overlay was the bucket-side conflation).
+   */
+  eventProperties: Record<string, unknown>;
+  /**
+   * D2: this-ingest contact-property patch, overlaid on the read contact row so
+   * the very first event after a property change evaluates correctly (risk 7).
+   */
+  contactProperties?: Record<string, unknown>;
   /** Optional override; defaults to the process bucket-registry singleton. */
   bucketRegistry?: ReturnType<typeof getBucketRegistrySingleton>;
 }): Promise<BucketTransition[]> {
@@ -63,7 +72,8 @@ export async function checkBucketMembership(opts: {
     userId,
     userEmail,
     event,
-    properties,
+    eventProperties,
+    contactProperties: contactPropertiesPatch,
   } = opts;
 
   // (1) Recursion guard — MUST be first. bucket:-prefixed events are transition
@@ -81,12 +91,18 @@ export async function checkBucketMembership(opts: {
 
   // (2) Candidate narrowing — the UNION of buckets referencing this event name
   // (eventIndex + the degenerate wildcard set) and buckets referencing any
-  // property present in this payload (propertyIndex). Section 6.2.
+  // property present in EITHER bag (propertyIndex): the eventProperties drive
+  // event-shaped criteria narrowing, the contactProperties patch surfaces a
+  // contact-property change so a property-criteria bucket is re-checked on the
+  // first event that mutates it. Section 6.2.
   const candidateMap = new Map<string, BucketMeta>();
   for (const bucket of bucketRegistry.getByReferencedEvent(event)) {
     candidateMap.set(bucket.id, bucket);
   }
-  for (const key of Object.keys(properties ?? {})) {
+  for (const key of [
+    ...Object.keys(eventProperties ?? {}),
+    ...Object.keys(contactPropertiesPatch ?? {}),
+  ]) {
     for (const bucket of bucketRegistry.getByReferencedProperty(key)) {
       candidateMap.set(bucket.id, bucket);
     }
@@ -109,19 +125,20 @@ export async function checkBucketMembership(opts: {
     return [];
   }
 
-  // (3) Property predicates evaluate against MERGED contact state, NOT the bare
-  // event payload (Section 6.1 rule #3). Read the EXISTING contacts row ONCE iff
-  // any surviving candidate references a property — pure event/count buckets skip
-  // the read entirely. We read the row that already exists (not the one
-  // upsertContact is concurrently writing) so we do not depend on the
-  // fire-and-forget upsert having run.
+  // (3) Property predicates evaluate against contact state ⊕ this-ingest
+  // contactProperties patch — NOT the raw event payload (Section 6.1 rule #3 /
+  // D2). Read the EXISTING contacts row ONCE iff any surviving candidate
+  // references a property — pure event/count buckets skip the read entirely.
+  // `ingestEvent` already awaited `resolveOrCreateContact` before us, so the row
+  // exists by the resolved key; the patch overlay still covers the read-after-
+  // write gap on a contact's very first event (risk 7).
   const needsContactState = candidates.some(
     (bucket) =>
       bucket.criteria != null &&
       collectPropertyNames(bucket.criteria).length > 0,
   );
 
-  let contactProperties: Record<string, unknown> = {};
+  let storedContactProps: Record<string, unknown> = {};
   let contactDeleted = false;
   if (needsContactState) {
     const [contact] = await db
@@ -133,7 +150,7 @@ export async function checkBucketMembership(opts: {
       .where(eq(contacts.externalId, userId))
       .limit(1);
     if (contact) {
-      contactProperties =
+      storedContactProps =
         (contact.properties as Record<string, unknown> | null) ?? {};
       contactDeleted = contact.deletedAt != null;
     }
@@ -144,10 +161,12 @@ export async function checkBucketMembership(opts: {
     return [];
   }
 
-  // event payload overlays cumulative contact state.
+  // this-ingest contactProperties patch overlays stored contact state. The raw
+  // event payload is REMOVED from property eval (D2 — bucket prop-criteria see
+  // contact state only).
   const journeyContext: Record<string, unknown> = {
-    ...contactProperties,
-    ...(properties ?? {}),
+    ...storedContactProps,
+    ...(contactPropertiesPatch ?? {}),
   };
 
   const transitions: BucketTransition[] = [];

package/src/container.ts

@@ -36,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". */
@@ -70,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`),
@@ -91,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
@@ -131,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).
@@ -237,6 +259,15 @@ export function createHogsendClient(
     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 =
     opts.email?.provider ??
     createResendProvider({
@@ -293,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,
@@ -306,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

@@ -175,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,
@@ -200,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

@@ -171,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

@@ -123,7 +123,7 @@ export async function emitBucketTransition(opts: {
       event: eventName,
       userId,
       userEmail: userEmail ?? "",
-      properties,
+      eventProperties: properties,
       idempotencyKey,
     },
   });
@@ -141,7 +141,7 @@ export async function emitBucketTransition(opts: {
         event: genericEvent,
         userId,
         userEmail: userEmail ?? "",
-        properties,
+        eventProperties: properties,
         idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}:generic`,
       },
     });