slotlock 0.8.0 → 0.10.0

package/holidays.d.ts

@@ -0,0 +1,38 @@
+/** The longest holiday calendar Slotlock reads: a megabyte. */
+export declare const SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES = 1048576;
+/** Closures one import may make. */
+export declare const SLOTLOCK_MAX_HOLIDAY_DAYS = 1000;
+export interface SlotlockHoliday {
+    /** The event's UID, with the day for each occurrence of a recurring one: importing again matches it. */
+    uid: string;
+    startsOn: string;
+    endsOn: string;
+    label: string;
+}
+export interface ParsedHolidayCalendar {
+    holidays: SlotlockHoliday[];
+    /** Events that were not all-day, cancelled, or outside the span. */
+    skipped: number;
+    /** The calendar's own name (X-WR-CALNAME), when it gives one: at most 200 characters. */
+    name?: string;
+}
+export declare function invalidHolidayCalendar(message: string): Error & {
+    code: 'invalid_holiday_calendar';
+};
+/**
+ * The days off an iCalendar text names from `from` to `to` (`YYYY-MM-DD`, inclusive): each all-day
+ * VEVENT, from DTSTART to the day before DTEND (one day without DTEND or DURATION), and each
+ * occurrence of a recurring one. Refuses (`invalid_holiday_calendar`) text that is not iCalendar,
+ * more than SLOTLOCK_MAX_HOLIDAY_DAYS holidays, and one longer than SLOTLOCK_MAX_EXCEPTION_DAYS.
+ */
+export declare function parseHolidayCalendar(text: string, span: {
+    from: string;
+    to: string;
+}): ParsedHolidayCalendar;
+/**
+ * The text at a holiday calendar's URL: `https` only, through `fetch` (give it the guarded fetch, so
+ * a private address is refused), at most SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES, within ten seconds.
+ * Refuses `invalid_holiday_calendar` for anything else, and `holiday_calendar_unreachable` when it
+ * cannot be read.
+ */
+export declare function fetchHolidayCalendar(fetcher: typeof fetch, url: string): Promise<string>;

package/holidays.js

