slotlock 0.8.0 → 0.9.0

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';
@@ -44,5 +55,5 @@ export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-wor
 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 { 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, 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, } from './types.js';

package/index.js

@@ -11,7 +11,15 @@ export { createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotloc
 export { createSlotlockMetrics } from './metrics.js';
 export { expandRules } from './rules.js';
 export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SLOTLOCK_MAX_AVAILABILITY_RULES, weeklyHoursToRules, } 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';
+// Stored hours that inherit, and closures and special days (RFC 0004 B1, B2).
+export { applicableHours, coveredByOpenWindows, exceptionDays, exceptionRanges, openWindows, parseExceptionDays, SLOTLOCK_MAX_AVAILABILITY_EXCEPTIONS, SLOTLOCK_MAX_EXCEPTION_DAYS, SLOTLOCK_MAX_EXCEPTION_WINDOWS, } from './hours.js';
+export { SLOTLOCK_OVERRIDE_RESOURCES, SLOTLOCK_HOLIDAY_REIMPORT_DAYS, SLOTLOCK_MAX_HOLIDAY_CALENDARS, } from './availability-store.js';
+export { readSlotlockHolidayCalendar, } from './holiday-import.js';
+export { fetchHolidayCalendar, parseHolidayCalendar, SLOTLOCK_MAX_HOLIDAY_CALENDAR_BYTES, SLOTLOCK_MAX_HOLIDAY_DAYS, } from './holidays.js';
+// The booking lifecycle, written down (RFC 0004 B4).
+export { SLOTLOCK_BOOKING_ACTIONS, SLOTLOCK_BOOKING_ENDS, SLOTLOCK_BOOKING_STATUSES, SLOTLOCK_BOOKING_TRANSITIONS, slotlockBookingNext, slotlockBookingRefusal, } from './lifecycle.js';
+export { findEarliestRange, sameTimeDaysLater } from './ranges.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
 export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MAX_ALTERNATIVES, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
@@ -30,4 +38,4 @@ export { closeSlotlockPartnerMonth, priceSlotlockPartnerMonth, slotlockClientLab
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } 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, } from './store.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, } from './store.js';

package/interop.d.ts

@@ -1,3 +1,4 @@
+import { type SlotlockExceptionDay } from './hours.js';
 import type { SlotlockCalendarEvent, WeeklyAvailabilityRule } from './types.js';
 /** The longest VAVAILABILITY text `parseVAvailability` reads. */
 export declare const SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS = 65536;
@@ -8,26 +9,43 @@ export interface EmitVAvailabilityOptions {
     timezone: string;
     /** The VAVAILABILITY's UID; each AVAILABLE's is this with its index. */
     uid: string;
+    /**
+     * Days exceptions replace (RFC 0004 B1): each weekly AVAILABLE gets an EXDATE for its window on
+     * them, and the hours an open day has instead are AVAILABLEs of their own, one per window with an
+     * RDATE for each further day with the same window.
+     */
+    days?: readonly SlotlockExceptionDay[];
 }
+/** The most days one VAVAILABILITY's EXDATEs, RDATEs and single AVAILABLEs may name. */
+export declare const SLOTLOCK_MAX_VAVAILABILITY_DAYS = 1000;
 /**
  * A VCALENDAR with one VAVAILABILITY holding an AVAILABLE per rule: DTSTART on the rule's first day
  * in a reference week of January 2024, with the IANA zone as TZID (no VTIMEZONE: RFC 7809 lets the
  * two sides agree on IANA names), DURATION and the rule's RRULE. `[]` is a VAVAILABILITY with no
  * AVAILABLE: never bookable. CRLF line endings, folded at 75 octets.
  */
