suaveplan/openspec/archive/2026-05-20-add-events-ics-export/proposal.md

add-events-ics-export

Package: @suaveplan/api-plugin-events Status: PROPOSED Type: feature-add (follow-up to shipped add-api-plugin-events) Spec delta: ./specs/api-plugin-events/spec.md

Why

The shipped @suaveplan/api-plugin-events (c59bf9a03) scoped out ICS / iCalendar export at landing time on the grounds that the parity-migration was already large and the export had no upstream code to migrate verbatim. The deferral is listed explicitly in openspec/archive/2026-05-19-add-api-plugin-events/proposal.md under ## Out of scope. Without ICS export, any consumer who wants to surface an "Add to Calendar" button or accept a calendar-app import from one of its events has to hand-roll the RFC 5545 builder. Hand-rolling RFC 5545 correctly is non-trivial — escape rules in §3.3.11, line folding at the 75-octet boundary in §3.1, CRLF line endings, and attendee mapping each introduce easy-to-miss defects.

This change ships ONLY ICS export. The other items still listed in the shipped proposal's ## Out of scope (RRULE recurrence, notification channel binding, calendar sync, waitlist, ticketing, SSE live updates) remain deferred to their own follow-up changes.

What changes

• ADDED: GET /events/:id/ics route — returns text/calendar; charset=utf-8 with a single-VEVENT VCALENDAR body for the requested event. Status, start, end, summary, description, location, and stable UID are all emitted from the existing event schema fields.
• ADDED: GET /events/:id/ics?with=rsvps variant — same VCALENDAR body plus one ATTENDEE line per RSVP row. Restricted to the event creator because the RSVP roster is private. Non-creators receive 403.
• ADDED: Content-Disposition: attachment; filename="event-<id>.ics" header on every success response.
• ADDED: RFC-5545 builder under src/ics/ics-builder/ — pure functions: buildVCalendar, foldLine (75-octet boundary per §3.1), escapeText (§3.3.11), formatDateUtc (UTC YYYYMMDDTHHMMSSZ), mapStatus (event status integer → CONFIRMED / CANCELLED / TENTATIVE), mapAttendeeStatus (RSVP going/maybe/not_going/invited → PARTSTAT ACCEPTED/TENTATIVE/DECLINED/NEEDS-ACTION).
• ADDED: ICS-export route module under src/routes/ics-export/ — createIcsExportRoutes({ eventRepository, rsvpRepository, clock, instruments }) returning an OpenAPIHono.
• ADDED: EVENTS_PLUGIN_CODES.ICS_INVALID_QUERY — Zod boundary failure on the with query parameter surfaces as HTTP 422 carrying this code.
• ADDED: Two OTel counters on the existing instruments bundle — events.ics.served_total{with} (incremented on every successful response, labelled with "none" or "rsvps") and events.ics.failed_total{reason} (incremented on every error response, labelled with "not_found", "forbidden", "unauthenticated", or "invalid_query").
• ADDED: Injectable Clock (@suaveplan/types) on the ICS route module so DTSTAMP is deterministic in tests; plugin defaults to Date.now.
• MODIFIED: EventsRoutesVariables — unchanged surface, the ICS routes reuse the same user slot set by the host auth middleware.
• MODIFIED: createEventsPlugin — onReady now mounts the ICS route module alongside createEventRoutes under the same basePath.

Source mapping

This change is a genesis-original feature; there is no upstream ICS code in ../suaveplan/packages/server/api-plugin-events/ to migrate. The requirement-to-source mapping is RFC-pinned, not code-pinned.