@@ -0,0 +1,209 @@
+// Holiday calendars (RFC 0004 B1): an iCalendar file of days off (a public-holiday feed, a
+// company's closures) read as closures. Each all-day VEVENT closes the local days it covers;
+// recurring ones are expanded over a bounded span. Timed events are not days off and are skipped.
+import ICAL from 'ical.js';
+import { SLOTLOCK_MAX_EXCEPTION_DAYS, dayToDate, epochDay } from './hours.js';
+/** The longest holiday calendar Slotlock reads: a megabyte. */
+export const SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES = 1_048_576;
+/** Closures one import may make. */
+export const SLOTLOCK_MAX_HOLIDAY_DAYS = 1_000;
+/** How long Slotlock waits for a holiday calendar URL. */
+const FETCH_TIMEOUT_MS = 10_000;
+const MAX_LABEL = 200;
+/** Steps through one recurring event's occurrences, and through all of a calendar's. */
+const MAX_STEPS_PER_EVENT = 5_000;
+const MAX_STEPS_PER_CALENDAR = 20_000;
+/**
+ * Repeats a calendar of days off has no use for, refused before they are expanded: ical.js steps a
+ * DAILY rule day by day until it finds a day of the month or year that may never come (February
+ * 30), and never returns; a rule more often than daily cannot name whole days.
+ */
+const SUB_DAILY = new Set(['SECONDLY', 'MINUTELY', 'HOURLY']);
+const DAILY_FILTERS = ['BYMONTHDAY', 'BYYEARDAY', 'BYWEEKNO'];
+/** Why a recurrence rule cannot be read here, or null when it can. */
+function unreadableRule(rule) {
+    const recur = rule;
+    const freq = String(recur?.freq ?? '').toUpperCase();
+    if (SUB_DAILY.has(freq))
+        return `it repeats ${freq.toLowerCase()}, and a holiday is a whole day`;
+    if (freq === 'DAILY' && DAILY_FILTERS.some((part) => recur?.parts?.[part] !== undefined)) {
+        return 'it repeats daily on days of the month or year: repeat it monthly or yearly instead';
+    }
+    return null;
+}
+export function invalidHolidayCalendar(message) {
+    return Object.assign(new Error(message), { code: 'invalid_holiday_calendar' });
+}
+const pad = (value, width = 2) => String(value).padStart(width, '0');
+const dateOf = (time) => `${pad(time.year, 4)}-${pad(time.month)}-${pad(time.day)}`;
+/**
+ * The days off an iCalendar text names from `from` to `to` (`YYYY-MM-DD`, inclusive): each all-day
+ * VEVENT, from DTSTART to the day before DTEND (one day without DTEND or DURATION), and each
+ * occurrence of a recurring one. Refuses (`invalid_holiday_calendar`) text that is not iCalendar,
+ * more than SLOTLOCK_MAX_HOLIDAY_DAYS holidays, and one longer than SLOTLOCK_MAX_EXCEPTION_DAYS.
+ */
+export function parseHolidayCalendar(text, span) {
+    if (Buffer.byteLength(text) > SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES) {
+        throw invalidHolidayCalendar('The calendar is larger than a megabyte');
+    }
+    const first = epochDay(span.from);
+    const last = epochDay(span.to);
+    if (first === null || last === null || last < first)
+        throw invalidHolidayCalendar('The span is not a range of days');
+    let root;
+    try {
+        root = new ICAL.Component(ICAL.parse(text));
+    }
+    catch {
+        throw invalidHolidayCalendar('The text is not iCalendar');
+    }
+    if (root.name !== 'vcalendar')
+        throw invalidHolidayCalendar('The text is not a VCALENDAR');
+    const holidays = [];
+    let skipped = 0;
+    let steps = 0;
+    const vevents = root.getAllSubcomponents('vevent');
+    // Each series' overrides, found once: ical.js otherwise looks through every event for each
+    // event, so a calendar of many events took minutes.
+    const overrides = new Map();
+    for (const component of vevents) {
+        if (!component.hasProperty('recurrence-id'))
+            continue;
+        const uid = String(component.getFirstPropertyValue('uid') ?? '');
+        overrides.set(uid, [...(overrides.get(uid) ?? []), component]);
+    }
+    const add = (holiday) => {
+        holidays.push(holiday);
+        if (holidays.length > SLOTLOCK_MAX_HOLIDAY_DAYS) {
+            throw invalidHolidayCalendar(`The calendar names more than ${SLOTLOCK_MAX_HOLIDAY_DAYS} holidays in the span`);
+        }
+    };
+    for (const component of vevents) {
+        // An override of one occurrence is read with its series.
+        if (component.hasProperty('recurrence-id'))
+            continue;
+        const event = new ICAL.Event(component, {
+            exceptions: overrides.get(String(component.getFirstPropertyValue('uid') ?? '')) ?? [],
+        });
+        const start = event.startDate;
+        const status = String(component.getFirstPropertyValue('status') ?? '').toUpperCase();
+        if (!start || !start.isDate || status === 'CANCELLED') {
+            skipped++;
+            continue;
+        }
+        const uid = String(component.getFirstPropertyValue('uid') ?? '').slice(0, 300);
+        const summary = String(component.getFirstPropertyValue('summary') ?? '').replace(/\s+/g, ' ').trim();
+        const label = [...(summary || 'Holiday')].slice(0, MAX_LABEL).join('');
+        const end = event.endDate;
+        const startDay = epochDay(dateOf(start));
+        // DTEND is the day after the last; without one an all-day event is its one day.
+        const length = end && end.isDate ? Math.max(1, epochDay(dateOf(end)) - startDay) : 1;
+        if (length > SLOTLOCK_MAX_EXCEPTION_DAYS) {
+            throw invalidHolidayCalendar(`"${label}" lasts more than ${SLOTLOCK_MAX_EXCEPTION_DAYS} days`);
+        }
+        const occurrence = (day, key) => {
+            const lastDay = day + length - 1;
+            if (lastDay < first || day > last) {
+                skipped++;
+                return;
+            }
+            add({ uid: key, startsOn: dayToDate(day), endsOn: dayToDate(lastDay), label });
+        };
+        if (!event.isRecurring()) {
+            occurrence(startDay, uid || `${dateOf(start)}:${label}`);
+            continue;
+        }
+        for (const rule of component.getAllProperties('rrule')) {
+            const why = unreadableRule(rule.getFirstValue());
+            if (why)
+                throw invalidHolidayCalendar(`"${label}" cannot be read: ${why}`);
+        }
+        try {
+            const iterator = event.iterator();
+            for (let next = iterator.next(), own = 0; next && own < MAX_STEPS_PER_EVENT; next = iterator.next(), own++) {
+                steps += 1;
+                if (steps > MAX_STEPS_PER_CALENDAR) {
+                    throw invalidHolidayCalendar('The calendar repeats too much to read: give its holidays from a later start');
+                }
+                const day = epochDay(dateOf(next));
+                if (day > last)
+                    break;
+                if (day + length - 1 < first)
+                    continue;
+                occurrence(day, `${uid || label}:${dateOf(next)}`);
+            }
+        }
+        catch (error) {
+            if (error.code === 'invalid_holiday_calendar')
+                throw error;
+            // ical.js refusing a rule it cannot follow.
+            throw invalidHolidayCalendar(`"${label}" repeats in a way that cannot be read`);
+        }
+    }
+    const given = String(root.getFirstPropertyValue('x-wr-calname') ?? '').replace(/\s+/g, ' ').trim();
+    const name = [...given].slice(0, MAX_LABEL).join('');
+    return { holidays, skipped, ...(name ? { name } : {}) };
+}
+/**
+ * The text at a holiday calendar's URL: `https` only, through `fetch` (give it the guarded fetch, so
+ * a private address is refused), at most SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES, within ten seconds.
+ * Refuses `invalid_holiday_calendar` for anything else, and `holiday_calendar_unreachable` when it
+ * cannot be read.
+ */
+export async function fetchHolidayCalendar(fetcher, url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw invalidHolidayCalendar('The calendar URL is not a URL');
+    }
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password) {
+        throw invalidHolidayCalendar('The calendar URL must be https, without credentials');
+    }
+    const unreachable = (message) => Object.assign(new Error(message), { code: 'holiday_calendar_unreachable' });
+    let response;
+    try {
+        response = await fetcher(parsed.href, {
+            headers: { accept: 'text/calendar' },
+            redirect: 'manual',
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        if (error.code === 'private_address') {
+            throw invalidHolidayCalendar('The calendar URL names a private address');
+        }
+        throw unreachable('The calendar URL could not be read');
+    }
+    if (!response.ok)
+        throw unreachable(`The calendar URL answered ${response.status}`);
+    const declared = Number(response.headers.get('content-length') ?? '0');
+    if (declared > SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES)
+        throw invalidHolidayCalendar('The calendar is larger than a megabyte');
+    const reader = response.body?.getReader();
+    if (!reader)
+        return '';
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        let read;
+        try {
+            read = await reader.read();
+        }
+        catch {
+            // Cut off while its body was read (the timeout, or the connection reset).
+            throw unreachable('The calendar URL could not be read');
+        }
+        const { done, value } = read;
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES) {
+            await reader.cancel();
+            throw invalidHolidayCalendar('The calendar is larger than a megabyte');
+        }
+        chunks.push(value);
+    }
+    return new TextDecoder().decode(Buffer.concat(chunks));
+}

