@rokoyfa/calendar 1.0.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +85 -3
- package/api/openapi.yaml +359 -3
- package/dist-lib/cdn/calendar-widget.js +11 -7
- package/dist-lib/cdn/calendar-widget.js.map +1 -1
- package/dist-lib/cdn/de-BjzK4Pgn.js +2 -0
- package/dist-lib/cdn/de-BjzK4Pgn.js.map +1 -0
- package/dist-lib/cdn/es-TA5DvEsw.js +2 -0
- package/dist-lib/cdn/es-TA5DvEsw.js.map +1 -0
- package/dist-lib/cdn/fr-Dx-nmhQ7.js +2 -0
- package/dist-lib/cdn/fr-Dx-nmhQ7.js.map +1 -0
- package/dist-lib/cdn/it-D_2eA3dT.js +2 -0
- package/dist-lib/cdn/it-D_2eA3dT.js.map +1 -0
- package/dist-lib/cdn/nl-dC1zae2Z.js +2 -0
- package/dist-lib/cdn/nl-dC1zae2Z.js.map +1 -0
- package/dist-lib/cdn/pl-9TYRPoy1.js +2 -0
- package/dist-lib/cdn/pl-9TYRPoy1.js.map +1 -0
- package/dist-lib/cdn/pt-CvBN-qx1.js +2 -0
- package/dist-lib/cdn/pt-CvBN-qx1.js.map +1 -0
- package/dist-lib/cdn/rolldown-runtime-CrjiCqGf.js +1 -0
- package/dist-lib/cdn/src-l8Q4aJRr.js +12 -0
- package/dist-lib/cdn/src-l8Q4aJRr.js.map +1 -0
- package/dist-lib/npm/{de-CCzGjeTd.js → de-Cuz-uz3s.js} +133 -8
- package/dist-lib/npm/de-Cuz-uz3s.js.map +1 -0
- package/dist-lib/npm/{es-Ciaf66rH.js → es-BnRzdU90.js} +133 -8
- package/dist-lib/npm/es-BnRzdU90.js.map +1 -0
- package/dist-lib/npm/{fr-CAqNm10Z.js → fr-B-nmvStg.js} +133 -8
- package/dist-lib/npm/fr-B-nmvStg.js.map +1 -0
- package/dist-lib/npm/index.js +5632 -2473
- package/dist-lib/npm/index.js.map +1 -1
- package/dist-lib/npm/{it-Cqqdu2ua.js → it-DMTpE4GO.js} +133 -8
- package/dist-lib/npm/it-DMTpE4GO.js.map +1 -0
- package/dist-lib/npm/{nl-CkchSA8q.js → nl-DQkyEt9Z.js} +133 -8
- package/dist-lib/npm/nl-DQkyEt9Z.js.map +1 -0
- package/dist-lib/npm/{pl-CCBDUr8k.js → pl-CcjU41yx.js} +133 -8
- package/dist-lib/npm/pl-CcjU41yx.js.map +1 -0
- package/dist-lib/npm/{pt-DucaCaoY.js → pt-Dulais2f.js} +133 -8
- package/dist-lib/npm/pt-Dulais2f.js.map +1 -0
- package/dist-lib/npm/types/components/Button.d.ts +1 -1
- package/dist-lib/npm/types/components/Icons.d.ts +5 -0
- package/dist-lib/npm/types/components/SegmentedControl.d.ts +2 -2
- package/dist-lib/npm/types/components/SegmentedField.d.ts +2 -11
- package/dist-lib/npm/types/components/StatusMessage.d.ts +0 -1
- package/dist-lib/npm/types/components/Tabs.d.ts +3 -1
- package/dist-lib/npm/types/config/routes.d.ts +1 -1
- package/dist-lib/npm/types/context/HostContext.d.ts +2 -1
- package/dist-lib/npm/types/context/TimeZoneContext.d.ts +3 -0
- package/dist-lib/npm/types/data/restDataSource.d.ts +4 -1
- package/dist-lib/npm/types/data/tenantDataSource.d.ts +3 -1
- package/dist-lib/npm/types/data/types.d.ts +3 -1
- package/dist-lib/npm/types/features/authorization/hooks/useAuth.d.ts +2 -1
- package/dist-lib/npm/types/features/authorization/hooks/useRedirectTarget.d.ts +4 -0
- package/dist-lib/npm/types/features/authorization/index.d.ts +1 -1
- package/dist-lib/npm/types/features/authorization/repositories/HostTokenAuthRepository.d.ts +2 -0
- package/dist-lib/npm/types/features/authorization/repositories/RemoteAuthRepository.d.ts +2 -0
- package/dist-lib/npm/types/features/authorization/types/auth.d.ts +3 -0
- package/dist-lib/npm/types/features/calendar/components/Calendar.d.ts +14 -1
- package/dist-lib/npm/types/features/calendar/components/CalendarHeader.d.ts +2 -1
- package/dist-lib/npm/types/features/calendar/components/DayColumn.d.ts +2 -1
- package/dist-lib/npm/types/features/calendar/components/EventLinks.d.ts +7 -0
- package/dist-lib/npm/types/features/calendar/components/EventLocation.d.ts +3 -0
- package/dist-lib/npm/types/features/calendar/components/EventSearchModal.d.ts +9 -0
- package/dist-lib/npm/types/features/calendar/components/EventTitle.d.ts +2 -1
- package/dist-lib/npm/types/features/calendar/components/MiniMonth.d.ts +2 -1
- package/dist-lib/npm/types/features/calendar/components/UndoNotice.d.ts +7 -0
- package/dist-lib/npm/types/features/calendar/constants/views.d.ts +3 -0
- package/dist-lib/npm/types/features/calendar/context/CurrentUserContext.d.ts +3 -0
- package/dist-lib/npm/types/features/calendar/context/HolidaysContext.d.ts +4 -0
- package/dist-lib/npm/types/features/calendar/hooks/useAttendeeCandidates.d.ts +3 -0
- package/dist-lib/npm/types/features/calendar/hooks/useEventDrag.d.ts +1 -1
- package/dist-lib/npm/types/features/calendar/hooks/useEventSearch.d.ts +7 -0
- package/dist-lib/npm/types/features/calendar/hooks/useEventSource.d.ts +2 -1
- package/dist-lib/npm/types/features/calendar/hooks/usePressDrag.d.ts +23 -0
- package/dist-lib/npm/types/features/calendar/hooks/useSegmentAttributes.d.ts +15 -0
- package/dist-lib/npm/types/features/calendar/hooks/useSlotSelection.d.ts +1 -4
- package/dist-lib/npm/types/features/calendar/index.d.ts +1 -2
- package/dist-lib/npm/types/features/calendar/types/editor.d.ts +3 -0
- package/dist-lib/npm/types/features/calendar/types/view.d.ts +1 -1
- package/dist-lib/npm/types/features/calendar/utils/eventDrag.d.ts +0 -1
- package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +0 -3
- package/dist-lib/npm/types/features/calendar/utils/search.d.ts +11 -0
- package/dist-lib/npm/types/features/calendars/components/ShowInPersonalSwitch.d.ts +4 -0
- package/dist-lib/npm/types/features/calendars/components/settings/ExchangeSection.d.ts +4 -0
- package/dist-lib/npm/types/features/calendars/components/settings/SubscribeSection.d.ts +4 -0
- package/dist-lib/npm/types/features/calendars/context/CalendarsProvider.d.ts +2 -1
- package/dist-lib/npm/types/features/calendars/index.d.ts +2 -2
- package/dist-lib/npm/types/features/calendars/repositories/LocalCalendarRepository.d.ts +12 -1
- package/dist-lib/npm/types/features/calendars/repositories/RemoteCalendarRepository.d.ts +3 -0
- package/dist-lib/npm/types/features/calendars/types/calendar.d.ts +5 -1
- package/dist-lib/npm/types/features/calendars/utils/activeCalendarStorage.d.ts +2 -0
- package/dist-lib/npm/types/features/calendars/utils/permissions.d.ts +1 -2
- package/dist-lib/npm/types/features/chat/components/ChatPanel.d.ts +8 -0
- package/dist-lib/npm/types/features/chat/components/ChatProvider.d.ts +13 -0
- package/dist-lib/npm/types/features/chat/components/UnreadBadge.d.ts +4 -0
- package/dist-lib/npm/types/features/chat/context/ChatContext.d.ts +14 -0
- package/dist-lib/npm/types/features/chat/hooks/useChatMessages.d.ts +13 -0
- package/dist-lib/npm/types/features/chat/hooks/useChatUnread.d.ts +7 -0
- package/dist-lib/npm/types/features/chat/index.d.ts +4 -0
- package/dist-lib/npm/types/features/chat/utils/time.d.ts +2 -0
- package/dist-lib/npm/types/features/events/components/AttendeesField.d.ts +15 -0
- package/dist-lib/npm/types/features/events/components/EventModal.d.ts +19 -3
- package/dist-lib/npm/types/features/events/components/LinksField.d.ts +8 -0
- package/dist-lib/npm/types/features/events/components/ReminderField.d.ts +6 -0
- package/dist-lib/npm/types/features/events/hooks/useEvents.d.ts +6 -3
- package/dist-lib/npm/types/features/events/index.d.ts +3 -1
- package/dist-lib/npm/types/features/events/utils/icalExchange.d.ts +11 -0
- package/dist-lib/npm/types/features/events/utils/undo.d.ts +7 -0
- package/dist-lib/npm/types/features/holidays/components/HolidaySettings.d.ts +1 -0
- package/dist-lib/npm/types/features/holidays/hooks/useHolidays.d.ts +3 -0
- package/dist-lib/npm/types/features/holidays/index.d.ts +2 -0
- package/dist-lib/npm/types/features/holidays/utils/holidayLibrary.d.ts +8 -0
- package/dist-lib/npm/types/features/preferences/components/NotificationSettings.d.ts +3 -0
- package/dist-lib/npm/types/features/preferences/index.d.ts +1 -0
- package/dist-lib/npm/types/features/reminders/ReminderNotices.d.ts +1 -0
- package/dist-lib/npm/types/features/reminders/useReminders.d.ts +2 -0
- package/dist-lib/npm/types/features/storage/hooks/useStorage.d.ts +1 -2
- package/dist-lib/npm/types/features/storage/index.d.ts +4 -2
- package/dist-lib/npm/types/features/storage/repositories/LocalEventRepository.d.ts +2 -1
- package/dist-lib/npm/types/features/storage/repositories/RemoteChatRepository.d.ts +18 -0
- package/dist-lib/npm/types/features/storage/repositories/RemoteEventRepository.d.ts +5 -2
- package/dist-lib/npm/types/features/storage/repositories/RemoteHolidayRepository.d.ts +7 -0
- package/dist-lib/npm/types/features/storage/types/storage.d.ts +30 -2
- package/dist-lib/npm/types/hooks/useDebouncedValue.d.ts +1 -0
- package/dist-lib/npm/types/hooks/useForm.d.ts +5 -0
- package/dist-lib/npm/types/hooks/useFormState.d.ts +5 -0
- package/dist-lib/npm/types/hooks/useKeyboardShortcuts.d.ts +3 -0
- package/dist-lib/npm/types/hooks/useLocationUrl.d.ts +1 -0
- package/dist-lib/npm/types/i18n/format.d.ts +1 -0
- package/dist-lib/npm/types/i18n/index.d.ts +0 -1
- package/dist-lib/npm/types/i18n/locale.d.ts +0 -2
- package/dist-lib/npm/types/i18n/messages/en/calendar.d.ts +17 -0
- package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +25 -0
- package/dist-lib/npm/types/i18n/messages/en/core.d.ts +2 -0
- package/dist-lib/npm/types/i18n/messages/en/events.d.ts +63 -3
- package/dist-lib/npm/types/i18n/messages/en/index.d.ts +128 -3
- package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +21 -0
- package/dist-lib/npm/types/i18n/messages/index.d.ts +128 -3
- package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
- package/dist-lib/npm/types/lib/config.d.ts +6 -2
- package/dist-lib/npm/types/lib/defaults.d.ts +2 -0
- package/dist-lib/npm/types/lib/element.d.ts +1 -1
- package/dist-lib/npm/types/lib/index.d.ts +4 -3
- package/dist-lib/npm/types/pages/RespondPage.d.ts +1 -0
- package/dist-lib/npm/types/utils/api.d.ts +4 -5
- package/dist-lib/npm/types/utils/apiError.d.ts +0 -2
- package/dist-lib/npm/types/utils/appError.d.ts +2 -1
- package/dist-lib/npm/types/utils/chat.d.ts +44 -0
- package/dist-lib/npm/types/utils/color.d.ts +0 -1
- package/dist-lib/npm/types/utils/date.d.ts +0 -6
- package/dist-lib/npm/types/utils/event.d.ts +41 -5
- package/dist-lib/npm/types/utils/holidays.d.ts +18 -0
- package/dist-lib/npm/types/utils/ical.d.ts +11 -0
- package/dist-lib/npm/types/utils/location.d.ts +4 -0
- package/dist-lib/npm/types/utils/notifications.d.ts +3 -0
- package/dist-lib/npm/types/utils/preferences.d.ts +7 -1
- package/dist-lib/npm/types/utils/recurrence.d.ts +3 -4
- package/dist-lib/npm/types/utils/reminders.d.ts +13 -0
- package/dist-lib/npm/types/utils/timeZone.d.ts +1 -1
- package/package.json +4 -1
- package/dist-lib/cdn/de-BPZBZXaZ.js +0 -2
- package/dist-lib/cdn/de-BPZBZXaZ.js.map +0 -1
- package/dist-lib/cdn/es-DsIckdik.js +0 -2
- package/dist-lib/cdn/es-DsIckdik.js.map +0 -1
- package/dist-lib/cdn/fr-DWAs3O6J.js +0 -2
- package/dist-lib/cdn/fr-DWAs3O6J.js.map +0 -1
- package/dist-lib/cdn/it-CbhjxqIb.js +0 -2
- package/dist-lib/cdn/it-CbhjxqIb.js.map +0 -1
- package/dist-lib/cdn/nl-mjTHznX5.js +0 -2
- package/dist-lib/cdn/nl-mjTHznX5.js.map +0 -1
- package/dist-lib/cdn/pl-CXT0jb2D.js +0 -2
- package/dist-lib/cdn/pl-CXT0jb2D.js.map +0 -1
- package/dist-lib/cdn/pt-D0oXlVdU.js +0 -2
- package/dist-lib/cdn/pt-D0oXlVdU.js.map +0 -1
- package/dist-lib/npm/de-CCzGjeTd.js.map +0 -1
- package/dist-lib/npm/es-Ciaf66rH.js.map +0 -1
- package/dist-lib/npm/fr-CAqNm10Z.js.map +0 -1
- package/dist-lib/npm/it-Cqqdu2ua.js.map +0 -1
- package/dist-lib/npm/nl-CkchSA8q.js.map +0 -1
- package/dist-lib/npm/pl-CCBDUr8k.js.map +0 -1
- package/dist-lib/npm/pt-DucaCaoY.js.map +0 -1
- package/dist-lib/npm/types/hooks/useArrowKeyNavigation.d.ts +0 -6
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,32 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@rokoyfa/calendar`. Versions follow [Semantic Versioning](https://semver.org/). From 1.0 on, breaking changes to props, attributes, DOM events, exported types, the data adapter and the REST contract only come with a new major version.
|
|
4
4
|
|
|
5
|
+
## Unreleased
|
|
6
|
+
|
|
7
|
+
- The event dialog is split into tabs: General, Repeat, Attendees and Details
|
|
8
|
+
- Locations and links: optional `location` and up to 10 website or other links in the Details tab. Locations are shown in the calendar, links too when the event is tall enough (with a globe icon, open in a new tab), both are searchable and exported to iCalendar
|
|
9
|
+
- Reminders: choose in the event dialog how long before an event to be reminded. Shown as a browser notification or a notice in the calendar while it is open. Reminders are personal per user
|
|
10
|
+
- Search over title, location, description and links with jump to the event. Custom adapters can implement `search`, otherwise the component searches the last and next year
|
|
11
|
+
- iCalendar export and import (.ics) in the calendar settings. Importing again updates events with the same `uid`, recurring events, exceptions, reminders and attendees are kept
|
|
12
|
+
- Attendees in team calendars with responses yes, maybe and no, plus a button to invite all members at once. Unanswered events are striped, declined ones crossed out
|
|
13
|
+
- The calendar you were in is restored after a reload
|
|
14
|
+
- Chat per event in team calendars (one per occurrence for recurring events) with live updates over a WebSocket, unread badges, edit and delete, moderation for owners, admins and managers, and optional emails to attendees with a link straight into the chat
|
|
15
|
+
- Public holidays for over 200 countries and their regions, computed in the browser with date-holidays (loaded only when shown) or delivered by your backend (`holiday-source="backend"`, `GET /holidays`). Region from the new `holidays` attribute, the language, or the user's setting
|
|
16
|
+
- Calendar subscriptions: a secret link per user and calendar for Google Calendar, Outlook or Apple Calendar (`/calendars/:id/feed`, `/feeds/:token.ics`)
|
|
17
|
+
- Email settings (invitations, changes, reminders) in a new Notifications tab, and a page that saves the yes / maybe / no answer from an invitation email without signing in (`POST /events/respond`)
|
|
18
|
+
- Members without edit rights can set their own reminders on any event (`PUT /events/:id/reminders`)
|
|
19
|
+
- Locations open in Google Maps from the dialog, the calendar grid and the reply page. Another map service can be set with `map-url`, locations that are web addresses open directly
|
|
20
|
+
- Duplicate events from the event dialog
|
|
21
|
+
- Undo after deleting, moving or resizing events (notice at the bottom or Ctrl+Z / ⌘Z). Single events are deleted without a confirmation, recurring ones still ask which events
|
|
22
|
+
- Keyboard shortcuts: `T` today, `N` new event, `/` search, `D` `W` `M` `Y` views. The header tooltips show them
|
|
23
|
+
- Time zone setting: automatic (zone from the host, otherwise the system, recommended) or a fixed zone. Events are shown in it and new events start in it
|
|
24
|
+
- Search results show times in your own time zone and open events that move to another day there
|
|
25
|
+
- New event fields `uid`, `location`, `links`, `reminders`, `attendees`, preference `timeZone`, new endpoints `GET /events/search` and `POST /events/:id/response`. Older events and backends without them keep working
|
|
26
|
+
|
|
27
|
+
## 1.1.0 – 2026-11-11
|
|
28
|
+
|
|
29
|
+
- Arrow keys switch to the previous or next day, week, month or year also right after loading and after closing a dialog, not only after clicking into the calendar. With several calendars on a page, the last used one reacts
|
|
30
|
+
|
|
5
31
|
## 1.0.0 – 2026-11-11
|
|
6
32
|
|
|
7
33
|
First stable release. The public API is now frozen in the sense of SemVer.
|
package/README.md
CHANGED
|
@@ -55,7 +55,10 @@ document.querySelector('calendar-widget').addEventListener('event-create', (e) =
|
|
|
55
55
|
| `messages` | property | – | Own texts per language, see below |
|
|
56
56
|
| `theme` | `theme` | system | `light`, `dark` |
|
|
57
57
|
| `initialView` | `initial-view` | user setting | `day`, `week`, `month`, `year` |
|
|
58
|
-
| `timeZone` | `time-zone` | browser | IANA zone the calendar is shown in, e.g. `Europe/Berlin
|
|
58
|
+
| `timeZone` | `time-zone` | browser | IANA zone the calendar is shown in, e.g. `Europe/Berlin`. New events start in it. A zone the user picks in the settings takes precedence |
|
|
59
|
+
| `holidays` | `holidays` | from `locale` | Public holidays to show: country or region code such as `DE`, `DE-NW`, `AT`, `US-CA`, or `off`. Users can override it in the settings |
|
|
60
|
+
| `mapUrl` | `map-url` | Google Maps | Map service for locations, with `{query}` for the place, e.g. `https://www.openstreetmap.org/search?query={query}` or `https://maps.apple.com/?q={query}` |
|
|
61
|
+
| `holidaySource` | `holiday-source` | `library` | `library` computes holidays in the browser, `backend` asks your backend (`GET /holidays`) and falls back to the library |
|
|
59
62
|
| `storageMode` | `storage-mode` | `local` | `local` or `remote` |
|
|
60
63
|
| `apiBaseUrl` | `api-base-url` | `/api` | Base URL of your backend |
|
|
61
64
|
| `features` | `auth`, `teams` | auth off, teams on | `teams="false"` turns team features off |
|
|
@@ -76,6 +79,55 @@ The CDN build loads languages other than English on demand from files next to `c
|
|
|
76
79
|
|
|
77
80
|
**Demo:** [`demo/cdn.html`](demo/cdn.html) shows local mode with an event log, a dark German month view and a compact widget. Download it and open it in a browser, it loads the published package from jsDelivr.
|
|
78
81
|
|
|
82
|
+
## Calendar subscriptions
|
|
83
|
+
|
|
84
|
+
With a backend that serves `/calendars/:id/feed` and `/feeds/:token.ics`, every signed-in user can subscribe to a calendar in another calendar app and see its events there, for example on the phone. Users get the link in the calendar settings: **Import & export** tab for team calendars, on the settings page for the personal calendar → **Subscribe** → **Create subscription link**. They can copy the link or open it in their calendar app.
|
|
85
|
+
|
|
86
|
+
- The subscription is **read-only**. Changes made in the other app do not come back.
|
|
87
|
+
- The link is **personal and secret**: it contains the user's own reminders, and anyone who has it can see all events of the calendar. **Create new link** turns the old one off, **End subscription** removes it.
|
|
88
|
+
- It stops working when the user leaves the calendar.
|
|
89
|
+
|
|
90
|
+
### Adding the link in calendar apps
|
|
91
|
+
|
|
92
|
+
| App | Steps |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| **Apple Calendar on Mac** | **Open in calendar app** in the settings, or *File → New Calendar Subscription…*, paste the link, **Subscribe**. Set *Auto-refresh* and choose *iCloud* as location so the calendar also appears on iPhone and iPad. |
|
|
95
|
+
| **Apple Calendar on iPhone / iPad** | **Open in calendar app** in the settings, or *Settings → Apps → Calendar → Calendar Accounts → Add Account → Other → Add Subscribed Calendar* (older iOS: *Settings → Calendar → Accounts*), paste the link as server, **Next**, **Save**. |
|
|
96
|
+
| **Google Calendar** | Only in the browser at calendar.google.com: next to *Other calendars* click **+** → **From URL**, paste the link, **Add calendar**. It then also shows in the Google Calendar apps on Android and iPhone. |
|
|
97
|
+
| **Outlook.com / Outlook on the web / new Outlook** | *Calendar → Add calendar → Subscribe from web*, paste the link, give it a name, **Import**. |
|
|
98
|
+
| **Classic Outlook for Windows** | *Home → Add Calendar → From Internet…* (in some versions *Open Calendar → From Internet*), paste the link, **OK**, confirm with **Yes**. |
|
|
99
|
+
| **Thunderbird** | *New Calendar → On the Network*, paste the link, choose the iCalendar (ICS) format. |
|
|
100
|
+
|
|
101
|
+
Menu names change between app versions. If a path does not match, look for “subscribe”, “from URL” or “from internet”.
|
|
102
|
+
|
|
103
|
+
### How quickly changes show up
|
|
104
|
+
|
|
105
|
+
A subscription is not live: the app downloads the whole calendar again at intervals that the app decides. Changes made in this calendar therefore appear with a delay:
|
|
106
|
+
|
|
107
|
+
| App | Refresh |
|
|
108
|
+
| --- | --- |
|
|
109
|
+
| Apple Calendar on Mac | Adjustable per subscription, from every 5 minutes to weekly (right-click the calendar → *Get Info* → *Auto-refresh*). *View → Refresh Calendars* (⌘R) refreshes right away. |
|
|
110
|
+
| Apple Calendar on iPhone / iPad | Follows *Fetch New Data* (*Settings → Apps → Calendar → Calendar Accounts → Fetch New Data*). Choose *Every 15 Minutes* or *Hourly*. Subscriptions have no push. A subscription added on the Mac with location *iCloud* is refreshed by iCloud. |
|
|
111
|
+
| Google Calendar | Google's own schedule, usually several hours, sometimes up to a day. Cannot be changed. |
|
|
112
|
+
| Outlook.com / web / new Outlook | Microsoft's own schedule, roughly every 3 hours, sometimes more than 24 hours. Cannot be changed. |
|
|
113
|
+
| Classic Outlook for Windows | Follows the update limit in the feed (one hour here) and Outlook's send/receive settings. |
|
|
114
|
+
|
|
115
|
+
The feed asks clients to reload every hour (`REFRESH-INTERVAL` and `X-PUBLISHED-TTL`), but most apps follow their own settings. For changes that must show up immediately, users should open this calendar directly. Two-way sync with near-instant updates would need a CalDAV server, which this component does not cover.
|
|
116
|
+
|
|
117
|
+
## Event chat
|
|
118
|
+
|
|
119
|
+
Events in team calendars have a **Chat** tab: every member can read and write, edit and delete their own messages, and owners, admins and managers (`manage_calendars`) can delete any message. Recurring events have one chat per occurrence. A detached occurrence keeps the chat of its original date. The calendar shows unread messages as a red badge on the event and in the tab title, and attendees can get an email about new messages (`emailChat`, on by default, at most one email per chat every few minutes).
|
|
120
|
+
|
|
121
|
+
Messages go over REST (see the OpenAPI file, tag *Chat*). New, edited and deleted messages arrive live over a WebSocket:
|
|
122
|
+
|
|
123
|
+
- **Address:** `{apiBaseUrl}/chat/socket` with `ws://` or `wss://`, derived from `apiBaseUrl` (relative addresses use the page's host). With `tenant` the tenant is added as `?tenant=…`, because browsers cannot set headers on WebSockets. Custom data sources can pass `chatSocketUrl` to `restDataSource`.
|
|
124
|
+
- **Sign-in:** the session cookie is sent with the handshake. Check the `Origin` header against the allowed origins and answer `401` without a session.
|
|
125
|
+
- **Server → client** (JSON text frames): `{ "type": "message.created" | "message.updated", "message": ChatMessage }` and `{ "type": "message.deleted", "id", "calendarId", "eventId", "occurrenceDate" }`, sent to every connected member of the calendar's team.
|
|
126
|
+
- **Client → server:** only `{ "type": "ping" }` every 25 seconds, answer with `{ "type": "pong" }` or ignore it.
|
|
127
|
+
- The component reconnects with growing pauses (1 to 30 seconds) and reloads the open chat and the unread counts after reconnecting, so a lost connection only delays messages.
|
|
128
|
+
|
|
129
|
+
Emails link to the host page with `?calendar=…&event=…&date=…&tab=chat`, which opens the event with the chat.
|
|
130
|
+
|
|
79
131
|
## Building your own backend
|
|
80
132
|
|
|
81
133
|
The full contract is [`api/openapi.yaml`](api/openapi.yaml) (OpenAPI 3.1, also shipped as `@rokoyfa/calendar/openapi.yaml`). The essentials:
|
|
@@ -91,7 +143,10 @@ type CalendarEvent = EventInput & {
|
|
|
91
143
|
}
|
|
92
144
|
|
|
93
145
|
type EventInput = {
|
|
146
|
+
uid: string // stable id for iCalendar, shared by a series and its detached events
|
|
94
147
|
title: string // 1–100 chars
|
|
148
|
+
location: string // max 200 chars, '' if none
|
|
149
|
+
links: EventLink[] // up to 10 http(s) links
|
|
95
150
|
startDate: string // 'YYYY-MM-DD'
|
|
96
151
|
start: string // 'HH:mm' in timeZone
|
|
97
152
|
endDate: string // inclusive for all-day events
|
|
@@ -104,8 +159,14 @@ type EventInput = {
|
|
|
104
159
|
excludedDates: string[] // occurrences removed from a series
|
|
105
160
|
seriesId: string | null // set on an occurrence detached from a series
|
|
106
161
|
originalDate: string | null // its original date in that series
|
|
162
|
+
reminders: number[] // minutes before the start, per user (see below)
|
|
163
|
+
attendees: Attendee[]
|
|
107
164
|
}
|
|
108
165
|
|
|
166
|
+
type Attendee = { email: string; name: string; status: 'needsAction' | 'accepted' | 'tentative' | 'declined' }
|
|
167
|
+
|
|
168
|
+
type EventLink = { url: string; label: string } // url max 2000 chars, label max 100 chars, '' if none
|
|
169
|
+
|
|
109
170
|
type Recurrence = {
|
|
110
171
|
frequency: 'daily' | 'weekly' | 'monthly' | 'yearly'
|
|
111
172
|
interval: number // 1–99
|
|
@@ -123,24 +184,41 @@ type CalendarSummary = {
|
|
|
123
184
|
}
|
|
124
185
|
|
|
125
186
|
type User = { id: string; email: string; name: string; emailVerified: boolean }
|
|
126
|
-
type Preferences = {
|
|
187
|
+
type Preferences = {
|
|
188
|
+
theme: 'system' | 'light' | 'dark'; defaultView: View; mobileDefaultView: View; locale: string
|
|
189
|
+
timeZone: string // 'auto' or IANA zone
|
|
190
|
+
holidays: string // 'auto', 'off' or a region such as 'DE-NW'
|
|
191
|
+
}
|
|
192
|
+
type PublicHoliday = { date: string; name: string } // GET /holidays, only with holiday-source="backend"
|
|
193
|
+
// Preferences also carry emailInvites, emailChanges, emailReminders, emailChat: booleans for the emails below
|
|
127
194
|
type Problem = { code: string; message: string } // every error response
|
|
128
195
|
```
|
|
129
196
|
|
|
130
197
|
The backend stores series as one event. The component expands occurrences itself.
|
|
131
198
|
|
|
199
|
+
**Reminders are personal.** Store them per user and event, return only the caller's own `reminders`, and keep other members' reminders when someone saves the event. The component shows reminders while it is open (browser notification or a notice in the calendar). Emails or push messages when it is closed are up to your backend.
|
|
200
|
+
|
|
132
201
|
### When the component calls your backend
|
|
133
202
|
|
|
134
203
|
| Moment | Requests |
|
|
135
204
|
| --- | --- |
|
|
136
205
|
| Widget loads | `GET /auth/me` (only with `auth`), then `GET /preferences`, `GET /colors`, `GET /calendars`, `GET /invitations` |
|
|
137
|
-
| Visible range changes | `GET /events?from=…&to=…&calendarId=…` with the calendars shown. The range is
|
|
206
|
+
| Visible range changes | `GET /events?from=…&to=…&calendarId=…` with the calendars shown. The range is two days wider than the view to cover time zone shifts. Return every event in the range **and** every series that can occur in it. |
|
|
138
207
|
| Create event | `POST /events` with `EventInput` + `calendarId` |
|
|
139
208
|
| Edit event / whole series | `PUT /events/:id` with the full `EventInput` |
|
|
140
209
|
| Edit only this occurrence | `PUT` the series with the date added to `excludedDates`, then `POST` a detached event with `seriesId` and `originalDate` |
|
|
141
210
|
| Edit this and following | `PUT` the series with `until` set to the day before (and `count: null`), `POST` a new series, `PUT` later detached events to relink them |
|
|
142
211
|
| Delete | single: `PUT` with `excludedDates` · following: `PUT` with `until`, `DELETE` its later detached events · all: `DELETE` detached events, then the series · plain: `DELETE /events/:id` |
|
|
212
|
+
| Search | `GET /events/search?q=…&calendarId=…` (optional: without it the component searches the last and next year via `GET /events`) |
|
|
213
|
+
| Answer as attendee | `POST /events/:id/response` with `{ status }` |
|
|
214
|
+
| Change only own reminders | `PUT /events/:id/reminders` with `{ reminders }` (also for members without edit rights) |
|
|
215
|
+
| Answer from an email link | `POST /events/respond` with `{ token, status }`, no session needed |
|
|
216
|
+
| Event chat | `GET`/`POST /events/:id/chat?date=…`, `POST /events/:id/chat/read`, `PATCH`/`DELETE /chat/messages/:id`, `GET /chat/unread?calendarId=…`, WebSocket `/chat/socket` |
|
|
217
|
+
| Subscription link | `GET`, `POST` (new link), `DELETE /calendars/:id/feed`. The link points at your `GET /feeds/:token.ics` |
|
|
218
|
+
| Reminders | `GET /events` for the next four weeks of all calendars, every five minutes while the widget is open |
|
|
219
|
+
| Import .ics | `GET /events` for the whole calendar, then `PUT` for known `uid`s and `POST` for new ones |
|
|
143
220
|
| Settings, colors | `PATCH /preferences`, `POST /colors`, `DELETE /colors/:rrggbb` |
|
|
221
|
+
| Holidays (only with `holiday-source="backend"`) | `GET /holidays?from=…&to=…®ion=DE-NW&lang=de`, answer `PublicHoliday[]` |
|
|
144
222
|
| Sign-in, teams, invitations | `/auth/*`, `/calendars`, `/teams/*`, `/invitations/*`, see the OpenAPI file |
|
|
145
223
|
|
|
146
224
|
Before editing "following" or "all" of a series, the component loads its detached events with `GET /events?seriesId=…`.
|
|
@@ -150,6 +228,8 @@ Before editing "following" or "all" of a series, the component loads its detache
|
|
|
150
228
|
- **Sessions:** requests use `credentials: 'include'`. Set an `HttpOnly` cookie on sign-in. If the widget runs on another domain: CORS for that origin with `Access-Control-Allow-Credentials: true`, allowed headers `Content-Type`, `Accept`, `Accept-Language`, `Authorization`, `X-Calendar-Tenant`, and the cookie as `SameSite=None; Secure`. Answer `401` when the session is gone.
|
|
151
229
|
- **Errors:** always `{ code, message }`. Known codes such as `invalidCredentials`, `emailTaken`, `forbidden`, `lastOwner` are shown translated, others with `message`.
|
|
152
230
|
- **Language:** every request carries `Accept-Language`. Use it, or the stored `locale`, for emails.
|
|
231
|
+
- **Emails about events** (your backend sends them, the component only stores the user's choice): an invitation with yes / maybe / no links to `/respond?status=accepted&token=…` when someone is added as attendee (`emailInvites`), a notice when title, time, place or repetition change or the event is cancelled (`emailChanges`), and reminders at the user's own reminder times even while the calendar is closed (`emailReminders`, off by default). Only to verified addresses, never to the person who made the change.
|
|
232
|
+
- **Subscriptions:** `GET /feeds/:token.ics` answers without a session with the calendar as iCalendar (RFC 5545) and the subscriber's own reminders. Keep one secret token per user and calendar, a new one replaces the old. Stop serving it when the user leaves the calendar.
|
|
153
233
|
- **Email links:** point them at the host page with the screen as parameter, e.g. `https://host.example/calendar?calendarPath=%2Freset-password%3Ftoken%3D…`.
|
|
154
234
|
|
|
155
235
|
Building, the test backend and all internals are described in German in [DEVELOPMENT.md](DEVELOPMENT.md).
|
|
@@ -157,3 +237,5 @@ Building, the test backend and all internals are described in German in [DEVELOP
|
|
|
157
237
|
## License
|
|
158
238
|
|
|
159
239
|
[MIT](LICENSE) © Rokoyfa
|
|
240
|
+
|
|
241
|
+
Public holiday data comes from [date-holidays](https://github.com/commenthol/date-holidays) (code ISC, data [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)). It is loaded only when holidays are shown.
|
package/api/openapi.yaml
CHANGED
|
@@ -34,6 +34,11 @@ tags:
|
|
|
34
34
|
- name: Teams
|
|
35
35
|
- name: Invitations
|
|
36
36
|
- name: Preferences
|
|
37
|
+
- name: Chat
|
|
38
|
+
description: |
|
|
39
|
+
One chat per event in team calendars, for recurring events one per occurrence (`date` = original date of the occurrence).
|
|
40
|
+
Live updates come over a WebSocket at `{base}/chat/socket`, see the README section “Event chat”.
|
|
41
|
+
- name: Holidays
|
|
37
42
|
paths:
|
|
38
43
|
/auth/me:
|
|
39
44
|
get:
|
|
@@ -73,7 +78,7 @@ paths:
|
|
|
73
78
|
properties:
|
|
74
79
|
password: { type: string }
|
|
75
80
|
responses:
|
|
76
|
-
'204': { description: Deleted, session cookie cleared }
|
|
81
|
+
'204': { description: 'Deleted, session cookie cleared' }
|
|
77
82
|
'403': { $ref: '#/components/responses/Problem' }
|
|
78
83
|
'409': { $ref: '#/components/responses/Problem' }
|
|
79
84
|
/auth/me/password:
|
|
@@ -167,7 +172,7 @@ paths:
|
|
|
167
172
|
summary: Sign out
|
|
168
173
|
security: []
|
|
169
174
|
responses:
|
|
170
|
-
'204': { description: Session ended, cookie cleared }
|
|
175
|
+
'204': { description: 'Session ended, cookie cleared' }
|
|
171
176
|
/auth/password-reset:
|
|
172
177
|
post:
|
|
173
178
|
tags: [Auth]
|
|
@@ -274,6 +279,93 @@ paths:
|
|
|
274
279
|
'400': { $ref: '#/components/responses/Problem' }
|
|
275
280
|
'403': { $ref: '#/components/responses/Problem' }
|
|
276
281
|
'404': { $ref: '#/components/responses/Problem' }
|
|
282
|
+
/events/search:
|
|
283
|
+
get:
|
|
284
|
+
tags: [Events]
|
|
285
|
+
summary: Search events
|
|
286
|
+
description: |
|
|
287
|
+
Events and series whose title, location, description or links contain `q` (case-insensitive), in the given calendars.
|
|
288
|
+
Optional for custom backends: without it the component searches the events of the last and next year itself.
|
|
289
|
+
parameters:
|
|
290
|
+
- { name: q, in: query, required: true, schema: { type: string, minLength: 2 } }
|
|
291
|
+
- name: calendarId
|
|
292
|
+
in: query
|
|
293
|
+
required: true
|
|
294
|
+
schema: { type: array, items: { type: string } }
|
|
295
|
+
style: form
|
|
296
|
+
explode: true
|
|
297
|
+
responses:
|
|
298
|
+
'200':
|
|
299
|
+
description: Matching events, at most 50
|
|
300
|
+
content:
|
|
301
|
+
application/json:
|
|
302
|
+
schema: { type: array, items: { $ref: '#/components/schemas/CalendarEvent' } }
|
|
303
|
+
'400': { $ref: '#/components/responses/Problem' }
|
|
304
|
+
/events/{id}/response:
|
|
305
|
+
parameters:
|
|
306
|
+
- { name: id, in: path, required: true, schema: { type: string } }
|
|
307
|
+
post:
|
|
308
|
+
tags: [Events]
|
|
309
|
+
summary: Answer an event invitation
|
|
310
|
+
description: Sets the status of the attendee whose email is the signed-in user's. Allowed for every attendee with read access. `403` if the user is not an attendee.
|
|
311
|
+
requestBody:
|
|
312
|
+
required: true
|
|
313
|
+
content:
|
|
314
|
+
application/json:
|
|
315
|
+
schema:
|
|
316
|
+
type: object
|
|
317
|
+
required: [status]
|
|
318
|
+
properties:
|
|
319
|
+
status: { $ref: '#/components/schemas/AttendeeStatus' }
|
|
320
|
+
responses:
|
|
321
|
+
'200': { $ref: '#/components/responses/Event' }
|
|
322
|
+
'400': { $ref: '#/components/responses/Problem' }
|
|
323
|
+
'403': { $ref: '#/components/responses/Problem' }
|
|
324
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
325
|
+
/events/{id}/reminders:
|
|
326
|
+
parameters:
|
|
327
|
+
- { name: id, in: path, required: true, schema: { type: string } }
|
|
328
|
+
put:
|
|
329
|
+
tags: [Events]
|
|
330
|
+
summary: Set the own reminders of an event
|
|
331
|
+
description: Changes only the reminders of the signed-in user. Allowed with read access, so members without edit rights can be reminded too.
|
|
332
|
+
requestBody:
|
|
333
|
+
required: true
|
|
334
|
+
content:
|
|
335
|
+
application/json:
|
|
336
|
+
schema:
|
|
337
|
+
type: object
|
|
338
|
+
required: [reminders]
|
|
339
|
+
properties:
|
|
340
|
+
reminders: { type: array, maxItems: 5, items: { type: integer, minimum: 0, maximum: 40320 } }
|
|
341
|
+
responses:
|
|
342
|
+
'200': { $ref: '#/components/responses/Event' }
|
|
343
|
+
'400': { $ref: '#/components/responses/Problem' }
|
|
344
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
345
|
+
/events/respond:
|
|
346
|
+
post:
|
|
347
|
+
tags: [Events]
|
|
348
|
+
summary: Answer an invitation from an email link
|
|
349
|
+
description: No session needed. The token comes from the invitation email (`/respond?status=…&token=…` on the host page) and stands for one attendee of one event.
|
|
350
|
+
security: []
|
|
351
|
+
requestBody:
|
|
352
|
+
required: true
|
|
353
|
+
content:
|
|
354
|
+
application/json:
|
|
355
|
+
schema:
|
|
356
|
+
type: object
|
|
357
|
+
required: [token, status]
|
|
358
|
+
properties:
|
|
359
|
+
token: { type: string }
|
|
360
|
+
status: { type: string, enum: [accepted, tentative, declined] }
|
|
361
|
+
responses:
|
|
362
|
+
'200':
|
|
363
|
+
description: Saved
|
|
364
|
+
content:
|
|
365
|
+
application/json:
|
|
366
|
+
schema: { $ref: '#/components/schemas/EventResponse' }
|
|
367
|
+
'400': { $ref: '#/components/responses/Problem' }
|
|
368
|
+
'410': { $ref: '#/components/responses/Problem' }
|
|
277
369
|
/events/{id}:
|
|
278
370
|
parameters:
|
|
279
371
|
- { name: id, in: path, required: true, schema: { type: string } }
|
|
@@ -331,6 +423,140 @@ paths:
|
|
|
331
423
|
responses:
|
|
332
424
|
'201': { $ref: '#/components/responses/CalendarSummary' }
|
|
333
425
|
'400': { $ref: '#/components/responses/Problem' }
|
|
426
|
+
/events/{id}/chat:
|
|
427
|
+
parameters:
|
|
428
|
+
- { name: id, in: path, required: true, description: 'Event id, for detached occurrences the id of their series', schema: { type: string } }
|
|
429
|
+
- { name: date, in: query, required: false, description: 'Required for recurring events: the original date of the occurrence. Not allowed for single events.', schema: { $ref: '#/components/schemas/ISODate' } }
|
|
430
|
+
get:
|
|
431
|
+
tags: [Chat]
|
|
432
|
+
summary: Messages of an event chat
|
|
433
|
+
description: Oldest first. Without `before` the newest page. Every member of the team calendar may read. `400` with `personalTeam` in personal calendars.
|
|
434
|
+
parameters:
|
|
435
|
+
- { name: before, in: query, required: false, description: 'Message id, returns messages older than this one', schema: { type: string } }
|
|
436
|
+
- { name: limit, in: query, required: false, schema: { type: integer, minimum: 1, maximum: 100, default: 50 } }
|
|
437
|
+
responses:
|
|
438
|
+
'200':
|
|
439
|
+
description: Page of messages
|
|
440
|
+
content:
|
|
441
|
+
application/json:
|
|
442
|
+
schema: { $ref: '#/components/schemas/ChatPage' }
|
|
443
|
+
'400': { $ref: '#/components/responses/Problem' }
|
|
444
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
445
|
+
post:
|
|
446
|
+
tags: [Chat]
|
|
447
|
+
summary: Write a message
|
|
448
|
+
description: Every member of the team calendar may write. Marks the chat as read for the author, sends `message.created` over the socket to all members and an email to attendees who want it.
|
|
449
|
+
requestBody:
|
|
450
|
+
required: true
|
|
451
|
+
content:
|
|
452
|
+
application/json:
|
|
453
|
+
schema: { type: object, required: [text], properties: { text: { type: string, minLength: 1, maxLength: 2000 } } }
|
|
454
|
+
responses:
|
|
455
|
+
'201':
|
|
456
|
+
description: Created
|
|
457
|
+
content:
|
|
458
|
+
application/json:
|
|
459
|
+
schema: { $ref: '#/components/schemas/ChatMessage' }
|
|
460
|
+
'400': { $ref: '#/components/responses/Problem' }
|
|
461
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
462
|
+
/events/{id}/chat/read:
|
|
463
|
+
parameters:
|
|
464
|
+
- { name: id, in: path, required: true, schema: { type: string } }
|
|
465
|
+
- { name: date, in: query, required: false, schema: { $ref: '#/components/schemas/ISODate' } }
|
|
466
|
+
post:
|
|
467
|
+
tags: [Chat]
|
|
468
|
+
summary: Mark the chat as read
|
|
469
|
+
responses:
|
|
470
|
+
'204': { description: Marked }
|
|
471
|
+
/chat/messages/{messageId}:
|
|
472
|
+
parameters:
|
|
473
|
+
- { name: messageId, in: path, required: true, schema: { type: string } }
|
|
474
|
+
patch:
|
|
475
|
+
tags: [Chat]
|
|
476
|
+
summary: Edit an own message
|
|
477
|
+
requestBody:
|
|
478
|
+
required: true
|
|
479
|
+
content:
|
|
480
|
+
application/json:
|
|
481
|
+
schema: { type: object, required: [text], properties: { text: { type: string, minLength: 1, maxLength: 2000 } } }
|
|
482
|
+
responses:
|
|
483
|
+
'200':
|
|
484
|
+
description: Edited, `editedAt` is set. Sends `message.updated` over the socket.
|
|
485
|
+
content:
|
|
486
|
+
application/json:
|
|
487
|
+
schema: { $ref: '#/components/schemas/ChatMessage' }
|
|
488
|
+
'403': { $ref: '#/components/responses/Problem' }
|
|
489
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
490
|
+
delete:
|
|
491
|
+
tags: [Chat]
|
|
492
|
+
summary: Delete a message
|
|
493
|
+
description: Own messages, or any message with `manage_calendars` (owner, admin, manager). Sends `message.deleted` over the socket.
|
|
494
|
+
responses:
|
|
495
|
+
'204': { description: Deleted }
|
|
496
|
+
'403': { $ref: '#/components/responses/Problem' }
|
|
497
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
498
|
+
/chat/unread:
|
|
499
|
+
get:
|
|
500
|
+
tags: [Chat]
|
|
501
|
+
summary: Unread messages per chat
|
|
502
|
+
description: Messages of others newer than the user's last read time, only chats with at least one.
|
|
503
|
+
parameters:
|
|
504
|
+
- name: calendarId
|
|
505
|
+
in: query
|
|
506
|
+
required: true
|
|
507
|
+
style: form
|
|
508
|
+
explode: true
|
|
509
|
+
schema: { type: array, items: { type: string } }
|
|
510
|
+
responses:
|
|
511
|
+
'200':
|
|
512
|
+
description: Counts
|
|
513
|
+
content:
|
|
514
|
+
application/json:
|
|
515
|
+
schema: { type: array, items: { $ref: '#/components/schemas/ChatUnread' } }
|
|
516
|
+
/calendars/{calendarId}/feed:
|
|
517
|
+
parameters:
|
|
518
|
+
- { $ref: '#/components/parameters/CalendarId' }
|
|
519
|
+
get:
|
|
520
|
+
tags: [Calendars]
|
|
521
|
+
summary: Own subscription link
|
|
522
|
+
responses:
|
|
523
|
+
'200':
|
|
524
|
+
description: Link or null
|
|
525
|
+
content:
|
|
526
|
+
application/json:
|
|
527
|
+
schema: { type: object, required: [url], properties: { url: { oneOf: [{ type: string, format: uri }, { type: 'null' }] } } }
|
|
528
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
529
|
+
post:
|
|
530
|
+
tags: [Calendars]
|
|
531
|
+
summary: Create a new subscription link
|
|
532
|
+
description: Replaces an existing link of this user for this calendar.
|
|
533
|
+
responses:
|
|
534
|
+
'201':
|
|
535
|
+
description: New link
|
|
536
|
+
content:
|
|
537
|
+
application/json:
|
|
538
|
+
schema: { type: object, required: [url], properties: { url: { type: string, format: uri } } }
|
|
539
|
+
'404': { $ref: '#/components/responses/Problem' }
|
|
540
|
+
delete:
|
|
541
|
+
tags: [Calendars]
|
|
542
|
+
summary: End the subscription
|
|
543
|
+
responses:
|
|
544
|
+
'204': { description: Ended }
|
|
545
|
+
/feeds/{token}.ics:
|
|
546
|
+
parameters:
|
|
547
|
+
- { name: token, in: path, required: true, schema: { type: string } }
|
|
548
|
+
get:
|
|
549
|
+
tags: [Calendars]
|
|
550
|
+
summary: Calendar subscription
|
|
551
|
+
description: No session needed. The calendar as iCalendar with the subscriber's own reminders as alarms. `404` when the token is unknown or the user is no longer a member.
|
|
552
|
+
security: []
|
|
553
|
+
responses:
|
|
554
|
+
'200':
|
|
555
|
+
description: iCalendar
|
|
556
|
+
content:
|
|
557
|
+
text/calendar:
|
|
558
|
+
schema: { type: string }
|
|
559
|
+
'404': { description: Unknown link }
|
|
334
560
|
/calendars/{calendarId}:
|
|
335
561
|
parameters:
|
|
336
562
|
- { $ref: '#/components/parameters/CalendarId' }
|
|
@@ -597,6 +823,28 @@ paths:
|
|
|
597
823
|
responses:
|
|
598
824
|
'204': { description: Declined }
|
|
599
825
|
'404': { $ref: '#/components/responses/Problem' }
|
|
826
|
+
/holidays:
|
|
827
|
+
get:
|
|
828
|
+
tags: [Holidays]
|
|
829
|
+
summary: Public holidays of a region
|
|
830
|
+
description: |
|
|
831
|
+
Optional. Only called with `holiday-source="backend"`. Without it, or when this request fails, the component computes holidays itself.
|
|
832
|
+
Return the public holidays (days off) between `from` and `to` inclusive, with names in `lang`.
|
|
833
|
+
parameters:
|
|
834
|
+
- { name: from, in: query, required: true, schema: { $ref: '#/components/schemas/ISODate' } }
|
|
835
|
+
- { name: to, in: query, required: true, schema: { $ref: '#/components/schemas/ISODate' } }
|
|
836
|
+
- name: region
|
|
837
|
+
in: query
|
|
838
|
+
required: true
|
|
839
|
+
description: Country, optionally with a subdivision, e.g. `DE`, `DE-NW`, `US-CA`
|
|
840
|
+
schema: { type: string, pattern: '^[A-Z]{2}(-[A-Z0-9]{1,6})?$' }
|
|
841
|
+
- { name: lang, in: query, required: true, schema: { type: string, examples: [de] } }
|
|
842
|
+
responses:
|
|
843
|
+
'200':
|
|
844
|
+
description: Holidays
|
|
845
|
+
content:
|
|
846
|
+
application/json:
|
|
847
|
+
schema: { type: array, items: { $ref: '#/components/schemas/PublicHoliday' } }
|
|
600
848
|
/preferences:
|
|
601
849
|
get:
|
|
602
850
|
tags: [Preferences]
|
|
@@ -618,6 +866,12 @@ paths:
|
|
|
618
866
|
defaultView: { $ref: '#/components/schemas/CalendarView' }
|
|
619
867
|
mobileDefaultView: { $ref: '#/components/schemas/CalendarView' }
|
|
620
868
|
locale: { $ref: '#/components/schemas/Locale' }
|
|
869
|
+
timeZone: { $ref: '#/components/schemas/PreferredTimeZone' }
|
|
870
|
+
holidays: { $ref: '#/components/schemas/HolidaySetting' }
|
|
871
|
+
emailInvites: { type: boolean }
|
|
872
|
+
emailChanges: { type: boolean }
|
|
873
|
+
emailReminders: { type: boolean }
|
|
874
|
+
emailChat: { type: boolean }
|
|
621
875
|
responses:
|
|
622
876
|
'200': { $ref: '#/components/responses/Preferences' }
|
|
623
877
|
'400': { $ref: '#/components/responses/Problem' }
|
|
@@ -787,7 +1041,18 @@ components:
|
|
|
787
1041
|
type: object
|
|
788
1042
|
required: [title, startDate, start, endDate, end, description, color, recurrence, excludedDates, seriesId, originalDate]
|
|
789
1043
|
properties:
|
|
1044
|
+
uid:
|
|
1045
|
+
type: string
|
|
1046
|
+
maxLength: 255
|
|
1047
|
+
description: Stable id for iCalendar exchange. Kept when importing again; the backend creates one if missing. Detached occurrences share the uid of their series.
|
|
790
1048
|
title: { type: string, minLength: 1, maxLength: 100 }
|
|
1049
|
+
location: { type: string, maxLength: 200, default: '' }
|
|
1050
|
+
links:
|
|
1051
|
+
type: array
|
|
1052
|
+
maxItems: 10
|
|
1053
|
+
default: []
|
|
1054
|
+
items: { $ref: '#/components/schemas/EventLink' }
|
|
1055
|
+
description: Website and other links. Only http and https addresses are accepted.
|
|
791
1056
|
startDate: { $ref: '#/components/schemas/ISODate' }
|
|
792
1057
|
start: { $ref: '#/components/schemas/Time' }
|
|
793
1058
|
endDate: { $ref: '#/components/schemas/ISODate' }
|
|
@@ -810,6 +1075,35 @@ components:
|
|
|
810
1075
|
originalDate:
|
|
811
1076
|
description: For a detached occurrence, its original date in the series
|
|
812
1077
|
oneOf: [{ $ref: '#/components/schemas/ISODate' }, { type: 'null' }]
|
|
1078
|
+
reminders:
|
|
1079
|
+
type: array
|
|
1080
|
+
maxItems: 5
|
|
1081
|
+
default: []
|
|
1082
|
+
items: { type: integer, minimum: 0, maximum: 40320 }
|
|
1083
|
+
description: |
|
|
1084
|
+
Minutes before the start (for all-day events before 00:00 of the first day) at which the signed-in user wants to be reminded.
|
|
1085
|
+
Personal: store them per user and return only the caller's own reminders. Changing them never affects other members.
|
|
1086
|
+
attendees:
|
|
1087
|
+
type: array
|
|
1088
|
+
maxItems: 100
|
|
1089
|
+
default: []
|
|
1090
|
+
items: { $ref: '#/components/schemas/Attendee' }
|
|
1091
|
+
EventLink:
|
|
1092
|
+
type: object
|
|
1093
|
+
required: [url]
|
|
1094
|
+
properties:
|
|
1095
|
+
url: { type: string, format: uri, maxLength: 2000, pattern: '^https?://' }
|
|
1096
|
+
label: { type: string, maxLength: 100, default: '' }
|
|
1097
|
+
AttendeeStatus:
|
|
1098
|
+
type: string
|
|
1099
|
+
enum: [needsAction, accepted, tentative, declined]
|
|
1100
|
+
Attendee:
|
|
1101
|
+
type: object
|
|
1102
|
+
required: [email, name, status]
|
|
1103
|
+
properties:
|
|
1104
|
+
email: { type: string, format: email }
|
|
1105
|
+
name: { type: string }
|
|
1106
|
+
status: { $ref: '#/components/schemas/AttendeeStatus' }
|
|
813
1107
|
CalendarEvent:
|
|
814
1108
|
allOf:
|
|
815
1109
|
- $ref: '#/components/schemas/EventInput'
|
|
@@ -909,11 +1203,73 @@ components:
|
|
|
909
1203
|
description: '`auto` or a BCP 47 language tag such as `en-US`, `en-GB`, `de-DE`'
|
|
910
1204
|
maxLength: 35
|
|
911
1205
|
pattern: '^(auto|[a-z]{2,3}(-[A-Za-z0-9]{2,8})*)$'
|
|
1206
|
+
HolidaySetting:
|
|
1207
|
+
type: string
|
|
1208
|
+
default: auto
|
|
1209
|
+
description: '`auto` (region given by the host, otherwise from the language), `off`, or a region such as `DE-NW`.'
|
|
1210
|
+
pattern: '^(auto|off|[A-Z]{2}(-[A-Z0-9]{1,6})?)$'
|
|
1211
|
+
ChatMessage:
|
|
1212
|
+
type: object
|
|
1213
|
+
required: [id, calendarId, eventId, occurrenceDate, author, text, createdAt, editedAt]
|
|
1214
|
+
properties:
|
|
1215
|
+
id: { type: string }
|
|
1216
|
+
calendarId: { type: string }
|
|
1217
|
+
eventId: { type: string }
|
|
1218
|
+
occurrenceDate: { oneOf: [{ $ref: '#/components/schemas/ISODate' }, { type: 'null' }] }
|
|
1219
|
+
author:
|
|
1220
|
+
description: null when the account was deleted
|
|
1221
|
+
oneOf: [{ type: object, required: [id, name], properties: { id: { type: string }, name: { type: string } } }, { type: 'null' }]
|
|
1222
|
+
text: { type: string }
|
|
1223
|
+
createdAt: { type: string, format: date-time }
|
|
1224
|
+
editedAt: { oneOf: [{ type: string, format: date-time }, { type: 'null' }] }
|
|
1225
|
+
ChatPage:
|
|
1226
|
+
type: object
|
|
1227
|
+
required: [messages, hasMore]
|
|
1228
|
+
properties:
|
|
1229
|
+
messages: { type: array, items: { $ref: '#/components/schemas/ChatMessage' } }
|
|
1230
|
+
hasMore: { type: boolean }
|
|
1231
|
+
ChatUnread:
|
|
1232
|
+
type: object
|
|
1233
|
+
required: [eventId, occurrenceDate, count]
|
|
1234
|
+
properties:
|
|
1235
|
+
eventId: { type: string }
|
|
1236
|
+
occurrenceDate: { oneOf: [{ $ref: '#/components/schemas/ISODate' }, { type: 'null' }] }
|
|
1237
|
+
count: { type: integer, minimum: 1 }
|
|
1238
|
+
EventResponse:
|
|
1239
|
+
type: object
|
|
1240
|
+
required: [title, location, startDate, start, endDate, end, allDay, timeZone, recurring, status]
|
|
1241
|
+
properties:
|
|
1242
|
+
title: { type: string }
|
|
1243
|
+
location: { type: string }
|
|
1244
|
+
startDate: { $ref: '#/components/schemas/ISODate' }
|
|
1245
|
+
start: { $ref: '#/components/schemas/Time' }
|
|
1246
|
+
endDate: { $ref: '#/components/schemas/ISODate' }
|
|
1247
|
+
end: { $ref: '#/components/schemas/Time' }
|
|
1248
|
+
allDay: { type: boolean }
|
|
1249
|
+
timeZone: { oneOf: [{ type: string }, { type: 'null' }] }
|
|
1250
|
+
recurring: { type: boolean }
|
|
1251
|
+
status: { $ref: '#/components/schemas/AttendeeStatus' }
|
|
1252
|
+
PublicHoliday:
|
|
1253
|
+
type: object
|
|
1254
|
+
required: [date, name]
|
|
1255
|
+
properties:
|
|
1256
|
+
date: { $ref: '#/components/schemas/ISODate' }
|
|
1257
|
+
name: { type: string }
|
|
1258
|
+
PreferredTimeZone:
|
|
1259
|
+
type: string
|
|
1260
|
+
default: auto
|
|
1261
|
+
description: '`auto` (zone given by the host, otherwise the system zone) or an IANA zone such as `Europe/Berlin`. Events are shown in this zone.'
|
|
912
1262
|
Preferences:
|
|
913
1263
|
type: object
|
|
914
|
-
required: [theme, defaultView, mobileDefaultView, locale]
|
|
1264
|
+
required: [theme, defaultView, mobileDefaultView, locale, timeZone, holidays, emailInvites, emailChanges, emailReminders, emailChat]
|
|
915
1265
|
properties:
|
|
916
1266
|
theme: { $ref: '#/components/schemas/Theme' }
|
|
917
1267
|
defaultView: { $ref: '#/components/schemas/CalendarView' }
|
|
918
1268
|
mobileDefaultView: { $ref: '#/components/schemas/CalendarView' }
|
|
919
1269
|
locale: { $ref: '#/components/schemas/Locale' }
|
|
1270
|
+
timeZone: { $ref: '#/components/schemas/PreferredTimeZone' }
|
|
1271
|
+
holidays: { $ref: '#/components/schemas/HolidaySetting' }
|
|
1272
|
+
emailInvites: { type: boolean, default: true, description: Email when someone invites the user to an event }
|
|
1273
|
+
emailChanges: { type: boolean, default: true, description: Email when an event the user is invited to changes or is cancelled }
|
|
1274
|
+
emailReminders: { type: boolean, default: false, description: Emails at the user's own reminder times }
|
|
1275
|
+
emailChat: { type: boolean, default: true, description: Email about new chat messages of events the user is invited to }
|