@hogsend/engine 0.6.0 → 0.7.0

package/src/lib/email-service-types.ts

@@ -53,6 +53,12 @@ export interface SendTrackedEmailOptions<
   replyTo?: string | string[];
   skipPreferenceCheck?: boolean;
   baseUrl?: string;
+  /**
+   * Caller-supplied idempotency key (POST /v1/emails). A retry with the same key
+   * short-circuits to the prior `email_sends` row instead of dispatching a
+   * duplicate provider send.
+   */
+  idempotencyKey?: string;
 }
 
 export interface TrackedSendResult {
@@ -128,6 +134,8 @@ export interface EmailServiceSendOptions<
   headers?: Record<string, string>;
   replyTo?: string | string[];
   skipPreferenceCheck?: boolean;
+  /** Caller-supplied idempotency key (POST /v1/emails) — dedups duplicate sends. */
+  idempotencyKey?: string;
 }
 
 export interface EmailServiceWebhookOptions {

package/src/lib/ingestion.ts

@@ -4,15 +4,27 @@ import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, journeyStates, userEvents } from "@hogsend/db";
 import { and, eq, inArray, isNull } from "drizzle-orm";
 import { checkBucketMembership } from "../buckets/check-membership.js";
-import { upsertContact } from "./contacts.js";
+import { resolveOrCreateContact } from "./contacts.js";
 import type { Logger } from "./logger.js";
 
 export interface IngestEvent {
   event: string;
-  userId: string;
-  userEmail: string;
-  properties: Record<string, unknown>;
+  /** D1: optional — email-only / anonymous events resolve a key downstream. */
+  userId?: string;
+  userEmail?: string;
+  /** D1: future anonymous→identified path. Threaded into the resolver. */
+  anonymousId?: string;
+  /** D2: → `user_events` + Hatchet `trigger.where`/`exitOn` ONLY. */
+  eventProperties: Record<string, unknown>;
+  /** D2: → `contacts.properties` merge ONLY. */
+  contactProperties?: Record<string, unknown>;
   idempotencyKey?: string;
+  /**
+   * Caller-supplied event time (§2.5 `timestamp`). When set, `user_events`
+   * `occurred_at` is stamped from it (backfill/replay) instead of defaulting to
+   * the ingest instant. Accepts a `Date` or an ISO-8601 string.
+   */
+  occurredAt?: Date | string;
 }
 
 export interface ExitResult {
@@ -35,14 +47,36 @@ export async function ingestEvent(opts: {
 }): Promise<IngestResult> {
   const { db, registry, hatchet, logger, event } = opts;
 
+  // (1) Resolve identity FIRST (awaited — no longer fire-and-forget). The
+  // contact-referencing tables join on a NOT NULL text key, so an email-only /
+  // anonymous event (D1 optional userId) needs a canonical key resolved before
+  // any insert (risk 2). The resolver applies ONLY contactProperties to
+  // `contacts.properties` (D2 split) and returns BOTH the canonical contact id
+  // AND its resolved string key (external_id ?? anonymous_id ?? contact.id —
+  // risk 1/6), so no second read-back of the contact row is needed.
+  const { resolvedKey } = await resolveOrCreateContact({
+    db,
+    userId: event.userId,
+    email: event.userEmail || undefined,
+    anonymousId: event.anonymousId,
+    contactProperties: event.contactProperties,
+  });
+
+  // Caller-supplied event time (backfill/replay). Coerced to a Date; undefined
+  // falls back to the `occurred_at` DB default (ingest instant).
+  const occurredAt = event.occurredAt ? new Date(event.occurredAt) : undefined;
+
+  // (2) Idempotency dedup + `user_events` insert keyed on the resolved key, with
+  // ONLY eventProperties in the properties bag (D2).
   if (event.idempotencyKey) {
     const result = await db
       .insert(userEvents)
       .values({
-        userId: event.userId,
+        userId: resolvedKey,
         event: event.event,
-        properties: event.properties,
+        properties: event.eventProperties,
         idempotencyKey: event.idempotencyKey,
+        ...(occurredAt ? { occurredAt } : {}),
       })
       .onConflictDoNothing({
         target: userEvents.idempotencyKey,
@@ -54,14 +88,17 @@ export async function ingestEvent(opts: {
     }
   } else {
     await db.insert(userEvents).values({
-      userId: event.userId,
+      userId: resolvedKey,
       event: event.event,
-      properties: event.properties,
+      properties: event.eventProperties,
+      ...(occurredAt ? { occurredAt } : {}),
     });
   }
 
+  // (3) Build the JSON-serializable subset of eventProperties for the Hatchet
+  // push payload (scalars only — the SDK serializes the envelope).
   const serializableProperties = Object.fromEntries(
-    Object.entries(event.properties).filter(
+    Object.entries(event.eventProperties).filter(
       ([, v]) =>
         typeof v === "string" ||
         typeof v === "number" ||
@@ -70,57 +107,50 @@ export async function ingestEvent(opts: {
     ),
   ) as Record<string, string | number | boolean | null>;
 
+  // (4) Hatchet push + (5) checkExits, both keyed on the resolved key. The push
+  // payload wire key STAYS `properties` (bucket tests assert on it — risk 9).
   const [, exits] = await Promise.all([
     hatchet.events.push(event.event, {
-      userId: event.userId,
-      userEmail: event.userEmail,
+      userId: resolvedKey,
+      userEmail: event.userEmail ?? "",
       properties: serializableProperties,
     }),
     checkExits(db, registry, hatchet, logger, {
-      userId: event.userId,
+      userId: resolvedKey,
       eventName: event.event,
-      properties: event.properties,
-    }),
-    upsertContact({
-      db,
-      externalId: event.userId,
-      email: event.userEmail || undefined,
-      properties: event.properties,
-    }).catch((err) => {
-      logger.warn("Contact upsert failed", {
-        userId: event.userId,
-        error: err instanceof Error ? err.message : String(err),
-      });
+      properties: event.eventProperties,
     }),
   ]);
 
-  // Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
-  // Promise.all above: its property eval reads MERGED contact state, and its
-  // bucket:entered/left emissions recurse back into ingestEvent (the recursion
-  // guard in checkBucketMembership bounds them). Best-effort: a bucket failure
-  // must not fail the ingest of the originating event.
+  // (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
+  // Promise.all above: its property eval reads contact state ⊕ this-ingest
+  // contactProperties patch, and its bucket:entered/left emissions recurse back
+  // into ingestEvent (the recursion guard in checkBucketMembership bounds them).
+  // Best-effort: a bucket failure must not fail the ingest of the originating
+  // event.
   try {
     await checkBucketMembership({
       db,
       registry,
       hatchet,
       logger,
-      userId: event.userId,
+      userId: resolvedKey,
       userEmail: event.userEmail || null,
       event: event.event,
-      properties: event.properties,
+      eventProperties: event.eventProperties,
+      contactProperties: event.contactProperties ?? {},
     });
   } catch (err) {
     logger.warn("Bucket membership check failed", {
       event: event.event,
-      userId: event.userId,
+      userId: resolvedKey,
       error: err instanceof Error ? err.message : String(err),
     });
   }
 
   logger.info("Event ingested", {
     event: event.event,
-    userId: event.userId,
+    userId: resolvedKey,
     exits: exits.filter((e) => e.exited).length,
   });
 

package/src/lib/mailer.ts

@@ -98,6 +98,7 @@ export function createTrackedMailer(
             headers: options.headers,
             replyTo: options.replyTo,
             skipPreferenceCheck: options.skipPreferenceCheck,
+            idempotencyKey: options.idempotencyKey,
             baseUrl: config.baseUrl,
           },
         });

package/src/lib/preferences.ts

@@ -0,0 +1,106 @@
+import type { Database } from "@hogsend/db";
+import { emailPreferences } from "@hogsend/db";
+import { sql } from "drizzle-orm";
+import { resolveRecipient } from "./contacts.js";
+
+/**
+ * Single source of truth for an `email_preferences` upsert: the `(user_id, email)`
+ * onConflict + the jsonb category-flip. Extracted from the private
+ * `upsertPreference` that used to live in `routes/email/unsubscribe.ts` (decision
+ * #9) so subscribe/unsubscribe routes, the preference center, list membership, and
+ * the unsubscribe-token flow all share ONE write.
+ *
+ * `externalId` is the `user_id` column value: the contact's `external_id` when it
+ * has one, else the contact `id` (uuid) fallback for an email-only contact (risk
+ * 10). `email` is REQUIRED — both columns are NOT NULL and form the PK.
+ */
+export async function upsertEmailPreference(opts: {
+  db: Database;
+  externalId: string;
+  email: string;
+  update: {
+    unsubscribedAll?: boolean;
+    suppressed?: boolean;
+    categoryKey?: string;
+    categoryValue?: boolean;
+  };
+}): Promise<void> {
+  const { db, externalId, email, update } = opts;
+
+  const setClause: Record<string, unknown> = { updatedAt: new Date() };
+
+  if (update.unsubscribedAll !== undefined) {
+    setClause.unsubscribedAll = update.unsubscribedAll;
+  }
+  if (update.suppressed !== undefined) {
+    setClause.suppressed = update.suppressed;
+  }
+  if (update.categoryKey !== undefined) {
+    const jsonValue = update.categoryValue ? "true" : "false";
+    setClause.categories = sql`jsonb_set(COALESCE(${emailPreferences.categories}, '{}'::jsonb), ${`{${update.categoryKey}}`}, ${jsonValue}::jsonb)`;
+  }
+
+  await db
+    .insert(emailPreferences)
+    .values({
+      userId: externalId,
+      email,
+      ...(update.unsubscribedAll !== undefined
+        ? { unsubscribedAll: update.unsubscribedAll }
+        : {}),
+      ...(update.suppressed !== undefined
+        ? { suppressed: update.suppressed }
+        : {}),
+      ...(update.categoryKey !== undefined
+        ? {
+            categories: { [update.categoryKey]: update.categoryValue ?? false },
+          }
+        : {}),
+    })
+    .onConflictDoUpdate({
+      target: [emailPreferences.userId, emailPreferences.email],
+      set: setClause,
+    });
+}
+
+/**
+ * D3 list-membership write. Resolves the caller's identity to the deterministic
+ * `(externalId | contactId fallback, email)` pair via `resolveRecipient`, then
+ * writes one category flip per list key through `upsertEmailPreference`.
+ *
+ * Requires a resolvable email — `email_preferences.email` is NOT NULL and the
+ * preference center / unsubscribe-token flow key on it (risk 10). The caller is
+ * expected to have already run `resolveOrCreateContact` (so the contact exists);
+ * this reads identity back. Throws if no email can be resolved — the route maps
+ * that to a 400 ("Contact has no email; cannot manage list membership").
+ */
+export async function applyListMembership(opts: {
+  db: Database;
+  userId?: string;
+  email?: string;
+  lists: Record<string, boolean>;
+}): Promise<void> {
+  const { db, userId, email, lists } = opts;
+
+  const entries = Object.entries(lists);
+  if (entries.length === 0) return;
+
+  const recipient = await resolveRecipient({ db, userId, email });
+  if (!recipient) {
+    throw new Error("Contact has no email; cannot manage list membership");
+  }
+
+  // `user_id` column = external_id when present, else the contact id (uuid)
+  // fallback — the SAME deterministic key used by subscribe writes,
+  // preference-center reads, and unsubscribe-token issuance (risk 10).
+  const externalId = recipient.externalId ?? recipient.contactId;
+
+  for (const [categoryKey, categoryValue] of entries) {
+    await upsertEmailPreference({
+      db,
+      externalId,
+      email: recipient.email,
+      update: { categoryKey, categoryValue },
+    });
+  }
+}

package/src/lib/tracked.ts

@@ -7,8 +7,13 @@ import type {
   TemplateName,
   TemplateRegistry,
 } from "@hogsend/email";
-import { getTemplate, renderToHtml } from "@hogsend/email";
+import {
+  generateUnsubscribeUrl,
+  getTemplate,
+  renderToHtml,
+} from "@hogsend/email";
 import { eq } from "drizzle-orm";
+import { getListRegistry } from "../lists/registry-singleton.js";
 import type {
   FrequencyCapConfig,
   SendTrackedEmailOptions,
@@ -50,11 +55,55 @@ export async function sendTrackedEmail<K extends TemplateName>(
     options,
   } = opts;
 
+  // The idempotency-collision result, built identically whether the prior row is
+  // found by the up-front short-circuit select OR the concurrent-insert loser
+  // path below: surface the winner's send id, mapping "sent" → sent and anything
+  // else → a skipped/"frequency_capped" placeholder.
+  const idempotentResult = (prior: {
+    id: string;
+    status: string;
+  }): TrackedSendResult =>
+    ({
+      emailSendId: prior.id,
+      resendId: "",
+      status: prior.status === "sent" ? "sent" : "skipped",
+      ...(prior.status === "sent" ? {} : { reason: "frequency_capped" }),
+    }) as TrackedSendResult;
+
+  // Idempotency short-circuit (POST /v1/emails): a retry with the same key
+  // returns the prior send instead of dispatching a duplicate provider call /
+  // tracking artifacts (mirrors the user_events idempotency pattern).
+  if (options.idempotencyKey) {
+    const existing = await db
+      .select({ id: emailSends.id, status: emailSends.status })
+      .from(emailSends)
+      .where(eq(emailSends.idempotencyKey, options.idempotencyKey))
+      .limit(1);
+    const prior = existing[0];
+    if (prior) {
+      return idempotentResult(prior);
+    }
+  }
+
+  // Resolve the template ONCE up front so its default category is available to
+  // the suppression check (a public /v1/emails send may omit `category`, in
+  // which case the per-category suppression must still consult the template's
+  // own category — otherwise an unsubscribed recipient leaks the mail while the
+  // row is stamped with that very category — risk 6 / §2.6).
+  const {
+    element,
+    subject: defaultSubject,
+    category: templateCategory,
+  } = getTemplate({ key: options.templateKey, props: options.props, registry });
+
+  const effectiveCategory = options.category ?? templateCategory;
+  const subject = options.subject ?? defaultSubject;
+
   if (!options.skipPreferenceCheck) {
     const suppression = await checkSuppression(
       db,
       options.to,
-      options.category,
+      effectiveCategory,
     );
     if (suppression) {
       const rows = await db
@@ -64,11 +113,14 @@ export async function sendTrackedEmail<K extends TemplateName>(
           fromEmail: options.from,
           toEmail: options.to,
           subject: options.subject ?? "",
-          category: options.category,
+          category: effectiveCategory,
           journeyStateId: options.journeyStateId,
           userId: options.userId,
           userEmail: options.userEmail ?? options.to,
           status: "failed",
+          // A suppressed send does NOT consume the idempotency key — leaving it
+          // unset lets a later retry (e.g. after the recipient re-subscribes)
+          // actually attempt the send rather than dedup to the suppressed row.
         })
         .returning({ id: emailSends.id });
 
@@ -89,6 +141,10 @@ export async function sendTrackedEmail<K extends TemplateName>(
     // Frequency cap — consulted only for non-system sends (system mail sets
     // skipPreferenceCheck and bypasses both suppression and the cap). On a cap
     // hit: no provider call, no row inserted, no throw — the journey continues.
+    // Keyed on the caller-supplied `options.category` (NOT the template default)
+    // so the cap's byCategory/exempt rules apply exactly to what the caller
+    // asked to cap — distinct from suppression, which needs the template default
+    // to honor a per-category unsubscribe even when the caller omits `category`.
     if (frequencyCap) {
       const capped = await isFrequencyCapped({
         db,
@@ -111,37 +167,91 @@ export async function sendTrackedEmail<K extends TemplateName>(
     }
   }
 
-  const {
-    element,
-    subject: defaultSubject,
-    category,
-  } = getTemplate({ key: options.templateKey, props: options.props, registry });
+  // Unsubscribe surface (RFC 8058 / CAN-SPAM): generate the per-recipient
+  // unsubscribe URL ONCE and inject it both as the in-body template prop AND the
+  // List-Unsubscribe / List-Unsubscribe-Post: One-Click headers, so EVERY send
+  // through the tracked mailer — journey AND public /v1/emails — carries it
+  // uniformly. Suppressed only for true system mail (skipPreferenceCheck). Built
+  // from the SAME user_id fallback (externalId ?? contactId) the email_sends row
+  // uses, keeping the token externalId consistent with the preference-center key.
+  const secret = process.env.BETTER_AUTH_SECRET;
+  let unsubscribeUrl: string | undefined;
+  if (!options.skipPreferenceCheck && options.baseUrl && secret) {
+    unsubscribeUrl = generateUnsubscribeUrl({
+      baseUrl: options.baseUrl,
+      secret,
+      externalId: options.userId ?? options.to,
+      email: options.to,
+      category: effectiveCategory,
+    });
+  }
 
-  const subject = options.subject ?? defaultSubject;
+  const sendHeaders: Record<string, string> = { ...(options.headers ?? {}) };
+  if (unsubscribeUrl && !("List-Unsubscribe" in sendHeaders)) {
+    sendHeaders["List-Unsubscribe"] = `<${unsubscribeUrl}>`;
+    sendHeaders["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
+  }
 
-  const insertRows = await db
-    .insert(emailSends)
-    .values({
-      templateKey: options.templateKey,
-      fromEmail: options.from,
-      toEmail: options.to,
-      subject,
-      category: options.category ?? category,
-      journeyStateId: options.journeyStateId,
-      userId: options.userId,
-      userEmail: options.userEmail ?? options.to,
-      status: "queued",
-    })
-    .returning({ id: emailSends.id });
+  // Re-render the template element with the unsubscribe URL merged into props so
+  // the in-body footer link renders for journeyless public sends too. Journey
+  // sends already pass `unsubscribeUrl` in props (lib/email.ts); only set it when
+  // the caller didn't, so we never clobber an explicitly-passed value.
+  const propsRecord = options.props as unknown as
+    | Record<string, unknown>
+    | undefined;
+  const sendElement =
+    unsubscribeUrl && propsRecord?.unsubscribeUrl == null
+      ? getTemplate({
+          key: options.templateKey,
+          props: {
+            ...(propsRecord ?? {}),
+            unsubscribeUrl,
+          } as unknown as typeof options.props,
+          registry,
+        }).element
+      : element;
+
+  const baseInsert = db.insert(emailSends).values({
+    templateKey: options.templateKey,
+    fromEmail: options.from,
+    toEmail: options.to,
+    subject,
+    category: effectiveCategory,
+    journeyStateId: options.journeyStateId,
+    userId: options.userId,
+    userEmail: options.userEmail ?? options.to,
+    status: "queued",
+    idempotencyKey: options.idempotencyKey,
+  });
+
+  // With an idempotency key, swallow a concurrent-insert collision on the unique
+  // index (the select-then-insert above is not atomic) and return the winner.
+  const insertRows = options.idempotencyKey
+    ? await baseInsert
+        .onConflictDoNothing({ target: emailSends.idempotencyKey })
+        .returning({ id: emailSends.id })
+    : await baseInsert.returning({ id: emailSends.id });
 
   const insertedRow = insertRows[0];
+  if (!insertedRow && options.idempotencyKey) {
+    // A concurrent send claimed the key first — return its row.
+    const winner = await db
+      .select({ id: emailSends.id, status: emailSends.status })
+      .from(emailSends)
+      .where(eq(emailSends.idempotencyKey, options.idempotencyKey))
+      .limit(1);
+    const won = winner[0];
+    if (won) {
+      return idempotentResult(won);
+    }
+  }
   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);
+      const rawHtml = await renderToHtml(sendElement);
       html = await prepareTrackedHtml({
         html: rawHtml,
         emailSendId,
@@ -154,9 +264,9 @@ export async function sendTrackedEmail<K extends TemplateName>(
       from: options.from,
       to: options.to,
       subject,
-      ...(html ? { html } : { react: element }),
+      ...(html ? { html } : { react: sendElement }),
       tags: options.tags,
-      headers: options.headers,
+      headers: sendHeaders,
       replyTo: options.replyTo,
     });
 
@@ -176,10 +286,18 @@ export async function sendTrackedEmail<K extends TemplateName>(
       status: "sent",
     };
   } catch (error) {
+    // A provider send failed (transient SMTP/network/429). Stamp `failed` AND
+    // RELEASE the idempotency key (set it null), exactly like the suppression
+    // path deliberately never consumes it: this lets a retry genuinely
+    // RE-ATTEMPT the send rather than dedup to this failed row. Without the
+    // release, the up-front short-circuit would return this `failed` row mapped
+    // to `skipped`, so a real delivery failure would (a) never be re-sent and
+    // (b) silently vanish from the campaign's failedCount into skippedCount.
     await db
       .update(emailSends)
       .set({
         status: "failed",
+        idempotencyKey: null,
         updatedAt: new Date(),
       })
       .where(eq(emailSends.id, emailSendId));
@@ -201,17 +319,24 @@ async function checkSuppression(
     .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 (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";
+  // Registry-aware polarity (§2.6, D3) — applied through the SINGLE source of
+  // truth `ListRegistry.isSubscribed` so it matches the preference center EXACTLY
+  // (categories default to `{}` when there is NO prefs row or NO categories map).
+  // This MUST run even when the row is absent/empty: an opt-out list
+  // (`defaultOptIn:false`) requires `categories[id] === true` to be subscribed,
+  // so absence-of-true (the common "never opted in" case) MUST block — otherwise
+  // a contact the preference center shows as "Unsubscribed" would still receive
+  // the mail (the two surfaces would disagree, which §2.6 forbids).
+  if (category) {
+    const categories = (prefs?.categories ?? {}) as Record<string, boolean>;
+    if (!getListRegistry().isSubscribed(categories, category)) {
+      return "category_unsubscribed";
+    }
   }
 
   return null;

package/src/lib/tracking-events.ts

@@ -78,7 +78,7 @@ export async function pushTrackingEvent(
       event,
       userId: ctx.userId,
       userEmail: ctx.userEmail,
-      properties,
+      eventProperties: properties,
     },
   });
 }

package/src/lists/define-list.ts

@@ -0,0 +1,81 @@
+/**
+ * Email lists (D3) — code-defined subscription categories layered on top of the
+ * existing `email_preferences.categories` JSONB. A list is just a named category
+ * with a declared default polarity (`defaultOptIn`); there is NO new table.
+ *
+ * `defineList()` is the authoring entry point, mirroring `defineBucket()` /
+ * `defineJourney()`: a synchronous, definition-time call that validates the id
+ * and returns a `DefinedList`. The id shares the `email_preferences.categories`
+ * key namespace, so two ids are RESERVED for the engine's own non-list
+ * categories (`transactional`, `journey`) and rejected here (open risk #11).
+ */
+
+/** A list id can collide with these built-in non-list categories — reject. */
+const RESERVED_LIST_IDS = new Set(["transactional", "journey"]);
+
+/** Allowed list-id shape: alphanumerics, dash, underscore (case-insensitive). */
+const LIST_ID_PATTERN = /^[a-z0-9_-]+$/i;
+
+/**
+ * The validated, fully-defaulted list metadata. `enabled` is always present
+ * after `defineList` (defaults to `true`); authoring input leaves it optional.
+ */
+export interface ListMeta<Id extends string = string> {
+  id: Id;
+  name: string;
+  description?: string;
+  defaultOptIn: boolean;
+  enabled: boolean;
+}
+
+/**
+ * A defined list. `meta` carries the canonical, defaulted metadata; `id` is
+ * surfaced directly for literal-typed consumption (mirrors `DefinedBucket`).
+ */
+export interface DefinedList<Id extends string = string> {
+  readonly meta: ListMeta<Id>;
+  readonly id: Id;
+}
+
+/**
+ * Define an email list. Validates the id against {@link LIST_ID_PATTERN} and the
+ * {@link RESERVED_LIST_IDS} blocklist (since list ids share the
+ * `email_preferences.categories` namespace), then returns a `DefinedList` with
+ * `enabled` defaulted to `true`.
+ *
+ * @throws if `id` is empty, malformed, or a reserved category id.
+ */
+export function defineList<const Id extends string>(meta: {
+  id: Id;
+  name: string;
+  description?: string;
+  defaultOptIn: boolean;
+  enabled?: boolean;
+}): DefinedList<Id> {
+  const { id, name, description, defaultOptIn, enabled } = meta;
+
+  if (!id || !LIST_ID_PATTERN.test(id)) {
+    throw new Error(
+      `Invalid list id "${id}": must match /^[a-z0-9_-]+$/i (letters, digits, "-", "_").`,
+    );
+  }
+
+  if (RESERVED_LIST_IDS.has(id.toLowerCase())) {
+    throw new Error(
+      `Reserved list id "${id}": "transactional" and "journey" are built-in email-preference categories and cannot be used as list ids.`,
+    );
+  }
+
+  const resolvedMeta: ListMeta<Id> = {
+    id,
+    name,
+    ...(description !== undefined ? { description } : {}),
+    defaultOptIn,
+    enabled: enabled ?? true,
+  };
+
+  return {
+    meta: resolvedMeta,
+    id,
+  };
+}