package/hours.d.ts

@@ -0,0 +1,125 @@
+import type { Interval, SlotlockInheritedAvailability, WeeklyAvailabilityRule } from './types.js';
+export type { SlotlockInheritedAvailability };
+/** Where a resource's hours come from. */
+export type SlotlockHoursSource = 'resource' | 'location' | 'tenant' | 'server';
+/** One window of an exception's day, in minutes after local midnight. */
+export interface SlotlockExceptionWindow {
+    startMinutes: number;
+    /** 1 to 1,440; a window may run past midnight into the next day. */
+    durationMinutes: number;
+}
+export type SlotlockExceptionOutcome = 'closed' | 'open';
+export type SlotlockExceptionSource = 'manual' | 'ics' | 'vavailability';
+/** Exceptions a tenant may keep, at all its scopes together. */
+export declare const SLOTLOCK_MAX_AVAILABILITY_EXCEPTIONS = 5000;
+/** The longest one exception may last, in days (both ends counted). */
+export declare const SLOTLOCK_MAX_EXCEPTION_DAYS = 367;
+/** Windows one open exception may give each day. */
+export declare const SLOTLOCK_MAX_EXCEPTION_WINDOWS = 4;
+/** A closure or a day of special hours, for the tenant, a location or one resource. */
+export interface SlotlockAvailabilityException {
+    id: string;
+    tenantRef: string;
+    /** The location it applies to (and every resource inside it), or none. */
+    location?: string;
+    /** The resource it applies to, or none. Neither: the whole tenant. */
+    resourceId?: string;
+    /** The first local day, `YYYY-MM-DD`. */
+    startsOn: string;
+    /** The last local day, `YYYY-MM-DD` (inclusive). */
+    endsOn: string;
+    outcome: SlotlockExceptionOutcome;
+    /** For `open`: the hours each of its days has instead of its usual ones. */
+    hours?: SlotlockExceptionWindow[];
+    label: string;
+    source: SlotlockExceptionSource;
+    /** For imports: the source's own id, so importing again updates rather than adds. */
+    sourceUid?: string;
+    /** The holiday calendar it was imported from (listHolidayCalendars), if any. */
+    calendarId?: string;
+    createdAt: Date;
+}
+/** An exception as the evaluator applies it, ranked from widest scope (0) to the resource's own. */
+export interface SlotlockRankedException {
+    startsOn: string;
+    endsOn: string;
+    outcome: SlotlockExceptionOutcome;
+    hours?: readonly SlotlockExceptionWindow[];
+    rank: number;
+}
+export declare function invalidException(message: string): Error & {
+    code: 'invalid_availability_exception';
+};
+/** Days since 1970-01-01 for a real `YYYY-MM-DD`, or null. */
+export declare function epochDay(date: string): number | null;
+/** `YYYY-MM-DD` for a day since 1970-01-01. */
+export declare function dayToDate(day: number): string;
+/** An exception's windows from untrusted input, or `invalid_availability_exception`. */
+export declare function parseExceptionWindows(value: unknown): SlotlockExceptionWindow[];
+/**
+ * An exception's dates and outcome from untrusted input: real dates, the end not before the start,
+ * at most SLOTLOCK_MAX_EXCEPTION_DAYS, and hours exactly when it opens.
+ */
+export declare function parseExceptionDays(input: {
+    startsOn: unknown;
+    endsOn?: unknown;
+    outcome: unknown;
+    hours?: unknown;
+}): {
+    startsOn: string;
+    endsOn: string;
+    outcome: SlotlockExceptionOutcome;
+    hours?: SlotlockExceptionWindow[];
+};
+/** Stored hours that do not read as windows read as none: the day stays closed. */
+export declare function storedExceptionWindows(value: unknown): SlotlockExceptionWindow[];
+/**
+ * The open windows of a resource within `window`: its weekly `hours`, with `exceptions` (in rank
+ * order) replacing the local days they name in `timezone`. Merged and sorted.
+ */
+export declare function openWindows(params: {
+    hours: readonly WeeklyAvailabilityRule[];
+    exceptions?: readonly SlotlockRankedException[];
+    timezone: string;
+    window: Interval;
+}): Interval[];
+/**
+ * The weekly hours that apply to a resource and where they come from: its own, else what it
+ * inherits, else the server's `fallback`.
+ */
+export declare function applicableHours(resource: {
+    availabilityRules?: readonly WeeklyAvailabilityRule[];
+    inheritedAvailability?: SlotlockInheritedAvailability;
+}, fallback: readonly WeeklyAvailabilityRule[]): {
+    rules: readonly WeeklyAvailabilityRule[];
+    source: SlotlockHoursSource;
+    location?: string;
+};
+/** Whether `interval` lies wholly inside the open windows. */
+export declare function coveredByOpenWindows(open: readonly Interval[], interval: Interval): boolean;
+/** The first and last UTC day an exception query for `window` must reach (zones span ±14 hours). */
+export declare function exceptionQueryDays(window: Interval): {
+    from: string;
+    to: string;
+};
+/** One local day as exceptions leave it: no windows is closed. */
+export interface SlotlockExceptionDay {
+    /** `YYYY-MM-DD`. */
+    date: string;
+    windows: SlotlockExceptionWindow[];
+}
+/**
+ * The days from `from` to `to` (`YYYY-MM-DD`, inclusive) that exceptions replace, each as the
+ * nearest exception leaves it, by date.
+ */
+export declare function exceptionDays(exceptions: readonly SlotlockRankedException[], from: string, to: string): SlotlockExceptionDay[];
+/**
+ * Consecutive days that read alike as exception ranges: no windows a closure, else hours of their
+ * own. The inverse of `exceptionDays` for one scope.
+ */
+export declare function exceptionRanges(days: readonly SlotlockExceptionDay[]): {
+    startsOn: string;
+    endsOn: string;
+    outcome: SlotlockExceptionOutcome;
+    hours?: SlotlockExceptionWindow[];
+}[];

