slotlock 0.7.0 → 0.9.0

package/event-feed.d.ts

@@ -1,7 +1,7 @@
 import type { Sql, TransactionSql } from 'postgres';
 type SlotlockSql = Sql | TransactionSql;
 /** What a change can be, as the feed and a webhook's `event_types` name it. */
-export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "approval.requested", "approval.granted", "approval.declined", "approval.expired", "webhook.disabled", "usage.threshold_reached", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
+export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "hold.paid", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "reservation.rescheduled", "reservation.completed", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "reservation.timezone_shifted", "reservation.timezone_conflict", "reminder.due", "coverage.stale", "coverage.conflict", "waitlist.offered", "waitlist.expired", "waitlist.joined", "waitlist.accepted", "waitlist.declined", "waitlist.lapsed", "waitlist.left", "approval.requested", "approval.granted", "approval.declined", "approval.expired", "webhook.disabled", "usage.threshold_reached", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
 export type SlotlockChangeType = (typeof SLOTLOCK_CHANGE_TYPES)[number];
 /**
  * Where a change came from (withTenant's `origin`): an agent protocol (`mcp`, `a2a`), the REST

package/event-feed.js

@@ -14,19 +14,37 @@ export const SLOTLOCK_CHANGE_TYPES = Object.freeze([
     'hold.confirmed',
     'hold.released',
     'hold.expired',
+    // The integrator's payment for a hold that waits for one (RFC 0004 C3).
+    'hold.paid',
     'reservation.created',
     'reservation.updated',
     'reservation.cancelled',
     'reservation.checked_in',
     'reservation.no_show',
+    // A booking moved (also reservation.updated), and one whose end has passed (RFC 0004 B4).
+    'reservation.rescheduled',
+    'reservation.completed',
     'event.created',
     'event.updated',
     'event.cancelled',
     'event.timezone_shifted',
     'event.timezone_conflict',
+    // A reservation that carries its wall time, which now falls at another instant (RFC 0004 B9).
+    'reservation.timezone_shifted',
+    'reservation.timezone_conflict',
+    // A stored reminder fell due (RFC 0004 P3): the change's id is the send key.
+    'reminder.due',
     'coverage.stale',
+    // A source reported busy time over a booking Slotlock already holds (RFC 0004 C1, C4).
+    'coverage.conflict',
     'waitlist.offered',
     'waitlist.expired',
+    // A waitlist entry joined, its offer accepted, declined or lapsed, and an entry left (RFC 0004 B6).
+    'waitlist.joined',
+    'waitlist.accepted',
+    'waitlist.declined',
+    'waitlist.lapsed',
+    'waitlist.left',
     // A write waiting for a person (approval policies): requested, then granted, declined or expired.
     'approval.requested',
     'approval.granted',

package/holiday-import.d.ts

@@ -0,0 +1,38 @@
+import { type SlotlockHoliday } from './holidays.js';
+/** Where a holiday calendar comes from, and what to call it. */
+export interface SlotlockHolidaySource {
+    /** The iCalendar text, pasted or uploaded. */
+    icalendar?: string;
+    /** An https URL to fetch it from. */
+    url?: string;
+    /**
+     * The calendar's name at its scope (1-200 characters): importing again under it replaces what
+     * it said. By default the calendar's own (X-WR-CALNAME), else the URL's host and path, else
+     * "Holidays".
+     */
+    name?: string;
+    /** Keep the URL and import it again every 30 days (maintenance). Needs `url`. */
+    subscribe?: boolean;
+    /** The first and last days to import, `YYYY-MM-DD`; by default today and two years on. */
+    from?: string;
+    to?: string;
+}
+/** A holiday calendar read and parsed, ready for importHolidayCalendar. */
+export interface SlotlockHolidayCalendarRead {
+    name: string;
+    holidays: SlotlockHoliday[];
+    /** Events that were not all-day, cancelled, or outside the span. */
+    skipped: number;
+    span: {
+        from: string;
+        to: string;
+    };
+    /** The URL to keep, for a subscription. */
+    url?: string;
+}
+/**
+ * Read a holiday calendar from its text or URL (`fetcher` fetches it; without one a URL is
+ * refused `holiday_url_not_served`), parse it over its span, and name it. Throws
+ * `invalid_holiday_calendar` and `holiday_calendar_unreachable`.
+ */
+export declare function readSlotlockHolidayCalendar(source: SlotlockHolidaySource, fetcher?: typeof fetch): Promise<SlotlockHolidayCalendarRead>;

