feat(library-traffic): Library Traffic Averaging Endpoints

[estao1]

Description

Adds three new REST + GraphQL endpoints under /v2/rest/libraryTraffic for accessing historical occupancy data, alongside small consistency improvements to the existing snapshot endpoint.

New endpoints

Endpoint	Purpose
GET /history	Raw, cursor-paginated occupancy rows. Filter by location, date range, or academic term.
GET /history/aggregated	Time-bucketed averages (hour / day / week / month). Scope with (startDate + endDate) or (year + quarter). Range cap per granularity to bound response size.
GET /history/pattern	Recurring-slot pattern averages — e.g. "typical 2pm", "typical Monday". Granularity controls the cycle (24 hour-of-day buckets, 7 day-of-week, 10 week-of-term, 12 month).

Equivalent GraphQL queries (libraryTrafficHistory, libraryTrafficHistoryAggregated, libraryTrafficHistoryPattern) are exposed with matching shapes and @cacheControl(maxAge: 1800).

Implementation notes

• Calendar-term joins. year + quarter + period are convenience filters that resolve via calendarTerm. Raw and aggregated overwrite the date range from the term; pattern joins on timestamp BETWEEN periodStart AND periodEnd so each row gets its term context.
• Week-of-term. The pattern endpoint computes week buckets relative to the term's period start (floor((ts - periodStart)/604800) + 1), so week numbers are 1–10 (term-relative) rather than ISO weeks of the year. When granularity=week with an explicit quarter filter, rows are separated per-term and include year / quarter in the response; otherwise data is combined across terms.
• Composite cursor. Raw pagination uses the row's UUID as the cursor with a (timestamp > cursor.ts) OR (timestamp = cursor.ts AND id > cursor.id) predicate to keep pagination stable across duplicate timestamps (multiple locations scraped at the same second).
• Production cache. REST routes register productionCache({ maxAge: 1800 }), matching the 30-minute scraper cadence and the GraphQL @cacheControl TTLs.
• Error mapping. Invalid cursors and missing calendar terms throw HTTPException(400) instead of Error, so users get proper status codes instead of 500s.
• Empty results. Cursor pagination's natural end state is an empty page — the three new history endpoints return 200 with an empty array/items, matching the codebase convention (courses, instructors, enrollment-history). The pre-existing snapshot endpoint keeps its 400-on-empty behavior.

Related Issue

Closes #243

Motivation and Context

The existing snapshot endpoint only exposes current occupancy. Consumers (study-spot recommendations, dashboards, etc.) need historical views — both raw records for export/analysis and aggregated/pattern views for charts.

How Has This Been Tested?

Manually verified each endpoint via curl against a local dev server with backfilled history:

• GET /libraryTraffic — snapshot regression
• GET /libraryTraffic/history — pagination terminates correctly; composite cursor handles duplicate timestamps
• GET /libraryTraffic/history/aggregated with (startDate + endDate), (year + quarter), and missing both (422)
• GET /libraryTraffic/history/pattern with granularity=hour|day|week|month, with and without year/quarter filters, verifying week-of-term buckets are 1–10 and labels are clean ("2pm", "Monday", "Week 5")
• GraphQL queries via Yoga playground for the same matrix
• pnpm check:types and pnpm check:biome clean for apps/api

Screenshots (if appropriate):

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My code involves a change to the database schema.
• My code requires a change to the documentation.

[HwijungK]

#300 adds WEEK_MS to stdlib which we could use instead of a hardcoded number but its not merged yet... If it gets merged before reminders to add. if not, its whatever really

[estao1]

ill keep this open for now then

[HwijungK]

Pattern Endpoint fails