CourseKitStarPlan
StarPlanClient
Minimal HTTP client for StarPlan JSON + iCal endpoints
StarPlanClient is a thin HTTP wrapper around an institution's StarPlan instance. It exposes three reads — programs, semesters, and per-semester iCal feeds — and is intentionally framework-agnostic.
Usage
import { StarPlanClient } from '@hfu.digital/coursekit-starplan';
const client = new StarPlanClient({
baseUrl: 'https://splan.hs-furtwangen.de',
planningUnit: '5',
// locale: 'de',
// fetchImpl: customFetch,
// logger: { debug, warn, error },
// fallbackCharset: 'iso-8859-1',
});
const programs = await client.fetchPrograms();
const semesters = await client.fetchSemesters(programs[0].id);
const ical = await client.fetchIcal(semesters[0].id);Options — StarPlanClientOptions
| Option | Type | Default | Description |
|---|---|---|---|
baseUrl | string | required | Base URL of the institution's StarPlan instance (no trailing slash) |
planningUnit | string | required | Planning-unit identifier (pu / puid query param). HFU = '5' |
locale | string | 'de' | Locale passed as the lan query param |
fetchImpl | typeof fetch | global fetch | Override fetch for auth wrappers or test stubs |
logger | { debug?, warn?, error? } | {} | Optional diagnostic logger |
fallbackCharset | string | 'iso-8859-1' | Charset to assume when Content-Type omits one |
Methods
| Method | Returns | Description |
|---|---|---|
fetchPrograms() | Promise<StarPlanProgram[]> | All programs the planning unit exposes |
fetchSemesters(programId) | Promise<StarPlanSemester[]> | All semesters belonging to one program |
fetchIcal(semesterId) | Promise<string> | Raw iCal text for a semester |
getIcalUrl(semesterId) | string | Synchronously build the iCal URL (for caching layers, CDNs, etc.) |
Types
interface StarPlanProgram {
id: string;
name: string;
shortName?: string;
}
interface StarPlanSemester {
id: string;
programId: string;
name: string;
shortName?: string;
}Notes
- The client does not parse iCal — pass the returned string to
parseIcal. - Charset handling is done by
fetchWithCharset(a small utility re-exported by the package). StarPlan typically returnsiso-8859-1, which is auto-decoded. - For per-request authentication, wrap
fetchImpland inject your auth headers there.