feat: add /events endpoints serving Luma calendar events

[mrdarrengriffin]

Serves the foundation's Luma community events so the project websites can show them without each talking to Luma.

Endpoints

• GET /events — every configured calendar with its events, in configuration order.
• GET /events/:slug — one calendar (e.g. /events/home-assistant-meetups); 404 for an unknown slug, without echoing the slug back.

Events are everything the calendar's iCalendar feed advertises — past ones included, sorted soonest first — so the consumer decides the window it shows. Each event carries id, summary, start/end (UTC ISO 8601, or a bare date for all-day events), description, location, latitude/longitude, status, and url — the event's Luma page link, which the feed only embeds in the description text, so the service lifts it out.

Design

Mirrors the livestream module's architecture: one Nest module (src/events), a controller over in-memory state, no database.

• Configuration: a new EVENTS_CALENDARS variable of calendarId:slug pairs, the same contract as LIVESTREAM_CHANNELS — slugs pinned in config so a Luma rename cannot change public URLs, display names read from each feed's X-WR-CALNAME at runtime, malformed config fails startup.
• Polling: each calendar's public iCalendar export (api.luma.com/ics/get?entity=calendar&id=…) is fetched at startup and every 15 minutes — unauthenticated and unmetered, so no quota to design around. A calendar whose fetch (or a 200 that isn't a calendar) fails keeps serving its last good content.
• Parsing: a small dependency-free iCalendar parser handling line folding, text escaping, quoted parameters, and the UTC / all-day / TZID date forms (TZID converted to UTC via Intl, no timezone dependency).
• updatedAt moves only when the served content changes, so it is safe for caching and change detection.

Testing

• Unit specs for the config parser, service (parsing, date forms, refresh cycle, failure modes) and controller; an events e2e suite booting a real Nest app with Luma stubbed at the fetch boundary; Swagger e2e assertions extended to the new endpoints and schemas.
• Full gate green: format, lint, typecheck, LikeC4 diagrams, 230 unit + 93 e2e tests.
• Smoke-tested against the real Home Assistant Meetups calendar (cal-6Tm2FkWzoBpLXWr): 38 events parsed end to end.

README, example.env and the C4 architecture model are updated to match.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Vp21Nq4X8pV68GfLeBwJ3e

---

Generated by Claude Code

[Copilot]

Pull request overview

Adds a new Events feature area to the NestJS web API that periodically fetches and parses Luma iCalendar feeds into in-memory state, and exposes that state via /events endpoints (mirroring the existing livestream module pattern).

Changes:

• Introduces src/events module (config parsing, polling service, controller, and Swagger response models) to serve Luma calendar events.
• Extends application wiring and Swagger docs to include the new endpoints and schemas.
• Adds unit + e2e coverage for config parsing, feed parsing/refresh behavior, controller behavior, and Swagger contract assertions.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/test-app.fixture.ts	Boots test app with EventsModule and stubs Luma ICS fetch.
test/swagger.e2e-spec.ts	Asserts /events paths and event/calendar schemas are documented.
test/events.e2e-spec.ts	End-to-end tests for events endpoints against stubbed ICS upstream.
src/main.ts	Updates Swagger description to include Luma events.
src/events/index.ts	Barrel exports for the events feature.
src/events/events.service.ts	Polling + parsing + in-memory state and read APIs for calendars/events.
src/events/events.service.spec.ts	Unit tests for parsing, date handling, refresh cycle, and error cases.
src/events/events.response.ts	Swagger response DTOs + schema documentation for events/calendars.
src/events/events.module.ts	DI wiring and startup parsing of EVENTS_CALENDARS.
src/events/events.controller.ts	Implements GET /events and GET /events/:slug endpoints.
src/events/events.controller.spec.ts	Unit tests for controller delegation and error propagation.
src/events/events.calendars.ts	Parses/validates EVENTS_CALENDARS and builds Luma ICS URLs.
src/events/events.calendars.spec.ts	Unit tests for calendar config parsing/validation and URL building.
src/app.module.ts	Registers EventsModule in the main app module.
README.md	Documents new endpoints, response shape, and config variable.
example.env	Adds EVENTS_CALENDARS documentation and example value.
docs/architecture/views.c4	Updates views to include Luma as an upstream.
docs/architecture/specification.c4	Adds iCalendar relationship type.
docs/architecture/model.c4	Adds Luma model elements and events components/relationships.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/events/events.service.ts:508

• LUMA_LINK_PATTERN extraction will include trailing sentence punctuation (e.g. a trailing "."), producing an invalid url value that is not actually the event's Luma page link. Consider post-processing the regex match to trim common trailing punctuation, and update the corresponding unit test that currently expects the period to be part of the URL.

      // A URL property when the feed grows one; today the Luma page link only
      // appears inside the description text.
      url:
        text('URL') ??
        (description ? LUMA_LINK_PATTERN.exec(description)?.[0] : undefined),

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.