@hogsend/engine 0.0.1 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -35,11 +35,11 @@
     "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"
+    "@hogsend/core": "^0.1.0",
+    "@hogsend/db": "^0.1.0",
+    "@hogsend/email": "^0.1.0",
+    "@hogsend/plugin-posthog": "^0.1.0",
+    "@hogsend/plugin-resend": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/app.ts

@@ -1,3 +1,4 @@
+import { user } from "@hogsend/db";
 import { OpenAPIHono } from "@hono/zod-openapi";
 import { apiReference } from "@scalar/hono-api-reference";
 import { compress } from "hono/compress";
@@ -8,6 +9,7 @@ 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 { mountStudio } from "./lib/studio.js";
 import type { ApiKeyContext } from "./middleware/api-key.js";
 import { errorHandler } from "./middleware/error-handler.js";
 import { requestLogger } from "./middleware/request-logger.js";
@@ -64,13 +66,48 @@ export function createApp(
     return c.json({ error: "Not Found" }, 404);
   });
 
+  // Closed signup: the first user may register (first-load "create admin");
+  // once any user exists, sign-up is blocked. This is the security control that
+  // lets `requireAdmin` trust any authenticated session in a single-tenant app.
+  app.use("/api/auth/sign-up/*", async (c, next) => {
+    if (c.req.method === "POST") {
+      const { db } = c.get("container");
+      const existing = await db.select({ id: user.id }).from(user).limit(1);
+      if (existing.length > 0) {
+        return c.json(
+          { error: "Sign-ups are closed. An admin already exists." },
+          403,
+        );
+      }
+    }
+    return next();
+  });
+
   app.on(["POST", "GET"], "/api/auth/*", (c) => {
     const { auth } = c.get("container");
     return auth.handler(c.req.raw);
   });
 
+  // Public bootstrap probe: tells the Studio whether to show the first-run
+  // "create admin" screen (no users yet) instead of the login screen.
+  app.get("/v1/auth/status", async (c) => {
+    const { db } = c.get("container");
+    const existing = await db.select({ id: user.id }).from(user).limit(1);
+    return c.json({ needsSetup: existing.length === 0 });
+  });
+
   registerRoutes(app, { webhookSources: opts.webhookSources ?? [] });
 
