@apiary-dev/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 IngeniumOfficial
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @apiary-dev/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency, framework-agnostic scheduling domain logic: slot generation,
+collision and buffer math, timezone-safe weekly rules, and headless calendar
+grids.
+
+- No runtime dependencies; built on `Date` and `Intl`
+- TypeScript-first: bundled ESM/CJS with types on npm
+- Runs on Node.js, Deno, Bun, and Cloudflare Workers
+
+## Install
+
+```bash
+pnpm add @apiary-dev/core
+```
+
+## Example
+
+Carve an operating window into bookable slots:
+
+```ts
+import { generateTimeSlots } from "@apiary-dev/core";
+
+const slots = generateTimeSlots({
+  windows: [
+    {
+      start: new Date("2026-01-05T09:00:00Z"),
+      end: new Date("2026-01-05T17:00:00Z"),
+    },
+  ],
+  existingBookings: [],
+  durationMinutes: 30,
+  intervalMinutes: 15,
+  buffers: { beforeMinutes: 5, afterMinutes: 5 },
+  minNoticeMinutes: 30,
+  maxHorizonMinutes: 7 * 24 * 60,
+});
+```
+
+Expand weekly recurring rules into windows:
+
+```ts
+import { expandWeeklyRules } from "@apiary-dev/core";
+
+const windows = expandWeeklyRules({
+  rules: [{ dayOfWeek: 1, startTime: "09:00", endTime: "17:00" }],
+  startDate: new Date("2026-01-05T00:00:00Z"),
+  endDate: new Date("2026-01-12T00:00:00Z"),
+  timeZone: "America/New_York",
+});
+```
+
+## Documentation
+
+Full API reference and guides are available at
+[apiary-f4n.pages.dev/reference/core/](https://apiary-f4n.pages.dev/reference/core/).
+
+## License
+
+ISC

package/dist/index.cjs

@@ -0,0 +1,419 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  applyBufferToRange: () => applyBufferToRange,
+  buildMonthMatrix: () => buildMonthMatrix,
+  buildMultiMonthMatrix: () => buildMultiMonthMatrix,
+  buildMultiWeekMatrix: () => buildMultiWeekMatrix,
+  buildWeekMatrix: () => buildWeekMatrix,
+  expandWeeklyRules: () => expandWeeklyRules,
+  generateTimeSlots: () => generateTimeSlots,
+  rangesOverlap: () => rangesOverlap,
+  utcToWallClock: () => utcToWallClock,
+  wallClockToUTC: () => wallClockToUTC
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/rules/collisions.ts
+function rangesOverlap(a, b) {
+  return a.start < b.end && a.end > b.start;
+}
+function applyBufferToRange(range, buffer) {
+  const beforeMs = (buffer?.beforeMinutes ?? 0) * 60 * 1e3;
+  const afterMs = (buffer?.afterMinutes ?? 0) * 60 * 1e3;
+  return {
+    start: new Date(range.start.getTime() - beforeMs),
+    end: new Date(range.end.getTime() + afterMs)
+  };
+}
+
+// src/engine/generator.ts
+function generateTimeSlots(options, now = /* @__PURE__ */ new Date()) {
+  const {
+    windows,
+    existingBookings,
+    durationMinutes,
+    intervalMinutes,
+    buffers = {},
+    minNoticeMinutes = 0,
+    maxHorizonMinutes
+  } = options;
+  if (windows.length === 0) return [];
+  const slotDurationMs = durationMinutes * 60 * 1e3;
+  const stepIntervalMs = intervalMinutes * 60 * 1e3;
+  const bufferBeforeMs = (buffers.beforeMinutes ?? 0) * 60 * 1e3;
+  const bufferAfterMs = (buffers.afterMinutes ?? 0) * 60 * 1e3;
+  const minNoticeCutoff = new Date(
+    now.getTime() + minNoticeMinutes * 60 * 1e3
+  );
+  const maxHorizonCutoff = maxHorizonMinutes !== void 0 ? new Date(now.getTime() + maxHorizonMinutes * 60 * 1e3) : null;
+  const bufferedBookings = existingBookings.map(
+    (b) => applyBufferToRange(b, buffers)
+  );
+  const candidateSlots = [];
+  for (const window of windows) {
+    let currentStartMs = window.start.getTime();
+    const windowEndMs = window.end.getTime();
+    while (currentStartMs + slotDurationMs <= windowEndMs) {
+      const slotStart = new Date(currentStartMs);
+      const slotEnd = new Date(currentStartMs + slotDurationMs);
+      const bufferedStartMs = currentStartMs - bufferBeforeMs;
+      const bufferedEndMs = currentStartMs + slotDurationMs + bufferAfterMs;
+      let available = true;
+      let reason = "AVAILABLE";
+      if (slotStart < minNoticeCutoff) {
+        available = false;
+        reason = "MIN_NOTICE_VIOLATION";
+      }
+      if (available && maxHorizonCutoff !== null && slotStart.getTime() > maxHorizonCutoff.getTime()) {
+        available = false;
+        reason = "MAX_HORIZON_EXCEEDED";
+      }
+      if (available && (bufferedStartMs < window.start.getTime() || bufferedEndMs > windowEndMs)) {
+        available = false;
+        reason = "OUTSIDE_BOUNDS";
+      }
+      if (available) {
+        const candidateRange = { start: slotStart, end: slotEnd };
+        const bufferedCandidate = applyBufferToRange(candidateRange, buffers);
+        const hasCollision = bufferedBookings.some(
+          (booking) => rangesOverlap(bufferedCandidate, booking)
+        );
+        if (hasCollision) {
+          available = false;
+          reason = "COLLISION";
+        }
+      }
+      candidateSlots.push({
+        start: slotStart,
+        end: slotEnd,
+        available,
+        reason
+      });
+      currentStartMs += stepIntervalMs;
+    }
+  }
+  return candidateSlots;
+}
+
+// src/engine/calendar.ts
+var toDateKey = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+function buildMonthMatrix(options) {
+  const { year, month, weekStartsOn = 0 } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const firstDayOfMonth = new Date(year, month - 1, 1);
+  let startOffset = firstDayOfMonth.getDay() - weekStartsOn;
+  if (startOffset < 0) startOffset += 7;
+  const startDate = new Date(firstDayOfMonth);
+  startDate.setDate(startDate.getDate() - startOffset);
+  const grid = [];
+  const currentDate = new Date(startDate);
+  for (let week = 0; week < 6; week++) {
+    const weekRow = [];
+    for (let day = 0; day < 7; day++) {
+      const isoString = toDateKey(currentDate);
+      const isCurrentMonth = currentDate.getMonth() === month - 1;
+      const dayOfWeek = currentDate.getDay();
+      weekRow.push({
+        date: new Date(currentDate),
+        isoString,
+        dayOfMonth: currentDate.getDate(),
+        dayOfWeek,
+        isCurrentMonth,
+        isToday: isoString === todayStr,
+        isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+        isBlocked: !isCurrentMonth,
+        blockReason: !isCurrentMonth ? "OUT_OF_BOUNDS" : void 0
+      });
+      currentDate.setDate(currentDate.getDate() + 1);
+    }
+    grid.push(weekRow);
+  }
+  return grid;
+}
+function buildWeekMatrix(options) {
+  const { targetDate, weekStartsOn = 0 } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const startOfWeek = new Date(targetDate);
+  let dayOffset = startOfWeek.getDay() - weekStartsOn;
+  if (dayOffset < 0) dayOffset += 7;
+  startOfWeek.setDate(startOfWeek.getDate() - dayOffset);
+  const week = [];
+  const currentDate = new Date(startOfWeek);
+  for (let i = 0; i < 7; i++) {
+    const isoString = toDateKey(currentDate);
+    const dayOfWeek = currentDate.getDay();
+    const isCurrentMonth = currentDate.getFullYear() === targetDate.getFullYear() && currentDate.getMonth() === targetDate.getMonth();
+    week.push({
+      date: new Date(currentDate),
+      isoString,
+      dayOfMonth: currentDate.getDate(),
+      dayOfWeek,
+      isCurrentMonth,
+      isToday: isoString === todayStr,
+      isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+      isBlocked: !isCurrentMonth,
+      blockReason: !isCurrentMonth ? "OUT_OF_BOUNDS" : void 0
+    });
+    currentDate.setDate(currentDate.getDate() + 1);
+  }
+  return week;
+}
+function buildMultiWeekMatrix(options) {
+  const {
+    startDate,
+    endDate,
+    maxWeeksAllowed = 12,
+    weekStartsOn = 0
+  } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const cursor = new Date(startDate);
+  let dayOffset = cursor.getDay() - weekStartsOn;
+  if (dayOffset < 0) dayOffset += 7;
+  cursor.setDate(cursor.getDate() - dayOffset);
+  const weeks = [];
+  let weekCount = 0;
+  const startMs = new Date(
+    startDate.getFullYear(),
+    startDate.getMonth(),
+    startDate.getDate()
+  ).getTime();
+  const endMs = new Date(
+    endDate.getFullYear(),
+    endDate.getMonth(),
+    endDate.getDate()
+  ).getTime();
+  while (cursor.getTime() <= endMs && weekCount < maxWeeksAllowed) {
+    const weekRow = [];
+    for (let i = 0; i < 7; i++) {
+      const currentMs = new Date(
+        cursor.getFullYear(),
+        cursor.getMonth(),
+        cursor.getDate()
+      ).getTime();
+      const isoString = toDateKey(cursor);
+      const dayOfWeek = cursor.getDay();
+      const isOutOfBounds = currentMs < startMs || currentMs > endMs;
+      weekRow.push({
+        date: new Date(cursor),
+        isoString,
+        dayOfMonth: cursor.getDate(),
+        dayOfWeek,
+        isCurrentMonth: true,
+        isToday: isoString === todayStr,
+        isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+        isBlocked: isOutOfBounds,
+        blockReason: isOutOfBounds ? "OUT_OF_BOUNDS" : void 0
+      });
+      cursor.setDate(cursor.getDate() + 1);
+    }
+    weeks.push(weekRow);
+    weekCount++;
+  }
+  return weeks;
+}
+function buildMultiMonthMatrix(options) {
+  const {
+    startDate,
+    endDate,
+    maxMonthsAllowed = 12,
+    weekStartsOn = 0
+  } = options;
+  const startMs = new Date(
+    startDate.getFullYear(),
+    startDate.getMonth(),
+    startDate.getDate()
+  ).getTime();
+  const endMs = new Date(
+    endDate.getFullYear(),
+    endDate.getMonth(),
+    endDate.getDate()
+  ).getTime();
+  const months = [];
+  let currentYear = startDate.getFullYear();
+  let currentMonth = startDate.getMonth() + 1;
+  let monthCount = 0;
+  const targetEndYear = endDate.getFullYear();
+  const targetEndMonth = endDate.getMonth() + 1;
+  while ((currentYear < targetEndYear || currentYear === targetEndYear && currentMonth <= targetEndMonth) && monthCount < maxMonthsAllowed) {
+    const baseGrid = buildMonthMatrix({
+      year: currentYear,
+      month: currentMonth,
+      weekStartsOn
+    });
+    const scopedGrid = baseGrid.map(
+      (weekRow) => weekRow.map((cell) => {
+        const cellMs = new Date(
+          cell.date.getFullYear(),
+          cell.date.getMonth(),
+          cell.date.getDate()
+        ).getTime();
+        const isOutOfBounds = cellMs < startMs || cellMs > endMs || !cell.isCurrentMonth;
+        return {
+          ...cell,
+          isBlocked: isOutOfBounds,
+          blockReason: isOutOfBounds ? "OUT_OF_BOUNDS" : void 0
+        };
+      })
+    );
+    months.push({
+      year: currentYear,
+      month: currentMonth,
+      grid: scopedGrid
+    });
+    monthCount++;
+    currentMonth++;
+    if (currentMonth > 12) {
+      currentMonth = 1;
+      currentYear++;
+    }
+  }
+  return months;
+}
+
+// src/engine/timezone.ts
+var wallClockToUTC = (wallClock, timeZone) => {
+  const pad = (n) => String(n).padStart(2, "0");
+  const isoStr = `${wallClock.year}-${pad(wallClock.month)}-${pad(wallClock.day)}T${pad(wallClock.hour)}:${pad(wallClock.minute)}:00`;
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const utcGuess = /* @__PURE__ */ new Date(`${isoStr}Z`);
+  const parts = Object.fromEntries(
+    formatter.formatToParts(utcGuess).map((p) => [p.type, p.value])
+  );
+  const localHeader = `${parts.year}-${parts.month}-${parts.day}T${parts.hour === "24" ? "00" : parts.hour}:${parts.minute}:${parts.second}`;
+  const diffMs = (/* @__PURE__ */ new Date(`${isoStr}Z`)).getTime() - (/* @__PURE__ */ new Date(`${localHeader}Z`)).getTime();
+  return new Date(utcGuess.getTime() + diffMs);
+};
+var utcToWallClock = (date, timeZone) => {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const parts = Object.fromEntries(
+    formatter.formatToParts(date).map((p) => [p.type, p.value])
+  );
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    hour: parts.hour === "24" ? 0 : Number(parts.hour),
+    minute: Number(parts.minute)
+  };
+};
+
+// src/engine/weekly.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var parseTime = (time) => {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+  if (!match) {
+    throw new Error(`Invalid time "${time}" \u2014 expected 24-hour "HH:mm".`);
+  }
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour > 23 || minute > 59) {
+    throw new Error(`Invalid time "${time}" \u2014 hour/minute out of range.`);
+  }
+  return { hour, minute };
+};
+var weekdayOf = (wallClock) => new Date(wallClock.year, wallClock.month - 1, wallClock.day).getDay();
+function expandWeeklyRules(options) {
+  const { rules, startDate, endDate, timeZone } = options;
+  const startMs = startDate.getTime();
+  const endMs = endDate.getTime();
+  if (endMs <= startMs) return [];
+  const parsedRules = rules.map((rule) => {
+    const start = parseTime(rule.startTime);
+    const end = parseTime(rule.endTime);
+    if (end.hour * 60 + end.minute <= start.hour * 60 + start.minute) {
+      throw new Error(
+        `Rule on day ${rule.dayOfWeek} must have endTime strictly after startTime (overnight spans are not supported).`
+      );
+    }
+    return { dayOfWeek: rule.dayOfWeek, start, end };
+  });
+  const firstUtcDayMs = startMs - startMs % DAY_MS;
+  const lastUtcDayMs = endMs - endMs % DAY_MS + DAY_MS;
+  const windows = [];
+  for (let t = firstUtcDayMs; t <= lastUtcDayMs; t += DAY_MS) {
+    const wallClock = utcToWallClock(new Date(t), timeZone);
+    const weekday = weekdayOf(wallClock);
+    for (const rule of parsedRules) {
+      if (rule.dayOfWeek !== weekday) continue;
+      const windowStart = wallClockToUTC(
+        { ...wallClock, hour: rule.start.hour, minute: rule.start.minute },
+        timeZone
+      );
+      const windowEnd = wallClockToUTC(
+        { ...wallClock, hour: rule.end.hour, minute: rule.end.minute },
+        timeZone
+      );
+      const clippedStart = Math.max(windowStart.getTime(), startMs);
+      const clippedEnd = Math.min(windowEnd.getTime(), endMs);
+      if (clippedEnd > clippedStart) {
+        windows.push({
+          start: new Date(clippedStart),
+          end: new Date(clippedEnd)
+        });
+      }
+    }
+  }
+  windows.sort(
+    (a, b) => a.start.getTime() - b.start.getTime() || a.end.getTime() - b.end.getTime()
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const window of windows) {
+    const key = `${window.start.getTime()}:${window.end.getTime()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(window);
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyBufferToRange,
+  buildMonthMatrix,
+  buildMultiMonthMatrix,
+  buildMultiWeekMatrix,
+  buildWeekMatrix,
+  expandWeeklyRules,
+  generateTimeSlots,
+  rangesOverlap,
+  utcToWallClock,
+  wallClockToUTC
+});

package/dist/index.d.cts

@@ -0,0 +1,219 @@
+interface TimeRange {
+    start: Date;
+    end: Date;
+}
+interface BufferConfig {
+    beforeMinutes?: number;
+    afterMinutes?: number;
+}
+type AvailabilityReason = "AVAILABLE" | "COLLISION" | "OUTSIDE_BOUNDS" | "MIN_NOTICE_VIOLATION" | "MAX_HORIZON_EXCEEDED";
+interface TimeSlot extends TimeRange {
+    available: boolean;
+    reason: AvailabilityReason;
+}
+/**
+ * Represents an active window of available time.
+ * Sourced either dynamically from weekly business hours or explicitly from DB shifts.
+ */
+interface AvailableWindow extends TimeRange {
+    id?: string;
+    providerId?: string;
+}
+interface SlotGeneratorOptions {
+    /** Source operating windows (Dynamic business hours OR Explicit DB shifts) */
+    windows: AvailableWindow[];
+    /** Confirmed bookings, holds, or blackout windows to subtract */
+    existingBookings: TimeRange[];
+    /** Duration of the appointment in minutes */
+    durationMinutes: number;
+    /** Step interval between slot start times in minutes (e.g. 15 for slots every 15 mins) */
+    intervalMinutes: number;
+    /** Required pre/post service buffer rules */
+    buffers?: BufferConfig;
+    /** Minimum notice required before a booking (in minutes) */
+    minNoticeMinutes?: number;
+    /** Maximum booking horizon in minutes. Slots starting beyond now + this are excluded. */
+    maxHorizonMinutes?: number;
+}
+
+interface BookingRepository {
+    /** Fetch active windows: supporting both Dynamic rules and Explicit shifts */
+    getAvailableWindows(params: {
+        startDate: Date;
+        endDate: Date;
+        providerId?: string;
+        mode: "dynamic" | "explicit";
+        /** IANA timezone the dynamic weekly rules are expressed in */
+        timeZone: string;
+    }): Promise<AvailableWindow[]>;
+    /** Fetch confirmed bookings and active holds in target window */
+    getBookingsInRange(startDate: Date, endDate: Date, providerId?: string): Promise<TimeRange[]>;
+    /** Create an atomic slot hold */
+    createHold(params: {
+        serviceId: string;
+        providerId: string;
+        range: TimeRange;
+        customerId?: string;
+    }): Promise<{
+        holdToken: string;
+        expiresAt: Date;
+    }>;
+    /** Confirm a hold into a permanent booking */
+    confirmBooking(params: {
+        holdToken: string;
+        customerDetails: Record<string, unknown>;
+    }): Promise<{
+        bookingId: string;
+    }>;
+}
+
+/**
+ * Checks if two half-open time ranges [start, end) overlap.
+ * Touch points (RangeA.end === RangeB.start) do NOT overlap.
+ */
+/**
+ *
+ * @param {TimeRange} a - First range
+ * @param {TimeRange} b - Second range
+ * @returns - True if the ranges overlap, false otherwise
+ */
+declare function rangesOverlap(a: TimeRange, b: TimeRange): boolean;
+/**
+ * Expands a target range by applying pre and post buffer padding.
+ */
+declare function applyBufferToRange(range: TimeRange, buffer?: BufferConfig): TimeRange;
+
+/**
+ *
+ * @param {SlotGeneratorOptions} options
+ * @param {Date} now
+ * @returns - Generated time slots
+ */
+declare function generateTimeSlots(options: SlotGeneratorOptions, now?: Date): TimeSlot[];
+
+interface CalendarDay {
+    /** JavaScript Date object representing the day at 00:00:00 local time */
+    date: Date;
+    /** Local date key formatted as YYYY-MM-DD for easy lookup */
+    isoString: string;
+    /** Day of the month (1-31) */
+    dayOfMonth: number;
+    /** Day of the week: 0 = Sunday, 1 = Monday, ..., 6 = Saturday */
+    dayOfWeek: number;
+    /** Indicates whether the day belongs to the target month being rendered */
+    isCurrentMonth: boolean;
+    /** Indicates whether this day matches the current local system date */
+    isToday: boolean;
+    /** Indicates Saturday or Sunday */
+    isWeekend: boolean;
+    /** Flagged true if outside explicit view boundaries or explicitly blocked */
+    isBlocked: boolean;
+    /** Reason why the cell is blocked, if applicable */
+    blockReason?: "OUT_OF_BOUNDS" | "CUSTOM_EXCLUSION" | "PAST_DATE";
+}
+type MonthGrid = CalendarDay[][];
+type WeekGrid = CalendarDay[];
+interface MonthGridOptions {
+    year: number;
+    month: number;
+    weekStartsOn?: 0 | 1;
+}
+interface WeekGridOptions {
+    targetDate: Date;
+    weekStartsOn?: 0 | 1;
+}
+interface MultiWeekViewOptions {
+    startDate: Date;
+    endDate: Date;
+    maxWeeksAllowed?: number;
+    weekStartsOn?: 0 | 1;
+}
+interface MultiMonthViewOptions {
+    startDate: Date;
+    endDate: Date;
+    maxMonthsAllowed?: number;
+    weekStartsOn?: 0 | 1;
+}
+interface MonthViewUnit {
+    year: number;
+    month: number;
+    grid: MonthGrid;
+}
+/**
+ * Builds a month grid matrix (6 weeks x 7 days) including leading
+ * and trailing padding days from adjacent months.
+ */
+declare function buildMonthMatrix(options: MonthGridOptions): MonthGrid;
+/**
+ * Builds a single 7-day array matrix for a specific target week.
+ */
+declare function buildWeekMatrix(options: WeekGridOptions): WeekGrid;
+/**
+ * Builds a multi-week matrix across a range of dates.
+ * Days outside [startDate, endDate] inside boundary weeks are marked as blocked.
+ */
+declare function buildMultiWeekMatrix(options: MultiWeekViewOptions): MonthGrid;
+/**
+ * Builds a multi-month matrix across a date range.
+ * Days outside [startDate, endDate] are tagged as blocked cells.
+ */
+declare function buildMultiMonthMatrix(options: MultiMonthViewOptions): MonthViewUnit[];
+
+interface WallClockTime {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+}
+/**
+ *
+ * @param {WallClockTime} wallClock - Wall clock target
+ * @param {string} timeZone - IANA timezone
+ * @returns - Exact UTC Date
+ */
+declare const wallClockToUTC: (wallClock: WallClockTime, timeZone: string) => Date;
+/**
+ *
+ * @param {Date} date - Exact UTC Date
+ * @param {string} timeZone - IANA timezone
+ * @returns - Wall-clock components in the target timezone
+ */
+declare const utcToWallClock: (date: Date, timeZone: string) => WallClockTime;
+
+/**
+ * Day of the week following JavaScript's Date#getDay() convention:
+ * 0 = Sunday, 1 = Monday, ..., 6 = Saturday.
+ */
+type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** A single weekly recurring operating rule expressed in local wall-clock time. */
+interface WeeklyRule {
+    dayOfWeek: DayOfWeek;
+    /** Local wall-clock start, 24-hour "HH:mm" */
+    startTime: string;
+    /** Local wall-clock end, 24-hour "HH:mm". Must be strictly after startTime. */
+    endTime: string;
+}
+interface WeeklyAvailabilityOptions {
+    /** Weekly rules to expand into windows */
+    rules: WeeklyRule[];
+    /** Query range start (inclusive), in UTC */
+    startDate: Date;
+    /** Query range end (exclusive), in UTC */
+    endDate: Date;
+    /** IANA timezone the rules are expressed in */
+    timeZone: string;
+}
+/**
+ * Expands weekly recurring rules into concrete windows within [startDate, endDate].
+ *
+ * Rules are expressed in local wall-clock time; windows are converted to UTC and
+ * clipped to the requested range. DST transitions are handled per-day via Intl,
+ * and duplicate windows (e.g. around a fall-back transition) are collapsed.
+ *
+ * @throws If a rule has an invalid time string or an overnight span (endTime <= startTime).
+ */
+declare function expandWeeklyRules(options: WeeklyAvailabilityOptions): AvailableWindow[];
+
+export { applyBufferToRange, buildMonthMatrix, buildMultiMonthMatrix, buildMultiWeekMatrix, buildWeekMatrix, expandWeeklyRules, generateTimeSlots, rangesOverlap, utcToWallClock, wallClockToUTC };
+export type { AvailabilityReason, AvailableWindow, BookingRepository, BufferConfig, CalendarDay, DayOfWeek, MonthGrid, MonthGridOptions, MonthViewUnit, MultiMonthViewOptions, MultiWeekViewOptions, SlotGeneratorOptions, TimeRange, TimeSlot, WallClockTime, WeekGrid, WeekGridOptions, WeeklyAvailabilityOptions, WeeklyRule };

package/dist/index.d.ts

@@ -0,0 +1,219 @@
+interface TimeRange {
+    start: Date;
+    end: Date;
+}
+interface BufferConfig {
+    beforeMinutes?: number;
+    afterMinutes?: number;
+}
+type AvailabilityReason = "AVAILABLE" | "COLLISION" | "OUTSIDE_BOUNDS" | "MIN_NOTICE_VIOLATION" | "MAX_HORIZON_EXCEEDED";
+interface TimeSlot extends TimeRange {
+    available: boolean;
+    reason: AvailabilityReason;
+}
+/**
+ * Represents an active window of available time.
+ * Sourced either dynamically from weekly business hours or explicitly from DB shifts.
+ */
+interface AvailableWindow extends TimeRange {
+    id?: string;
+    providerId?: string;
+}
+interface SlotGeneratorOptions {
+    /** Source operating windows (Dynamic business hours OR Explicit DB shifts) */
+    windows: AvailableWindow[];
+    /** Confirmed bookings, holds, or blackout windows to subtract */
+    existingBookings: TimeRange[];
+    /** Duration of the appointment in minutes */
+    durationMinutes: number;
+    /** Step interval between slot start times in minutes (e.g. 15 for slots every 15 mins) */
+    intervalMinutes: number;
+    /** Required pre/post service buffer rules */
+    buffers?: BufferConfig;
+    /** Minimum notice required before a booking (in minutes) */
+    minNoticeMinutes?: number;
+    /** Maximum booking horizon in minutes. Slots starting beyond now + this are excluded. */
+    maxHorizonMinutes?: number;
+}
+
+interface BookingRepository {
+    /** Fetch active windows: supporting both Dynamic rules and Explicit shifts */
+    getAvailableWindows(params: {
+        startDate: Date;
+        endDate: Date;
+        providerId?: string;
+        mode: "dynamic" | "explicit";
+        /** IANA timezone the dynamic weekly rules are expressed in */
+        timeZone: string;
+    }): Promise<AvailableWindow[]>;
+    /** Fetch confirmed bookings and active holds in target window */
+    getBookingsInRange(startDate: Date, endDate: Date, providerId?: string): Promise<TimeRange[]>;
+    /** Create an atomic slot hold */
+    createHold(params: {
+        serviceId: string;
+        providerId: string;
+        range: TimeRange;
+        customerId?: string;
+    }): Promise<{
+        holdToken: string;
+        expiresAt: Date;
+    }>;
+    /** Confirm a hold into a permanent booking */
+    confirmBooking(params: {
+        holdToken: string;
+        customerDetails: Record<string, unknown>;
+    }): Promise<{
+        bookingId: string;
+    }>;
+}
+
+/**
+ * Checks if two half-open time ranges [start, end) overlap.
+ * Touch points (RangeA.end === RangeB.start) do NOT overlap.
+ */
+/**
+ *
+ * @param {TimeRange} a - First range
+ * @param {TimeRange} b - Second range
+ * @returns - True if the ranges overlap, false otherwise
+ */
+declare function rangesOverlap(a: TimeRange, b: TimeRange): boolean;
+/**
+ * Expands a target range by applying pre and post buffer padding.
+ */
+declare function applyBufferToRange(range: TimeRange, buffer?: BufferConfig): TimeRange;
+
+/**
+ *
+ * @param {SlotGeneratorOptions} options
+ * @param {Date} now
+ * @returns - Generated time slots
+ */
+declare function generateTimeSlots(options: SlotGeneratorOptions, now?: Date): TimeSlot[];
+
+interface CalendarDay {
+    /** JavaScript Date object representing the day at 00:00:00 local time */
+    date: Date;
+    /** Local date key formatted as YYYY-MM-DD for easy lookup */
+    isoString: string;
+    /** Day of the month (1-31) */
+    dayOfMonth: number;
+    /** Day of the week: 0 = Sunday, 1 = Monday, ..., 6 = Saturday */
+    dayOfWeek: number;
+    /** Indicates whether the day belongs to the target month being rendered */
+    isCurrentMonth: boolean;
+    /** Indicates whether this day matches the current local system date */
+    isToday: boolean;
+    /** Indicates Saturday or Sunday */
+    isWeekend: boolean;
+    /** Flagged true if outside explicit view boundaries or explicitly blocked */
+    isBlocked: boolean;
+    /** Reason why the cell is blocked, if applicable */
+    blockReason?: "OUT_OF_BOUNDS" | "CUSTOM_EXCLUSION" | "PAST_DATE";
+}
+type MonthGrid = CalendarDay[][];
+type WeekGrid = CalendarDay[];
+interface MonthGridOptions {
+    year: number;
+    month: number;
+    weekStartsOn?: 0 | 1;
+}
+interface WeekGridOptions {
+    targetDate: Date;
+    weekStartsOn?: 0 | 1;
+}
+interface MultiWeekViewOptions {
+    startDate: Date;
+    endDate: Date;
+    maxWeeksAllowed?: number;
+    weekStartsOn?: 0 | 1;
+}
+interface MultiMonthViewOptions {
+    startDate: Date;
+    endDate: Date;
+    maxMonthsAllowed?: number;
+    weekStartsOn?: 0 | 1;
+}
+interface MonthViewUnit {
+    year: number;
+    month: number;
+    grid: MonthGrid;
+}
+/**
+ * Builds a month grid matrix (6 weeks x 7 days) including leading
+ * and trailing padding days from adjacent months.
+ */
+declare function buildMonthMatrix(options: MonthGridOptions): MonthGrid;
+/**
+ * Builds a single 7-day array matrix for a specific target week.
+ */
+declare function buildWeekMatrix(options: WeekGridOptions): WeekGrid;
+/**
+ * Builds a multi-week matrix across a range of dates.
+ * Days outside [startDate, endDate] inside boundary weeks are marked as blocked.
+ */
+declare function buildMultiWeekMatrix(options: MultiWeekViewOptions): MonthGrid;
+/**
+ * Builds a multi-month matrix across a date range.
+ * Days outside [startDate, endDate] are tagged as blocked cells.
+ */
+declare function buildMultiMonthMatrix(options: MultiMonthViewOptions): MonthViewUnit[];
+
+interface WallClockTime {
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+}
+/**
+ *
+ * @param {WallClockTime} wallClock - Wall clock target
+ * @param {string} timeZone - IANA timezone
+ * @returns - Exact UTC Date
+ */
+declare const wallClockToUTC: (wallClock: WallClockTime, timeZone: string) => Date;
+/**
+ *
+ * @param {Date} date - Exact UTC Date
+ * @param {string} timeZone - IANA timezone
+ * @returns - Wall-clock components in the target timezone
+ */
+declare const utcToWallClock: (date: Date, timeZone: string) => WallClockTime;
+
+/**
+ * Day of the week following JavaScript's Date#getDay() convention:
+ * 0 = Sunday, 1 = Monday, ..., 6 = Saturday.
+ */
+type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** A single weekly recurring operating rule expressed in local wall-clock time. */
+interface WeeklyRule {
+    dayOfWeek: DayOfWeek;
+    /** Local wall-clock start, 24-hour "HH:mm" */
+    startTime: string;
+    /** Local wall-clock end, 24-hour "HH:mm". Must be strictly after startTime. */
+    endTime: string;
+}
+interface WeeklyAvailabilityOptions {
+    /** Weekly rules to expand into windows */
+    rules: WeeklyRule[];
+    /** Query range start (inclusive), in UTC */
+    startDate: Date;
+    /** Query range end (exclusive), in UTC */
+    endDate: Date;
+    /** IANA timezone the rules are expressed in */
+    timeZone: string;
+}
+/**
+ * Expands weekly recurring rules into concrete windows within [startDate, endDate].
+ *
+ * Rules are expressed in local wall-clock time; windows are converted to UTC and
+ * clipped to the requested range. DST transitions are handled per-day via Intl,
+ * and duplicate windows (e.g. around a fall-back transition) are collapsed.
+ *
+ * @throws If a rule has an invalid time string or an overnight span (endTime <= startTime).
+ */
+declare function expandWeeklyRules(options: WeeklyAvailabilityOptions): AvailableWindow[];
+
+export { applyBufferToRange, buildMonthMatrix, buildMultiMonthMatrix, buildMultiWeekMatrix, buildWeekMatrix, expandWeeklyRules, generateTimeSlots, rangesOverlap, utcToWallClock, wallClockToUTC };
+export type { AvailabilityReason, AvailableWindow, BookingRepository, BufferConfig, CalendarDay, DayOfWeek, MonthGrid, MonthGridOptions, MonthViewUnit, MultiMonthViewOptions, MultiWeekViewOptions, SlotGeneratorOptions, TimeRange, TimeSlot, WallClockTime, WeekGrid, WeekGridOptions, WeeklyAvailabilityOptions, WeeklyRule };

package/dist/index.js

@@ -0,0 +1,383 @@
+// src/rules/collisions.ts
+function rangesOverlap(a, b) {
+  return a.start < b.end && a.end > b.start;
+}
+function applyBufferToRange(range, buffer) {
+  const beforeMs = (buffer?.beforeMinutes ?? 0) * 60 * 1e3;
+  const afterMs = (buffer?.afterMinutes ?? 0) * 60 * 1e3;
+  return {
+    start: new Date(range.start.getTime() - beforeMs),
+    end: new Date(range.end.getTime() + afterMs)
+  };
+}
+
+// src/engine/generator.ts
+function generateTimeSlots(options, now = /* @__PURE__ */ new Date()) {
+  const {
+    windows,
+    existingBookings,
+    durationMinutes,
+    intervalMinutes,
+    buffers = {},
+    minNoticeMinutes = 0,
+    maxHorizonMinutes
+  } = options;
+  if (windows.length === 0) return [];
+  const slotDurationMs = durationMinutes * 60 * 1e3;
+  const stepIntervalMs = intervalMinutes * 60 * 1e3;
+  const bufferBeforeMs = (buffers.beforeMinutes ?? 0) * 60 * 1e3;
+  const bufferAfterMs = (buffers.afterMinutes ?? 0) * 60 * 1e3;
+  const minNoticeCutoff = new Date(
+    now.getTime() + minNoticeMinutes * 60 * 1e3
+  );
+  const maxHorizonCutoff = maxHorizonMinutes !== void 0 ? new Date(now.getTime() + maxHorizonMinutes * 60 * 1e3) : null;
+  const bufferedBookings = existingBookings.map(
+    (b) => applyBufferToRange(b, buffers)
+  );
+  const candidateSlots = [];
+  for (const window of windows) {
+    let currentStartMs = window.start.getTime();
+    const windowEndMs = window.end.getTime();
+    while (currentStartMs + slotDurationMs <= windowEndMs) {
+      const slotStart = new Date(currentStartMs);
+      const slotEnd = new Date(currentStartMs + slotDurationMs);
+      const bufferedStartMs = currentStartMs - bufferBeforeMs;
+      const bufferedEndMs = currentStartMs + slotDurationMs + bufferAfterMs;
+      let available = true;
+      let reason = "AVAILABLE";
+      if (slotStart < minNoticeCutoff) {
+        available = false;
+        reason = "MIN_NOTICE_VIOLATION";
+      }
+      if (available && maxHorizonCutoff !== null && slotStart.getTime() > maxHorizonCutoff.getTime()) {
+        available = false;
+        reason = "MAX_HORIZON_EXCEEDED";
+      }
+      if (available && (bufferedStartMs < window.start.getTime() || bufferedEndMs > windowEndMs)) {
+        available = false;
+        reason = "OUTSIDE_BOUNDS";
+      }
+      if (available) {
+        const candidateRange = { start: slotStart, end: slotEnd };
+        const bufferedCandidate = applyBufferToRange(candidateRange, buffers);
+        const hasCollision = bufferedBookings.some(
+          (booking) => rangesOverlap(bufferedCandidate, booking)
+        );
+        if (hasCollision) {
+          available = false;
+          reason = "COLLISION";
+        }
+      }
+      candidateSlots.push({
+        start: slotStart,
+        end: slotEnd,
+        available,
+        reason
+      });
+      currentStartMs += stepIntervalMs;
+    }
+  }
+  return candidateSlots;
+}
+
+// src/engine/calendar.ts
+var toDateKey = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+function buildMonthMatrix(options) {
+  const { year, month, weekStartsOn = 0 } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const firstDayOfMonth = new Date(year, month - 1, 1);
+  let startOffset = firstDayOfMonth.getDay() - weekStartsOn;
+  if (startOffset < 0) startOffset += 7;
+  const startDate = new Date(firstDayOfMonth);
+  startDate.setDate(startDate.getDate() - startOffset);
+  const grid = [];
+  const currentDate = new Date(startDate);
+  for (let week = 0; week < 6; week++) {
+    const weekRow = [];
+    for (let day = 0; day < 7; day++) {
+      const isoString = toDateKey(currentDate);
+      const isCurrentMonth = currentDate.getMonth() === month - 1;
+      const dayOfWeek = currentDate.getDay();
+      weekRow.push({
+        date: new Date(currentDate),
+        isoString,
+        dayOfMonth: currentDate.getDate(),
+        dayOfWeek,
+        isCurrentMonth,
+        isToday: isoString === todayStr,
+        isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+        isBlocked: !isCurrentMonth,
+        blockReason: !isCurrentMonth ? "OUT_OF_BOUNDS" : void 0
+      });
+      currentDate.setDate(currentDate.getDate() + 1);
+    }
+    grid.push(weekRow);
+  }
+  return grid;
+}
+function buildWeekMatrix(options) {
+  const { targetDate, weekStartsOn = 0 } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const startOfWeek = new Date(targetDate);
+  let dayOffset = startOfWeek.getDay() - weekStartsOn;
+  if (dayOffset < 0) dayOffset += 7;
+  startOfWeek.setDate(startOfWeek.getDate() - dayOffset);
+  const week = [];
+  const currentDate = new Date(startOfWeek);
+  for (let i = 0; i < 7; i++) {
+    const isoString = toDateKey(currentDate);
+    const dayOfWeek = currentDate.getDay();
+    const isCurrentMonth = currentDate.getFullYear() === targetDate.getFullYear() && currentDate.getMonth() === targetDate.getMonth();
+    week.push({
+      date: new Date(currentDate),
+      isoString,
+      dayOfMonth: currentDate.getDate(),
+      dayOfWeek,
+      isCurrentMonth,
+      isToday: isoString === todayStr,
+      isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+      isBlocked: !isCurrentMonth,
+      blockReason: !isCurrentMonth ? "OUT_OF_BOUNDS" : void 0
+    });
+    currentDate.setDate(currentDate.getDate() + 1);
+  }
+  return week;
+}
+function buildMultiWeekMatrix(options) {
+  const {
+    startDate,
+    endDate,
+    maxWeeksAllowed = 12,
+    weekStartsOn = 0
+  } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const cursor = new Date(startDate);
+  let dayOffset = cursor.getDay() - weekStartsOn;
+  if (dayOffset < 0) dayOffset += 7;
+  cursor.setDate(cursor.getDate() - dayOffset);
+  const weeks = [];
+  let weekCount = 0;
+  const startMs = new Date(
+    startDate.getFullYear(),
+    startDate.getMonth(),
+    startDate.getDate()
+  ).getTime();
+  const endMs = new Date(
+    endDate.getFullYear(),
+    endDate.getMonth(),
+    endDate.getDate()
+  ).getTime();
+  while (cursor.getTime() <= endMs && weekCount < maxWeeksAllowed) {
+    const weekRow = [];
+    for (let i = 0; i < 7; i++) {
+      const currentMs = new Date(
+        cursor.getFullYear(),
+        cursor.getMonth(),
+        cursor.getDate()
+      ).getTime();
+      const isoString = toDateKey(cursor);
+      const dayOfWeek = cursor.getDay();
+      const isOutOfBounds = currentMs < startMs || currentMs > endMs;
+      weekRow.push({
+        date: new Date(cursor),
+        isoString,
+        dayOfMonth: cursor.getDate(),
+        dayOfWeek,
+        isCurrentMonth: true,
+        isToday: isoString === todayStr,
+        isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+        isBlocked: isOutOfBounds,
+        blockReason: isOutOfBounds ? "OUT_OF_BOUNDS" : void 0
+      });
+      cursor.setDate(cursor.getDate() + 1);
+    }
+    weeks.push(weekRow);
+    weekCount++;
+  }
+  return weeks;
+}
+function buildMultiMonthMatrix(options) {
+  const {
+    startDate,
+    endDate,
+    maxMonthsAllowed = 12,
+    weekStartsOn = 0
+  } = options;
+  const startMs = new Date(
+    startDate.getFullYear(),
+    startDate.getMonth(),
+    startDate.getDate()
+  ).getTime();
+  const endMs = new Date(
+    endDate.getFullYear(),
+    endDate.getMonth(),
+    endDate.getDate()
+  ).getTime();
+  const months = [];
+  let currentYear = startDate.getFullYear();
+  let currentMonth = startDate.getMonth() + 1;
+  let monthCount = 0;
+  const targetEndYear = endDate.getFullYear();
+  const targetEndMonth = endDate.getMonth() + 1;
+  while ((currentYear < targetEndYear || currentYear === targetEndYear && currentMonth <= targetEndMonth) && monthCount < maxMonthsAllowed) {
+    const baseGrid = buildMonthMatrix({
+      year: currentYear,
+      month: currentMonth,
+      weekStartsOn
+    });
+    const scopedGrid = baseGrid.map(
+      (weekRow) => weekRow.map((cell) => {
+        const cellMs = new Date(
+          cell.date.getFullYear(),
+          cell.date.getMonth(),
+          cell.date.getDate()
+        ).getTime();
+        const isOutOfBounds = cellMs < startMs || cellMs > endMs || !cell.isCurrentMonth;
+        return {
+          ...cell,
+          isBlocked: isOutOfBounds,
+          blockReason: isOutOfBounds ? "OUT_OF_BOUNDS" : void 0
+        };
+      })
+    );
+    months.push({
+      year: currentYear,
+      month: currentMonth,
+      grid: scopedGrid
+    });
+    monthCount++;
+    currentMonth++;
+    if (currentMonth > 12) {
+      currentMonth = 1;
+      currentYear++;
+    }
+  }
+  return months;
+}
+
+// src/engine/timezone.ts
+var wallClockToUTC = (wallClock, timeZone) => {
+  const pad = (n) => String(n).padStart(2, "0");
+  const isoStr = `${wallClock.year}-${pad(wallClock.month)}-${pad(wallClock.day)}T${pad(wallClock.hour)}:${pad(wallClock.minute)}:00`;
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const utcGuess = /* @__PURE__ */ new Date(`${isoStr}Z`);
+  const parts = Object.fromEntries(
+    formatter.formatToParts(utcGuess).map((p) => [p.type, p.value])
+  );
+  const localHeader = `${parts.year}-${parts.month}-${parts.day}T${parts.hour === "24" ? "00" : parts.hour}:${parts.minute}:${parts.second}`;
+  const diffMs = (/* @__PURE__ */ new Date(`${isoStr}Z`)).getTime() - (/* @__PURE__ */ new Date(`${localHeader}Z`)).getTime();
+  return new Date(utcGuess.getTime() + diffMs);
+};
+var utcToWallClock = (date, timeZone) => {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const parts = Object.fromEntries(
+    formatter.formatToParts(date).map((p) => [p.type, p.value])
+  );
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    hour: parts.hour === "24" ? 0 : Number(parts.hour),
+    minute: Number(parts.minute)
+  };
+};
+
+// src/engine/weekly.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var parseTime = (time) => {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+  if (!match) {
+    throw new Error(`Invalid time "${time}" \u2014 expected 24-hour "HH:mm".`);
+  }
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour > 23 || minute > 59) {
+    throw new Error(`Invalid time "${time}" \u2014 hour/minute out of range.`);
+  }
+  return { hour, minute };
+};
+var weekdayOf = (wallClock) => new Date(wallClock.year, wallClock.month - 1, wallClock.day).getDay();
+function expandWeeklyRules(options) {
+  const { rules, startDate, endDate, timeZone } = options;
+  const startMs = startDate.getTime();
+  const endMs = endDate.getTime();
+  if (endMs <= startMs) return [];
+  const parsedRules = rules.map((rule) => {
+    const start = parseTime(rule.startTime);
+    const end = parseTime(rule.endTime);
+    if (end.hour * 60 + end.minute <= start.hour * 60 + start.minute) {
+      throw new Error(
+        `Rule on day ${rule.dayOfWeek} must have endTime strictly after startTime (overnight spans are not supported).`
+      );
+    }
+    return { dayOfWeek: rule.dayOfWeek, start, end };
+  });
+  const firstUtcDayMs = startMs - startMs % DAY_MS;
+  const lastUtcDayMs = endMs - endMs % DAY_MS + DAY_MS;
+  const windows = [];
+  for (let t = firstUtcDayMs; t <= lastUtcDayMs; t += DAY_MS) {
+    const wallClock = utcToWallClock(new Date(t), timeZone);
+    const weekday = weekdayOf(wallClock);
+    for (const rule of parsedRules) {
+      if (rule.dayOfWeek !== weekday) continue;
+      const windowStart = wallClockToUTC(
+        { ...wallClock, hour: rule.start.hour, minute: rule.start.minute },
+        timeZone
+      );
+      const windowEnd = wallClockToUTC(
+        { ...wallClock, hour: rule.end.hour, minute: rule.end.minute },
+        timeZone
+      );
+      const clippedStart = Math.max(windowStart.getTime(), startMs);
+      const clippedEnd = Math.min(windowEnd.getTime(), endMs);
+      if (clippedEnd > clippedStart) {
+        windows.push({
+          start: new Date(clippedStart),
+          end: new Date(clippedEnd)
+        });
+      }
+    }
+  }
+  windows.sort(
+    (a, b) => a.start.getTime() - b.start.getTime() || a.end.getTime() - b.end.getTime()
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const window of windows) {
+    const key = `${window.start.getTime()}:${window.end.getTime()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(window);
+  }
+  return result;
+}
+export {
+  applyBufferToRange,
+  buildMonthMatrix,
+  buildMultiMonthMatrix,
+  buildMultiWeekMatrix,
+  buildWeekMatrix,
+  expandWeeklyRules,
+  generateTimeSlots,
+  rangesOverlap,
+  utcToWallClock,
+  wallClockToUTC
+};

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@apiary-dev/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Apiary core: zero-dependency, framework-agnostic scheduling domain logic",
+  "license": "ISC",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^9.0.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest"
+  }
 }