@catlabtech/mycal-core 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,517 +1,22 @@
-// src/schemas.ts
-import { z } from "zod";
-var isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Must be ISO 8601 date (YYYY-MM-DD)");
-var localizedString = z.object({
-  ms: z.string().min(1),
-  en: z.string().min(1),
-  zh: z.string().optional()
-});
-var holidayTypeSchema = z.enum([
-  "federal",
-  "state",
-  "islamic",
-  "islamic_state",
-  "replacement",
-  "adhoc"
-]);
-var holidayStatusSchema = z.enum([
-  "confirmed",
-  "tentative",
-  "announced",
-  "cancelled"
-]);
-var gazetteLevelSchema = z.enum(["P", "N"]);
-var holidaySourceSchema = z.enum([
-  "jpm",
-  "jakim",
-  "state-gov",
-  "community",
-  "admin"
-]);
-var holidaySchema = z.object({
-  id: z.string().min(1),
-  date: isoDate,
-  endDate: isoDate.optional(),
-  name: localizedString,
-  type: holidayTypeSchema,
-  status: holidayStatusSchema,
-  states: z.array(z.string().min(1)).min(1),
-  isPublicHoliday: z.boolean(),
-  gazetteLevel: gazetteLevelSchema,
-  isReplacementFor: z.string().optional(),
-  hijriDate: z.string().optional(),
-  gazetteRef: z.string().optional(),
-  source: holidaySourceSchema,
-  confirmedAt: z.string().optional(),
-  createdAt: z.string(),
-  updatedAt: z.string()
-});
-var holidayFileSchema = z.array(holidaySchema);
-var stateGroupSchema = z.enum(["A", "B"]);
-var weekendConfigSchema = z.object({
-  from: isoDate,
-  to: isoDate.nullable(),
-  weekendDays: z.array(z.number().int().min(0).max(6)),
-  group: stateGroupSchema
-});
-var stateSchema = z.object({
-  code: z.string().min(1),
-  aliases: z.array(z.string()),
-  name: localizedString,
-  type: z.enum(["state", "federal_territory"]),
-  weekendHistory: z.array(weekendConfigSchema).min(1),
-  group: stateGroupSchema
-});
-var statesFileSchema = z.array(stateSchema);
-var schoolTermSegmentSchema = z.object({
-  startDate: isoDate,
-  endDate: isoDate,
-  schoolDays: z.number().int().min(0)
-});
-var schoolTermSchema = z.object({
-  id: z.string().min(1),
-  year: z.number().int().min(2020).max(2100),
-  term: z.union([z.literal(1), z.literal(2)]),
-  group: stateGroupSchema,
-  segments: z.array(schoolTermSegmentSchema).min(1),
-  totalSchoolDays: z.number().int().min(0),
-  startDate: isoDate,
-  endDate: isoDate
-});
-var schoolHolidayTypeSchema = z.enum([
-  "cuti_penggal_1",
-  "cuti_pertengahan",
-  "cuti_penggal_2",
-  "cuti_akhir",
-  "cuti_perayaan_kpm"
-]);
-var schoolHolidaySchema = z.object({
-  id: z.string().min(1),
-  year: z.number().int().min(2020).max(2100),
-  group: stateGroupSchema,
-  type: schoolHolidayTypeSchema,
-  name: localizedString,
-  startDate: isoDate,
-  endDate: isoDate,
-  days: z.number().int().min(1),
-  states: z.array(z.string()).optional(),
-  excludeStates: z.array(z.string()).optional(),
-  remarks: z.string().optional()
-});
-var schoolTermsFileSchema = z.array(schoolTermSchema);
-var schoolHolidaysFileSchema = z.array(schoolHolidaySchema);
-var examTypeSchema = z.enum([
-  "spm",
-  "stpm",
-  "muet",
-  "pt3",
-  "stam",
-  "other"
-]);
-var examSchema = z.object({
-  id: z.string().min(1),
-  year: z.number().int().min(2020).max(2100),
-  name: z.string().min(1),
-  fullName: localizedString,
-  type: examTypeSchema,
-  startDate: isoDate,
-  endDate: isoDate.optional(),
-  status: z.enum(["confirmed", "tentative"]),
-  resultsDate: isoDate.optional(),
-  source: z.enum(["kpm", "mpm"])
-});
-var examsFileSchema = z.array(examSchema);
-
-// src/state-resolver.ts
-function resolveStateCode(query, states) {
-  const normalized = query.toLowerCase().trim();
-  for (const state of states) {
-    if (state.code === normalized) return state;
-    for (const alias of state.aliases) {
-      if (alias.toLowerCase() === normalized) return state;
-    }
-  }
-  return null;
-}
-function getStateByCode(code, states) {
-  return states.find((s) => s.code === code) ?? null;
-}
-function getStatesByGroup(group, states) {
-  return states.filter((s) => s.group === group);
-}
-
-// src/weekend.ts
-var DAY_NAMES = [
-  "Sunday",
-  "Monday",
-  "Tuesday",
-  "Wednesday",
-  "Thursday",
-  "Friday",
-  "Saturday"
-];
-function getWeekendConfig(state, date) {
-  for (const config of state.weekendHistory) {
-    const from = config.from;
-    const to = config.to;
-    if (date >= from && (to === null || date <= to)) {
-      return config;
-    }
-  }
-  return state.weekendHistory[0];
-}
-function isWeekend(date, state) {
-  const config = getWeekendConfig(state, date);
-  const dayOfWeek = (/* @__PURE__ */ new Date(date + "T12:00:00Z")).getUTCDay();
-  return config.weekendDays.includes(dayOfWeek);
-}
-function getDayOfWeekName(date) {
-  const dayIndex = (/* @__PURE__ */ new Date(date + "T12:00:00Z")).getUTCDay();
-  return DAY_NAMES[dayIndex];
-}
-function getWeekendDayNames(state, date) {
-  const config = getWeekendConfig(state, date);
-  return config.weekendDays.map((d) => DAY_NAMES[d]);
-}
-function addDays(date, days) {
-  const d = /* @__PURE__ */ new Date(date + "T12:00:00Z");
-  d.setUTCDate(d.getUTCDate() + days);
-  return d.toISOString().slice(0, 10);
-}
-function nextWorkingDay(date, state, holidayDates) {
-  let candidate = addDays(date, 1);
-  while (isWeekend(candidate, state) || holidayDates.has(candidate)) {
-    candidate = addDays(candidate, 1);
-  }
-  return candidate;
-}
-function diffDays(start, end) {
-  const s = (/* @__PURE__ */ new Date(start + "T00:00:00")).getTime();
-  const e = (/* @__PURE__ */ new Date(end + "T00:00:00")).getTime();
-  return Math.round((e - s) / (1e3 * 60 * 60 * 24));
-}
-
-// src/filter.ts
-function filterHolidays(holidays, filter) {
-  return holidays.filter((h) => {
-    if (filter.year !== void 0) {
-      const year = parseInt(h.date.slice(0, 4), 10);
-      if (year !== filter.year) return false;
-    }
-    if (filter.month !== void 0) {
-      const month = parseInt(h.date.slice(5, 7), 10);
-      if (month !== filter.month) return false;
-    }
-    if (filter.state !== void 0) {
-      if (!h.states.includes("*") && !h.states.includes(filter.state)) {
-        return false;
-      }
-    }
-    if (filter.type !== void 0 && h.type !== filter.type) return false;
-    if (filter.status !== void 0 && h.status !== filter.status) return false;
-    return true;
-  });
-}
-function findHolidaysByDate(date, holidays, stateCode) {
-  return holidays.filter((h) => {
-    if (h.date !== date) return false;
-    if (h.status === "cancelled") return false;
-    if (stateCode && !h.states.includes("*") && !h.states.includes(stateCode)) {
-      return false;
-    }
-    return true;
-  });
-}
-function findNextHoliday(afterDate, holidays, stateCode, type, limit = 1) {
-  const filtered = holidays.filter((h) => {
-    if (h.date <= afterDate) return false;
-    if (h.status === "cancelled") return false;
-    if (stateCode && !h.states.includes("*") && !h.states.includes(stateCode)) {
-      return false;
-    }
-    if (type !== void 0 && h.type !== type) return false;
-    return true;
-  }).sort((a, b) => a.date.localeCompare(b.date));
-  return filtered.slice(0, limit);
-}
-
-// src/replacement.ts
-function calculateReplacementHolidays(holidays, state) {
-  const stateHolidays = holidays.filter(
-    (h) => h.status !== "cancelled" && (h.states.includes("*") || h.states.includes(state.code))
-  );
-  const holidayDates = new Set(stateHolidays.map((h) => h.date));
-  const replacementDates = /* @__PURE__ */ new Set();
-  const replacements = [];
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  for (const holiday of stateHolidays) {
-    if (holiday.type === "replacement") continue;
-    if (isWeekend(holiday.date, state)) {
-      const allOccupied = /* @__PURE__ */ new Set([...holidayDates, ...replacementDates]);
-      const replacementDate = nextWorkingDay(holiday.date, state, allOccupied);
-      replacementDates.add(replacementDate);
-      replacements.push({
-        id: `${holiday.id}-replacement`,
-        date: replacementDate,
-        name: {
-          ms: `Cuti Ganti ${holiday.name.ms}`,
-          en: `Replacement for ${holiday.name.en}`,
-          zh: holiday.name.zh ? `\u8865\u5047 ${holiday.name.zh}` : void 0
-        },
-        type: "replacement",
-        status: holiday.status,
-        states: [state.code],
-        isPublicHoliday: true,
-        gazetteLevel: holiday.gazetteLevel,
-        isReplacementFor: holiday.id,
-        source: holiday.source,
-        createdAt: now,
-        updatedAt: now
-      });
-    }
-  }
-  const dateGroups = /* @__PURE__ */ new Map();
-  for (const h of stateHolidays) {
-    if (h.type === "replacement") continue;
-    const existing = dateGroups.get(h.date) ?? [];
-    dateGroups.set(h.date, [...existing, h]);
-  }
-  for (const [, group] of dateGroups) {
-    if (group.length <= 1) continue;
-    const stateHoliday = group.find((h) => h.gazetteLevel === "N");
-    if (!stateHoliday) continue;
-    if (replacements.some((r) => r.isReplacementFor === stateHoliday.id)) continue;
-    const allOccupied = /* @__PURE__ */ new Set([...holidayDates, ...replacementDates]);
-    const replacementDate = nextWorkingDay(stateHoliday.date, state, allOccupied);
-    replacementDates.add(replacementDate);
-    replacements.push({
-      id: `${stateHoliday.id}-overlap-replacement`,
-      date: replacementDate,
-      name: {
-        ms: `Cuti Ganti ${stateHoliday.name.ms}`,
-        en: `Replacement for ${stateHoliday.name.en}`,
-        zh: stateHoliday.name.zh ? `\u8865\u5047 ${stateHoliday.name.zh}` : void 0
-      },
-      type: "replacement",
-      status: stateHoliday.status,
-      states: [state.code],
-      isPublicHoliday: true,
-      gazetteLevel: stateHoliday.gazetteLevel,
-      isReplacementFor: stateHoliday.id,
-      source: stateHoliday.source,
-      createdAt: now,
-      updatedAt: now
-    });
-  }
-  return replacements;
-}
-
-// src/business-days.ts
-function countBusinessDays(start, end, state, holidays) {
-  const totalDays = diffDays(start, end) + 1;
-  let businessDays = 0;
-  let weekendCount = 0;
-  let holidayCount = 0;
-  const holidayList = [];
-  let current = start;
-  while (current <= end) {
-    const weekend = isWeekend(current, state);
-    const dayHolidays = findHolidaysByDate(current, holidays, state.code);
-    const isHoliday = dayHolidays.length > 0;
-    if (weekend) {
-      weekendCount++;
-    } else if (isHoliday) {
-      holidayCount++;
-      for (const h of dayHolidays) {
-        if (!holidayList.some((existing) => existing.id === h.id)) {
-          holidayList.push(h);
-        }
-      }
-    } else {
-      businessDays++;
-    }
-    current = addDays(current, 1);
-  }
-  return {
-    totalDays,
-    businessDays,
-    holidays: holidayCount,
-    weekendDays: weekendCount,
-    holidayList
-  };
-}
-function addBusinessDays(startDate, daysToAdd, state, holidays) {
-  let remaining = daysToAdd;
-  let current = startDate;
-  while (remaining > 0) {
-    current = addDays(current, 1);
-    const weekend = isWeekend(current, state);
-    const isHoliday = findHolidaysByDate(current, holidays, state.code).length > 0;
-    if (!weekend && !isHoliday) {
-      remaining--;
-    }
-  }
-  return current;
-}
-
-// src/school.ts
-function findSchoolTermByDate(date, terms, group) {
-  return terms.find(
-    (t) => t.group === group && date >= t.startDate && date <= t.endDate
-  ) ?? null;
-}
-function findSchoolHolidayByDate(date, holidays, group, stateCode) {
-  return holidays.find((h) => {
-    if (h.group !== group) return false;
-    if (date < h.startDate || date > h.endDate) return false;
-    if (stateCode && h.excludeStates?.includes(stateCode)) return false;
-    if (h.states && !h.states.includes(stateCode ?? "")) return false;
-    return true;
-  }) ?? null;
-}
-function isSchoolDay(date, terms, schoolHolidays, group, isPublicHoliday, isWeekendDay, stateCode) {
-  if (isWeekendDay) return false;
-  if (isPublicHoliday) return false;
-  const schoolHoliday = findSchoolHolidayByDate(
-    date,
-    schoolHolidays,
-    group,
-    stateCode
-  );
-  if (schoolHoliday) return false;
-  const term = findSchoolTermByDate(date, terms, group);
-  return term !== null;
-}
-
-// src/ical.ts
-function escapeIcal(text) {
-  return text.replace(/[\\;,]/g, (c) => `\\${c}`).replace(/\n/g, "\\n");
-}
-function formatIcalDate(date) {
-  return date.replace(/-/g, "");
-}
-function holidayToVevent(h) {
-  const dtstart = formatIcalDate(h.date);
-  const dtend = h.endDate ? formatIcalDate(h.endDate) : formatIcalDate(h.date);
-  return [
-    "BEGIN:VEVENT",
-    `DTSTART;VALUE=DATE:${dtstart}`,
-    `DTEND;VALUE=DATE:${dtend}`,
-    `SUMMARY:${escapeIcal(h.name.en)}`,
-    `DESCRIPTION:${escapeIcal(h.name.ms)}${h.hijriDate ? ` (${h.hijriDate})` : ""}`,
-    `UID:${h.id}@mycal.my`,
-    `STATUS:${h.status === "tentative" ? "TENTATIVE" : "CONFIRMED"}`,
-    "END:VEVENT"
-  ].join("\r\n");
-}
-function schoolHolidayToVevent(h) {
-  return [
-    "BEGIN:VEVENT",
-    `DTSTART;VALUE=DATE:${formatIcalDate(h.startDate)}`,
-    `DTEND;VALUE=DATE:${formatIcalDate(h.endDate)}`,
-    `SUMMARY:[School] ${escapeIcal(h.name.en)}`,
-    `DESCRIPTION:${escapeIcal(h.name.ms)}`,
-    `UID:${h.id}@mycal.my`,
-    "STATUS:CONFIRMED",
-    "END:VEVENT"
-  ].join("\r\n");
-}
-function generateIcal(holidays, schoolHolidays, calendarName) {
-  const header = [
-    "BEGIN:VCALENDAR",
-    "VERSION:2.0",
-    "PRODID:-//MyCal//Malaysia Calendar API//EN",
-    `X-WR-CALNAME:${escapeIcal(calendarName)}`,
-    "X-WR-TIMEZONE:Asia/Kuala_Lumpur",
-    "CALSCALE:GREGORIAN",
-    "METHOD:PUBLISH",
-    "REFRESH-INTERVAL;VALUE=DURATION:PT6H",
-    "X-PUBLISHED-TTL:PT6H"
-  ].join("\r\n");
-  const events = [
-    ...holidays.filter((h) => h.status !== "cancelled").map(holidayToVevent),
-    ...schoolHolidays.map(schoolHolidayToVevent)
-  ].join("\r\n");
-  return `${header}\r
-${events}\r
-END:VCALENDAR\r
-`;
-}
-
-// src/hijri.ts
-var HIJRI_MONTHS = [
-  { number: 1, nameMs: "Muharam", nameEn: "Muharram", nameAr: "\u0645\u062D\u0631\u0651\u0645" },
-  { number: 2, nameMs: "Safar", nameEn: "Safar", nameAr: "\u0635\u0641\u0631" },
-  { number: 3, nameMs: "Rabiulawal", nameEn: "Rabi al-Awwal", nameAr: "\u0631\u0628\u064A\u0639 \u0627\u0644\u0623\u0648\u0651\u0644" },
-  { number: 4, nameMs: "Rabiulakhir", nameEn: "Rabi al-Thani", nameAr: "\u0631\u0628\u064A\u0639 \u0627\u0644\u062B\u0627\u0646\u064A" },
-  { number: 5, nameMs: "Jamadilawal", nameEn: "Jumada al-Ula", nameAr: "\u062C\u0645\u0627\u062F\u0649 \u0627\u0644\u0623\u0648\u0644\u0649" },
-  { number: 6, nameMs: "Jamadilakhir", nameEn: "Jumada al-Thani", nameAr: "\u062C\u0645\u0627\u062F\u0649 \u0627\u0644\u062B\u0627\u0646\u064A\u0629" },
-  { number: 7, nameMs: "Rejab", nameEn: "Rajab", nameAr: "\u0631\u062C\u0628" },
-  { number: 8, nameMs: "Syaaban", nameEn: "Sha'ban", nameAr: "\u0634\u0639\u0628\u0627\u0646" },
-  { number: 9, nameMs: "Ramadan", nameEn: "Ramadan", nameAr: "\u0631\u0645\u0636\u0627\u0646" },
-  { number: 10, nameMs: "Syawal", nameEn: "Shawwal", nameAr: "\u0634\u0648\u0651\u0627\u0644" },
-  { number: 11, nameMs: "Zulkaedah", nameEn: "Dhu al-Qi'dah", nameAr: "\u0630\u0648 \u0627\u0644\u0642\u0639\u062F\u0629" },
-  { number: 12, nameMs: "Zulhijjah", nameEn: "Dhu al-Hijjah", nameAr: "\u0630\u0648 \u0627\u0644\u062D\u062C\u0651\u0629" }
-];
-function parseHijriDate(hijriStr) {
-  const match = hijriStr.match(/^(\d+)\s+(.+?)\s+(\d+)$/);
-  if (!match) return null;
-  const day = parseInt(match[1], 10);
-  const monthName = match[2].toLowerCase();
-  const year = parseInt(match[3], 10);
-  const month = HIJRI_MONTHS.find(
-    (m) => m.nameMs.toLowerCase() === monthName || m.nameEn.toLowerCase() === monthName
-  );
-  if (!month) return null;
-  return { day, month, year };
-}
-function formatHijriDate(day, monthNumber, year) {
-  const month = HIJRI_MONTHS.find((m) => m.number === monthNumber);
-  if (!month) return `${day} ? ${year}`;
-  return `${day} ${month.nameMs} ${year}`;
-}
-var ISLAMIC_HOLIDAY_DATES = [
-  { nameMs: "Awal Muharam", nameEn: "Islamic New Year", hijriMonth: 1, hijriDay: 1 },
-  { nameMs: "Maulidur Rasul", nameEn: "Prophet Muhammad's Birthday", hijriMonth: 3, hijriDay: 12 },
-  { nameMs: "Israk dan Mikraj", nameEn: "Isra' Mi'raj", hijriMonth: 7, hijriDay: 27 },
-  { nameMs: "Nuzul Al-Quran", nameEn: "Revelation of the Quran", hijriMonth: 9, hijriDay: 17 },
-  { nameMs: "Hari Raya Aidilfitri", nameEn: "Eid al-Fitr", hijriMonth: 10, hijriDay: 1 },
-  { nameMs: "Hari Raya Haji", nameEn: "Eid al-Adha", hijriMonth: 12, hijriDay: 10 },
-  { nameMs: "Hari Arafah", nameEn: "Day of Arafah", hijriMonth: 12, hijriDay: 9 }
-];
-export {
-  HIJRI_MONTHS,
-  ISLAMIC_HOLIDAY_DATES,
-  addBusinessDays,
-  addDays,
-  calculateReplacementHolidays,
-  countBusinessDays,
-  diffDays,
-  examSchema,
-  examsFileSchema,
-  filterHolidays,
-  findHolidaysByDate,
-  findNextHoliday,
-  findSchoolHolidayByDate,
-  findSchoolTermByDate,
-  formatHijriDate,
-  generateIcal,
-  getDayOfWeekName,
-  getStateByCode,
-  getStatesByGroup,
-  getWeekendConfig,
-  getWeekendDayNames,
-  holidayFileSchema,
-  holidaySchema,
-  isSchoolDay,
-  isWeekend,
-  nextWorkingDay,
-  parseHijriDate,
-  resolveStateCode,
-  schoolHolidaySchema,
-  schoolHolidaysFileSchema,
-  schoolTermSchema,
-  schoolTermsFileSchema,
-  stateSchema,
-  statesFileSchema
-};
+// Schemas
+export { holidaySchema, holidayCategorySchema, holidayFileSchema, stateSchema, statesFileSchema, schoolTermSchema, schoolTermsFileSchema, schoolHolidaySchema, schoolHolidaysFileSchema, examSchema, examsFileSchema, } from "./schemas.js";
+// State resolution
+export { resolveStateCode, getStateByCode, getStatesByGroup, } from "./state-resolver.js";
+// Weekend utilities
+export { getWeekendConfig, isWeekend, getDayOfWeekName, getWeekendDayNames, addDays, nextWorkingDay, diffDays, } from "./weekend.js";
+// Holiday filtering
+export { filterHolidays, findHolidaysByDate, findNextHoliday, groupHolidaysByDate, } from "./filter.js";
+// Replacement holiday calculation
+export { calculateReplacementHolidays } from "./replacement.js";
+// Business days
+export { countBusinessDays, addBusinessDays, subtractBusinessDays, isBusinessDay, nextBusinessDay, previousBusinessDay, } from "./business-days.js";
+// Long weekends & leave optimization
+export { findLongWeekends, optimizeLeave } from "./long-weekend.js";
+// Input validation & request-safety utilities
+export { isValidISODate, timingSafeEqualString, isSafePublicHttpsUrl, } from "./validation.js";
+// School calendar
+export { findSchoolTermByDate, findSchoolHolidayByDate, filterSchoolHolidays, isSchoolDay, } from "./school.js";
+// iCal generation
+export { generateIcal } from "./ical.js";
+// Hijri utilities
+export { HIJRI_MONTHS, ISLAMIC_HOLIDAY_DATES, parseHijriDate, formatHijriDate, } from "./hijri.js";

