fete/specs/013-calendar-export/spec.md

# Feature Specification: Add Event to Calendar

**Feature**: `013-calendar-export`
**Created**: 2026-03-06
**Status**: Draft
**Source**: Migrated from spec/userstories.md

## User Scenarios & Testing

### User Story 1 - Download .ics file (Priority: P1)

A guest who wants to remember the event opens the event page and downloads an iCalendar file to import into their personal calendar application. The file contains all relevant event details: title, description, start date/time, location, and the public event URL. The UID in the file is derived from the event token so that re-downloading the file and re-importing it updates the existing calendar entry rather than creating a duplicate.

**Why this priority**: Core calendar integration — the most common and universally supported way to add an event to a calendar across all platforms.

**Independent Test**: Can be fully tested by visiting a valid event page, clicking the `.ics` download link, and verifying the downloaded file is a valid iCalendar (RFC 5545) document with the correct event fields and a stable UID.

**Acceptance Scenarios**:

1. **Given** a valid event page, **When** the guest clicks the `.ics` download link, **Then** a standards-compliant iCalendar file is downloaded containing the event title, description (if present), start date and time, location (if present), the public event URL, and a unique UID derived from the event token.
2. **Given** the guest downloads the `.ics` file twice for the same event, **When** they import both files into a calendar application, **Then** the calendar application updates the existing entry rather than creating a duplicate (due to the stable UID).
3. **Given** a guest holding only the event link (no RSVP, no login), **When** they access the `.ics` download link, **Then** the file is served without requiring any authentication or personal data.
4. **Given** an event whose expiry date has passed, **When** the guest accesses the `.ics` download link, **Then** the file is still served (the guest can still obtain the calendar record of a past event).

---

### User Story 2 - Subscribe via webcal:// link (Priority: P2)

A guest subscribes to the event via a `webcal://` link so that their calendar application automatically picks up any changes — such as a rescheduled date or updated location — when the organizer edits the event via US-5.

**Why this priority**: Adds live-update value on top of the static `.ics` download. Requires the `.ics` download (P1) to already work. Most useful in conjunction with US-5 (Edit event details).

**Independent Test**: Can be tested by opening the `webcal://` URL in a calendar application and verifying it subscribes to the feed and shows the correct event details.

**Acceptance Scenarios**:

1. **Given** a valid event page, **When** the guest clicks the `webcal://` subscription link, **Then** their calendar application subscribes to the feed and displays the event.
2. **Given** a subscribed `webcal://` feed and an organizer who edits the event date via US-5, **When** the calendar application syncs the feed, **Then** the calendar entry is updated to reflect the new date.
3. **Given** a `webcal://` endpoint, **When** it is accessed, **Then** it serves identical iCalendar content as the `.ics` download, using the same event token in the URL.

---

### User Story 3 - Cancelled event reflected in calendar (Priority: P3)

When an event is cancelled (US-18), the `.ics` file and `webcal://` feed include `STATUS:CANCELLED` so that subscribed calendar applications reflect the cancellation automatically on their next sync.

**Why this priority**: Quality-of-life enhancement dependent on US-18 (cancel event). Deferred until US-18 is implemented.

**Independent Test**: Can be tested by cancelling an event and verifying the calendar feed includes `STATUS:CANCELLED`.

**Acceptance Scenarios**:

1. **Given** an event that has been cancelled (US-18), **When** a calendar application syncs the `webcal://` feed, **Then** the calendar entry is updated to show the cancelled status.
2. **Given** an event that has been cancelled (US-18), **When** the guest downloads the `.ics` file, **Then** it includes `STATUS:CANCELLED`.

> **Note**: Deferred until US-18 is implemented.

---

### Edge Cases

- What happens when the event has no description or location? The `.ics` file must omit those optional fields rather than including blank values.
- What happens if the server has no public URL configured? The event URL included in the `.ics` file must always be the correct public event URL.
- What happens if the event's date or timezone changes after a guest already imported the `.ics` file? The static import will be stale; the `webcal://` subscription will auto-update on next sync.

## Requirements

### Functional Requirements

- **FR-001**: System MUST expose a server-side endpoint that generates and serves a standards-compliant iCalendar (RFC 5545) `.ics` file for any event identified by its event token.
- **FR-002**: The `.ics` file MUST include: event title, description (if present), start date and time, location (if present), the public event URL, and a unique UID derived from the event token.
- **FR-003**: The UID in the `.ics` file MUST be stable across regenerations (same event token always produces the same UID) so that calendar applications update existing entries on re-import rather than creating duplicates.
- **FR-004**: The `.ics` file MUST be generated server-side; no external calendar or QR code service is called.
- **FR-005**: System MUST expose a `webcal://` subscription endpoint that serves identical iCalendar content as the `.ics` download, using the same event token in the URL.
- **FR-006**: Both the `.ics` download link and the `webcal://` subscription link MUST be accessible to any visitor holding the event link — no RSVP, login, or personal data required.
- **FR-007**: No personal data, name, or IP address MUST be logged when either link is accessed.
- **FR-008**: Both links MUST remain available and functional after the event's expiry date has passed.
- **FR-009**: When an event is cancelled (US-18), the `.ics` file and `webcal://` feed MUST include `STATUS:CANCELLED`. [Deferred until US-18 is implemented]

### Key Entities

- **CalendarFeed**: A virtual resource derived from the Event entity. Identified by the event token. Serialized to iCalendar (RFC 5545) format on demand. Has no independent storage — always generated from current event state.

## Success Criteria

### Measurable Outcomes

- **SC-001**: Downloading the `.ics` file and importing it into a standard calendar application (Google Calendar, Apple Calendar, Outlook) results in the event appearing with correct title, date/time, and location.
- **SC-002**: Re-importing the `.ics` file after an event edit updates the existing calendar entry rather than creating a duplicate.
- **SC-003**: Subscribing via `webcal://` and triggering a calendar sync after an event edit (US-5) reflects the updated details in the calendar application.
- **SC-004**: Both endpoints are accessible without authentication and without transmitting any personal data.
- **SC-005**: No external service is contacted during `.ics` generation or `webcal://` feed serving.