iCal endpoints

The iCal endpoints serve standards-compliant text/calendar feeds suitable for any calendar application that subscribes to an HTTPS URL.

GET /v1/starplan/ical/:semesterId

Returns a .ics document covering the next 365 days of occurrences for the given semester.

Behavior:

• Looks up the semester (404 if unknown) and its linked academic period.
• If the semester has no academicPeriodId yet (not linked to live timetable data), the feed is returned with no events instead of failing.
• Events are expanded via CourseKit's QueryService.getSchedule(), so recurrence is materialized — calendar clients see one VEVENT per occurrence rather than an RRULE.
• The calendar X-WR-CALNAME is "<programShortName> – <semesterName>" (or "StarPlan – <semesterName>" if the program lookup fails).
• Each VEVENT UID is "<eventId>-YYYY-MM-DD@hfu.digital", stable across sync cycles for the same occurrence date.

curl https://api.hfu.digital/v1/starplan/ical/<semesterId> \
  -o semester.ics

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//HFU Digital//StarPlan//EN
X-WR-CALNAME:AIB – Semester 3
BEGIN:VEVENT
UID:ev-abc-2026-04-22@hfu.digital
SUMMARY:Datenbanken 1
DTSTART:20260422T080000Z
DTEND:20260422T093000Z
…
END:VEVENT
…
END:VCALENDAR

GET /v1/starplan/ical/:semesterId/url

Resolves the upstream StarPlan iCal URL that the platform uses to fetch this semester's data, plus the upstream splan ids the cache row carries.

curl https://api.hfu.digital/v1/starplan/ical/<semesterId>/url

{
  "url":              "https://splan.hs-furtwangen.de/.../ical?lan=de&puid=<currentPu>&type=pg&pgid=<splanSemesterId>",
  "splanProgramId":   "<splanProgramId>",
  "splanSemesterId":  "<splanSemesterId>"
}

Returns 404 Not Found when:

• No StarPlanICalCache row exists for the semester yet (the sync job has not produced one), or
• No StarPlanConfig row exists at all (the platform has not been configured to talk to StarPlan).

This endpoint is primarily for debugging mismatches between upstream and the platform's mirror — most consumers should use the curated :semesterId feed above, not the raw upstream URL.

What the iCal endpoints are not

• Not personal feeds. Per-user iCal lives on the internal api/ service at /ical/:feedToken (token-only auth) and is generated through the website's "My calendar" settings. It is not part of the public StarPlan contract — its routes, headers, and feed shape may change without notice.
• Not real-time push. Calendar clients pull on their own schedule. If you need change push semantics, subscribe to a webhook.
• Not a horizon parameter. The 365-day window is fixed; the endpoint does not currently accept from/to query params. Use GET /v1/starplan/week/:week for arbitrary windows.