package/holiday-import.js

@@ -0,0 +1,57 @@
+// Reading a holiday calendar to import (RFC 0004 B1), shared by the application API, the dashboard,
+// the CLI and maintenance: pasted or uploaded text, or an https URL fetched before any transaction
+// opens, parsed over a span of days, and named, so importing it again replaces what it said.
+import { dayToDate, epochDay } from './hours.js';
+import { fetchHolidayCalendar, invalidHolidayCalendar, parseHolidayCalendar } from './holidays.js';
+/** Days a span may cover, and the default. */
+const MAX_SPAN_DAYS = 1_096;
+const DEFAULT_SPAN_DAYS = 730;
+/** A URL's host and path, as a calendar's name. */
+function nameOfUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return [...`${parsed.host}${parsed.pathname === '/' ? '' : parsed.pathname}`].slice(0, 200).join('');
+    }
+    catch {
+        return 'Holidays';
+    }
+}
+/**
+ * Read a holiday calendar from its text or URL (`fetcher` fetches it; without one a URL is
+ * refused `holiday_url_not_served`), parse it over its span, and name it. Throws
+ * `invalid_holiday_calendar` and `holiday_calendar_unreachable`.
+ */
+export async function readSlotlockHolidayCalendar(source, fetcher) {
+    const given = [source.icalendar, source.url].filter((value) => value !== undefined && value !== '');
+    if (given.length !== 1)
+        throw invalidHolidayCalendar('Give the calendar as text or as a URL, one of them');
+    if (source.subscribe === true && !source.url)
+        throw invalidHolidayCalendar('Only a calendar read from a URL can be subscribed to');
+    const today = Math.floor(Date.now() / 86_400_000);
+    const from = source.from ?? dayToDate(today);
+    const to = source.to ?? dayToDate((epochDay(from) ?? today) + DEFAULT_SPAN_DAYS);
+    const first = epochDay(from);
+    const last = epochDay(to);
+    if (first === null || last === null || last < first || last - first > MAX_SPAN_DAYS) {
+        throw invalidHolidayCalendar('from and to must be days at most three years apart');
+    }
+    let text;
+    if (source.url) {
+        if (!fetcher) {
+            throw Object.assign(new Error('This server does not fetch calendars by URL'), { code: 'holiday_url_not_served' });
+        }
+        text = await fetchHolidayCalendar(fetcher, source.url);
+    }
+    else {
+        text = source.icalendar;
+    }
+    const parsed = parseHolidayCalendar(text, { from, to });
+    const name = source.name?.trim() || parsed.name || (source.url ? nameOfUrl(source.url) : 'Holidays');
+    return {
+        name,
+        holidays: parsed.holidays,
+        skipped: parsed.skipped,
+        span: { from, to },
+        ...(source.subscribe === true && source.url ? { url: source.url } : {}),
+    };
+}

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,150 @@
+// 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;
+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;
+    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 root.getAllSubcomponents('vevent')) {
+        // An override of one occurrence is read with its series.
+        if (component.hasProperty('recurrence-id'))
+            continue;
+        const event = new ICAL.Event(component);
+        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;
+        }
+        const iterator = event.iterator();
+        for (let next = iterator.next(), steps = 0; next && steps < 5_000; next = iterator.next(), steps++) {
+            const day = epochDay(dateOf(next));
+            if (day > last)
+                break;
+            if (day + length - 1 < first)
+                continue;
+            occurrence(day, `${uid || label}:${dateOf(next)}`);
+        }
+    }
+    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 (;;) {
+        const { done, value } = await reader.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[];
+}[];