package/hours.js

@@ -0,0 +1,224 @@
+// Bookable hours with their exceptions (RFC 0004 B1, B2): the one evaluator search and enforced
+// writes share. A resource's hours are its own, else its location's (nearest up the chain), else its
+// tenant's, else the server's. Exceptions then replace whole local days: a closure empties them, an
+// opening gives them hours of their own. Each applies in the resource's time zone, the tenant's
+// first, then each location's from the outermost in, then the resource's own, so the nearer wins.
+import { mergeIntervals } from './engine.js';
+import { expandRules } from './rules.js';
+import { createTimeZoneConverter } from './timezone.js';
+const DAY_MS = 86_400_000;
+const MINUTE_MS = 60_000;
+const DAY_MINUTES = 1_440;
+/** Exceptions a tenant may keep, at all its scopes together. */
+export const SLOTLOCK_MAX_AVAILABILITY_EXCEPTIONS = 5_000;
+/** The longest one exception may last, in days (both ends counted). */
+export const SLOTLOCK_MAX_EXCEPTION_DAYS = 367;
+/** Windows one open exception may give each day. */
+export const SLOTLOCK_MAX_EXCEPTION_WINDOWS = 4;
+export function invalidException(message) {
+    return Object.assign(new Error(message), { code: 'invalid_availability_exception' });
+}
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** Days since 1970-01-01 for a real `YYYY-MM-DD`, or null. */
+export function epochDay(date) {
+    const match = DATE.exec(date);
+    if (!match)
+        return null;
+    const [, year, month, day] = match.map(Number);
+    const ms = Date.UTC(year, month - 1, day);
+    const back = new Date(ms);
+    if (year < 1 || back.getUTCFullYear() !== year || back.getUTCMonth() !== month - 1 || back.getUTCDate() !== day) {
+        return null;
+    }
+    return Math.round(ms / DAY_MS);
+}
+/** `YYYY-MM-DD` for a day since 1970-01-01. */
+export function dayToDate(day) {
+    return new Date(day * DAY_MS).toISOString().slice(0, 10);
+}
+/** An exception's windows from untrusted input, or `invalid_availability_exception`. */
+export function parseExceptionWindows(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > SLOTLOCK_MAX_EXCEPTION_WINDOWS) {
+        throw invalidException(`Open hours must be 1 to ${SLOTLOCK_MAX_EXCEPTION_WINDOWS} windows`);
+    }
+    return value.map((window, index) => {
+        const candidate = window;
+        if (typeof candidate !== 'object' ||
+            candidate === null ||
+            Array.isArray(candidate) ||
+            Object.keys(candidate).some((key) => key !== 'startMinutes' && key !== 'durationMinutes') ||
+            !Number.isInteger(candidate.startMinutes) ||
+            candidate.startMinutes < 0 ||
+            candidate.startMinutes >= DAY_MINUTES ||
+            !Number.isInteger(candidate.durationMinutes) ||
+            candidate.durationMinutes < 1 ||
+            candidate.durationMinutes > DAY_MINUTES) {
+            throw invalidException(`Window ${index} needs startMinutes (0-1439) and durationMinutes (1-1440)`);
+        }
+        return { startMinutes: candidate.startMinutes, durationMinutes: candidate.durationMinutes };
+    });
+}
+/**
+ * An exception's dates and outcome from untrusted input: real dates, the end not before the start,
+ * at most SLOTLOCK_MAX_EXCEPTION_DAYS, and hours exactly when it opens.
+ */
+export function parseExceptionDays(input) {
+    const startsOn = typeof input.startsOn === 'string' ? input.startsOn : '';
+    const endsOn = input.endsOn === undefined || input.endsOn === null ? startsOn : String(input.endsOn);
+    const first = epochDay(startsOn);
+    const last = epochDay(endsOn);
+    if (first === null || last === null)
+        throw invalidException('Dates must be real days, YYYY-MM-DD');
+    if (last < first)
+        throw invalidException('The last day must not be before the first');
+    if (last - first + 1 > SLOTLOCK_MAX_EXCEPTION_DAYS) {
+        throw invalidException(`An exception lasts at most ${SLOTLOCK_MAX_EXCEPTION_DAYS} days`);
+    }
+    if (input.outcome === 'closed') {
+        if (input.hours !== undefined && input.hours !== null)
+            throw invalidException('A closure has no hours');
+        return { startsOn, endsOn, outcome: 'closed' };
+    }
+    if (input.outcome === 'open') {
+        return { startsOn, endsOn, outcome: 'open', hours: parseExceptionWindows(input.hours) };
+    }
+    throw invalidException('The outcome must be closed or open');
+}
+/** Stored hours that do not read as windows read as none: the day stays closed. */
+export function storedExceptionWindows(value) {
+    try {
+        return parseExceptionWindows(value);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The open windows of a resource within `window`: its weekly `hours`, with `exceptions` (in rank
+ * order) replacing the local days they name in `timezone`. Merged and sorted.
+ */
+export function openWindows(params) {
+    const { window, timezone } = params;
+    const weekly = expandRules([...params.hours], window, timezone);
+    const exceptions = [...(params.exceptions ?? [])].sort((a, b) => a.rank - b.rank);
+    if (exceptions.length === 0)
+        return weekly;
+    const converter = createTimeZoneConverter(timezone);
+    const at = (day, minutes) => converter.wallFrameToUtc(day * DAY_MS + minutes * MINUTE_MS, { gap: 'end' }).getTime();
+    // The local days the window can touch: a zone is at most fourteen hours from UTC.
+    const firstDay = Math.floor(window.start.getTime() / DAY_MS) - 1;
+    const lastDay = Math.floor(window.end.getTime() / DAY_MS) + 1;
+    let open = weekly;
+    for (const exception of exceptions) {
+        const from = Math.max(epochDay(exception.startsOn) ?? Number.POSITIVE_INFINITY, firstDay);
+        const to = Math.min(epochDay(exception.endsOn) ?? Number.NEGATIVE_INFINITY, lastDay);
+        if (from > to)
+            continue;
+        const removed = { start: at(from, 0), end: at(to + 1, 0) };
+        open = open.flatMap((part) => {
+            const start = part.start.getTime();
+            const end = part.end.getTime();
+            if (end <= removed.start || start >= removed.end)
+                return [part];
+            const kept = [];
+            if (start < removed.start)
+                kept.push({ start: part.start, end: new Date(removed.start) });
+            if (end > removed.end)
+                kept.push({ start: new Date(removed.end), end: part.end });
+            return kept;
+        });
+        if (exception.outcome === 'open') {
+            for (let day = from; day <= to; day++) {
+                for (const hours of exception.hours ?? []) {
+                    const start = Math.max(at(day, hours.startMinutes), window.start.getTime());
+                    const end = Math.min(at(day, hours.startMinutes + hours.durationMinutes), window.end.getTime());
+                    if (end > start)
+                        open.push({ start: new Date(start), end: new Date(end) });
+                }
+            }
+        }
+    }
+    return mergeIntervals(open.filter((part) => part.end.getTime() > part.start.getTime()));
+}
+/**
+ * The weekly hours that apply to a resource and where they come from: its own, else what it
+ * inherits, else the server's `fallback`.
+ */
+export function applicableHours(resource, fallback) {
+    if (resource.availabilityRules !== undefined)
+        return { rules: resource.availabilityRules, source: 'resource' };
+    const inherited = resource.inheritedAvailability;
+    if (inherited !== undefined) {
+        return inherited.location !== undefined
+            ? { rules: inherited.rules, source: inherited.source, location: inherited.location }
+            : { rules: inherited.rules, source: inherited.source };
+    }
+    return { rules: fallback, source: 'server' };
+}
+/** Whether `interval` lies wholly inside the open windows. */
+export function coveredByOpenWindows(open, interval) {
+    let covered = interval.start.getTime();
+    for (const part of [...open].sort((a, b) => a.start.getTime() - b.start.getTime())) {
+        if (part.start.getTime() > covered)
+            break;
+        covered = Math.max(covered, part.end.getTime());
+        if (covered >= interval.end.getTime())
+            return true;
+    }
+    return covered >= interval.end.getTime();
+}
+/** The first and last UTC day an exception query for `window` must reach (zones span ±14 hours). */
+export function exceptionQueryDays(window) {
+    return {
+        from: dayToDate(Math.floor(window.start.getTime() / DAY_MS) - 1),
+        to: dayToDate(Math.floor(window.end.getTime() / DAY_MS) + 1),
+    };
+}
+/**
+ * The days from `from` to `to` (`YYYY-MM-DD`, inclusive) that exceptions replace, each as the
+ * nearest exception leaves it, by date.
+ */
+export function exceptionDays(exceptions, from, to) {
+    const first = epochDay(from);
+    const last = epochDay(to);
+    if (first === null || last === null)
+        return [];
+    const days = new Map();
+    for (const exception of [...exceptions].sort((a, b) => a.rank - b.rank)) {
+        const start = Math.max(epochDay(exception.startsOn) ?? Number.POSITIVE_INFINITY, first);
+        const end = Math.min(epochDay(exception.endsOn) ?? Number.NEGATIVE_INFINITY, last);
+        for (let day = start; day <= end; day++) {
+            days.set(day, exception.outcome === 'open' ? [...(exception.hours ?? [])] : []);
+        }
+    }
+    return [...days.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([day, windows]) => ({ date: dayToDate(day), windows }));
+}
+/**
+ * Consecutive days that read alike as exception ranges: no windows a closure, else hours of their
+ * own. The inverse of `exceptionDays` for one scope.
+ */
+export function exceptionRanges(days) {
+    const sorted = [...days].sort((a, b) => a.date.localeCompare(b.date));
+    const ranges = [];
+    const key = (windows) => JSON.stringify([...windows].sort((a, b) => a.startMinutes - b.startMinutes || a.durationMinutes - b.durationMinutes));
+    let previous = null;
+    for (const day of sorted) {
+        const at = epochDay(day.date);
+        if (at === null)
+            continue;
+        const same = key(day.windows);
+        const last = ranges.at(-1);
+        if (last && previous && previous.day === at - 1 && previous.key === same) {
+            last.endsOn = day.date;
+        }
+        else {
+            ranges.push(day.windows.length === 0
+                ? { startsOn: day.date, endsOn: day.date, outcome: 'closed' }
+                : { startsOn: day.date, endsOn: day.date, outcome: 'open', hours: JSON.parse(same) });
+        }
+        previous = { day: at, key: same };
+    }
+    return ranges;
+}

package/index.d.ts

@@ -8,7 +8,18 @@ export { type SlotlockMetrics, createSlotlockMetrics } from './metrics.js';
 export { expandRules } from './rules.js';
 export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SLOTLOCK_MAX_AVAILABILITY_RULES, weeklyHoursToRules, } from './weekly-hours.js';
 export type { HoursWindow, Weekday, WeeklyHours } from './weekly-hours.js';
-export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS, toJSCalendarEvent, } from './interop.js';
+export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS, SLOTLOCK_MAX_VAVAILABILITY_DAYS, toJSCalendarEvent, } from './interop.js';
+export { applicableHours, coveredByOpenWindows, exceptionDays, exceptionRanges, openWindows, parseExceptionDays, SLOTLOCK_MAX_AVAILABILITY_EXCEPTIONS, SLOTLOCK_MAX_EXCEPTION_DAYS, SLOTLOCK_MAX_EXCEPTION_WINDOWS, } from './hours.js';
+export type { SlotlockAvailabilityException, SlotlockExceptionDay, SlotlockExceptionOutcome, SlotlockExceptionSource, SlotlockExceptionWindow, SlotlockHoursSource, SlotlockRankedException, } from './hours.js';
+export type { SlotlockAvailabilityDefaults, SlotlockAvailabilityDefaultsResult, SlotlockAvailabilityExceptionInput, SlotlockOverrideResources, SlotlockHolidayCalendar, SlotlockHolidayImport, } from './availability-store.js';
+export { SLOTLOCK_OVERRIDE_RESOURCES, SLOTLOCK_HOLIDAY_REIMPORT_DAYS, SLOTLOCK_MAX_HOLIDAY_CALENDARS, } from './availability-store.js';
+export { type SlotlockHolidayCalendarRead, type SlotlockHolidaySource, readSlotlockHolidayCalendar, } from './holiday-import.js';
+export { fetchHolidayCalendar, parseHolidayCalendar, SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES, SLOTLOCK_MAX_HOLIDAY_DAYS, } from './holidays.js';
+export type { ParsedHolidayCalendar, SlotlockHoliday } from './holidays.js';
+export { SLOTLOCK_BOOKING_ACTIONS, SLOTLOCK_BOOKING_ENDS, SLOTLOCK_BOOKING_STATUSES, SLOTLOCK_BOOKING_TRANSITIONS, slotlockBookingNext, slotlockBookingRefusal, } from './lifecycle.js';
+export type { SlotlockBookingAction, SlotlockBookingStatus, SlotlockEndReason } from './lifecycle.js';
+export { findEarliestRange, sameTimeDaysLater } from './ranges.js';
+export type { SlotlockRangeSearch } from './ranges.js';
 export type { EmitVAvailabilityOptions, JSCalendarAlert, JSCalendarEvent, JSCalendarParticipant, JSCalendarRecurrenceRule, ParsedVAvailability, } from './interop.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
 export type { LocalDateTime, TimeZoneConverter, ZonedCalendarDate, ZonedWallTime, } from './timezone.js';
