Contract: Calendar Visual and Appointment Feed

Navigation

• /calendar: visual calendar; default month on desktop, responsive safe alternative on narrow viewports.
• /calendar/settings: Google/Microsoft connection management and OAuth callback feedback.
• OAuth success/failure redirects MUST target /calendar/settings.

Appointment feed

GET /api/appointments?from=<ISO>&to=<ISO>&timezone=<IANA>

Success — 200

{
  "appointments": [
    {
      "id": "uuid",
      "patientId": "uuid",
      "patientDisplayName": "Nome exibível",
      "startsAt": "2026-08-10T12:00:00.000Z",
      "durationMinutes": 50,
      "timezone": "America/Sao_Paulo",
      "status": "scheduled",
      "syncStatus": "pending"
    }
  ]
}

• Sorted by startsAt ASC, id ASC.
• Includes only the authenticated owner and from <= startsAt < to.
• Range limit: 42 days.
• No clinical content or sensitive patient attributes.

Errors

• 400 invalid_range: invalid ISO instant, from >= to, missing timezone or range over 42 days.
• 400 invalid_timezone: unknown IANA timezone.
• 401 authentication_required: no valid session.
• Unexpected errors follow the safe error envelope with request identifier.

UI states

• Loading: skeleton/announcement without clearing period controls.
• Empty: explicit no-appointments state and create action.
• Error: safe message and retry retaining current period/view.
• Loaded: month/week grid; overlaps remain separately focusable.
• Mobile fallback: chronological list grouped by local date.

Accessibility

• Previous, next, today and view selectors have accessible names.
• Events are reachable and activatable by keyboard.
• Current day, selected view and cancelled status are not color-only.
• Focus returns predictably after detail/create dialogs or navigation.