package/dist/long-weekend.d.ts

@@ -0,0 +1,18 @@
+import type { Holiday, State, LongWeekend, LeaveSuggestion } from "./types.js";
+/**
+ * Natural long weekends for a state in a given year: runs of 3+ consecutive
+ * non-working days (weekend days and/or public holidays) that need no leave.
+ *
+ * Shared by the REST `/holidays/long-weekends` route and the MCP server so the
+ * two cannot diverge.
+ */
+export declare function findLongWeekends(year: number, state: State, holidays: readonly Holiday[]): LongWeekend[];
+/**
+ * Leave optimizer: where can you spend up to `maxLeave` working days to chain
+ * weekends and public holidays into the longest possible continuous break?
+ *
+ * Returns suggestions sorted by efficiency (days off gained per leave day spent),
+ * then by total length. Each suggestion's `leaveDates` are the exact working days
+ * to request off — e.g. "take 2026-09-14 & 2026-09-15 → 2026-09-12…2026-09-16".
+ */
+export declare function optimizeLeave(year: number, state: State, holidays: readonly Holiday[], maxLeave?: number): LeaveSuggestion[];

package/dist/long-weekend.js

@@ -0,0 +1,127 @@
+import { addDays, diffDays, isWeekend } from "./weekend.js";
+import { groupHolidaysByDate } from "./filter.js";
+/**
+ * Natural long weekends for a state in a given year: runs of 3+ consecutive
+ * non-working days (weekend days and/or public holidays) that need no leave.
+ *
+ * Shared by the REST `/holidays/long-weekends` route and the MCP server so the
+ * two cannot diverge.
+ */
+export function findLongWeekends(year, state, holidays) {
+    const holidayMap = groupHolidaysByDate(holidays, state.code);
+    const isOff = (d) => isWeekend(d, state) || holidayMap.has(d);
+    const yearStart = `${year}-01-01`;
+    const yearEnd = `${year}-12-31`;
+    // Scan a little past both year boundaries so a run that is still "off" at
+    // Dec 31 (or already running on Jan 1) is measured in full instead of being
+    // truncated at the boundary. A run is only *reported* when it starts within
+    // the requested year, so a boundary-straddling long weekend is attributed to
+    // exactly one year and never double-counted.
+    const scanStart = addDays(yearStart, -7);
+    const scanEnd = addDays(yearEnd, 7);
+    const result = [];
+    let current = scanStart;
+    while (current <= scanEnd) {
+        if (!isOff(current)) {
+            current = addDays(current, 1);
+            continue;
+        }
+        const startDate = current;
+        const streakHolidays = [];
+        let weekendDays = 0;
+        let totalDays = 0;
+        while (current <= scanEnd && isOff(current)) {
+            if (isWeekend(current, state))
+                weekendDays++;
+            const hs = holidayMap.get(current);
+            if (hs)
+                streakHolidays.push(...hs);
+            totalDays++;
+            current = addDays(current, 1);
+        }
+        if (totalDays >= 3 && startDate >= yearStart && startDate <= yearEnd) {
+            result.push({
+                startDate,
+                endDate: addDays(current, -1),
+                totalDays,
+                holidays: streakHolidays,
+                weekendDays,
+                bridgeDaysNeeded: 0, // natural long weekend — no leave required
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Leave optimizer: where can you spend up to `maxLeave` working days to chain
+ * weekends and public holidays into the longest possible continuous break?
+ *
+ * Returns suggestions sorted by efficiency (days off gained per leave day spent),
+ * then by total length. Each suggestion's `leaveDates` are the exact working days
+ * to request off — e.g. "take 2026-09-14 & 2026-09-15 → 2026-09-12…2026-09-16".
+ */
+export function optimizeLeave(year, state, holidays, maxLeave = 3) {
+    if (!Number.isInteger(maxLeave) || maxLeave < 1)
+        return [];
+    const holidayMap = groupHolidaysByDate(holidays, state.code);
+    const isOff = (d) => isWeekend(d, state) || holidayMap.has(d);
+    const yearEnd = `${year}-12-31`;
+    const suggestions = [];
+    let s = `${year}-01-01`;
+    while (s <= yearEnd) {
+        // A break starts on an off-day whose previous day is a working day.
+        if (!isOff(s) || isOff(addDays(s, -1))) {
+            s = addDays(s, 1);
+            continue;
+        }
+        let leave = 0;
+        let d = s;
+        while (d <= yearEnd) {
+            if (!isOff(d)) {
+                leave++;
+                if (leave > maxLeave)
+                    break;
+            }
+            const next = addDays(d, 1);
+            // Window [s..d] is a complete break when it ends on an off-day followed by
+            // a working day, and at least one leave day was spent inside it.
+            if (leave >= 1 && isOff(d) && !isOff(next)) {
+                const leaveDates = [];
+                const within = [];
+                let c = s;
+                while (c <= d) {
+                    if (!isOff(c))
+                        leaveDates.push(c);
+                    const hs = holidayMap.get(c);
+                    if (hs)
+                        within.push(...hs);
+                    c = addDays(c, 1);
+                }
+                const totalDays = diffDays(s, d) + 1;
+                suggestions.push({
+                    startDate: s,
+                    endDate: d,
+                    totalDays,
+                    leaveDates,
+                    leaveCost: leaveDates.length,
+                    efficiency: Math.round((totalDays / leaveDates.length) * 100) / 100,
+                    holidays: within,
+                });
+            }
+            d = next;
+        }
+        s = addDays(s, 1);
+    }
+    suggestions.sort((a, b) => b.efficiency - a.efficiency ||
+        b.totalDays - a.totalDays ||
+        a.startDate.localeCompare(b.startDate));
+    // Collapse duplicate windows (the same break can be reached from one start).
+    const seen = new Set();
+    return suggestions.filter((x) => {
+        const key = `${x.startDate}:${x.endDate}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}

package/dist/replacement.d.ts

@@ -0,0 +1,2 @@
+import type { Holiday, State } from "./types.js";
+export declare function calculateReplacementHolidays(holidays: readonly Holiday[], state: State): readonly Holiday[];