@@ -25,7 +36,7 @@ export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenan
 export type { SlotlockMaintenanceResult, SlotlockMaintenanceScheduler, SlotlockMaintenanceSchedulerOptions, } from './maintenance.js';
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, isSlotlockTestTenant, slotlockLiveTenant, SLOTLOCK_TEST_API_KEY_PREFIX, SLOTLOCK_TEST_TENANT_SUFFIX, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
-export type { SlotlockDashboard, SlotlockDashboardAssistantOptions, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, } from './dashboard.js';
+export type { SlotlockDashboard, SlotlockDashboardAssistantOptions, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, SlotlockInvitationSender, } from './dashboard.js';
 export { createSlotlockAssistantStore, createSlotlockMemoryAssistantStore, SLOTLOCK_ASSISTANT_TOOL_USE, } from './assistant.js';
 export type { SlotlockAssistantStore } from './assistant.js';
 export { createSlotlockPartnerKeyAuthenticator, createSlotlockPartnerStore, parseSlotlockPartnerContract, slotlockPartnerTenantRef, SLOTLOCK_PARTNER_ACCOUNT, SLOTLOCK_PARTNER_ID, SLOTLOCK_PARTNER_SCOPE, } from './partners.js';
@@ -35,6 +46,13 @@ export type { SlotlockOverageReport } from './overage.js';
 export { createSlotlockOtlpExporter, readSlotlockOtlpConfig, slotlockCallSpan } from './otel.js';
 export type { SlotlockOtlpConfig, SlotlockTraceExporter } from './otel.js';
 export type { SlotlockDashboardTeams } from './teams.js';
