@catlabtech/mycal-core 0.1.2 → 0.1.3

package/dist/schemas.js

@@ -0,0 +1,136 @@
+import { z } from "zod";
+const isoDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Must be ISO 8601 date (YYYY-MM-DD)");
+const localizedString = z.object({
+    ms: z.string().min(1),
+    en: z.string().min(1),
+    zh: z.string().optional(),
+});
+// ─── Holiday Schema ───
+export const holidayTypeSchema = z.enum([
+    "federal",
+    "state",
+    "islamic",
+    "islamic_state",
+    "replacement",
+    "adhoc",
+]);
+export const holidayStatusSchema = z.enum([
+    "confirmed",
+    "tentative",
+    "announced",
+    "cancelled",
+]);
+export const gazetteLevelSchema = z.enum(["P", "N"]);
+export const holidayCategorySchema = z.enum([
+    "public",
+    "bank",
+    "optional",
+    "half_day",
+    "observance",
+]);
+export const holidaySourceSchema = z.enum([
+    "jpm",
+    "jakim",
+    "state-gov",
+    "community",
+    "admin",
+]);
+export const 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,
+    category: holidayCategorySchema.optional(),
+    isEstimated: z.boolean().optional(),
+    confirmedAt: z.string().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+});
+export const holidayFileSchema = z.array(holidaySchema);
+// ─── State Schema ───
+export const stateGroupSchema = z.enum(["A", "B"]);
+export const weekendConfigSchema = z.object({
+    from: isoDate,
+    to: isoDate.nullable(),
+    weekendDays: z.array(z.number().int().min(0).max(6)),
+    group: stateGroupSchema,
+});
+export const 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,
+    isoCode: z.string().optional(),
+});
+export const statesFileSchema = z.array(stateSchema);
+// ─── School Calendar Schemas ───
+export const schoolTermSegmentSchema = z.object({
+    startDate: isoDate,
+    endDate: isoDate,
+    schoolDays: z.number().int().min(0),
+});
+export const 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,
+});
+export const schoolHolidayTypeSchema = z.enum([
+    "cuti_penggal_1",
+    "cuti_pertengahan",
+    "cuti_penggal_2",
+    "cuti_akhir",
+    "cuti_perayaan_kpm",
+]);
+export const 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(),
+});
+export const schoolTermsFileSchema = z.array(schoolTermSchema);
+export const schoolHolidaysFileSchema = z.array(schoolHolidaySchema);
+// ─── Exam Schema ───
+export const examTypeSchema = z.enum([
+    "spm",
+    "stpm",
+    "muet",
+    "pt3",
+    "stam",
+    "other",
+]);
+export const 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"]),
+});
+export const examsFileSchema = z.array(examSchema);

package/dist/school.d.ts

@@ -0,0 +1,10 @@
+import type { SchoolTerm, SchoolHoliday, StateGroup } from "./types.js";
+export declare function findSchoolTermByDate(date: string, terms: readonly SchoolTerm[], group: StateGroup): SchoolTerm | null;
+export declare function findSchoolHolidayByDate(date: string, holidays: readonly SchoolHoliday[], group: StateGroup, stateCode?: string): SchoolHoliday | null;
+/**
+ * List the school holidays that apply to a group (and optionally a specific
+ * state, honouring `states`/`excludeStates` overrides). Shared by the REST
+ * `/school/holidays` and iCal feed routes so the filter logic lives in one place.
+ */
+export declare function filterSchoolHolidays(holidays: readonly SchoolHoliday[], group: StateGroup, stateCode?: string): readonly SchoolHoliday[];
+export declare function isSchoolDay(date: string, terms: readonly SchoolTerm[], schoolHolidays: readonly SchoolHoliday[], group: StateGroup, isPublicHoliday: boolean, isWeekendDay: boolean, stateCode?: string): boolean;

package/dist/school.js

@@ -0,0 +1,44 @@
+export function findSchoolTermByDate(date, terms, group) {
+    return (terms.find((t) => t.group === group && date >= t.startDate && date <= t.endDate) ?? null);
+}
+export 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;
+        // Check state-level exceptions
+        if (stateCode && h.excludeStates?.includes(stateCode))
+            return false;
+        if (h.states && !h.states.includes(stateCode ?? ""))
+            return false;
+        return true;
+    }) ?? null);
+}
+/**
+ * List the school holidays that apply to a group (and optionally a specific
+ * state, honouring `states`/`excludeStates` overrides). Shared by the REST
+ * `/school/holidays` and iCal feed routes so the filter logic lives in one place.
+ */
+export function filterSchoolHolidays(holidays, group, stateCode) {
+    return holidays.filter((h) => {
+        if (h.group !== group)
+            return false;
+        if (stateCode && h.excludeStates?.includes(stateCode))
+            return false;
+        if (h.states && stateCode && !h.states.includes(stateCode))
+            return false;
+        return true;
+    });
+}
+export 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;
+}

