@hogsend/engine 0.0.1 → 0.1.0

package/package.json

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

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;
@@ -44,6 +59,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 +110,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.
@@ -133,6 +170,19 @@ 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 emailService =
     opts.overrides?.mailer ??
     createTrackedMailer(
@@ -143,6 +193,8 @@ export function createHogsendClient(
         webhookSecret: env.RESEND_WEBHOOK_SECRET,
         bounceThreshold: 3,
         baseUrl: env.API_PUBLIC_URL,
+        frequencyCap: defaults.frequencyCap,
+        logger,
       },
       {
         provider,
@@ -168,5 +220,6 @@ export function createHogsendClient(
     registry,
     hatchet: opts.overrides?.hatchet ?? hatchet,
     clientJournal: opts.clientJournal ?? { entries: [] },
+    defaults,
   };
 }

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,14 @@ 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 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/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,
@@ -44,7 +46,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 +89,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<

package/src/lib/frequency-cap.ts

@@ -0,0 +1,54 @@
+import { durationToMs } from "@hogsend/core";
+import type { Database } from "@hogsend/db";
+import { emailSends } from "@hogsend/db";
+import { and, count, eq, gte, ne } from "drizzle-orm";
+import type { FrequencyCapConfig } from "./email-service-types.js";
+
+const DEFAULT_EXEMPT = ["transactional"];
+
+/**
+ * True if this recipient has hit the configured send cap within the window.
+ *
+ * - `config` undefined → false (feature is opt-in; safe default = no cap).
+ * - An exempt `category` (default "transactional") → false.
+ * - A `byCategory[category]` override uses its own count/window AND filters the
+ *   COUNT by that category; otherwise the global rule counts ALL of the
+ *   recipient's non-failed sends in the window (NULL-category rows included).
+ *
+ * The COUNT is served by `email_sends_freq_cap_idx (to_email, created_at,
+ * category)`. Never-dispatched / failed rows (`status = 'failed'`) are excluded.
+ */
+export async function isFrequencyCapped(opts: {
+  db: Database;
+  to: string;
+  category?: string;
+  config?: FrequencyCapConfig;
+}): Promise<boolean> {
+  const { db, to, category, config } = opts;
+  if (!config) return false;
+
+  const exempt = config.exemptCategories ?? DEFAULT_EXEMPT;
+  if (category && exempt.includes(category)) return false;
+
+  const override = category ? config.byCategory?.[category] : undefined;
+  const rule = override ?? { count: config.count, window: config.window };
+
+  const since = new Date(Date.now() - durationToMs(rule.window));
+
+  const conditions = [
+    eq(emailSends.toEmail, to),
+    gte(emailSends.createdAt, since),
+    ne(emailSends.status, "failed"),
+  ];
+  // The byCategory branch counts only sends in that category.
+  if (override && category) {
+    conditions.push(eq(emailSends.category, category));
+  }
+
+  const [row] = await db
+    .select({ n: count() })
+    .from(emailSends)
+    .where(and(...conditions));
+
+  return (row?.n ?? 0) >= rule.count;
+}

package/src/lib/mailer.ts

@@ -82,6 +82,8 @@ export function createTrackedMailer(
           registry,
           retryOptions: retryDefaults,
           prepareTrackedHtml: deps.prepareTrackedHtml,
+          frequencyCap: config.frequencyCap,
+          logger: config.logger,
           options: {
             templateKey: options.template,
             props: options.props,

package/src/lib/timezone.ts

@@ -0,0 +1,126 @@
+import { isValidTimeZone, type TimeZone } from "@hogsend/core/schedule";
+import { contacts, type Database } from "@hogsend/db";
+import { eq } from "drizzle-orm";
+
+export interface ResolveTimezoneInput {
+  /** Explicit per-call override, e.g. from `ctx.when.tz("Area/City")`. */
+  explicit?: string;
+  /** PostHog person properties ($timezone, $geoip_time_zone). */
+  posthogProperties?: Record<string, unknown>;
+  /** The `contacts.timezone` cache column. */
+  contactTimezone?: string | null;
+  /** The `contacts.properties` jsonb. */
+  contactProperties?: Record<string, unknown> | null;
+  /** The client `defaults.timezone`. */
+  defaultTimezone?: string;
+  logger?: { warn(msg: string): void };
+}
+
+/**
+ * Source of a resolved timezone, surfaced so callers (e.g. `define-journey`)
+ * can decide whether to opportunistically cache it back to `contacts.timezone`.
+ */
+export type TimezoneSource =
+  | "explicit"
+  | "posthog_timezone"
+  | "posthog_geoip"
+  | "contact_column"
+  | "contact_properties"
+  | "default"
+  | "fallback";
+
+export interface ResolveTimezoneResult {
+  timezone: string;
+  source: TimezoneSource;
+}
+
+function candidate(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Resolve a user's IANA timezone via the precedence chain. The first *valid*
+ * candidate wins; invalid candidates are skipped and warned. Never throws —
+ * the terminal fallback is `"UTC"`.
+ *
+ * Precedence: explicit → PostHog `$timezone` → PostHog `$geoip_time_zone` →
+ * `contacts.timezone` → `contacts.properties.timezone` → client default → UTC.
+ */
+export function resolveTimezoneWithSource(
+  input: ResolveTimezoneInput,
+): ResolveTimezoneResult {
+  const { logger } = input;
+
+  // An explicit (author-supplied) timezone is a hard contract: if it is present
+  // but invalid, throw rather than silently falling through to UTC. Data-sourced
+  // candidates below stay lenient (warn + skip) — they are not author input.
+  const explicit = candidate(input.explicit);
+  if (explicit !== undefined && !isValidTimeZone(explicit)) {
+    throw new TypeError(
+      `resolveTimezone: invalid explicit timezone "${explicit}"`,
+    );
+  }
+
+  const chain: Array<{ value: string | undefined; source: TimezoneSource }> = [
+    { value: candidate(input.explicit), source: "explicit" },
+    {
+      value: candidate(input.posthogProperties?.$timezone),
+      source: "posthog_timezone",
+    },
+    {
+      value: candidate(input.posthogProperties?.$geoip_time_zone),
+      source: "posthog_geoip",
+    },
+    { value: candidate(input.contactTimezone), source: "contact_column" },
+    {
+      value: candidate(input.contactProperties?.timezone),
+      source: "contact_properties",
+    },
+    { value: candidate(input.defaultTimezone), source: "default" },
+  ];
+
+  for (const { value, source } of chain) {
+    if (value === undefined) continue;
+    if (isValidTimeZone(value)) {
+      return { timezone: value, source };
+    }
+    logger?.warn(`resolveTimezone: ignoring invalid tz '${value}'`);
+  }
+
+  return { timezone: "UTC", source: "fallback" };
+}
+
+/** Convenience wrapper returning just the resolved IANA timezone string. */
+export function resolveTimezone(input: ResolveTimezoneInput): string {
+  return resolveTimezoneWithSource(input).timezone;
+}
+
+/**
+ * Persist a known timezone for a contact (e.g. one the user picked in your
+ * app's settings) into the canonical `contacts.timezone` column, so the
+ * resolution chain prefers it over PostHog/geoip on the next journey run.
+ *
+ * Validates the zone and throws `TypeError` on an invalid one — this is an
+ * explicit, author-driven write, not best-effort data ingestion. Returns
+ * `{ updated: false }` if no contact exists yet for `userId` (it is created on
+ * first event ingestion); call again once the contact exists.
+ */
+export async function setContactTimezone(opts: {
+  db: Database;
+  userId: string;
+  timezone: TimeZone;
+}): Promise<{ updated: boolean }> {
+  const { db, userId, timezone } = opts;
+
+  if (!isValidTimeZone(timezone)) {
+    throw new TypeError(`setContactTimezone: invalid timezone "${timezone}"`);
+  }
+
+  const rows = await db
+    .update(contacts)
+    .set({ timezone, updatedAt: new Date() })
+    .where(eq(contacts.externalId, userId))
+    .returning({ id: contacts.id });
+
+  return { updated: rows.length > 0 };
+}

package/src/lib/tracked.ts

@@ -10,9 +10,12 @@ import { getTemplate, renderToHtml } from "@hogsend/email";
 import type { EmailProvider } from "@hogsend/plugin-resend";
 import { eq } from "drizzle-orm";
 import type {
+  FrequencyCapConfig,
   SendTrackedEmailOptions,
   TrackedSendResult,
 } from "./email-service-types.js";
+import { isFrequencyCapped } from "./frequency-cap.js";
+import type { Logger } from "./logger.js";
 
 export type PrepareTrackedHtmlFn = (opts: {
   html: string;
@@ -28,12 +31,24 @@ interface TrackedEmailDeps {
   registry: TemplateRegistry;
   retryOptions?: RetryOptions;
   prepareTrackedHtml?: PrepareTrackedHtmlFn;
+  /** Optional per-client frequency cap; undefined disables capping. */
+  frequencyCap?: FrequencyCapConfig;
+  /** Optional structured logger for operational events (e.g. cap skips). */
+  logger?: Logger;
 }
 
 export async function sendTrackedEmail<K extends TemplateName>(
   opts: TrackedEmailDeps & { options: SendTrackedEmailOptions<K> },
 ): Promise<TrackedSendResult> {
-  const { db, provider, registry, prepareTrackedHtml, options } = opts;
+  const {
+    db,
+    provider,
+    registry,
+    prepareTrackedHtml,
+    frequencyCap,
+    logger,
+    options,
+  } = opts;
 
   if (!options.skipPreferenceCheck) {
     const suppression = await checkSuppression(
@@ -68,6 +83,30 @@ export async function sendTrackedEmail<K extends TemplateName>(
             : "suppressed",
       };
     }
+
+    // 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.
+    if (frequencyCap) {
+      const capped = await isFrequencyCapped({
+        db,
+        to: options.to,
+        category: options.category,
+        config: frequencyCap,
+      });
+      if (capped) {
+        logger?.info("send skipped: frequency_capped", {
+          to: options.to,
+          category: options.category,
+        });
+        return {
+          emailSendId: "",
+          resendId: "",
+          status: "skipped",
+          reason: "frequency_capped",
+        };
+      }
+    }
   }
 
   const {