Requirement	Source	Notes
GET /events/:id/ics returns text/calendar; charset=utf-8 with a single VEVENT	RFC 5545 §3.4 (iCalendar object) + §3.6.1 (VEVENT component)	Body is one VCALENDAR with one VEVENT.
Stable UID per event	RFC 5545 §3.8.4.7	UID:${eventId}@suaveplan.events form — deterministic from the event id.
DTSTAMP in UTC YYYYMMDDTHHMMSSZ form	RFC 5545 §3.8.7.2 + §3.3.5	Sourced from injected Clock so tests are byte-stable.
DTSTART / DTEND in UTC YYYYMMDDTHHMMSSZ form	RFC 5545 §3.8.2.4 / §3.8.2.2 + §3.3.5	Events on this plugin are stored in UTC per the existing service contract (event schema timezone defaults "UTC"); VTIMEZONE blocks are explicitly scoped out for v0.1.
SUMMARY set to event title, escaped per §3.3.11	RFC 5545 §3.8.1.12 + §3.3.11	, ; \ newline are backslash-escaped.
DESCRIPTION set to event description if present, escaped per §3.3.11	RFC 5545 §3.8.1.5 + §3.3.11	Same escape rules as SUMMARY.
LOCATION set to event location.name if present, escaped	RFC 5545 §3.8.1.7 + §3.3.11	Free-form text. Address / coordinates not included in v0.1.
STATUS mapped from event status integer (0→TENTATIVE, 1→CONFIRMED, 2→CANCELLED)	RFC 5545 §3.8.1.11	TENTATIVE / CONFIRMED / CANCELLED are the only VEVENT-valid values.
SEQUENCE:0 always emitted (event schema has no revision counter)	RFC 5545 §3.8.7.4	Explicitly fixed at 0 until a revision field is added.
Line folding at 75 octets per §3.1 (continuation lines start with one space)	RFC 5545 §3.1	Byte-level fold; long DESCRIPTION lines are folded inside the builder.
CRLF (\r\n) line endings throughout	RFC 5545 §3.1	Every output line including the final BEGIN/END terminators.
?with=rsvps adds one ATTENDEE line per RSVP, with CN from user_name, PARTSTAT from the RSVP status, and the user id encoded as mailto:<id>@suaveplan.local when user_email is absent	RFC 5545 §3.8.4.1 (ATTENDEE) + §3.3.3 (CAL-ADDRESS)	mailto: placeholder satisfies CAL-ADDRESS while preserving the user id; the @suaveplan.local suffix is non-routable.
?with=rsvps requires creator (403 for non-creators)	Genesis security convention	RSVP roster is private; only the event owner may export it.
Content-Disposition: attachment; filename="event-<id>.ics"	RFC 6266 §4 (Content-Disposition)	Forces calendar-app download instead of inline render.
Typed EVENTS_PLUGIN_CODES.ICS_INVALID_QUERY for malformed with	AGENTS.md §2c	New code rather than reusing an unrelated existing code; thrown by ≥1 prod path (Zod boundary handler).
OTel counters events.ics.served_total{with} + events.ics.failed_total{reason}	CLAUDE.md "Observability" + genesis-wide policy	Real in-memory MeterProvider asserts emission.

Out of scope

The shipped proposal's full ## Out of scope list is preserved unchanged for the items NOT being addressed here:

• RRULE recurrence / RFC 5545 RRULE expansion — deferred to add-api-plugin-events-recurrence.
• VTIMEZONE blocks — events are stored UTC; tzid emission lands when @suaveplan/datetime adds the canonical IANA-to-VTIMEZONE mapper.
• Calendar-feed subscriptions (text/calendar polled at a stable URL with an Etag), push delivery via WebDAV / CalDAV, ticketing payloads (X-WR-* Apple extensions, structured ATTACH).
• Notification fan-out via @suaveplan/notification-channel — unchanged from the shipped proposal.
• Rate-limit / audit-log on the ICS endpoint — composed at the host level once api-plugin-rate-limit / api-plugin-audit ship.

Verification approach

• src/ics/ics-builder/ics-builder.test.ts — byte-level builder tests: fold at 75 octets, escape , ; \ newline, CRLF endings, UTC date format, status mapping, attendee PARTSTAT mapping, RSVP variant body.
• src/routes/ics-export/ics-export.test.ts — real Hono request: 200 on success, 401 on missing user, 404 on missing event, 403 when a non-creator requests ?with=rsvps, 422 on invalid with value, Content-Type and Content-Disposition header asserts, OTel counter assertions via real in-memory MeterProvider.
• src/otel/instruments.test.ts — extended to cover the two new counters.
• src/error-codes/error-codes.test.ts — extended to cover the new ICS_INVALID_QUERY code reachability.
• src/api-plugin-events.spec-conformance.test.ts — pins the new public symbols createIcsExportRoutes + buildVCalendar.

Migration impact

Additive only on the public surface. Consumers who already mount createEventsPlugin() automatically gain the GET /events/:id/ics endpoint on their existing basePath. No breaking changes to existing routes, schemas, or error codes.

Impact

Affected dependents

Run bunx turbo ls --filter=...@suaveplan/api-plugin-events to enumerate.

• No @suaveplan/* dependents exist on genesis today (verified by bunx turbo ls --filter=...@suaveplan/api-plugin-events — zero matches). Downstream apps that already mount the plugin gain the new endpoint automatically.