package/dist/state-resolver.d.ts

@@ -0,0 +1,4 @@
+import type { State } from "./types.js";
+export declare function resolveStateCode(query: string, states: readonly State[]): State | null;
+export declare function getStateByCode(code: string, states: readonly State[]): State | null;
+export declare function getStatesByGroup(group: "A" | "B", states: readonly State[]): readonly State[];

package/dist/state-resolver.js

@@ -0,0 +1,18 @@
+export 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;
+}
+export function getStateByCode(code, states) {
+    return states.find((s) => s.code === code) ?? null;
+}
+export function getStatesByGroup(group, states) {
+    return states.filter((s) => s.group === group);
+}

package/dist/types.d.ts

@@ -0,0 +1,144 @@
+export interface LocalizedString {
+    readonly ms: string;
+    readonly en: string;
+    readonly zh?: string;
+}
+export type HolidayType = "federal" | "state" | "islamic" | "islamic_state" | "replacement" | "adhoc";
+export type HolidayCategory = "public" | "bank" | "optional" | "half_day" | "observance";
+export type HolidayStatus = "confirmed" | "tentative" | "announced" | "cancelled";
+export type GazetteLevel = "P" | "N";
+export type HolidaySource = "jpm" | "jakim" | "state-gov" | "community" | "admin";
+export interface Holiday {
+    readonly id: string;
+    readonly date: string;
+    readonly endDate?: string;
+    readonly name: LocalizedString;
+    readonly type: HolidayType;
+    readonly status: HolidayStatus;
+    readonly states: readonly string[];
+    readonly isPublicHoliday: boolean;
+    readonly gazetteLevel: GazetteLevel;
+    readonly isReplacementFor?: string;
+    readonly hijriDate?: string;
+    readonly gazetteRef?: string;
+    readonly source: HolidaySource;
+    readonly category?: HolidayCategory;
+    readonly isEstimated?: boolean;
+    readonly confirmedAt?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export type StateGroup = "A" | "B";
+export interface WeekendConfig {
+    readonly from: string;
+    readonly to: string | null;
+    readonly weekendDays: readonly number[];
+    readonly group: StateGroup;
+}
+export type StateType = "state" | "federal_territory";
+export interface State {
+    readonly code: string;
+    readonly aliases: readonly string[];
+    readonly name: LocalizedString;
+    readonly type: StateType;
+    readonly weekendHistory: readonly WeekendConfig[];
+    readonly group: StateGroup;
+    readonly isoCode?: string;
+}
+export interface SchoolTermSegment {
+    readonly startDate: string;
+    readonly endDate: string;
+    readonly schoolDays: number;
+}
+export interface SchoolTerm {
+    readonly id: string;
+    readonly year: number;
+    readonly term: 1 | 2;
+    readonly group: StateGroup;
+    readonly segments: readonly SchoolTermSegment[];
+    readonly totalSchoolDays: number;
+    readonly startDate: string;
+    readonly endDate: string;
+}
+export type SchoolHolidayType = "cuti_penggal_1" | "cuti_pertengahan" | "cuti_penggal_2" | "cuti_akhir" | "cuti_perayaan_kpm";
+export interface SchoolHoliday {
+    readonly id: string;
+    readonly year: number;
+    readonly group: StateGroup;
+    readonly type: SchoolHolidayType;
+    readonly name: LocalizedString;
+    readonly startDate: string;
+    readonly endDate: string;
+    readonly days: number;
+    readonly states?: readonly string[];
+    readonly excludeStates?: readonly string[];
+    readonly remarks?: string;
+}
+export type ExamType = "spm" | "stpm" | "muet" | "pt3" | "stam" | "other";
+export type ExamSource = "kpm" | "mpm";
+export interface Exam {
+    readonly id: string;
+    readonly year: number;
+    readonly name: string;
+    readonly fullName: LocalizedString;
+    readonly type: ExamType;
+    readonly startDate: string;
+    readonly endDate?: string;
+    readonly status: "confirmed" | "tentative";
+    readonly resultsDate?: string;
+    readonly source: ExamSource;
+}
+export interface CheckDateResult {
+    readonly date: string;
+    readonly dayOfWeek: string;
+    readonly isHoliday: boolean;
+    readonly isWeekend: boolean;
+    readonly isWorkingDay: boolean;
+    readonly isSchoolDay: boolean;
+    readonly holidays: readonly Holiday[];
+    readonly school: {
+        readonly group: StateGroup;
+        readonly term: SchoolTerm | null;
+        readonly holiday: SchoolHoliday | null;
+    } | null;
+    readonly state: {
+        readonly code: string;
+        readonly weekendDays: readonly string[];
+        readonly group: StateGroup;
+    };
+}
+export interface BusinessDaysResult {
+    readonly totalDays: number;
+    readonly businessDays: number;
+    readonly holidays: number;
+    readonly weekendDays: number;
+    readonly holidayList: readonly Holiday[];
+}
+export interface LongWeekend {
+    readonly startDate: string;
+    readonly endDate: string;
+    readonly totalDays: number;
+    readonly holidays: readonly Holiday[];
+    readonly weekendDays: number;
+    readonly bridgeDaysNeeded: number;
+}
+export interface LeaveSuggestion {
+    readonly startDate: string;
+    readonly endDate: string;
+    readonly totalDays: number;
+    readonly leaveDates: readonly string[];
+    readonly leaveCost: number;
+    readonly efficiency: number;
+    readonly holidays: readonly Holiday[];
+}
+export interface ChangelogEntry {
+    readonly timestamp: string;
+    readonly event: string;
+    readonly holidayId?: string;
+    readonly examId?: string;
+    readonly description: string;
+    readonly changes?: Record<string, {
+        from: unknown;
+        to: unknown;
+    }>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// ─── Localized String ───
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Input-validation and request-safety helpers shared by the API layer. Kept here
+ * (pure, dependency-free) so they are unit-testable and reusable by any consumer.
+ */
+/** True only for a real calendar date in strict `YYYY-MM-DD` form (rejects 2026-02-30). */
+export declare function isValidISODate(value: string): boolean;
+/**
+ * Constant-time string comparison for secrets (API keys). Returns early only on
+ * a length mismatch; otherwise compares every byte so timing does not leak how
+ * many leading characters matched.
+ */
+export declare function timingSafeEqualString(a: string, b: string): boolean;
+/**
+ * SSRF guard for user-supplied callback/webhook URLs. Requires HTTPS and rejects
+ * obviously-internal targets (localhost, *.local/.internal, and private/loopback/
+ * link-local/reserved IP literals incl. the 169.254.169.254 cloud-metadata IP).
+ *
+ * Best-effort at registration time: DNS is NOT resolved here, so delivery code
+ * MUST re-validate the resolved IP to defend against DNS rebinding.
+ */
+export declare function isSafePublicHttpsUrl(raw: string): boolean;

package/dist/validation.js

@@ -0,0 +1,94 @@
+/**
+ * Input-validation and request-safety helpers shared by the API layer. Kept here
+ * (pure, dependency-free) so they are unit-testable and reusable by any consumer.
+ */
+/** True only for a real calendar date in strict `YYYY-MM-DD` form (rejects 2026-02-30). */
+export function isValidISODate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const d = new Date(value + "T12:00:00Z");
+    return !Number.isNaN(d.getTime()) && d.toISOString().slice(0, 10) === value;
+}
+/**
+ * Constant-time string comparison for secrets (API keys). Returns early only on
+ * a length mismatch; otherwise compares every byte so timing does not leak how
+ * many leading characters matched.
+ */
+export function timingSafeEqualString(a, b) {
+    const enc = new TextEncoder();
+    const ab = enc.encode(a);
+    const bb = enc.encode(b);
+    if (ab.length !== bb.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < ab.length; i++)
+        diff |= ab[i] ^ bb[i];
+    return diff === 0;
+}
+function isPrivateOrReservedIp(host) {
+    // IPv6 literal (URL.hostname has already stripped the [brackets]).
+    if (host.includes(":")) {
+        if (host === "::1" || host === "::")
+            return true;
+        if (host.startsWith("fe80"))
+            return true; // link-local
+        if (host.startsWith("fc") || host.startsWith("fd"))
+            return true; // unique-local
+        if (host.startsWith("::ffff:"))
+            return isPrivateOrReservedIp(host.slice(7));
+        return false;
+    }
+    const m = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m)
+        return false; // not an IP literal → a hostname (resolve-time check needed)
+    const octets = m.slice(1).map(Number);
+    if (octets.some((n) => n > 255))
+        return true; // malformed → block
+    const [a, b] = octets;
+    if (a === 0)
+        return true; // "this" network
+    if (a === 10)
+        return true; // private
+    if (a === 127)
+        return true; // loopback
+    if (a === 169 && b === 254)
+        return true; // link-local + cloud metadata 169.254.169.254
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // private
+    if (a === 192 && b === 168)
+        return true; // private
+    if (a === 100 && b >= 64 && b <= 127)
+        return true; // CGNAT (RFC 6598)
+    if (a >= 224)
+        return true; // multicast / reserved
+    return false;
+}
+/**
+ * SSRF guard for user-supplied callback/webhook URLs. Requires HTTPS and rejects
+ * obviously-internal targets (localhost, *.local/.internal, and private/loopback/
+ * link-local/reserved IP literals incl. the 169.254.169.254 cloud-metadata IP).
+ *
+ * Best-effort at registration time: DNS is NOT resolved here, so delivery code
+ * MUST re-validate the resolved IP to defend against DNS rebinding.
+ */
+export function isSafePublicHttpsUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol !== "https:")
+        return false;
+    // URL.hostname keeps the [brackets] around IPv6 literals — strip them so the
+    // address checks below see a bare "::1" / "fe80::…".
+    const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+    if (host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host.endsWith(".local") ||
+        host.endsWith(".internal")) {
+        return false;
+    }
+    return !isPrivateOrReservedIp(host);
+}

