@hogsend/engine 0.6.0 → 0.8.0

package/src/lib/tracked.ts

@@ -7,15 +7,28 @@ 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,
   TrackedSendResult,
 } from "./email-service-types.js";
 import { isFrequencyCapped } from "./frequency-cap.js";
-import type { Logger } from "./logger.js";
+import { hatchet } from "./hatchet.js";
+import { createLogger, type Logger } from "./logger.js";
+import { emitOutbound } from "./outbound.js";
+
+// Module-level fallback logger for the outbound emit — the tracked-mailer's
+// `logger` dep is optional, but `emitOutbound` requires one. Mirrors the
+// `createLogger(process.env.LOG_LEVEL)` singleton pattern used elsewhere in the
+// engine libs (define-journey, preferences).
+const emitLogger = createLogger(process.env.LOG_LEVEL);
 
 export type PrepareTrackedHtmlFn = (opts: {
   html: string;
@@ -50,11 +63,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 +121,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 +149,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 +175,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,32 +272,74 @@ 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,
     });
 
+    const sentAt = new Date();
     await db
       .update(emailSends)
       .set({
         resendId: result.id,
         status: "sent",
-        sentAt: new Date(),
-        updatedAt: new Date(),
+        sentAt,
+        updatedAt: sentAt,
       })
       .where(eq(emailSends.id, emailSendId));
 
