feat: explore public schedule sharing and class roster discovery

[SebastianBoehler]

Idea

Allow users to make their schedule public/shareable so schedules can be matched with other people. This could enable discovery features such as seeing who attends the same lecture or who is registered for a specific class.

Possible user value

• Match schedules with friends or classmates.
• See classmates connected to a lecture or class.
• Help students coordinate study groups, attendance, or shared planning.

Product questions

• Should sharing be opt-in per schedule, per class, or globally?
• What privacy controls are required before exposing schedule/class membership?
• Should visibility be limited to authenticated university users?
• Can class membership be inferred only from shared schedules, or should the API support an explicit roster-style view?

First implementation shape

• Add explicit schedule visibility settings.
• Add shareable schedule representation without exposing private metadata.
• Add matching/discovery endpoint or UI flow for shared lectures/classes.
• Handle empty or private states clearly instead of showing placeholder/mock data.

Captured from project memory request.

[SebastianBoehler]

Implementation notes after a quick repo pass:

What appears to exist already

• Authenticated Alma timetable extraction is already in place. AlmaClient.fetch_timetable_for_term() loads the Alma timetable page, resolves the selected term, reads the iCalendar export URL, parses/expands ICS events, and enriches events with room details (package/src/tue_api_wrapper/client.py).
• There is a richer timetable view contract with term/week/date filtering, visible range metadata, calendar feed URL, PDF support flags, and feed-token refresh support (package/src/tue_api_wrapper/alma_timetable_client.py, exposed through /api/alma/timetable/view, /api/alma/timetable/controls, and /api/alma/timetable/export-url/refresh).
• Course assignment grouping already exists via /api/alma/timetable/course-assignments. It groups timetable occurrences by course summary and tries to resolve Alma course metadata, detail URLs, CP totals, event type, and organization (package/src/tue_api_wrapper/alma_course_assignments_client.py). This is probably the best existing base for stable "same class" matching keys.
• Next.js already has an agenda/timetable UI with term/week/day/date controls, ICS export, feed refresh, PDF link, and credit summary display (nextjs/components/alma-timetable-panel.tsx, nextjs/components/alma-timetable-actions.tsx).
• Electron/Desktop already renders a timetable calendar from dashboard agenda data and can open the Alma export URL (desktop/src/components/dashboard/CalendarPage.tsx).
• iOS already keeps credentialed timetable fetching native: it logs in to Alma on-device, parses the iCalendar feed in Swift, caches upcoming lectures, and exposes widgets/live activities (ios/README.md, ios/Shared/Alma/AlmaClient.swift, ios/Shared/ICS/*).

What does not appear to exist yet

• No explicit schedule visibility model: no private, link-only, university-visible, per-course opt-in, or revocation state found.
• No shareable schedule contract that strips private fields and excludes Alma feed tokens/export URLs.
• No persistence layer for shared schedules or classmates/matching.
• No roster or discovery endpoint that answers "who else is in this lecture/class?".
• No UX flow for opting into schedule sharing or choosing which courses to expose.
• No duplicate/privacy policy around exposing names, course membership, rooms, or free/busy blocks.

Suggested implementation shape

1. Start with a Python contract, not UI-first. Add a typed shared schedule payload derived from existing timetable/course-assignment data, for example:

   • owner_id or pseudonymous local identifier
   • display_name only if user opted in
   • term_id, term_label
   • visibility: private | link_only | university_visible
   • shared_courses: normalized course keys derived from assignment metadata: course_number, normalized title, detail_url, term_id, and stable slot hashes
   • optional free_busy_blocks, if we want schedule matching without exposing course names
   • created_at, updated_at, expires_at, revoked_at

2. Treat Alma ICS/export URLs as secrets. They should never be copied into a public/shared schedule payload. Generate a sanitized representation from parsed occurrences and course assignments.

3. Keep credentialed upstream access local. Clients may fetch Alma locally, then explicitly publish only the sanitized snapshot after consent. A hosted registry can store shared snapshots, but it should never receive university credentials or session cookies.

4. Build MVP in two layers:

   • Backend/contract layer in this repo: build_shareable_schedule_snapshot(timetable, assignments, settings) plus tests proving private fields/export URLs are omitted.
   • Registry/API layer: POST /api/schedule-shares to create/update a share, DELETE /api/schedule-shares/{id} to revoke, GET /api/schedule-shares/{token} for link-only views, and GET /api/classes/{course_key}/members for opted-in classmates.

5. Matching should initially use coarse, reviewable keys:

   • primary: Alma detail URL or resolved course number + term
   • fallback: normalized summary + recurring weekday/time slot
   • avoid matching only by title when multiple groups/tutorials may share a name

6. Privacy defaults:

   • default state is private/off
   • per-course sharing should be possible before global schedule sharing
   • link-only schedules should use revocable opaque tokens
   • university-visible rosters should require authenticated university users
   • show counts before names: "4 classmates also share this class" is safer than exposing people immediately

Possible first acceptance criteria

• A user can preview exactly what would be shared before publishing.
• The shared payload contains no raw ICS, Alma export URL, credential-derived token, session URL, or private notes.
• User can choose all courses or selected courses for one term.
• User can revoke sharing and the public/link endpoint stops returning the schedule.
• Matching endpoint returns classmates for a course only when both sides opted into compatible visibility.
• Tests cover sanitized serialization, matching key generation, private/default state, and revocation behavior.

[SebastianBoehler]

Hey agents, whats your name. can you see my comment

[SebastianBoehler]

Yep, I can see your comment. I’m Codex in this runtime.

To make this issue implementation-ready, I’d separate the product decision from the first technical slice:

Clarifying questions

1. What is the first target use case: share my full schedule with a friend, discover classmates in one class, or show aggregate overlap counts first?
2. Should MVP sharing be link-only only, or should university-visible rosters be in scope from day one?
3. What identity should classmates see: display name, GitHub/StudyOS handle, pseudonymous user id, or count-only until both users opt in?
4. Should sharing be per-term and per-course by default? I’d avoid a global “make all future schedules public” switch for the first version.
5. Where should shared snapshots live for MVP: local-only/exported JSON, a lightweight StudyOS registry, or GitHub-backed issue/discussion prototype? The registry path needs a clearer privacy/retention decision.

Likely overlap / duplicates

I don’t see a direct duplicate among the current issues. The nearest adjacent issue is #17, but that is about local computer-use agent backend direction. It could inform how credentialed Alma fetching stays local, but it should not absorb this feature. This issue should remain about sanitized schedule-sharing contracts, consent, and discovery behavior.

Suggested scope boundary for first PR

Start with the wrapper contract only, not roster UI or hosted storage:

• derive a shareable schedule snapshot from existing timetable/course-assignment data
• define visibility/settings models with private-by-default behavior
• generate stable course matching keys from detail_url / course number + term / slot fallback
• prove the shared payload never includes raw ICS, Alma export URLs, session URLs, cookies, credentials, or private notes
• add tests for sanitization, matching keys, selected-course sharing, and private defaults

That would give later clients and any registry/API a safe contract to build on.

Proposed acceptance criteria

• A user can preview the exact sanitized payload before publishing or exporting it.
• Default state is private and produces no shareable roster/discovery output.
• A user can share selected courses for one term without sharing every timetable item.
• Shared course entries include stable matching keys plus human-readable course metadata where available.
• Alma feed/export URLs, raw ICS content, session-derived URLs, credentials, and private notes are absent from serialized shared payloads.
• Classmate discovery only matches users who both opted into compatible visibility for the same course key.
• Revocation/expiry is represented in the contract, even if storage is deferred to a later PR.
• Focused tests cover serialization sanitization, key generation, selected-course filtering, default-private behavior, and revoked/expired snapshots.

Once those questions are answered, I’d treat the first implementation as a Python package/test PR. UI, link-token storage, and university-visible roster endpoints can follow as separate issues/PRs because they carry more privacy and operational decisions.

[SebastianBoehler]

hey codex, can you reply and tell me a developer meme a funny one

[SebastianBoehler]

Developer meme of the day:

Why do programmers prefer dark mode?
Because light attracts bugs.

Back to issue-shaping mode when you want it. 🙂