package/dist/weekend.d.ts

@@ -0,0 +1,8 @@
+import type { State, WeekendConfig } from "./types.js";
+export declare function getWeekendConfig(state: State, date: string): WeekendConfig;
+export declare function isWeekend(date: string, state: State): boolean;
+export declare function getDayOfWeekName(date: string): string;
+export declare function getWeekendDayNames(state: State, date: string): readonly string[];
+export declare function addDays(date: string, days: number): string;
+export declare function nextWorkingDay(date: string, state: State, holidayDates: ReadonlySet<string>): string;
+export declare function diffDays(start: string, end: string): number;

package/dist/weekend.js

@@ -0,0 +1,57 @@
+const DAY_NAMES = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+];
+// `weekendHistory` MUST be ordered newest-first: this returns the first config
+// whose [from, to] range covers `date`, and the fallback below returns entry [0]
+// (the most recent) when no range matches. The schema enforces a non-empty array.
+export 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;
+        }
+    }
+    // Fallback: use first (most recent) config
+    return state.weekendHistory[0];
+}
+export function isWeekend(date, state) {
+    const config = getWeekendConfig(state, date);
+    const dayOfWeek = new Date(date + "T12:00:00Z").getUTCDay();
+    return config.weekendDays.includes(dayOfWeek);
+}
+export function getDayOfWeekName(date) {
+    const dayIndex = new Date(date + "T12:00:00Z").getUTCDay();
+    return DAY_NAMES[dayIndex];
+}
+export function getWeekendDayNames(state, date) {
+    const config = getWeekendConfig(state, date);
+    return config.weekendDays.map((d) => DAY_NAMES[d]);
+}
+export function addDays(date, days) {
+    const d = new Date(date + "T12:00:00Z");
+    d.setUTCDate(d.getUTCDate() + days);
+    return d.toISOString().slice(0, 10);
+}
+export function nextWorkingDay(date, state, holidayDates) {
+    let candidate = addDays(date, 1);
+    while (isWeekend(candidate, state) || holidayDates.has(candidate)) {
+        candidate = addDays(candidate, 1);
+    }
+    return candidate;
+}
+export function diffDays(start, end) {
+    // Anchor at noon UTC (like every other date helper here) so whole-day
+    // arithmetic is immune to the runtime timezone and DST. Parsing as
+    // "YYYY-MM-DDT00:00:00" without a zone would use local time and could be
+    // off by a day for contributors running outside UTC.
+    const s = new Date(start + "T12:00:00Z").getTime();
+    const e = new Date(end + "T12:00:00Z").getTime();
+    return Math.round((e - s) / 86_400_000);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catlabtech/mycal-core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Core types, schemas, and business logic for the Malaysia Calendar API",
   "keywords": [
     "malaysia",