uExcelerate Calendar Service (1.0.0)

Returns events for a specific date pulled in real-time from every connected calendar (Google, Microsoft, Apple) and merged with internal session records. Public route — kept un-authenticated for legacy callers and debugging. Source: src/routes/calendarRoutes.ts

Creates a calendar event (1:1 or group coaching session) and fans it out across every connected calendar provider for the participants. Sends external-provider notifications to attendees per the connected calendar (Google / Microsoft / Apple) and updates the linked session record in the database. Owner can be ADMIN, COACH, or COACHEE; participant arrays are conditionally required based on owner. Source: src/routes/calendarRoutes.ts

Updates an existing event's metadata (title, time, attendees, location). If the event has external-provider IDs stored, syncs the change back to every connected calendar so the change is reflected in attendees' native calendar apps. Owner + participants are required when scheduling fields change. Source: src/routes/calendarRoutes.ts

Cancels an event and propagates the cancellation to every external calendar provider where it was created. Triggers cancellation notifications to attendees through each provider. Source: src/routes/calendarRoutes.ts

Approves a pending (manager-approval-required) session and pushes it out to all connected calendars. Used by the admin / manager approval flow when auto-approval is disabled. Source: src/routes/calendarRoutes.ts

Returns per-recipient invite delivery status (sent / bounced / complaint / delivered) for an event. Powered by SES delivery webhooks captured at /api/v1/ses/notifications. Source: src/routes/calendarRoutes.ts

Manually re-sends ICS invites for an event. By default re-targets only recipients whose previous delivery failed (bounced / complaint). Useful for recovering from transient SES failures. Source: src/routes/calendarRoutes.ts

Returns ad-hoc external email attendees attached to a session — guests that are not registered uExcelerate users. Source: src/routes/calendarRoutes.ts

Replaces the entire set of ad-hoc external attendees for a session and sends an ICS invite email to each new attendee. sessionType distinguishes coaching vs group session storage. Source: src/routes/calendarRoutes.ts

Returns the role list assigned to the authenticated user (some combination of Coach / Learner / Admin). Drives role-switching in the frontend. Source: src/routes/availabilityRoutes.ts

Retrieves the requesting user's weekly availability windows across all assigned roles. Used by the coach scheduling UI and the slot-finder algorithm. Source: src/routes/availabilityRoutes.ts

Replaces the authenticated user's weekly availability windows for a given role. Optional useDefaultAvailability=true falls back to organization defaults. Source: src/routes/availabilityRoutes.ts

Updates the authenticated user's preferred IANA timezone for a given role. Affects slot rendering and external-calendar event times. Source: src/routes/availabilityRoutes.ts

Returns bookable slots for a one-on-one session on a given date. Both coachId and learnerId are required; the intersection of their availability + free/busy + holiday calendars drives the slot color/availability. Source: src/routes/availabilityRoutes.ts

Array-based slot lookup used by the admin scheduling flow. Selection logic — 1 coach + 1 learner = intersection of both; 1 coach + many learners = coach availability only; many coaches + 1 learner = learner availability only; many + many = default availability windows. Source: src/routes/availabilityRoutes.ts

Returns a month view color-coded by availability, holidays, and existing events for a single coach/learner pairing. coachId is required when role=Coach; learnerId is required when role=Learner. Source: src/routes/availabilityRoutes.ts

Array-based month calendar for admin flows. Same coach/learner selection logic as /available-slots-admin. Source: src/routes/availabilityRoutes.ts

Returns user + role-specific holidays and unavailability blocks for a given month. Used to grey out dates in the calendar UI. Source: src/routes/availabilityRoutes.ts

Public legacy endpoint used by the legacy uex-server to check whether a user is free at a specific dateTime. Bypasses bearer auth for service-to-service calls. Source: src/routes/legacyRoutes.ts

Public legacy endpoint used by the legacy uex-server to check whether a user has completed calendar setup (any connection + any availability window). Source: src/routes/legacyRoutes.ts

Returns all holidays (personal time off) for the authenticated user across all roles. Source: src/routes/availabilityRoutes.ts

Creates a holiday / personal time off entry covering a date range (inclusive) for the authenticated user and a specific role. Source: src/routes/availabilityRoutes.ts

Deletes a holiday entry by its UUID. The owning user must match the authenticated user. Source: src/routes/availabilityRoutes.ts

Returns the OAuth 2.0 authorization URL the client should redirect the user to in order to grant calendar access. Supports google, outlook, and apple (CalDAV). Source: src/routes/calendarRoutes.ts

OAuth 2.0 callback from Google. Receives the authorization code, exchanges it for access + refresh tokens, and persists the calendar connection for the user identified by the signed state parameter. Not called directly by clients — registered as a redirect URI with Google. Source: src/routes/calendarRoutes.ts

OAuth 2.0 callback from Microsoft (Outlook / Microsoft 365). Receives the authorization code, exchanges it for tokens via the Graph identity platform, and persists the connection. Not called directly by clients — registered as a redirect URI with Microsoft. Source: src/routes/calendarRoutes.ts

Connects an Apple iCloud Calendar via CalDAV using an app-specific password. Validates the credentials against the supplied CalDAV server URL and stores the connection. Source: src/routes/calendarRoutes.ts

Service-to-service endpoint called by auth-service immediately after a user signs in with Google or Microsoft. Reuses the OAuth tokens already collected during login to auto-provision a calendar connection — the user does not see a second consent screen. Source: src/routes/calendarRoutes.ts

Lists every external calendar connection the authenticated user has active (Google, Microsoft, Apple). Used by the settings UI to render connection cards and by the event creator to decide which providers to fan out to. Source: src/routes/calendarRoutes.ts

Disconnects an external calendar connection by its UUID, revoking stored tokens. Future events for this user will no longer fan out to that provider. Source: src/routes/calendarRoutes.ts

Returns the authenticated user's calendar-connection and availability-setup completeness for a given role. Drives the onboarding checklist. Source: src/routes/statusRoutes.ts

Returns whether the authenticated user should see the calendar setup / welcome banner. Used by the frontend to drive a one-time onboarding nudge. Source: src/routes/calendarRoutes.ts

Marks the calendar welcome notification as seen for the authenticated user so it stops appearing on subsequent logins. Source: src/routes/calendarRoutes.ts

Amazon SES event webhook (bounces, complaints, deliveries) delivered via SNS. Body is the raw SES SNS notification payload. No bearer auth — verified via SNS signature (verification is currently TODO). Source: src/routes/calendarRoutes.ts

Lightweight health probe used by load balancers and container orchestrators. Returns 200 when the service process is up; does not verify DB or downstream connectivity. Source: src/server.ts