-export declare function emitVAvailability({ rules, timezone, uid }: EmitVAvailabilityOptions): string;
+export declare function emitVAvailability({ rules, timezone, uid, days }: EmitVAvailabilityOptions): string;
 export interface ParsedVAvailability {
     /** The TZID every AVAILABLE named, `UTC` for UTC times, or null when they are all floating. */
     timezone: string | null;
     rules: WeeklyAvailabilityRule[];
+    /**
+     * The days EXDATEs, RDATEs and single AVAILABLEs change, each with the windows it has: none is
+     * closed. Empty when the hours are only weekly.
+     */
+    days: SlotlockExceptionDay[];
 }
 /**
- * Weekly rules from an iCalendar VAVAILABILITY (RFC 7953): one VAVAILABILITY, each AVAILABLE a
- * weekly RRULE with a time of day and a length. Refuses (`invalid_availability`) what weekly
- * rules cannot say: a VAVAILABILITY bounded by DTSTART or DTEND, more than one, an AVAILABLE
- * without RRULE, with RDATE, EXDATE or RECURRENCE-ID, a whole-day DTSTART, seconds, AVAILABLEs in
- * different zones, and any rule `parseAvailabilityRules` refuses. An RRULE without BYDAY takes
- * DTSTART's day, as RFC 5545 reads it.
+ * Weekly rules and the days that differ from them, from an iCalendar VAVAILABILITY (RFC 7953): one
+ * VAVAILABILITY, each AVAILABLE either a weekly RRULE with a time of day and a length, or a single
+ * window. EXDATE takes a weekly window off its day, RDATE adds a window (of the AVAILABLE's length,
+ * or a PERIOD's), and a single AVAILABLE adds its own: each day they name becomes a day with hours
+ * of its own (`days`), as exceptions keep them (RFC 0004 B1). Refuses (`invalid_availability`) what
+ * these cannot say: a VAVAILABILITY bounded by DTSTART or DTEND, more than one, RECURRENCE-ID, a
+ * whole-day DTSTART, seconds, AVAILABLEs in different zones, an EXDATE at another time than its
+ * window, a day with more than four windows or one over a day, more than
+ * SLOTLOCK_MAX_VAVAILABILITY_DAYS such days, and any rule `parseAvailabilityRules` refuses. An
+ * RRULE without BYDAY takes DTSTART's day, as RFC 5545 reads it.
  */
 export declare function parseVAvailability(text: string): ParsedVAvailability;
 /** A JSCalendar Event object (RFC 8984 §5.1): the properties Slotlock fills. */

package/interop.js

@@ -3,6 +3,7 @@
 // (RFC 8984). Pure functions: the application API serves them, and an application may call them
 // directly.
 import ICAL from 'ical.js';
+import { epochDay } from './hours.js';
 import { zonedDateTimeFields } from './timezone.js';
 import { invalidAvailability, parseAvailabilityRules } from './weekly-hours.js';
 /** The longest VAVAILABILITY text `parseVAvailability` reads. */
@@ -40,13 +41,21 @@ function referenceDay(rrule) {
     const index = DAYS.findIndex((day) => named.includes(day));
     return new Date(REFERENCE_SUNDAY + Math.max(index, 0) * 86_400_000);
 }
+/** The most days one VAVAILABILITY's EXDATEs, RDATEs and single AVAILABLEs may name. */
+export const SLOTLOCK_MAX_VAVAILABILITY_DAYS = 1_000;
+const compactDate = (date) => date.replaceAll('-', '');
+const wallStamp = (date, minutes) => `${compactDate(date)}T${pad(Math.floor(minutes / 60))}${pad(minutes % 60)}00`;
+/** The weekday codes an RRULE's BYDAY names. */
+const byDays = (rrule) => new Set((/(?:^|;)BYDAY=([^;]*)/.exec(rrule)?.[1] ?? '').split(',').map((day) => day.slice(-2)));
+/** The weekday code of `YYYY-MM-DD`. */
+const weekdayOf = (date) => DAYS[new Date(`${date}T00:00:00Z`).getUTCDay()];
 /**
  * A VCALENDAR with one VAVAILABILITY holding an AVAILABLE per rule: DTSTART on the rule's first day
  * in a reference week of January 2024, with the IANA zone as TZID (no VTIMEZONE: RFC 7809 lets the
  * two sides agree on IANA names), DURATION and the rule's RRULE. `[]` is a VAVAILABILITY with no
  * AVAILABLE: never bookable. CRLF line endings, folded at 75 octets.
  */