+  // Serve the Studio SPA at /studio/* (static layer, no auth — the SPA gates
+  // itself via /v1/auth/status + login; data endpoints stay behind requireAdmin).
+  // No-op when no built dist is present, so an unbuilt studio never crashes boot.
+  const studio = mountStudio(app);
+  if (studio.mounted) {
+    container.logger.info(
+      `Studio mounted at /studio (dist: ${studio.distPath})`,
+    );
+  }
+
   opts.routes?.(app);
 
   if (container.env.NODE_ENV !== "production") {

package/src/container.ts

@@ -1,5 +1,7 @@
 import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { TimeZone } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
+import type { SendWindow } from "@hogsend/core/schedule";
 import {
   createDatabase,
   type Database,
@@ -15,17 +17,30 @@ import {
 } from "@hogsend/plugin-resend";
 import type { Resend } from "resend";
 import { env } from "./env.js";
+import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.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 type {
+  EmailService,
+  FrequencyCapConfig,
+} 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 HogsendDefaults {
+  /** Global fallback IANA timezone for scheduling. Defaults to "UTC". */
+  timezone: TimeZone;
+  /** Default quiet-hours / send window auto-applied by `ctx.when`. */
+  sendWindow?: SendWindow;
+  /** Optional per-recipient frequency cap enforced in the mailer. */
+  frequencyCap?: FrequencyCapConfig;
+}
+
 export interface HogsendClient {
   env: typeof env;
   logger: Logger;
@@ -34,6 +49,13 @@ export interface HogsendClient {
   auth: Auth;
   email: Resend;
   emailService: EmailService;
+  /**
+   * The app's template registry (key → component + subject + category +
+   * optional preview/examples). Same object threaded into the engine mailer;
+   * exposed here so admin preview/catalog routes can enumerate keys and render
+   * templates without going through a send. Empty when no templates are wired.
+   */
+  templates: TemplateRegistry;
   analytics?: PostHogService;
   registry: JourneyRegistry;
   hatchet: HatchetClient;
@@ -44,6 +66,12 @@ export interface HogsendClient {
    * track. The CLIENT track never gates boot (client-owned); engine does.
    */
   clientJournal: JournalShape;
+  /**
+   * Resolved scheduling + frequency-cap defaults. `timezone` always has a value
+   * ("UTC" when unset). Read by the journey context (tz/window) and the mailer
+   * (frequency cap).
+   */
+  defaults: HogsendDefaults;
 }
 
 export interface HogsendClientOptions {
@@ -89,6 +117,22 @@ export interface HogsendClientOptions {
    * Defaults to `{ entries: [] }` (empty client track ⇒ trivially in sync).
    */
   clientJournal?: JournalShape;
+  /**
+   * Declarative scheduling + delivery defaults.
+   *
+   * - `timezone` — global fallback IANA tz (e.g. "UTC"), the terminal step of
+   *   the per-user tz resolution chain.
+   * - `sendWindow` — quiet-hours window ("HH:mm".."HH:mm") auto-applied by
+   *   `ctx.when` so scheduled instants land inside the window. Enforced ONLY at
+   *   the scheduling layer; immediate transactional sends bypass it.
+   * - `frequencyCap` — per-recipient send cap enforced in the mailer choke
+   *   point. Opt-in; "transactional" is exempt by default.
+   */
+  defaults?: {
+    timezone?: TimeZone;
+    sendWindow?: SendWindow;
+    frequencyCap?: FrequencyCapConfig;
+  };
   /**
    * Genuinely advanced / test-only seams. You probably don't need these —
    * prefer the first-class `email` / `analytics` args above.
@@ -117,6 +161,18 @@ export function createHogsendClient(
       db,
       secret: env.BETTER_AUTH_SECRET,
       baseURL: env.BETTER_AUTH_URL,
+      // Always trust the public API origin; add any explicitly configured ones
+      // (e.g. a remote Studio origin) on top. baseURL is trusted automatically.
+      trustedOrigins: Array.from(
+        new Set(
+          [
+            env.API_PUBLIC_URL,
+            ...(env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",") ?? []),
+          ]
+            .map((o) => o.trim())
+            .filter(Boolean),
+        ),
+      ),
     });
 
   const email = createResendClient({ apiKey: env.RESEND_API_KEY });
@@ -133,16 +189,33 @@ export function createHogsendClient(
       webhookSecret: env.RESEND_WEBHOOK_SECRET,
     });
 
+  const defaults: HogsendDefaults = {
+    timezone: opts.defaults?.timezone ?? "UTC",
+    sendWindow: opts.defaults?.sendWindow,
+    frequencyCap: opts.defaults?.frequencyCap,
+  };
+
+  // Expose the scheduling slice to the module-level journey task, which has no
+  // client reference of its own.
+  setClientScheduleDefaults({
+    timezone: defaults.timezone,
+    sendWindow: defaults.sendWindow,
+  });
+
+  const templates = opts.email?.templates ?? ({} as TemplateRegistry);
+
   const emailService =
     opts.overrides?.mailer ??
     createTrackedMailer(
       {
         defaultFrom: env.RESEND_FROM_EMAIL,
-        templates: opts.email?.templates ?? ({} as TemplateRegistry),
+        templates,
         db,
         webhookSecret: env.RESEND_WEBHOOK_SECRET,
         bounceThreshold: 3,
         baseUrl: env.API_PUBLIC_URL,
+        frequencyCap: defaults.frequencyCap,
+        logger,
       },
       {
         provider,
@@ -164,9 +237,11 @@ export function createHogsendClient(
     auth,
     email,
     emailService,
+    templates,
     analytics,
     registry,
     hatchet: opts.overrides?.hatchet ?? hatchet,
     clientJournal: opts.clientJournal ?? { entries: [] },
+    defaults,
   };
 }

package/src/env.ts

@@ -16,6 +16,10 @@ export const env = createEnv({
     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"),
+    // Extra origins allowed to call the auth endpoints (beyond BETTER_AUTH_URL),
+    // comma-separated. Needed when the Studio is served from a different origin
+    // than the API — e.g. the `hogsend studio` CLI pointing at a remote instance.
+    BETTER_AUTH_TRUSTED_ORIGINS: z.string().optional(),
     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

package/src/index.ts

@@ -23,6 +23,7 @@ export {
   createHogsendClient,
   type HogsendClient,
   type HogsendClientOptions,
+  type HogsendDefaults,
 } from "./container.js";
 // --- Env ---
 export { API_VERSION, env } from "./env.js";
@@ -65,11 +66,14 @@ export type {
   EmailServiceSendOptions,
   EmailServiceWebhookOptions,
   EmailServiceWebhookResult,
+  FrequencyCapConfig,
+  FrequencyCapWindow,
   SendTrackedEmailOptions,
   TrackedSendResult,
 } from "./lib/email-service-types.js";
 // --- Enrollment guards ---
 export { checkEmailPreferences } from "./lib/enrollment-guards.js";
+export { isFrequencyCapped } from "./lib/frequency-cap.js";
 export { hatchet } from "./lib/hatchet.js";
 // --- Ingestion pipeline ---
 export {
@@ -82,6 +86,15 @@ 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 MountStudioResult, mountStudio } from "./lib/studio.js";
+export {
+  type ResolveTimezoneInput,
+  type ResolveTimezoneResult,
+  resolveTimezone,
+  resolveTimezoneWithSource,
+  setContactTimezone,
+  type TimezoneSource,
+} from "./lib/timezone.js";
 export {
   type PrepareTrackedHtmlFn,
   sendTrackedEmail,

package/src/journeys/client-defaults-singleton.ts

@@ -0,0 +1,29 @@
+import type { SendWindow } from "@hogsend/core/schedule";
+
+/**
+ * The scheduling-relevant slice of the client `defaults`, set once by
+ * `createHogsendClient` and read by the module-level journey task in
+ * `define-journey` (which has no client reference of its own). Frequency-cap
+ * config is threaded through the mailer, not here.
+ */
+export interface ClientScheduleDefaults {
+  timezone: string;
+  sendWindow?: SendWindow;
+}
+
+let _defaults: ClientScheduleDefaults = { timezone: "UTC" };
+
+export function setClientScheduleDefaults(
+  defaults: ClientScheduleDefaults,
+): void {
+  _defaults = defaults;
+}
+
+export function getClientScheduleDefaults(): ClientScheduleDefaults {
+  return _defaults;
+}
+
+/** Reset to the UTC default — only for test cleanup. */
+export function resetClientScheduleDefaults(): void {
+  _defaults = { timezone: "UTC" };
+}

package/src/journeys/define-journey.ts

@@ -5,7 +5,7 @@ import type {
   JourneyRunFn,
   JourneyUser,
 } from "@hogsend/core/types";
-import { journeyConfigs, journeyStates } from "@hogsend/db";
+import { contacts, journeyConfigs, journeyStates } from "@hogsend/db";
 import { and, eq, inArray } from "drizzle-orm";
 import { getDb } from "../lib/db.js";
 import {
@@ -15,6 +15,8 @@ import {
 import { hatchet } from "../lib/hatchet.js";
 import { createLogger } from "../lib/logger.js";
 import { getPostHog } from "../lib/posthog.js";
+import { resolveTimezoneWithSource } from "../lib/timezone.js";
+import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
 import { createJourneyContext } from "./journey-context.js";
 import { getJourneyRegistrySingleton } from "./registry-singleton.js";
 
@@ -127,17 +129,58 @@ export function defineJourney(options: {
         journeyName: meta.name,
       };
 
+      const posthog = getPostHog();
+      const scheduleDefaults = getClientScheduleDefaults();
+
+      // Resolve the user's timezone via the precedence chain (explicit is N/A
+      // at enrollment; PostHog person props → contacts row → client default →
+      // UTC). Best-effort: failures fall through to the client default tz.
+      // Independent I/O — fetch the contact row and PostHog person props
+      // concurrently. PostHog failures fall through to undefined.
+      const [contact, posthogProperties] = await Promise.all([
+        db.query.contacts.findFirst({
+          where: eq(contacts.externalId, userId),
+        }),
+        posthog?.getPersonProperties(userId).catch(() => undefined),
+      ]);
+
+      const tz = resolveTimezoneWithSource({
+        posthogProperties,
+        contactTimezone: contact?.timezone ?? null,
+        contactProperties: contact?.properties ?? null,
+        defaultTimezone: scheduleDefaults.timezone,
+        logger,
+      });
+
+      // Opportunistic cache write: when the tz came from a PostHog source and
+      // the contacts.timezone column is empty, persist it (fire-and-forget;
+      // PostHog/JSONB remain authoritative so nothing blocks on the column).
+      if (
+        (tz.source === "posthog_timezone" || tz.source === "posthog_geoip") &&
+        contact &&
+        !contact.timezone
+      ) {
+        db.update(contacts)
+          .set({ timezone: tz.timezone, updatedAt: new Date() })
+          .where(eq(contacts.id, contact.id))
+          .catch(() => {
+            // best-effort cache write; never block the journey
+          });
+      }
+
       const ctx = createJourneyContext({
         db,
         hatchet,
         hatchetCtx,
         registry: getJourneyRegistrySingleton(),
         logger,
-        posthog: getPostHog(),
+        posthog,
         stateId,
         userId,
         userEmail,
         journeyContext: { ...properties },
+        resolvedTimezone: tz.timezone,
+        defaultSendWindow: scheduleDefaults.sendWindow,
       });
 
       try {

package/src/journeys/journey-context.ts

@@ -2,7 +2,21 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { DurationObject } from "@hogsend/core";
 import { evaluateEventCondition } from "@hogsend/core";
 import type { JourneyRegistry } from "@hogsend/core/registry";
-import type { JourneyContext } from "@hogsend/core/types";
+import {
+  isValidTimeZone,
+  resolveAfter,
+  resolveNextLocalTime,
+  resolveNextWeekday,
+  resolveTomorrow,
+  type SendWindow,
+} from "@hogsend/core/schedule";
+import type {
+  IfPast,
+  JourneyContext,
+  TimeOfDayBuilder,
+  Weekday,
+  WhenBuilder,
+} from "@hogsend/core/types";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
 import type { PostHogService } from "@hogsend/plugin-posthog";
 import { and, count, eq, max } from "drizzle-orm";
@@ -13,7 +27,11 @@ import type { Logger } from "../lib/logger.js";
 interface JourneyContextConfig {
   db: Database;
   hatchet: HatchetClient;
-  hatchetCtx: { sleepFor: (duration: DurationObject) => Promise<unknown> };
+  hatchetCtx: {
+    // Hatchet's real `sleepFor` accepts a number (milliseconds) in addition to
+    // duration strings/objects; we use the number-ms form for `sleepUntil`.
+    sleepFor: (duration: DurationObject | number) => Promise<unknown>;
+  };
   registry: JourneyRegistry;
   logger: Logger;
   posthog?: PostHogService;
@@ -21,6 +39,61 @@ interface JourneyContextConfig {
   userId: string;
   userEmail: string;
   journeyContext: Record<string, unknown>;
+  /** The user's resolved IANA timezone, bound into `ctx.when`. */
+  resolvedTimezone: string;
+  /** The client default send window, auto-applied by `ctx.when`. */
+  defaultSendWindow?: SendWindow;
+}
+
+/**
+ * Build the timezone-bound fluent scheduler. A thin wrapper over the pure core
+ * resolvers: it injects the user's resolved tz, the real current instant, and
+ * the (optionally overridden) send window, returning absolute `Date`s.
+ */
+function createWhenBuilder(opts: {
+  timezone: string;
+  window?: SendWindow;
+  ifPast: IfPast;
+}): WhenBuilder {
+  const baseOpts = () => ({
+    timezone: opts.timezone,
+    now: new Date(),
+    window: opts.window,
+    ifPast: opts.ifPast,
+  });
+
+  const timeBuilder = (resolve: (time: string) => Date): TimeOfDayBuilder => ({
+    at: (time) => resolve(time),
+  });
+
+  return {
+    next(weekday: Weekday) {
+      return timeBuilder((time) =>
+        resolveNextWeekday(weekday, time, baseOpts()),
+      );
+    },
+    nextLocal(time: string) {
+      return resolveNextLocalTime(time, baseOpts());
+    },
+    tomorrow() {
+      return timeBuilder((time) => resolveTomorrow(time, baseOpts()));
+    },
+    in(duration: DurationObject) {
+      return timeBuilder((time) => resolveAfter(duration, time, baseOpts()));
+    },
+    tz(timezone: string) {
+      if (!isValidTimeZone(timezone)) {
+        throw new TypeError(`ctx.when.tz: invalid timezone "${timezone}"`);
+      }
+      return createWhenBuilder({ ...opts, timezone });
+    },
+    window(start: string, end: string) {
+      return createWhenBuilder({ ...opts, window: { start, end } });
+    },
+    ifPast(strategy: IfPast) {
+      return createWhenBuilder({ ...opts, ifPast: strategy });
+    },
+  };
 }
 
 export function createJourneyContext(
@@ -37,31 +110,63 @@ export function createJourneyContext(
     userId,
     userEmail,
     journeyContext,
+    resolvedTimezone,
+    defaultSendWindow,
   } = config;
 
-  return {
-    async sleep({ duration, label }) {
-      const sleptAt = new Date().toISOString();
+  // Shared wait lifecycle: mark the state "waiting", durably sleep, mark it
+  // "active" again. `sleep` passes a DurationObject; `sleepUntil` passes a
+  // precomputed ms delay — Hatchet's `sleepFor` accepts both.
+  const performSleep = async (
+    durationOrMs: DurationObject | number,
+    nodeId: string,
+  ): Promise<{ sleptAt: string; resumedAt: string }> => {
+    const sleptAt = new Date().toISOString();
 
-      await db
-        .update(journeyStates)
-        .set({
-          status: "waiting",
-          currentNodeId: label ?? `wait:${JSON.stringify(duration)}`,
-          updatedAt: new Date(),
-        })
-        .where(eq(journeyStates.id, stateId));
+    await db
+      .update(journeyStates)
+      .set({ status: "waiting", currentNodeId: nodeId, updatedAt: new Date() })
+      .where(eq(journeyStates.id, stateId));
 
-      await hatchetCtx.sleepFor(duration);
+    await hatchetCtx.sleepFor(durationOrMs);
 
-      const resumedAt = new Date().toISOString();
+    const resumedAt = new Date().toISOString();
 
-      await db
-        .update(journeyStates)
-        .set({ status: "active", updatedAt: new Date() })
-        .where(eq(journeyStates.id, stateId));
+    await db
+      .update(journeyStates)
+      .set({ status: "active", updatedAt: new Date() })
+      .where(eq(journeyStates.id, stateId));
+
+    return { sleptAt, resumedAt };
+  };
+
+  return {
+    when: createWhenBuilder({
+      timezone: resolvedTimezone,
+      window: defaultSendWindow,
+      ifPast: "next",
+    }),
+
+    async sleep({ duration, label }) {
+      return performSleep(
+        duration,
+        label ?? `wait:${JSON.stringify(duration)}`,
+      );
+    },
+
+    async sleepUntil(at, opts) {
+      const target = at instanceof Date ? at.getTime() : new Date(at).getTime();
+      if (Number.isNaN(target)) {
+        throw new TypeError("sleepUntil: invalid date");
+      }
 
-      return { sleptAt, resumedAt };
+      // Compute the wake delay ONCE. Durability comes from Hatchet preserving
+      // the deadline across replays/restarts; a past instant gives ms = 0.
+      const ms = Math.max(0, target - Date.now());
+      return performSleep(
+        ms,
+        opts?.label ?? `wait-until:${new Date(target).toISOString()}`,
+      );
     },
 
     async checkpoint(label) {

package/src/lib/auth.ts

@@ -8,12 +8,19 @@ export function createAuth(opts: {
   db: Database;
   secret: string;
   baseURL: string;
+  /**
+   * Extra origins allowed to call auth endpoints, beyond `baseURL` (which is
+   * always trusted). Needed when the Studio is served from a different origin
+   * than the API (e.g. the `hogsend studio` CLI against a remote instance).
+   */
+  trustedOrigins?: string[];
 }) {
-  const { db, secret, baseURL } = opts;
+  const { db, secret, baseURL, trustedOrigins } = opts;
   return betterAuth({
     basePath: "/api/auth",
     secret,
     baseURL,
+    ...(trustedOrigins && trustedOrigins.length > 0 ? { trustedOrigins } : {}),
     database: drizzleAdapter(db, {
       provider: "pg",
       schema,

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

@@ -1,3 +1,4 @@
+import type { DurationObject } from "@hogsend/core";
 import type {
   EmailServiceRenderOptions,
   EmailServiceRenderResult,
@@ -13,6 +14,7 @@ import type {
   WebhookEventType,
   WebhookHandlerMap,
 } from "@hogsend/plugin-resend";
+import type { Logger } from "./logger.js";
 
 export type {
   BatchEmailItem,
@@ -33,6 +35,9 @@ export interface SendTrackedEmailOptions<
   to: string;
   subject?: string;
   journeyStateId?: string;
+  /** Denormalized recipient identity, persisted on the email_sends row for reporting. */
+  userId?: string;
+  userEmail?: string;
   category?: string;
   tags?: Array<{ name: string; value: string }>;
   headers?: Record<string, string>;
@@ -44,7 +49,28 @@ export interface SendTrackedEmailOptions<
 export interface TrackedSendResult {
   emailSendId: string;
   resendId: string;
-  status: "sent" | "suppressed" | "unsubscribed";
+  status: "sent" | "suppressed" | "unsubscribed" | "skipped";
+  /** Present only when `status === "skipped"` by the frequency cap. */
+  reason?: "frequency_capped";
+}
+
+// ---------------------------------------------------------------------------
+// Frequency capping (client default config)
+// ---------------------------------------------------------------------------
+
+export interface FrequencyCapWindow {
+  count: number;
+  window: DurationObject;
+}
+
+export interface FrequencyCapConfig {
+  /** Global send count allowed within `window` per recipient. */
+  count: number;
+  window: DurationObject;
+  /** Per-category overrides (count + window, filtered by that category). */
+  byCategory?: Record<string, FrequencyCapWindow>;
+  /** Categories exempt from capping. Defaults to ["transactional"]. */
+  exemptCategories?: string[];
 }
 
 // ---------------------------------------------------------------------------
@@ -66,6 +92,14 @@ export interface EmailServiceConfig {
   retryOptions?: RetryOptions;
   bounceThreshold?: number;
   baseUrl?: string;
+  /**
+   * Optional per-client frequency cap. When set, sends are counted per
+   * recipient within the window and skipped (no provider call, no `sent` row)
+   * once the cap is reached. Opt-in: undefined ⇒ no capping.
+   */
+  frequencyCap?: FrequencyCapConfig;
+  /** Optional structured logger; used e.g. to record frequency-cap skips. */
+  logger?: Logger;
 }
 
 export interface EmailServiceSendOptions<
@@ -77,6 +111,9 @@ export interface EmailServiceSendOptions<
   from?: string;
   subject?: string;
   journeyStateId?: string;
+  /** Denormalized recipient identity, persisted on the email_sends row for reporting. */
+  userId?: string;
+  userEmail?: string;
   category?: string;
   tags?: Array<{ name: string; value: string }>;
   headers?: Record<string, string>;

package/src/lib/email.ts

@@ -76,6 +76,8 @@ export async function sendEmail(
     to: opts.to,
     subject: opts.subject,
     journeyStateId: opts.journeyStateId,
+    userId: opts.userId,
+    userEmail: opts.to,
     category: "journey",
     tags: [
       { name: "journeyId", value: opts.journeyName ?? opts.template },