+export { createSlotlockInvitationEmailSender, SlotlockInvitationEmailError, slotlockInvitationEmail, } from './invitation-email.js';
+export type { SlotlockInvitationEmailConfig } from './invitation-email.js';
+export { createSlotlockDashboardWorkspaces, createSlotlockMemoryDashboardWorkspaces, createSlotlockWorkspaceCheck, } from './workspaces.js';
+export type { SlotlockDashboardWorkspaces, SlotlockGitHubMembership, SlotlockInvitationPreview, SlotlockTeamRefusal, SlotlockTeamWorkspace, SlotlockWorkspaceInvitation, SlotlockWorkspaceMember, SlotlockWorkspaceStanding, SlotlockWorkspaceTeams, SlotlockDashboardSession, SlotlockDashboardSessions, } from './workspaces.js';
+export { SLOTLOCK_DASHBOARD_PAGE_CAPABILITIES, SLOTLOCK_DASHBOARD_POST_CAPABILITIES, SLOTLOCK_FRESH_CAPABILITIES, SLOTLOCK_ROLE_CAPABILITIES, SLOTLOCK_SCOPED_CAPABILITIES, SLOTLOCK_SCOPED_DASHBOARD_PAGES, SLOTLOCK_SCOPED_DASHBOARD_POSTS, SLOTLOCK_WORKSPACE_CAPABILITIES, SLOTLOCK_WORKSPACE_ROLE_NAMES, SLOTLOCK_WORKSPACE_ROLES, isSlotlockWorkspaceRole, slotlockMemberCan, slotlockRoleCan, slotlockRoleKeyScopes, slotlockRoleMayGrant, } from './workspace-roles.js';
+export { slotlockDashboardRequestScope } from './dashboard-scope.js';
+export type { SlotlockWorkspaceCapability, SlotlockWorkspaceRole } from './workspace-roles.js';
 export { closeSlotlockPartnerMonth, priceSlotlockPartnerMonth, slotlockClientLabel, slotlockPartnerMonthChecksum, } from './partner-billing.js';
 export type { SlotlockPartnerAccountMonth, SlotlockPartnerInvoiceLine, SlotlockPartnerMonthClose, } from './partner-billing.js';
 export type { SlotlockPartnerAccount, SlotlockPartnerContract, SlotlockPartnerPlan, SlotlockPartnerPricing, SlotlockPartnerStore, } from './partners.js';