+    // OUTBOUND `email.sent` — fired ONLY on a real provider-accepted send (this
+    // success branch). Suppressed/frequency-capped/failed branches and the
+    // `db === undefined` mailer fallback do NOT reach here, so they never emit.
+    // `dedupeKey` = `email.sent:<emailSendId>`: this runs inside the tracked
+    // mailer which a journey (a Hatchet-retryable durable task) invokes, so a
+    // re-execution recomputes the identical key and the unique
+    // `(endpointId, dedupeKey)` index absorbs the duplicate. STRICTLY
+    // fire-and-forget: an un-caught reject here would bubble into the catch below
+    // and wrongly re-mark the (already sent) row `failed` (risk 2).
+    void emitOutbound({
+      db,
+      hatchet,
+      logger: logger ?? emitLogger,
+      event: "email.sent",
+      dedupeKey: `email.sent:${emailSendId}`,
+      payload: {
+        emailSendId,
+        resendId: result.id,
+        templateKey: options.templateKey,
+        to: options.to,
+        userId: options.userId ?? null,
+        category: effectiveCategory ?? null,
+        journeyStateId: options.journeyStateId ?? null,
+        subject,
+        sentAt: sentAt.toISOString(),
+      },
+    }).catch((err: unknown) => {
+      (logger ?? emitLogger).warn("emitOutbound email.sent failed", {
+        emailSendId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+
     return {
       emailSendId,
       resendId: result.id,
       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 +361,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

@@ -10,6 +10,8 @@ interface EmailSendContext {
   userId: string;
   userEmail: string;
   templateKey: string | null;
+  resendId: string | null;
+  to: string;
 }
 
 export async function resolveEmailSendContext(
@@ -20,6 +22,7 @@ export async function resolveEmailSendContext(
     .select({
       toEmail: emailSends.toEmail,
       templateKey: emailSends.templateKey,
+      resendId: emailSends.resendId,
       userId: journeyStates.userId,
       userEmail: journeyStates.userEmail,
     })
@@ -35,6 +38,58 @@ export async function resolveEmailSendContext(
     userId: row.userId ?? row.toEmail,
     userEmail: row.userEmail ?? row.toEmail,
     templateKey: row.templateKey,
+    resendId: row.resendId,
+    to: row.toEmail,
+  };
+}
+
+export interface ResendEmailSendContext {
+  emailSendId: string;
+  userId: string;
+  userEmail: string;
+  templateKey: string | null;
+  to: string;
+}
+
+/**
+ * Mirror of {@link resolveEmailSendContext} that resolves by the provider's
+ * `resendId` instead of the internal `email_sends.id`. Used by the
+ * provider-webhook enrichment path (`email.delivered`/`email.bounced`) where the
+ * only handle we hold is the Resend `email_id`.
+ *
+ * Returns the internal `emailSendId` plus the same denormalized identity
+ * (`userId`/`userEmail` fall back to the recipient address, exactly like the
+ * id-keyed resolver) and `to` recipient. Returns null when no send row carries
+ * that `resendId` yet (e.g. a webhook arriving before the send row is committed).
+ */
+export async function resolveEmailSendContextByResendId(
+  db: Database,
+  resendId: string,
+): Promise<ResendEmailSendContext | null> {
+  const rows = await db
+    .select({
+      emailSendId: emailSends.id,
+      toEmail: emailSends.toEmail,
+      templateKey: emailSends.templateKey,
+      userId: journeyStates.userId,
+      userEmail: journeyStates.userEmail,
+      sendUserId: emailSends.userId,
+      sendUserEmail: emailSends.userEmail,
+    })
+    .from(emailSends)
+    .leftJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
+    .where(eq(emailSends.resendId, resendId))
+    .limit(1);
+
+  const row = rows[0];
+  if (!row) return null;
+
+  return {
+    emailSendId: row.emailSendId,
+    userId: row.userId ?? row.sendUserId ?? row.toEmail,
+    userEmail: row.userEmail ?? row.sendUserEmail ?? row.toEmail,
+    templateKey: row.templateKey,
+    to: row.toEmail,
   };
 }
 
@@ -47,6 +102,13 @@ export interface PushTrackingEventOpts {
   event: string;
   emailSendId: string;
   properties?: Record<string, unknown>;
+  /**
+   * Pre-resolved send context. When provided (including `null`), the duplicate
+   * `resolveEmailSendContext` read is skipped — the tracking routes resolve once
+   * and share the result with the outbound emit on the hot path. Omit to resolve
+   * lazily.
+   */
+  resolvedContext?: EmailSendContext | null;
 }
 
 export async function pushTrackingEvent(
@@ -54,7 +116,10 @@ export async function pushTrackingEvent(
 ): Promise<void> {
   const { db, hatchet, registry, logger, posthog, event, emailSendId } = opts;
 
-  const ctx = await resolveEmailSendContext(db, emailSendId);
+  const ctx =
+    opts.resolvedContext !== undefined
+      ? opts.resolvedContext
+      : await resolveEmailSendContext(db, emailSendId);
   if (!ctx) return;
 
   const properties: Record<string, unknown> = {
@@ -78,7 +143,7 @@ export async function pushTrackingEvent(
       event,
       userId: ctx.userId,
       userEmail: ctx.userEmail,
-      properties,
+      eventProperties: properties,
     },
   });
 }

package/src/lib/webhook-signing.ts

@@ -0,0 +1,151 @@
+import { randomBytes } from "node:crypto";
+import { Webhook } from "svix";
+
+/**
+ * Outbound webhook signing core.
+ *
+ * Hogsend emits a Svix-style HMAC-SHA256 signed event stream. The signing
+ * scheme is the Standard Webhooks spec (the same one `svix` implements and that
+ * `plugin-resend` consumes for inbound Resend webhooks):
+ *
+ *   signedContent = `${id}.${timestampSeconds}.${body}`
+ *   signature     = base64( HMAC_SHA256( base64decode(secret without `whsec_`), signedContent ) )
+ *   header value  = `v1,${signature}`
+ *
+ * Pure `node:crypto` equivalent (documented for the SDK / spec consumers and
+ * subscriber-side verification without a `svix` dependency):
+ *
+ *   import { createHmac, timingSafeEqual } from "node:crypto";
+ *   const key = Buffer.from(secret.slice(6), "base64"); // drop the `whsec_` prefix
+ *   const sig = createHmac("sha256", key)
+ *     .update(`${id}.${ts}.${body}`)
+ *     .digest("base64");
+ *   const header = `v1,${sig}`;
+ *   // compare each space-delimited `v1,<sig>` candidate with timingSafeEqual.
+ */
+
+/**
+ * The 12-event catalog — the SINGLE source of truth (schema, routes, client,
+ * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
+ * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
+ */
+export const WEBHOOK_EVENT_TYPES = [
+  "contact.created",
+  "contact.updated",
+  "contact.deleted",
+  "contact.unsubscribed",
+  "email.sent",
+  "email.delivered",
+  "email.opened",
+  "email.clicked",
+  "email.bounced",
+  "journey.completed",
+  "bucket.entered",
+  "bucket.left",
+] as const;
+
+export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
+
+/**
+ * Generate a new `whsec_<base64(32 bytes)>` signing secret plus its display
+ * prefix (safe to surface on list/get responses).
+ *
+ * NOTE: the secret body is STANDARD base64, not base64url. svix (via
+ * standardwebhooks → @stablelib/base64) strips the `whsec_` prefix and decodes
+ * the remainder with a STRICT standard-base64 decoder that rejects the `-`/`_`
+ * characters base64url emits (~74% of base64url secrets contain one and fail
+ * `new Webhook(secret)`). Standard base64 round-trips cleanly through both svix
+ * and the `node:crypto` fallback (`Buffer.from(secret.slice(6), "base64")`).
+ */
+export function generateWebhookSecret(): {
+  secret: string;
+  secretPrefix: string;
+} {
+  const secret = `whsec_${randomBytes(32).toString("base64")}`;
+  return { secret, secretPrefix: secret.slice(0, 12) };
+}
+
+export interface SignedWebhook {
+  headers: {
+    "Webhook-Id": string;
+    "Webhook-Timestamp": string;
+    "Webhook-Signature": string;
+    "Content-Type": "application/json";
+  };
+  /**
+   * The EXACT bytes that were signed AND must be sent. Never re-stringify the
+   * payload between signing and sending — the signature covers these bytes.
+   */
+  body: string;
+}
+
+/**
+ * Sign an outbound webhook payload, producing the Standard Webhooks header set
+ * (`Webhook-Id` / `Webhook-Timestamp` / `Webhook-Signature`) plus the exact
+ * `body` bytes that were signed.
+ *
+ * `timestamp` is unix SECONDS — the caller passes `Math.floor(Date.now()/1000)`.
+ * `payload` is JSON-stringified when an object; a string is used verbatim.
+ */
+export function signWebhook(opts: {
+  id: string;
+  timestamp: number;
+  payload: unknown;
+  secret: string;
+}): SignedWebhook {
+  const body =
+    typeof opts.payload === "string"
+      ? opts.payload
+      : JSON.stringify(opts.payload);
+
+  const wh = new Webhook(opts.secret);
+  // svix's `sign` takes the timestamp as a Date and floors it to seconds
+  // internally; pass the canonical seconds back through a Date to keep the exact
+  // value the caller intended.
+  const signature = wh.sign(opts.id, new Date(opts.timestamp * 1000), body);
+
+  return {
+    headers: {
+      "Webhook-Id": opts.id,
+      "Webhook-Timestamp": String(opts.timestamp),
+      "Webhook-Signature": signature,
+      "Content-Type": "application/json",
+    },
+    body,
+  };
+}
+
+/**
+ * Consumer/test-facing verification of an inbound Hogsend webhook. Enforces the
+ * 5-minute timestamp tolerance and uses a constant-time signature compare (both
+ * inside svix). Throws on a bad signature or stale timestamp.
+ *
+ * Accepts either Title-Case (`Webhook-Id`) or lowercase (`webhook-id`) header
+ * keys — and the `svix-*` aliases — by normalizing the header map first.
+ */
+export function verifyWebhookSignature(opts: {
+  payload: string;
+  headers: Record<string, string>;
+  secret: string;
+}): unknown {
+  const lowered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(opts.headers)) {
+    lowered[key.toLowerCase()] = value;
+  }
+
+  // Coalesce to "" so a genuinely-absent header reaches svix as an empty
+  // string — svix then throws its own clear "Missing required header" rather
+  // than a type error here.
+  const id = lowered["webhook-id"] ?? lowered["svix-id"] ?? "";
+  const timestamp =
+    lowered["webhook-timestamp"] ?? lowered["svix-timestamp"] ?? "";
+  const signature =
+    lowered["webhook-signature"] ?? lowered["svix-signature"] ?? "";
+
+  const wh = new Webhook(opts.secret);
+  return wh.verify(opts.payload, {
+    "webhook-id": id,
+    "webhook-timestamp": timestamp,
+    "webhook-signature": signature,
+  });
+}

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,
+  };
+}