-export function emitVAvailability({ rules, timezone, uid }) {
+export function emitVAvailability({ rules, timezone, uid, days }) {
     const lines = [
         'BEGIN:VCALENDAR',
         'VERSION:2.0',
@@ -59,7 +68,31 @@ export function emitVAvailability({ rules, timezone, uid }) {
         const day = referenceDay(rule.rrule);
         const hour = Math.floor(rule.startMinutes / 60);
         const minute = rule.startMinutes % 60;
-        lines.push('BEGIN:AVAILABLE', `UID:${uid}-${index}`, `DTSTAMP:${VAVAILABILITY_DTSTAMP}`, `DTSTART;TZID=${timezone}:${day.getUTCFullYear()}${pad(day.getUTCMonth() + 1)}${pad(day.getUTCDate())}T${pad(hour)}${pad(minute)}00`, `DURATION:PT${rule.durationMinutes}M`, `RRULE:${rule.rrule}`, 'END:AVAILABLE');
+        lines.push('BEGIN:AVAILABLE', `UID:${uid}-${index}`, `DTSTAMP:${VAVAILABILITY_DTSTAMP}`, `DTSTART;TZID=${timezone}:${day.getUTCFullYear()}${pad(day.getUTCMonth() + 1)}${pad(day.getUTCDate())}T${pad(hour)}${pad(minute)}00`, `DURATION:PT${rule.durationMinutes}M`, `RRULE:${rule.rrule}`);
+        const weekdays = byDays(rule.rrule);
+        const excluded = (days ?? [])
+            .filter((day) => weekdays.has(weekdayOf(day.date)))
+            .map((day) => wallStamp(day.date, rule.startMinutes));
+        if (excluded.length > 0)
+            lines.push(`EXDATE;TZID=${timezone}:${excluded.join(',')}`);
+        lines.push('END:AVAILABLE');
+    });
+    // An open day's hours: one AVAILABLE per window, repeated by RDATE on each further day with it.
+    const byWindow = new Map();
+    for (const day of days ?? []) {
+        for (const window of day.windows) {
+            const key = `${window.startMinutes}:${window.durationMinutes}`;
+            const entry = byWindow.get(key) ?? { window, dates: [] };
+            entry.dates.push(day.date);
+            byWindow.set(key, entry);
+        }
+    }
+    [...byWindow.values()].forEach(({ window, dates }, index) => {
+        const [first, ...rest] = [...dates].sort();
+        lines.push('BEGIN:AVAILABLE', `UID:${uid}-day-${index}`, `DTSTAMP:${VAVAILABILITY_DTSTAMP}`, `DTSTART;TZID=${timezone}:${wallStamp(first, window.startMinutes)}`, `DURATION:PT${window.durationMinutes}M`);
+        if (rest.length > 0)
+            lines.push(`RDATE;TZID=${timezone}:${rest.map((date) => wallStamp(date, window.startMinutes)).join(',')}`);
+        lines.push('END:AVAILABLE');
     });
     lines.push('END:VAVAILABILITY', 'END:VCALENDAR');
     return `${lines.map(fold).join(CRLF)}${CRLF}`;
@@ -72,12 +105,16 @@ function single(component, name) {
     return properties[0] ?? null;
 }
 /**
- * Weekly rules from an iCalendar VAVAILABILITY (RFC 7953): one VAVAILABILITY, each AVAILABLE a
- * weekly RRULE with a time of day and a length. Refuses (`invalid_availability`) what weekly
- * rules cannot say: a VAVAILABILITY bounded by DTSTART or DTEND, more than one, an AVAILABLE
- * without RRULE, with RDATE, EXDATE or RECURRENCE-ID, a whole-day DTSTART, seconds, AVAILABLEs in
- * different zones, and any rule `parseAvailabilityRules` refuses. An RRULE without BYDAY takes
- * DTSTART's day, as RFC 5545 reads it.
+ * Weekly rules and the days that differ from them, from an iCalendar VAVAILABILITY (RFC 7953): one
+ * VAVAILABILITY, each AVAILABLE either a weekly RRULE with a time of day and a length, or a single
+ * window. EXDATE takes a weekly window off its day, RDATE adds a window (of the AVAILABLE's length,
+ * or a PERIOD's), and a single AVAILABLE adds its own: each day they name becomes a day with hours
+ * of its own (`days`), as exceptions keep them (RFC 0004 B1). Refuses (`invalid_availability`) what
+ * these cannot say: a VAVAILABILITY bounded by DTSTART or DTEND, more than one, RECURRENCE-ID, a
+ * whole-day DTSTART, seconds, AVAILABLEs in different zones, an EXDATE at another time than its
+ * window, a day with more than four windows or one over a day, more than
+ * SLOTLOCK_MAX_VAVAILABILITY_DAYS such days, and any rule `parseAvailabilityRules` refuses. An
+ * RRULE without BYDAY takes DTSTART's day, as RFC 5545 reads it.
  */
 export function parseVAvailability(text) {
     if (text.length > SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS) {
@@ -99,16 +136,26 @@ export function parseVAvailability(text) {
         throw invalidAvailability('A VAVAILABILITY bounded by DTSTART or DTEND cannot be weekly hours');
     }
     const zones = new Set();
-    const rules = availability.getAllSubcomponents('available').map((available, index) => {
-        for (const name of ['rdate', 'exdate', 'recurrence-id']) {
-            if (available.hasProperty(name)) {
-                throw invalidAvailability(`AVAILABLE ${index} has ${name.toUpperCase()}: weekly hours cannot say it`);
-            }
+    // What EXDATE, RDATE and single AVAILABLEs say, day by day: weekly windows taken away, and
+    // windows added.
+    const excluded = new Map();
+    const added = new Map();
+    const named = new Set();
+    const nameDay = (date, index) => {
+        named.add(date);
+        if (named.size > SLOTLOCK_MAX_VAVAILABILITY_DAYS) {
+            throw invalidAvailability(`AVAILABLE ${index}: at most ${SLOTLOCK_MAX_VAVAILABILITY_DAYS} days may differ from the week`);
+        }
+    };
+    const weekly = [];
+    availability.getAllSubcomponents('available').forEach((available, index) => {
+        if (available.hasProperty('recurrence-id')) {
+            throw invalidAvailability(`AVAILABLE ${index} has RECURRENCE-ID: weekly hours cannot say it`);
         }
         const dtstart = single(available, 'dtstart');
         const rrule = single(available, 'rrule');
-        if (!dtstart || !rrule)
-            throw invalidAvailability(`AVAILABLE ${index} needs DTSTART and RRULE`);
+        if (!dtstart)
+            throw invalidAvailability(`AVAILABLE ${index} needs DTSTART`);
         const start = dtstart.getFirstValue();
         if (start.isDate)
             throw invalidAvailability(`AVAILABLE ${index} starts on a date, not a time`);
@@ -139,16 +186,97 @@ export function parseVAvailability(text) {
         if (!Number.isInteger(durationMinutes) || durationMinutes < 1) {
             throw invalidAvailability(`AVAILABLE ${index} does not last a whole number of minutes`);
         }
+        const startMinutes = start.hour * 60 + start.minute;
+        const dateOf = (time) => `${pad(time.year, 4)}-${pad(time.month)}-${pad(time.day)}`;
+        // EXDATE and RDATE are read in DTSTART's zone: another would move them.
+        const sameZone = (property, name) => {
+            if (property.getParameter('tzid') !== dtstart.getParameter('tzid')) {
+                throw invalidAvailability(`AVAILABLE ${index} has ${name} in another zone than DTSTART`);
+            }
+        };
+        const addWindow = (date, minutes, length) => {
+            if (length > 1_440) {
+                throw invalidAvailability(`AVAILABLE ${index} adds a window longer than a day on ${date}`);
+            }
+            nameDay(date, index);
+            added.set(date, [...(added.get(date) ?? []), { startMinutes: minutes, durationMinutes: length }]);
+        };
+        for (const property of available.getAllProperties('rdate')) {
+            sameZone(property, 'RDATE');
+            for (const value of property.getValues()) {
+                if (value instanceof ICAL.Period) {
+                    const from = value.start;
+                    const to = value.getEnd();
+                    const length = (wallSeconds(to) - wallSeconds(from)) / 60;
+                    if (from.isDate || from.second !== 0 || !Number.isInteger(length) || length < 1) {
+                        throw invalidAvailability(`AVAILABLE ${index} has an RDATE period that is not whole minutes`);
+                    }
+                    addWindow(dateOf(from), from.hour * 60 + from.minute, length);
+                }
+                else {
+                    const time = value;
+                    if (time.isDate || time.second !== 0) {
+                        throw invalidAvailability(`AVAILABLE ${index} has an RDATE that is not a time to the minute`);
+                    }
+                    addWindow(dateOf(time), time.hour * 60 + time.minute, durationMinutes);
+                }
+            }
+        }
+        if (!rrule) {
+            // A single window on its day.
+            addWindow(dateOf(start), startMinutes, durationMinutes);
+            if (available.hasProperty('exdate')) {
+                throw invalidAvailability(`AVAILABLE ${index} has EXDATE but no RRULE`);
+            }
+            return;
+        }
         let value = String(rrule.getFirstValue());
         if (!/(?:^|;)BYDAY=/.test(value)) {
             value = `${value};BYDAY=${DAYS[start.dayOfWeek() - 1]}`;
         }
-        return { rrule: value, startMinutes: start.hour * 60 + start.minute, durationMinutes };
+        const position = weekly.length;
+        weekly.push({ rule: { rrule: value, startMinutes, durationMinutes }, index });
+        for (const property of available.getAllProperties('exdate')) {
+            sameZone(property, 'EXDATE');
+            for (const time of property.getValues()) {
+                if (!time.isDate && time.hour * 60 + time.minute !== startMinutes) {
+                    throw invalidAvailability(`AVAILABLE ${index} has an EXDATE at another time than its window`);
+                }
+                const date = dateOf(time);
+                nameDay(date, index);
+                excluded.set(date, (excluded.get(date) ?? new Set()).add(position));
+            }
+        }
     });
     if (zones.size > 1)
         throw invalidAvailability('The AVAILABLEs are in different time zones');
     const [timezone = null] = zones;
-    return { timezone, rules: parseAvailabilityRules(rules) };
+    const rules = parseAvailabilityRules(weekly.map(({ rule }) => rule));
+    // Each named day as it reads: the weekly windows that fall on it and are not excluded, and those
+    // added.
+    const days = [...named].sort().map((date) => {
+        const weekday = weekdayOf(date);
+        const untilOk = (rrule) => {
+            const until = /(?:^|;)UNTIL=(\d{8})/.exec(rrule)?.[1];
+            return until === undefined || compactDate(date) <= until;
+        };
+        const windows = [];
+        rules.forEach((rule, position) => {
+            if (!byDays(rule.rrule).has(weekday) || !untilOk(rule.rrule) || excluded.get(date)?.has(position))
+                return;
+            if (rule.durationMinutes > 1_440) {
+                throw invalidAvailability(`A window longer than a day falls on ${date}, which differs from the week`);
+            }
+            windows.push({ startMinutes: rule.startMinutes, durationMinutes: rule.durationMinutes });
+        });
+        windows.push(...(added.get(date) ?? []));
+        if (windows.length > 4)
+            throw invalidAvailability(`${date} has more than 4 windows`);
+        if (epochDay(date) === null)
+            throw invalidAvailability(`${date} is not a day`);
+        return { date, windows };
+    });
+    return { timezone, rules, days };
 }
 const wallSeconds = (time) => Date.UTC(time.year, time.month - 1, time.day, time.hour, time.minute, time.second) / 1000;
 /** An instant as a LocalDateTime (RFC 8984 §1.4.4) on the wall clock of `timezone`. */

package/lifecycle.d.ts

@@ -0,0 +1,31 @@
+import type { SlotlockChangeType } from './event-feed.js';
+export declare const SLOTLOCK_BOOKING_STATUSES: readonly ["held", "confirmed", "checked_in", "completed", "cancelled", "no_show", "released", "expired", "erased"];
+export type SlotlockBookingStatus = (typeof SLOTLOCK_BOOKING_STATUSES)[number];
+/** What moves a hold or booking, and who does it. */
+export declare const SLOTLOCK_BOOKING_ACTIONS: readonly ["confirm", "release", "expire", "reschedule", "check_in", "cancel", "no_show", "complete", "erase"];
+export type SlotlockBookingAction = (typeof SLOTLOCK_BOOKING_ACTIONS)[number];
+/** Where an end leaves a hold or booking: nothing moves it again, but erasure. */
+export declare const SLOTLOCK_BOOKING_ENDS: ReadonlySet<SlotlockBookingStatus>;
+/** Why a tombstoned reference ended, as `reservation_tombstones.end_reason` keeps it. */
+export type SlotlockEndReason = 'cancelled' | 'no_show' | 'released' | 'expired' | 'erased';
+type Move = {
+    to: SlotlockBookingStatus;
+    change: SlotlockChangeType | readonly SlotlockChangeType[] | null;
+};
+/**
+ * Each allowed move: the status it leads to and the feed change it writes (null: none; a list: all
+ * of them, in order). Anything not here is refused with `SLOTLOCK_BOOKING_REFUSALS`.
+ */
+export declare const SLOTLOCK_BOOKING_TRANSITIONS: Readonly<Record<SlotlockBookingStatus, Readonly<Partial<Record<SlotlockBookingAction, Move>>>>>;
+/** The refusal a move gets from a status it is not allowed from, as the store names it. */
+export declare function slotlockBookingRefusal(from: SlotlockBookingStatus, action: SlotlockBookingAction): string;
+/** What `action` does from `from`: the status it leads to and the change it writes, or its refusal. */
+export declare function slotlockBookingNext(from: SlotlockBookingStatus, action: SlotlockBookingAction): {
+    ok: true;
+    to: SlotlockBookingStatus;
+    changes: readonly SlotlockChangeType[];
+} | {
+    ok: false;
+    code: string;
+};
+export {};