@@ -43,6 +61,7 @@ export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalend
 export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-worker.js';
 export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
 export type { ExternalCalendarChange, ExternalCalendarChangeInput, ExternalCalendarStatus, ICalendarEvent, ICalendarExpansionWindow, ICalendarFeedRead, ICalendarSeriesRefusal, ITipMethod, } from './sync.js';
-export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
-export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_TENANT_WRITE_METHODS, type SlotlockHoldTenantOptions, type SlotlockMigrationOptions, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantLimits, type SlotlockTenantStore, } from './store.js';
-export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockAgendaEntry, SlotlockHold, SlotlockCalendarEvent, SlotlockBookingDescription, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, SlotlockBookingRuleDefaults, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';
+export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_APPEND_ONLY_TABLES, SLOTLOCK_AUDIT_RETENTION_DAYS, SLOTLOCK_CHANGE_RETENTION_BY_PLAN, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
+export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_SOURCE_BUSY_MAX, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_MAX_CONTACTS_PER_TENANT, SLOTLOCK_PAYMENT_HOLD_MAX_TTL_MS, SLOTLOCK_TENANT_WRITE_METHODS, SLOTLOCK_TENANT_EXPORT_HOURS, SLOTLOCK_TENANT_EXPORT_MAX_BYTES, SLOTLOCK_TENANT_EXPORT_PART_ROWS, SLOTLOCK_MAX_TENANT_EXPORTS, buildSlotlockTenantExport, slotlockAuditEventRecord, type SlotlockAuditEvent, type SlotlockAuditEventInput, type SlotlockSubject, type SlotlockSubjectErasure, type SlotlockSubjectExport, type SlotlockTenantExport, type SlotlockTenantExportPartResult, type SlotlockHoldTenantOptions, type SlotlockMigrationOptions, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantLimits, type SlotlockTenantStore, } from './store.js';
+export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockAgendaEntry, SlotlockHold, MarkHoldPaidResult, SlotlockContact, SlotlockContactConsent, PutContactResult, SourceBusyCommand, SourceBusyResult, SlotlockCalendarEvent, SlotlockBookingDescription, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, SlotlockBookingRuleDefaults, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, SlotlockInheritedAvailability, WeeklyAvailabilityRule, SlotlockSubjectTable, SlotlockTenantExportTable, } from './types.js';
+export { SLOTLOCK_SUBJECT_TABLES, SLOTLOCK_TENANT_EXPORT_LEFT_OUT, SLOTLOCK_TENANT_EXPORT_TABLES, } from './types.js';