@hogsend/core 0.0.1 → 0.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/core",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,7 @@
     "./types": "./src/types/index.ts",
     "./registry": "./src/registry/index.ts",
     "./conditions": "./src/conditions/index.ts",
+    "./schedule": "./src/schedule/index.ts",
     "./schemas": "./src/schemas/index.ts"
   },
   "files": [
@@ -26,15 +27,20 @@
     "access": "public"
   },
   "dependencies": {
+    "@js-temporal/polyfill": "^0.5.1",
     "drizzle-orm": "^0.45.2",
+    "iana-db-timezones": "^0.3.0",
     "zod": "^4.4.3",
-    "@hogsend/db": "^0.0.1"
+    "@hogsend/db": "^0.1.0"
   },
   "devDependencies": {
     "@types/node": "latest",
+    "vitest": "^4.1.8",
     "@repo/typescript-config": "0.0.0"
   },
   "scripts": {
-    "check-types": "tsc --noEmit"
+    "check-types": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/index.ts

@@ -12,5 +12,6 @@ export {
   minutes,
 } from "./duration.js";
 export { JourneyRegistry } from "./registry/index.js";
+export * from "./schedule/index.js";
 export { journeyMetaSchema } from "./schemas/index.js";
 export * from "./types/index.js";

package/src/schedule/index.ts

@@ -0,0 +1,10 @@
+export {
+  resolveAfter,
+  resolveNextLocalTime,
+  resolveNextWeekday,
+  resolveTomorrow,
+  type ScheduleOptions,
+} from "./resolvers.js";
+export { parseTimeOfDay, weekdayToIso } from "./time.js";
+export { isValidTimeZone, type TimeZone } from "./tz.js";
+export { clampToWindow, type SendWindow } from "./window.js";

package/src/schedule/resolvers.ts

@@ -0,0 +1,136 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { DurationObject } from "../duration.js";
+import { durationToMs } from "../duration.js";
+import type { IfPast, Weekday } from "../types/journey-context.js";
+import { parseTimeOfDay, weekdayToIso } from "./time.js";
+import { clampToWindow, type SendWindow } from "./window.js";
+
+export interface ScheduleOptions {
+  /** Resolved IANA timezone, e.g. "America/New_York". */
+  timezone: string;
+  /** Explicit "current" instant — no ambient `Date.now()`. */
+  now: Date;
+  /** Optional quiet-hours window in the same tz. */
+  window?: SendWindow;
+  /** How to treat a naive resolved instant that is already <= now. */
+  ifPast?: IfPast;
+}
+
+/**
+ * Convert a `ZonedDateTime` to a `Date`, applying the `ifPast` policy and the
+ * optional send window. This is the shared tail of every resolver:
+ *
+ * 1. `ifPast` — `"next"` (default) rolls the instant forward by `rollDays` when
+ *    it is at/before `now` (never fewer than 1 day, so a snapped past instant
+ *    always lands in the future); `"now"` clamps it to the current instant.
+ * 2. `clampToWindow` — if a window is configured, the final instant is mapped
+ *    into the open window (the LAST step, after `ifPast`).
+ */
+function finalize(
+  candidate: Temporal.ZonedDateTime,
+  opts: ScheduleOptions,
+  rollDays: number,
+): Date {
+  const nowMs = opts.now.getTime();
+  let resolved = candidate;
+
+  if (resolved.epochMilliseconds <= nowMs) {
+    if ((opts.ifPast ?? "next") === "now") {
+      resolved = Temporal.Instant.fromEpochMilliseconds(
+        nowMs,
+      ).toZonedDateTimeISO(opts.timezone);
+    } else {
+      // ifPast "next": always roll forward. Resolvers that snap to an
+      // arbitrary HH:mm (resolveAfter / resolveTomorrow) pass rollDays 0, so a
+      // snapped time landing at/before now must still advance at least one day
+      // — otherwise a past instant would be returned and fire immediately.
+      resolved = resolved.add({ days: Math.max(rollDays, 1) });
+    }
+  }
+
+  const instant = new Date(resolved.epochMilliseconds);
+  return opts.window
+    ? clampToWindow(instant, opts.window, opts.timezone)
+    : instant;
+}
+
+/**
+ * Build the wall-clock `HH:mm` instant on `date` in `opts.timezone`.
+ *
+ * Disambiguation `"compatible"` (the JS-`Date` rule) is the documented choice:
+ * on a spring-forward gap it yields the post-gap instant ("first valid instant
+ * going forward"); on a fall-back overlap it yields the earlier occurrence.
+ */
+function atTime(
+  date: Temporal.PlainDate,
+  time: string,
+  timezone: string,
+): Temporal.ZonedDateTime {
+  const { hour, minute } = parseTimeOfDay(time);
+  return date
+    .toPlainDateTime(Temporal.PlainTime.from({ hour, minute }))
+    .toZonedDateTime(timezone, { disambiguation: "compatible" });
+}
+
+function nowZoned(opts: ScheduleOptions): Temporal.ZonedDateTime {
+  return Temporal.Instant.fromEpochMilliseconds(
+    opts.now.getTime(),
+  ).toZonedDateTimeISO(opts.timezone);
+}
+
+/**
+ * Next occurrence of `HH:mm` local: today if still in the future (per
+ * `ifPast`), otherwise tomorrow.
+ */
+export function resolveNextLocalTime(
+  time: string,
+  opts: ScheduleOptions,
+): Date {
+  const candidate = atTime(nowZoned(opts).toPlainDate(), time, opts.timezone);
+  return finalize(candidate, opts, 1);
+}
+
+/**
+ * Upcoming `weekday` at `HH:mm` local. If today IS the weekday and the time is
+ * still in the future, returns today; otherwise the next matching weekday
+ * (1..7 days ahead).
+ */
+export function resolveNextWeekday(
+  weekday: Weekday,
+  time: string,
+  opts: ScheduleOptions,
+): Date {
+  const targetIso = weekdayToIso(weekday);
+  const today = nowZoned(opts).toPlainDate();
+  const delta = (targetIso - today.dayOfWeek + 7) % 7;
+  const candidate = atTime(today.add({ days: delta }), time, opts.timezone);
+  // If the chosen day is today (delta === 0) but the time already passed, roll
+  // a full week forward rather than a single day.
+  return finalize(candidate, opts, 7);
+}
+
+/** Tomorrow (now + 1 calendar day in tz) at `HH:mm` local. */
+export function resolveTomorrow(time: string, opts: ScheduleOptions): Date {
+  const tomorrow = nowZoned(opts).toPlainDate().add({ days: 1 });
+  const candidate = atTime(tomorrow, time, opts.timezone);
+  // Tomorrow at HH:mm is already in the future; rollDays 0 means finalize only
+  // intervenes for ifPast="now" or the defensive 1-day roll if it ever lands
+  // at/before now.
+  return finalize(candidate, opts, 0);
+}
+
+/**
+ * `now` + `duration`, then snapped to `HH:mm` local on the resulting calendar
+ * day.
+ */
+export function resolveAfter(
+  duration: DurationObject,
+  time: string,
+  opts: ScheduleOptions,
+): Date {
+  const shifted = Temporal.Instant.fromEpochMilliseconds(
+    opts.now.getTime() + durationToMs(duration),
+  ).toZonedDateTimeISO(opts.timezone);
+  const candidate = atTime(shifted.toPlainDate(), time, opts.timezone);
+  return finalize(candidate, opts, 0);
+}

package/src/schedule/schedule.test.ts

@@ -0,0 +1,283 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { describe, expect, it } from "vitest";
+import { days, hours } from "../duration.js";
+import {
+  clampToWindow,
+  isValidTimeZone,
+  parseTimeOfDay,
+  resolveAfter,
+  resolveNextLocalTime,
+  resolveNextWeekday,
+  resolveTomorrow,
+  weekdayToIso,
+} from "./index.js";
+
+const NY = "America/New_York";
+
+/** Build a Date from a wall-clock time in a tz (compatible disambiguation). */
+function at(
+  tz: string,
+  y: number,
+  m: number,
+  d: number,
+  h: number,
+  min: number,
+): Date {
+  const zdt = Temporal.PlainDateTime.from({
+    year: y,
+    month: m,
+    day: d,
+    hour: h,
+    minute: min,
+  }).toZonedDateTime(tz, { disambiguation: "compatible" });
+  return new Date(zdt.epochMilliseconds);
+}
+
+/** UTC offset string ("-04:00") of a Date in a tz. */
+function offsetOf(date: Date, tz: string): string {
+  return Temporal.Instant.fromEpochMilliseconds(
+    date.getTime(),
+  ).toZonedDateTimeISO(tz).offset;
+}
+
+/** Local wall-clock "HH:mm" of a Date in a tz. */
+function wall(date: Date, tz: string): string {
+  const zdt = Temporal.Instant.fromEpochMilliseconds(
+    date.getTime(),
+  ).toZonedDateTimeISO(tz);
+  return `${String(zdt.hour).padStart(2, "0")}:${String(zdt.minute).padStart(
+    2,
+    "0",
+  )}`;
+}
+
+describe("parseTimeOfDay", () => {
+  it("parses HH:mm", () => {
+    expect(parseTimeOfDay("08:30")).toEqual({ hour: 8, minute: 30 });
+    expect(parseTimeOfDay("23:59")).toEqual({ hour: 23, minute: 59 });
+  });
+  it("throws on malformed / out-of-range", () => {
+    expect(() => parseTimeOfDay("8h")).toThrow();
+    expect(() => parseTimeOfDay("24:00")).toThrow();
+    expect(() => parseTimeOfDay("12:60")).toThrow();
+  });
+});
+
+describe("weekdayToIso", () => {
+  it("maps short and full names to the same ISO weekday", () => {
+    expect(weekdayToIso("tue")).toBe(2);
+    expect(weekdayToIso("tuesday")).toBe(2);
+    expect(weekdayToIso("sun")).toBe(7);
+    expect(weekdayToIso("monday")).toBe(1);
+  });
+});
+
+describe("resolveNextLocalTime", () => {
+  it("returns same-day when time is still future", () => {
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveNextLocalTime("14:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 1, 14, 0));
+  });
+
+  it("rolls to next day when past (ifPast default 'next')", () => {
+    const now = at(NY, 2026, 6, 1, 15, 0);
+    const got = resolveNextLocalTime("14:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 14, 0));
+  });
+
+  it("ifPast 'now' clamps to the current instant", () => {
+    const now = at(NY, 2026, 6, 1, 15, 0);
+    const got = resolveNextLocalTime("14:00", {
+      timezone: NY,
+      now,
+      ifPast: "now",
+    });
+    expect(got.getTime()).toBe(now.getTime());
+  });
+
+  it("exact equality (now == target) rolls forward under 'next'", () => {
+    const now = at(NY, 2026, 6, 1, 14, 0);
+    const got = resolveNextLocalTime("14:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 14, 0));
+  });
+});
+
+describe("resolveNextWeekday", () => {
+  it("short/full names produce identical instants", () => {
+    const now = at(NY, 2026, 6, 1, 9, 0); // Monday
+    const a = resolveNextWeekday("tue", "08:00", { timezone: NY, now });
+    const b = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(a).toEqual(b);
+  });
+
+  it("Mon → next Tuesday is tomorrow", () => {
+    const now = at(NY, 2026, 6, 1, 9, 0); // Monday 2026-06-01
+    const got = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("Tue 06:00 → today 08:00 (same-day future)", () => {
+    const now = at(NY, 2026, 6, 2, 6, 0); // Tuesday
+    const got = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("Tue 09:00 → next Tuesday (7 days)", () => {
+    const now = at(NY, 2026, 6, 2, 9, 0); // Tuesday
+    const got = resolveNextWeekday("tuesday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 9, 8, 0));
+  });
+
+  it("Sunday → next Monday is tomorrow (week wrap)", () => {
+    const now = at(NY, 2026, 6, 7, 12, 0); // Sunday 2026-06-07
+    const got = resolveNextWeekday("monday", "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 8, 8, 0));
+  });
+});
+
+describe("resolveTomorrow", () => {
+  it("returns tomorrow at HH:mm", () => {
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveTomorrow("08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+});
+
+describe("resolveAfter", () => {
+  it("now + 2 days snapped to 08:00 local", () => {
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveAfter(days(2), "08:00", { timezone: NY, now });
+    expect(got).toEqual(at(NY, 2026, 6, 3, 8, 0));
+  });
+
+  it("in 1 hour crossing midnight snaps to next day's HH:mm", () => {
+    const now = at(NY, 2026, 6, 1, 23, 30);
+    const got = resolveAfter(hours(1), "08:00", { timezone: NY, now });
+    // now + 1h => 2026-06-02 00:30 local => snapped to 08:00 that day.
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("snapped HH:mm earlier than now on the same day rolls forward (not past)", () => {
+    // now 09:00, +1h => 10:00 same day, but .at('08:00') pulls back to 08:00
+    // which is already in the past. Must roll to tomorrow's 08:00, never < now.
+    const now = at(NY, 2026, 6, 1, 9, 0);
+    const got = resolveAfter(hours(1), "08:00", { timezone: NY, now });
+    expect(got.getTime()).toBeGreaterThan(now.getTime());
+    expect(got).toEqual(at(NY, 2026, 6, 2, 8, 0));
+  });
+
+  it("snapped HH:mm earlier than now with ifPast 'now' clamps to current instant", () => {
+    const now = at(NY, 2026, 6, 1, 9, 0);
+    const got = resolveAfter(hours(1), "08:00", {
+      timezone: NY,
+      now,
+      ifPast: "now",
+    });
+    expect(got.getTime()).toBe(now.getTime());
+  });
+});
+
+describe("DST handling (America/New_York)", () => {
+  it("spring-forward gap (2026-03-08 02:30) picks post-gap EDT instant", () => {
+    // Clocks jump 02:00 -> 03:00; 02:30 does not exist.
+    const now = at(NY, 2026, 3, 8, 0, 0);
+    const got = resolveNextLocalTime("02:30", { timezone: NY, now });
+    // "compatible" => later instant; resulting offset is EDT (-04:00).
+    expect(offsetOf(got, NY)).toBe("-04:00");
+    expect(wall(got, NY)).toBe("03:30");
+  });
+
+  it("fall-back overlap (2026-11-01 01:30) picks earlier (EDT) instant", () => {
+    const now = at(NY, 2026, 11, 1, 0, 0);
+    const got = resolveNextLocalTime("01:30", { timezone: NY, now });
+    // The earlier of the two 01:30s is still EDT (-04:00).
+    expect(offsetOf(got, NY)).toBe("-04:00");
+    expect(wall(got, NY)).toBe("01:30");
+  });
+
+  it("resolveTomorrow across spring-forward uses calendar add (not +24h)", () => {
+    const now = at(NY, 2026, 3, 7, 23, 0); // EST
+    const got = resolveTomorrow("08:00", { timezone: NY, now });
+    expect(wall(got, NY)).toBe("08:00");
+    expect(offsetOf(got, NY)).toBe("-04:00"); // 2026-03-08 is EDT
+  });
+});
+
+describe("clampToWindow", () => {
+  const win = { start: "09:00", end: "17:00" };
+
+  it("inside window is unchanged", () => {
+    const inst = at(NY, 2026, 6, 1, 12, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(inst);
+  });
+
+  it("before open snaps to today's open", () => {
+    const inst = at(NY, 2026, 6, 1, 7, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(at(NY, 2026, 6, 1, 9, 0));
+  });
+
+  it("after close snaps to tomorrow's open", () => {
+    const inst = at(NY, 2026, 6, 1, 19, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(at(NY, 2026, 6, 2, 9, 0));
+  });
+
+  it("exactly at close (17:00) is treated as after-close", () => {
+    const inst = at(NY, 2026, 6, 1, 17, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(at(NY, 2026, 6, 2, 9, 0));
+  });
+
+  it("exactly at open (09:00) is unchanged (inclusive)", () => {
+    const inst = at(NY, 2026, 6, 1, 9, 0);
+    expect(clampToWindow(inst, win, NY)).toEqual(inst);
+  });
+
+  it("start === end is always open", () => {
+    const inst = at(NY, 2026, 6, 1, 3, 0);
+    const allDay = { start: "00:00", end: "00:00" };
+    expect(clampToWindow(inst, allDay, NY)).toEqual(inst);
+  });
+
+  describe("overnight window 22:00-06:00", () => {
+    const overnight = { start: "22:00", end: "06:00" };
+    it("23:00 is in the open tail", () => {
+      const inst = at(NY, 2026, 6, 1, 23, 0);
+      expect(clampToWindow(inst, overnight, NY)).toEqual(inst);
+    });
+    it("03:00 is in the early-morning open", () => {
+      const inst = at(NY, 2026, 6, 1, 3, 0);
+      expect(clampToWindow(inst, overnight, NY)).toEqual(inst);
+    });
+    it("12:00 quiet gap snaps forward to tonight's open", () => {
+      const inst = at(NY, 2026, 6, 1, 12, 0);
+      expect(clampToWindow(inst, overnight, NY)).toEqual(
+        at(NY, 2026, 6, 1, 22, 0),
+      );
+    });
+  });
+
+  it("clamp into next-open via resolver window option", () => {
+    // 19:00 local resolved with a 09:00-17:00 window => next day 09:00.
+    const now = at(NY, 2026, 6, 1, 10, 0);
+    const got = resolveNextLocalTime("19:00", {
+      timezone: NY,
+      now,
+      window: win,
+    });
+    expect(got).toEqual(at(NY, 2026, 6, 2, 9, 0));
+  });
+});
+
+describe("isValidTimeZone", () => {
+  it("accepts valid IANA zones", () => {
+    expect(isValidTimeZone("America/New_York")).toBe(true);
+    expect(isValidTimeZone("UTC")).toBe(true);
+    expect(isValidTimeZone("Europe/London")).toBe(true);
+  });
+  it("rejects invalid / empty without throwing", () => {
+    expect(isValidTimeZone("Not/AZone")).toBe(false);
+    expect(isValidTimeZone("")).toBe(false);
+    expect(isValidTimeZone("garbage")).toBe(false);
+    // @ts-expect-error testing non-string robustness
+    expect(isValidTimeZone(null)).toBe(false);
+  });
+});

package/src/schedule/time.ts

@@ -0,0 +1,53 @@
+import type { Weekday } from "../types/journey-context.js";
+
+export type { IfPast, Weekday } from "../types/journey-context.js";
+
+/**
+ * Map of accepted weekday names (short + full, lowercase) to ISO weekday
+ * numbers (Monday = 1 … Sunday = 7), matching `Temporal.PlainDate#dayOfWeek`.
+ */
+const WEEKDAY_TO_ISO: Record<Weekday, number> = {
+  mon: 1,
+  monday: 1,
+  tue: 2,
+  tuesday: 2,
+  wed: 3,
+  wednesday: 3,
+  thu: 4,
+  thursday: 4,
+  fri: 5,
+  friday: 5,
+  sat: 6,
+  saturday: 6,
+  sun: 7,
+  sunday: 7,
+};
+
+/**
+ * Resolve a {@link Weekday} name to its ISO weekday number (1..7). Throws on an
+ * unknown name — this is author error, not a runtime fall-through case.
+ */
+export function weekdayToIso(weekday: Weekday): number {
+  const iso = WEEKDAY_TO_ISO[weekday.toLowerCase() as Weekday];
+  if (iso === undefined) {
+    throw new TypeError(`Unknown weekday: "${weekday}"`);
+  }
+  return iso;
+}
+
+/**
+ * Parse a `"HH:mm"` string into `{ hour, minute }`. Throws on malformed input
+ * (author error — the scheduling API takes a literal time-of-day string).
+ */
+export function parseTimeOfDay(time: string): { hour: number; minute: number } {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+  if (!match) {
+    throw new TypeError(`Invalid time-of-day (expected "HH:mm"): "${time}"`);
+  }
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour < 0 || hour > 23 || minute < 0 || minute > 59) {
+    throw new TypeError(`Time-of-day out of range: "${time}"`);
+  }
+  return { hour, minute };
+}

package/src/schedule/tz.ts

@@ -0,0 +1,31 @@
+import { Temporal } from "@js-temporal/polyfill";
+import type { TimezoneCode } from "iana-db-timezones";
+
+/**
+ * A valid IANA timezone identifier (e.g. `"America/New_York"`, `"Europe/London"`)
+ * — the full canonical + alias set, as a string-literal union. Sourced from
+ * `iana-db-timezones` (type-only import, erased at build). Use this for
+ * author-supplied timezones (`ctx.when.tz(...)`, client `defaults.timezone`) to
+ * get autocomplete and compile-time typo-catching. Timezones that arrive as
+ * runtime *data* (PostHog props, contact rows) stay plain `string` and are
+ * validated via {@link isValidTimeZone}.
+ */
+export type TimeZone = TimezoneCode;
+
+/**
+ * True if `tz` is a usable IANA timezone identifier. Probes the zone via
+ * Temporal inside a try/catch — it never throws, even on garbage input, so it
+ * is safe to use as a validity gate in a precedence chain.
+ */
+export function isValidTimeZone(tz: string): boolean {
+  if (typeof tz !== "string" || tz.length === 0) {
+    return false;
+  }
+  try {
+    // `Temporal.Now.zonedDateTimeISO(tz)` throws RangeError on an unknown zone.
+    Temporal.Now.zonedDateTimeISO(tz);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/schedule/window.ts

@@ -0,0 +1,91 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { parseTimeOfDay } from "./time.js";
+
+/** A quiet-hours / send window as wall-clock `"HH:mm"` edges in some tz. */
+export interface SendWindow {
+  start: string;
+  end: string;
+}
+
+/**
+ * Build the absolute instant for a `PlainDate` at `HH:mm` in `timezone`.
+ *
+ * All wall-clock → instant conversions use disambiguation `"compatible"` (the
+ * JS-`Date`-equivalent rule): on a spring-forward gap it picks the later (post-
+ * gap) instant; on a fall-back overlap it picks the earlier occurrence. This
+ * keeps window edges DST-safe.
+ */
+function instantAt(
+  date: Temporal.PlainDate,
+  hour: number,
+  minute: number,
+  timezone: string,
+): Temporal.ZonedDateTime {
+  return date
+    .toPlainDateTime(Temporal.PlainTime.from({ hour, minute }))
+    .toZonedDateTime(timezone, { disambiguation: "compatible" });
+}
+
+/**
+ * Map an instant into the open send window in `timezone`. No-op if the instant
+ * is already inside the window.
+ *
+ * - Normal window (`start < end`, e.g. `09:00`–`17:00`): open means
+ *   `open <= instant < close`. Before open → today's open; at/after close →
+ *   tomorrow's open.
+ * - Overnight window (`start > end`, e.g. `22:00`–`06:00`): wraps midnight.
+ *   Open means `instant >= open` OR `instant < close`. In the quiet daytime
+ *   gap → tonight's open.
+ * - `start === end` → always open (no clamp).
+ *
+ * "Next day" uses Temporal calendar arithmetic (`add({ days: 1 })`), so a 23/25-
+ * hour DST day still lands on the correct `HH:mm` wall-clock.
+ */
+export function clampToWindow(
+  instant: Date,
+  window: SendWindow,
+  timezone: string,
+): Date {
+  const { hour: openH, minute: openM } = parseTimeOfDay(window.start);
+  const { hour: closeH, minute: closeM } = parseTimeOfDay(window.end);
+
+  // start === end → always open.
+  if (openH === closeH && openM === closeM) {
+    return instant;
+  }
+
+  const zdt = Temporal.Instant.fromEpochMilliseconds(
+    instant.getTime(),
+  ).toZonedDateTimeISO(timezone);
+  const date = zdt.toPlainDate();
+
+  const todayOpen = instantAt(date, openH, openM, timezone);
+  const todayClose = instantAt(date, closeH, closeM, timezone);
+  const normal = openH < closeH || (openH === closeH && openM < closeM);
+
+  if (normal) {
+    if (Temporal.ZonedDateTime.compare(zdt, todayOpen) < 0) {
+      return new Date(todayOpen.epochMilliseconds);
+    }
+    if (Temporal.ZonedDateTime.compare(zdt, todayClose) >= 0) {
+      const tomorrowOpen = instantAt(
+        date.add({ days: 1 }),
+        openH,
+        openM,
+        timezone,
+      );
+      return new Date(tomorrowOpen.epochMilliseconds);
+    }
+    return instant;
+  }
+
+  // Overnight window (start > end): close is in the morning, open in the evening.
+  if (Temporal.ZonedDateTime.compare(zdt, todayClose) < 0) {
+    return instant; // early-morning open tail
+  }
+  if (Temporal.ZonedDateTime.compare(zdt, todayOpen) >= 0) {
+    return instant; // late-evening open head
+  }
+  // Quiet daytime gap [close, open) → snap forward to tonight's open.
+  return new Date(todayOpen.epochMilliseconds);
+}

package/src/types/journey-context.ts

@@ -1,4 +1,5 @@
 import type { DurationObject } from "../duration.js";
+import type { TimeZone } from "../schedule/tz.js";
 
 export interface SleepOptions {
   duration: DurationObject;
@@ -10,6 +11,51 @@ export interface SleepResult {
   resumedAt: string;
 }
 
+export interface SleepUntilOptions {
+  label?: string;
+}
+
+export type Weekday =
+  | "mon"
+  | "tue"
+  | "wed"
+  | "thu"
+  | "fri"
+  | "sat"
+  | "sun"
+  | "monday"
+  | "tuesday"
+  | "wednesday"
+  | "thursday"
+  | "friday"
+  | "saturday"
+  | "sunday";
+
+/** How to treat a resolved instant that is already in the past. */
+export type IfPast = "next" | "now";
+
+export interface TimeOfDayBuilder {
+  /** Resolve to an absolute instant at `time` ("HH:mm") in the bound tz. */
+  at(time: string): Date;
+}
+
+export interface WhenBuilder {
+  /** Upcoming named weekday; chain `.at("HH:mm")`. */
+  next(weekday: Weekday): TimeOfDayBuilder;
+  /** Next occurrence of `time` local (today if future, else tomorrow). */
+  nextLocal(time: string): Date;
+  /** Tomorrow in the bound tz; chain `.at("HH:mm")`. */
+  tomorrow(): TimeOfDayBuilder;
+  /** `duration` from now, snapped to `.at("HH:mm")` on that day. */
+  in(duration: DurationObject): TimeOfDayBuilder;
+  /** Override the resolved user tz for this chain only. Returns a new builder. */
+  tz(timezone: TimeZone): WhenBuilder;
+  /** Override the default send window for this chain. Returns a new builder. */
+  window(start: string, end: string): WhenBuilder;
+  /** How to treat an already-past resolved time. Default "next". */
+  ifPast(strategy: IfPast): WhenBuilder;
+}
+
 export interface TriggerOptions {
   event: string;
   userId: string;
@@ -52,6 +98,13 @@ export interface EmailHistoryResult {
 
 export interface JourneyContext {
   sleep(opts: SleepOptions): Promise<SleepResult>;
+
+  /** Durable sleep until an absolute instant (`Date` or ISO string). */
+  sleepUntil(at: Date | string, opts?: SleepUntilOptions): Promise<SleepResult>;
+
+  /** Timezone-bound fluent scheduler. Always terminates in a `Date`. */
+  when: WhenBuilder;
+
   checkpoint(label: string): Promise<void>;
   trigger(opts: TriggerOptions): Promise<void>;
   identify(properties: Record<string, unknown>): void;