slotlock 0.3.0 → 0.5.1

package/index.d.ts

@@ -1,8 +1,14 @@
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
+export { type SlotlockBookingRule, type SlotlockBookingRules, bookingRuleBroken, bookingSearch, nextStepStart, parseBookingRules, } from './booking-rules.js';
+export { type CreateWebhookEndpointResult, type ListChangesResult, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, type SlotlockChange, type SlotlockChangeType, type SlotlockEventFeed, type SlotlockWebhookClaim, type SlotlockWebhookEndpoint, } from './event-feed.js';
+export { type SlotlockCloudEvent, type SlotlockWebhookPassResult, type SlotlockWebhookResponse, type SlotlockWebhookScheduler, type SlotlockWebhookSender, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
+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 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';
 export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, 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';
@@ -16,7 +22,7 @@ export type { SlotlockApplicationBackend, SlotlockApplicationInvocationContext,
 export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 export type { SlotlockMaintenanceResult, SlotlockMaintenanceScheduler, SlotlockMaintenanceSchedulerOptions, } from './maintenance.js';
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, 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, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
+export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
 export type { SlotlockDashboard, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, } from './dashboard.js';
 export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
@@ -25,4 +31,4 @@ export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emit
 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, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.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, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';

package/index.js

@@ -4,8 +4,13 @@
 // TypeScript 6 default) still loads @types/node.
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
+export { bookingRuleBroken, bookingSearch, nextStepStart, parseBookingRules, } from './booking-rules.js';
+export { SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, } from './event-feed.js';
+export { createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
+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 { 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_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, 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';
@@ -13,7 +18,7 @@ export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend,
 export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, } from './application-api.js';
 export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, 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, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
+export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
 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';

package/interop.d.ts

@@ -0,0 +1,117 @@
+import type { SlotlockCalendarEvent, WeeklyAvailabilityRule } from './types.js';
+/** The longest VAVAILABILITY text `parseVAvailability` reads. */
+export declare const SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS = 65536;
+export interface EmitVAvailabilityOptions {
+    /** The resource's weekly rules, in `timezone`. */
+    rules: readonly WeeklyAvailabilityRule[];
+    /** The IANA zone the rules are read in: every DTSTART names it as its TZID. */
+    timezone: string;
+    /** The VAVAILABILITY's UID; each AVAILABLE's is this with its index. */
+    uid: string;
+}
+/**
+ * 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 interface ParsedVAvailability {
+    /** The TZID every AVAILABLE named, `UTC` for UTC times, or null when they are all floating. */
+    timezone: string | null;
+    rules: WeeklyAvailabilityRule[];
+}
+/**
+ * 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.
+ */
+export declare function parseVAvailability(text: string): ParsedVAvailability;
+/** A JSCalendar Event object (RFC 8984 §5.1): the properties Slotlock fills. */
+export interface JSCalendarEvent {
+    '@type': 'Event';
+    uid: string;
+    updated: string;
+    created: string;
+    sequence: number;
+    prodId: string;
+    title: string;
+    description?: string;
+    start: string;
+    timeZone: string;
+    duration: string;
+    status: 'confirmed' | 'tentative';
+    freeBusyStatus: 'free' | 'busy';
+    locations?: Record<string, {
+        '@type': 'Location';
+        name: string;
+    }>;
+    participants?: Record<string, JSCalendarParticipant>;
+    alerts?: Record<string, JSCalendarAlert>;
+    recurrenceRules?: JSCalendarRecurrenceRule[];
+    recurrenceOverrides?: Record<string, {
+        excluded: true;
+    } | {
+        start: string;
+        duration: string;
+    }>;
+    /** The RRULE the recurrence was written as, kept verbatim (RFC 8984 §3.3 vendor property). */
+    'slotlock.pylota.io:rrule'?: string;
+}
+export interface JSCalendarParticipant {
+    '@type': 'Participant';
+    name?: string;
+    email: string;
+    sendTo: {
+        imip: string;
+    };
+    roles: Record<string, true>;
+    participationStatus?: 'needs-action' | 'accepted' | 'declined' | 'tentative' | 'delegated';
+    expectReply?: boolean;
+}
+export interface JSCalendarAlert {
+    '@type': 'Alert';
+    trigger: {
+        '@type': 'OffsetTrigger';
+        offset: string;
+        relativeTo: 'start';
+    };
+    action: 'display' | 'email';
+}
+export interface JSCalendarRecurrenceRule {
+    '@type': 'RecurrenceRule';
+    frequency: 'yearly' | 'monthly' | 'weekly' | 'daily' | 'hourly' | 'minutely' | 'secondly';
+    interval?: number;
+    firstDayOfWeek?: string;
+    byDay?: {
+        '@type': 'NDay';
+        day: string;
+        nthOfPeriod?: number;
+    }[];
+    byMonthDay?: number[];
+    byMonth?: string[];
+    byYearDay?: number[];
+    byWeekNo?: number[];
+    byHour?: number[];
+    byMinute?: number[];
+    bySecond?: number[];
+    bySetPosition?: number[];
+    count?: number;
+    until?: string;
+}
+/**
+ * An RRULE as a JSCalendar RecurrenceRule (RFC 8984 §4.3.3), or null when it holds a part the
+ * mapping does not know (the verbatim RRULE is exported beside it either way). A UTC UNTIL becomes
+ * the wall time in `timezone`; a date UNTIL the end of that day.
+ */
+export declare function recurrenceRuleFromRRule(rrule: string, timezone: string): JSCalendarRecurrenceRule | null;
+/**
+ * A Slotlock calendar event as a JSCalendar Event (RFC 8984): its id as `uid`, its revision as
+ * `sequence`, start as a LocalDateTime in its zone with an exact duration, the organizer an
+ * `owner` participant, reminders `OffsetTrigger` alerts before the start, and the recurrence as
+ * `recurrenceRules` with `recurrenceOverrides` keyed by each exception's original start.
+ */
+export declare function toJSCalendarEvent(event: SlotlockCalendarEvent): JSCalendarEvent;

package/interop.js

@@ -0,0 +1,356 @@
+// Calendar interchange in the standards' own shapes: a resource's weekly bookable hours as an
+// iCalendar VAVAILABILITY (RFC 7953), read and written, and a calendar event as a JSCalendar Event
+// (RFC 8984). Pure functions: the application API serves them, and an application may call them
+// directly.
+import ICAL from 'ical.js';
+import { zonedDateTimeFields } from './timezone.js';
+import { parseAvailabilityRules } from './weekly-hours.js';
+/** The longest VAVAILABILITY text `parseVAvailability` reads. */
+export const SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS = 65_536;
+const PRODID = '-//Pylota//Slotlock//EN';
+const CRLF = '\r\n';
+const DAYS = ['SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'];
+/** 2024-01-07 is a Sunday: the reference week runs Sunday 7 to Saturday 13 January. */
+const REFERENCE_SUNDAY = Date.UTC(2024, 0, 7);
+const VAVAILABILITY_DTSTAMP = '20240101T000000Z';
+function invalidAvailability(message) {
+    return Object.assign(new Error(message), { code: 'invalid_availability' });
+}
+const pad = (value, width = 2) => String(value).padStart(width, '0');
+/** RFC 5545 §3.1: lines of at most 75 octets, continued with a leading space. */
+function fold(line) {
+    const bytes = Buffer.from(line, 'utf8');
+    if (bytes.length <= 75)
+        return line;
+    const parts = [];
+    let start = 0;
+    let limit = 75;
+    while (start < bytes.length) {
+        let end = Math.min(start + limit, bytes.length);
+        // Never split a UTF-8 sequence: back up over continuation bytes.
+        while (end < bytes.length && (bytes[end] & 0xc0) === 0x80)
+            end -= 1;
+        parts.push(bytes.subarray(start, end).toString('utf8'));
+        start = end;
+        limit = 74;
+    }
+    return parts.join(`${CRLF} `);
+}
+/** The first day of the reference week the rule's BYDAY names, so DTSTART is its first occurrence. */
+function referenceDay(rrule) {
+    const byDay = /(?:^|;)BYDAY=([^;]*)/.exec(rrule)?.[1] ?? '';
+    const named = byDay.split(',').map((day) => day.slice(-2));
+    const index = DAYS.findIndex((day) => named.includes(day));
+    return new Date(REFERENCE_SUNDAY + Math.max(index, 0) * 86_400_000);
+}
+/**
+ * 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 }) {
+    const lines = [
+        'BEGIN:VCALENDAR',
+        'VERSION:2.0',
+        `PRODID:${PRODID}`,
+        'BEGIN:VAVAILABILITY',
+        `UID:${uid}`,
+        `DTSTAMP:${VAVAILABILITY_DTSTAMP}`,
+    ];
+    rules.forEach((rule, index) => {
+        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('END:VAVAILABILITY', 'END:VCALENDAR');
+    return `${lines.map(fold).join(CRLF)}${CRLF}`;
+}
+/** The one property `name` of `component`, refusing a repeat. */
+function single(component, name) {
+    const properties = component.getAllProperties(name);
+    if (properties.length > 1)
+        throw invalidAvailability(`An AVAILABLE has more than one ${name.toUpperCase()}`);
+    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.
+ */
+export function parseVAvailability(text) {
+    if (text.length > SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS) {
+        throw invalidAvailability(`The iCalendar text is longer than ${SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS} characters`);
+    }
+    let root;
+    try {
+        root = new ICAL.Component(ICAL.parse(text));
+    }
+    catch {
+        throw invalidAvailability('The text is not iCalendar');
+    }
+    const availabilities = root.name === 'vavailability' ? [root] : root.getAllSubcomponents('vavailability');
+    if (availabilities.length !== 1) {
+        throw invalidAvailability('The iCalendar text needs exactly one VAVAILABILITY');
+    }
+    const availability = availabilities[0];
+    if (availability.hasProperty('dtstart') || availability.hasProperty('dtend')) {
+        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`);
+            }
+        }
+        const dtstart = single(available, 'dtstart');
+        const rrule = single(available, 'rrule');
+        if (!dtstart || !rrule)
+            throw invalidAvailability(`AVAILABLE ${index} needs DTSTART and RRULE`);
+        const start = dtstart.getFirstValue();
+        if (start.isDate)
+            throw invalidAvailability(`AVAILABLE ${index} starts on a date, not a time`);
+        if (start.second !== 0)
+            throw invalidAvailability(`AVAILABLE ${index} starts at a second`);
+        const tzid = dtstart.getParameter('tzid');
+        zones.add(typeof tzid === 'string' ? tzid : start.zone === ICAL.Timezone.utcTimezone ? 'UTC' : null);
+        let durationMinutes;
+        const dtend = single(available, 'dtend');
+        const duration = single(available, 'duration');
+        if (dtend && duration)
+            throw invalidAvailability(`AVAILABLE ${index} has both DTEND and DURATION`);
+        if (duration) {
+            const seconds = duration.getFirstValue().toSeconds();
+            durationMinutes = seconds / 60;
+        }
+        else if (dtend) {
+            if (dtend.getParameter('tzid') !== dtstart.getParameter('tzid')) {
+                throw invalidAvailability(`AVAILABLE ${index} ends in another zone than it starts`);
+            }
+            // Both are wall times in one zone: their difference is the window's length on the clock.
+            const end = dtend.getFirstValue();
+            durationMinutes = (wallSeconds(end) - wallSeconds(start)) / 60;
+        }
+        else {
+            throw invalidAvailability(`AVAILABLE ${index} needs DTEND or DURATION`);
+        }
+        if (!Number.isInteger(durationMinutes) || durationMinutes < 1) {
+            throw invalidAvailability(`AVAILABLE ${index} does not last a whole number of minutes`);
+        }
+        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 };
+    });
+    if (zones.size > 1)
+        throw invalidAvailability('The AVAILABLEs are in different time zones');
+    const [timezone = null] = zones;
+    return { timezone, rules: parseAvailabilityRules(rules) };
+}
+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`. */
+function localDateTime(instant, timezone) {
+    const wall = zonedDateTimeFields(instant, timezone);
+    return `${pad(wall.year, 4)}-${pad(wall.month)}-${pad(wall.day)}T${pad(wall.hour)}:${pad(wall.minute)}:${pad(wall.second)}`;
+}
+/** An exact length as an RFC 8984 Duration of hours, minutes and seconds. */
+function exactDuration(milliseconds) {
+    const total = Math.max(0, Math.round(milliseconds / 1000));
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    if (total === 0)
+        return 'PT0S';
+    return `PT${hours ? `${hours}H` : ''}${minutes ? `${minutes}M` : ''}${seconds ? `${seconds}S` : ''}`;
+}
+const FREQUENCIES = new Set(['YEARLY', 'MONTHLY', 'WEEKLY', 'DAILY', 'HOURLY', 'MINUTELY', 'SECONDLY']);
+const NUMBER_PARTS = {
+    BYMONTHDAY: 'byMonthDay',
+    BYYEARDAY: 'byYearDay',
+    BYWEEKNO: 'byWeekNo',
+    BYHOUR: 'byHour',
+    BYMINUTE: 'byMinute',
+    BYSECOND: 'bySecond',
+    BYSETPOS: 'bySetPosition',
+};
+/**
+ * An RRULE as a JSCalendar RecurrenceRule (RFC 8984 §4.3.3), or null when it holds a part the
+ * mapping does not know (the verbatim RRULE is exported beside it either way). A UTC UNTIL becomes
+ * the wall time in `timezone`; a date UNTIL the end of that day.
+ */
+export function recurrenceRuleFromRRule(rrule, timezone) {
+    const parts = new Map();
+    for (const part of rrule.split(';')) {
+        const [key, value] = part.split('=');
+        if (!key || value === undefined || parts.has(key.toUpperCase()))
+            return null;
+        parts.set(key.toUpperCase(), value);
+    }
+    const frequency = parts.get('FREQ');
+    if (!frequency || !FREQUENCIES.has(frequency))
+        return null;
+    const rule = {
+        '@type': 'RecurrenceRule',
+        frequency: frequency.toLowerCase(),
+    };
+    const integers = (value) => {
+        const list = value.split(',').map(Number);
+        return list.every(Number.isInteger) ? list : null;
+    };
+    for (const [key, value] of parts) {
+        if (key === 'FREQ')
+            continue;
+        if (key === 'INTERVAL' || key === 'COUNT') {
+            const amount = Number(value);
+            if (!Number.isInteger(amount) || amount < 1)
+                return null;
+            rule[key === 'INTERVAL' ? 'interval' : 'count'] = amount;
+        }
+        else if (key === 'WKST') {
+            if (!/^(MO|TU|WE|TH|FR|SA|SU)$/.test(value))
+                return null;
+            rule.firstDayOfWeek = value.toLowerCase();
+        }
+        else if (key === 'BYDAY') {
+            const days = value.split(',').map((entry) => /^([+-]?\d{1,2})?(MO|TU|WE|TH|FR|SA|SU)$/.exec(entry));
+            if (days.some((match) => match === null))
+                return null;
+            rule.byDay = days.map((match) => {
+                const [, nth, day] = match;
+                return {
+                    '@type': 'NDay',
+                    day: day.toLowerCase(),
+                    ...(nth ? { nthOfPeriod: Number(nth) } : {}),
+                };
+            });
+        }
+        else if (key === 'BYMONTH') {
+            if (!/^\d{1,2}(,\d{1,2})*$/.test(value))
+                return null;
+            rule.byMonth = value.split(',').map((month) => String(Number(month)));
+        }
+        else if (key in NUMBER_PARTS) {
+            const list = integers(value);
+            if (!list)
+                return null;
+            rule[NUMBER_PARTS[key]] = list;
+        }
+        else if (key === 'UNTIL') {
+            const match = /^(\d{4})(\d{2})(\d{2})(?:T(\d{2})(\d{2})(\d{2})(Z)?)?$/.exec(value);
+            if (!match)
+                return null;
+            const [, year, month, day, hour, minute, second, utc] = match;
+            if (hour === undefined)
+                rule.until = `${year}-${month}-${day}T23:59:59`;
+            else if (utc) {
+                rule.until = localDateTime(new Date(Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second))), timezone);
+            }
+            else
+                rule.until = `${year}-${month}-${day}T${hour}:${minute}:${second}`;
+        }
+        else {
+            return null;
+        }
+    }
+    return rule;
+}
+const ROLES = {
+    chair: { attendee: true, chair: true },
+    required: { attendee: true },
+    optional: { attendee: true, optional: true },
+    non_participant: { informational: true },
+};
+/**
+ * A Slotlock calendar event as a JSCalendar Event (RFC 8984): its id as `uid`, its revision as
+ * `sequence`, start as a LocalDateTime in its zone with an exact duration, the organizer an
+ * `owner` participant, reminders `OffsetTrigger` alerts before the start, and the recurrence as
+ * `recurrenceRules` with `recurrenceOverrides` keyed by each exception's original start.
+ */
+export function toJSCalendarEvent(event) {
+    const output = {
+        '@type': 'Event',
+        uid: event.id,
+        updated: event.updatedAt.toISOString(),
+        created: event.createdAt.toISOString(),
+        sequence: event.revision,
+        prodId: PRODID,
+        title: event.summary,
+        start: localDateTime(event.start, event.timezone),
+        timeZone: event.timezone,
+        duration: exactDuration(event.end.getTime() - event.start.getTime()),
+        status: event.status ?? 'confirmed',
+        freeBusyStatus: event.transparency === 'transparent' ? 'free' : 'busy',
+    };
+    if (event.description !== undefined)
+        output.description = event.description;
+    if (event.location !== undefined) {
+        output.locations = { l1: { '@type': 'Location', name: event.location } };
+    }
+    const participants = {};
+    if (event.organizer) {
+        participants.p0 = {
+            '@type': 'Participant',
+            ...(event.organizer.name !== undefined ? { name: event.organizer.name } : {}),
+            email: event.organizer.email,
+            sendTo: { imip: `mailto:${event.organizer.email}` },
+            roles: { owner: true },
+        };
+    }
+    (event.attendees ?? []).forEach((attendee, index) => {
+        const participant = {
+            '@type': 'Participant',
+            ...(attendee.name !== undefined ? { name: attendee.name } : {}),
+            email: attendee.email,
+            sendTo: { imip: `mailto:${attendee.email}` },
+            roles: ROLES[attendee.role ?? 'required'] ?? { attendee: true },
+        };
+        if (attendee.participationStatus !== undefined) {
+            participant.participationStatus =
+                attendee.participationStatus === 'needs_action' ? 'needs-action' : attendee.participationStatus;
+        }
+        if (attendee.rsvp !== undefined)
+            participant.expectReply = attendee.rsvp;
+        participants[`p${index + 1}`] = participant;
+    });
+    if (Object.keys(participants).length > 0)
+        output.participants = participants;
+    if (event.reminders && event.reminders.length > 0) {
+        output.alerts = Object.fromEntries(event.reminders.map((reminder, index) => [
+            `a${index + 1}`,
+            {
+                '@type': 'Alert',
+                trigger: {
+                    '@type': 'OffsetTrigger',
+                    offset: reminder.minutesBeforeStart === 0 ? 'PT0S' : `-PT${reminder.minutesBeforeStart}M`,
+                    relativeTo: 'start',
+                },
+                action: reminder.action,
+            },
+        ]));
+    }
+    if (event.recurrence) {
+        output['slotlock.pylota.io:rrule'] = event.recurrence.rrule;
+        const rule = recurrenceRuleFromRRule(event.recurrence.rrule, event.timezone);
+        if (rule)
+            output.recurrenceRules = [rule];
+        const exceptions = event.recurrence.exceptions ?? [];
+        if (exceptions.length > 0) {
+            output.recurrenceOverrides = Object.fromEntries(exceptions.map((exception) => [
+                localDateTime(exception.recurrenceId, event.timezone),
+                exception.cancelled || !exception.start || !exception.end
+                    ? { excluded: true }
+                    : {
+                        start: localDateTime(exception.start, event.timezone),
+                        duration: exactDuration(exception.end.getTime() - exception.start.getTime()),
+                    },
+            ]));
+        }
+    }
+    return output;
+}

package/maintenance.d.ts

@@ -9,10 +9,21 @@ export interface SlotlockMaintenanceResult {
     refused: number;
     /**
      * Expired holds and the answers kept for keyed ones, and past the retention window event
-     * idempotency answers, agents' event cancellations and booking references retired with no
-     * booking, deleted. A cancelled booking's tombstone stays.
+     * idempotency answers, agents' event cancellations, booking references retired with no
+     * booking and feed changes, deleted. A cancelled booking's tombstone stays.
      */
     pruned: number;
+    /**
+     * Future one-off events whose wall time now falls at another instant (time zone rules changed):
+     * reported on the feed, or moved with `followZoneRules` (store.followZoneRules).
+     */
+    zoneShifts: number;
+    /** Coverage sources gone stale since the last pass, now reported on the feed (`coverage.stale`). */
+    staleSources: number;
+    /** Bookings left unclaimed past their check-in window, released (`reservation.no_show`). */
+    noShows: number;
+    /** Waitlist entries whose window came free, each now holding it (`waitlist.offered`). */
+    waitlistOffers: number;
     /** More was left than one pass does: run another. */
     capped: boolean;
     /**
@@ -30,6 +41,7 @@ export interface SlotlockMaintenanceResult {
 export declare function maintainSlotlockTenant(store: SlotlockStore, tenantRef: string, options?: {
     batches?: number;
     signal?: AbortSignal;
+    followZoneRules?: boolean;
 }): Promise<SlotlockMaintenanceResult>;
 /**
  * Run `work` holding the tenant's maintenance lock on a connection of its own, or return

package/maintenance.js

@@ -1,5 +1,5 @@
 import { ignoreRejection } from './hooks.js';
-import { calendarEventRollingHorizon } from './store.js';
+import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, calendarEventRollingHorizon } from './store.js';
 /**
  * One maintenance pass for a tenant: roll its recurring events to the rolling horizon, then purge
  * its expired holds with their answers and prune its events' and bookings' bookkeeping past the
@@ -43,7 +43,8 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     let pruned = 0;
     let eventsLeft = true;
     let bookingsLeft = true;
-    for (let batch = 0; batch < batches && (eventsLeft || bookingsLeft); batch++) {
+    let changesLeft = true;
+    for (let batch = 0; batch < batches && (eventsLeft || bookingsLeft || changesLeft); batch++) {
         options.signal?.throwIfAborted();
         if (eventsLeft) {
             const prune = await store.withTenant(tenantRef, (tenant) => tenant.pruneCalendarEventRetention({ tenantRef }));
@@ -55,6 +56,29 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
             pruned += prune.expiredHoldsDeleted + prune.holdCommandsDeleted + prune.tombstonesDeleted;
             bookingsLeft = prune.hasMore;
         }
+        if (changesLeft) {
+            const deleted = await store.withTenant(tenantRef, (tenant) => tenant.pruneChanges({ tenantRef, limit: CHANGE_PRUNE_BATCH }));
+            pruned += deleted;
+            changesLeft = deleted === CHANGE_PRUNE_BATCH;
+        }
+    }
+    options.signal?.throwIfAborted();
+    const zones = await store.withTenant(tenantRef, (tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
+    const staleSources = await store.withTenant(tenantRef, (tenant) => tenant.reportStaleCoverage({ tenantRef }));
+    // No-shows first: the time they free is offered to the waitlist in the same pass.
+    const noShows = await store.withTenant(tenantRef, (tenant) => tenant.releaseNoShows({ tenantRef }));
+    // The whole waitlist, in join order, a page at a time and each page its own transaction, so a
+    // later entry whose window is free is offered however many wait before it.
+    let waitlistOffers = 0;
+    let page = null;
+    for (let pages = 0; pages < WAITLIST_PAGES; pages++) {
+        options.signal?.throwIfAborted();
+        const from = page;
+        const offers = await store.withTenant(tenantRef, (tenant) => tenant.offerWaitlist({ tenantRef, ...(from ? { after: from } : {}) }));
+        waitlistOffers += offers.offered;
+        page = offers.next;
+        if (!page)
+            break;
     }
     if (rollFailure)
         throw rollFailure.error;
@@ -63,10 +87,18 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         conflicts,
         refused,
         pruned,
-        capped: rollCapped || eventsLeft || bookingsLeft,
+        zoneShifts: zones.shifted,
+        staleSources,
+        noShows,
+        waitlistOffers,
+        capped: rollCapped || eventsLeft || bookingsLeft || changesLeft,
         rollPending: rollCapped && after !== null && (after.rollRetryAt ?? null) === null,
     };
 }
+/** Pages of 50 that cover a tenant's whole waitlist (SLOTLOCK_MAX_WAITLIST_PER_TENANT). */
+const WAITLIST_PAGES = Math.ceil(SLOTLOCK_MAX_WAITLIST_PER_TENANT / 50);
+/** Feed changes past the retention deleted per batch. */
+const CHANGE_PRUNE_BATCH = 1_000;
 /** The advisory lock key for one tenant's maintenance (64-bit, from the tenant reference). */
 const LOCK_NAMESPACE = 'slotlock.maintenance:';
 /**