@rokoyfa/calendar 1.2.0 → 1.3.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.
Files changed (144) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/DEVELOPER_GUIDE.md +1045 -0
  3. package/README.md +41 -190
  4. package/api/openapi.yaml +395 -4
  5. package/demo/calendar.config.jsonc +183 -0
  6. package/demo/calendar.config.yaml +180 -0
  7. package/dist-lib/cdn/browser-BSbYkIQu.js +130 -0
  8. package/dist-lib/cdn/browser-BSbYkIQu.js.map +1 -0
  9. package/dist-lib/cdn/calendar-widget.js +14 -11
  10. package/dist-lib/cdn/calendar-widget.js.map +1 -1
  11. package/dist-lib/cdn/de-Dqga3QZG.js +2 -0
  12. package/dist-lib/cdn/de-Dqga3QZG.js.map +1 -0
  13. package/dist-lib/cdn/es-BWSfTMjh.js +2 -0
  14. package/dist-lib/cdn/es-BWSfTMjh.js.map +1 -0
  15. package/dist-lib/cdn/fr-N9gwLjVq.js +2 -0
  16. package/dist-lib/cdn/fr-N9gwLjVq.js.map +1 -0
  17. package/dist-lib/cdn/it-B5Ib2xLn.js +2 -0
  18. package/dist-lib/cdn/it-B5Ib2xLn.js.map +1 -0
  19. package/dist-lib/cdn/nl-CjI7Uc8l.js +2 -0
  20. package/dist-lib/cdn/nl-CjI7Uc8l.js.map +1 -0
  21. package/dist-lib/cdn/pl-FRu3yQhc.js +2 -0
  22. package/dist-lib/cdn/pl-FRu3yQhc.js.map +1 -0
  23. package/dist-lib/cdn/pt-DBKJ-3Is.js +2 -0
  24. package/dist-lib/cdn/pt-DBKJ-3Is.js.map +1 -0
  25. package/dist-lib/npm/{de-Cuz-uz3s.js → de-DhWrY8Ae.js} +111 -3
  26. package/dist-lib/npm/de-DhWrY8Ae.js.map +1 -0
  27. package/dist-lib/npm/{es-BnRzdU90.js → es-Bj8leuD5.js} +111 -3
  28. package/dist-lib/npm/es-Bj8leuD5.js.map +1 -0
  29. package/dist-lib/npm/{fr-B-nmvStg.js → fr-DzAFZ0jh.js} +111 -3
  30. package/dist-lib/npm/fr-DzAFZ0jh.js.map +1 -0
  31. package/dist-lib/npm/index.js +3876 -1400
  32. package/dist-lib/npm/index.js.map +1 -1
  33. package/dist-lib/npm/{it-DMTpE4GO.js → it-lEmGP5yo.js} +111 -3
  34. package/dist-lib/npm/it-lEmGP5yo.js.map +1 -0
  35. package/dist-lib/npm/{nl-DQkyEt9Z.js → nl-d1h63dvm.js} +111 -3
  36. package/dist-lib/npm/nl-d1h63dvm.js.map +1 -0
  37. package/dist-lib/npm/{pl-CcjU41yx.js → pl-DynFKadb.js} +111 -3
  38. package/dist-lib/npm/pl-DynFKadb.js.map +1 -0
  39. package/dist-lib/npm/{pt-Dulais2f.js → pt-foL7jDsE.js} +111 -3
  40. package/dist-lib/npm/pt-foL7jDsE.js.map +1 -0
  41. package/dist-lib/npm/types/components/Icons.d.ts +2 -0
  42. package/dist-lib/npm/types/config/routes.d.ts +1 -0
  43. package/dist-lib/npm/types/context/HostBridge.d.ts +38 -0
  44. package/dist-lib/npm/types/context/HostContext.d.ts +39 -2
  45. package/dist-lib/npm/types/data/restDataSource.d.ts +3 -1
  46. package/dist-lib/npm/types/data/tenantDataSource.d.ts +3 -1
  47. package/dist-lib/npm/types/data/types.d.ts +4 -1
  48. package/dist-lib/npm/types/features/attachments/components/AttachmentsField.d.ts +8 -0
  49. package/dist-lib/npm/types/features/attachments/hooks/useAttachments.d.ts +11 -0
  50. package/dist-lib/npm/types/features/attachments/index.d.ts +2 -0
  51. package/dist-lib/npm/types/features/authorization/components/account/DataExportSection.d.ts +1 -0
  52. package/dist-lib/npm/types/features/authorization/hooks/useAuth.d.ts +1 -0
  53. package/dist-lib/npm/types/features/authorization/index.d.ts +1 -0
  54. package/dist-lib/npm/types/features/authorization/repositories/HostTokenAuthRepository.d.ts +1 -0
  55. package/dist-lib/npm/types/features/authorization/repositories/RemoteAuthRepository.d.ts +1 -0
  56. package/dist-lib/npm/types/features/authorization/types/auth.d.ts +2 -0
  57. package/dist-lib/npm/types/features/calendar/components/Calendar.d.ts +7 -1
  58. package/dist-lib/npm/types/features/calendar/components/CalendarHeader.d.ts +3 -1
  59. package/dist-lib/npm/types/features/calendar/constants/views.d.ts +2 -2
  60. package/dist-lib/npm/types/features/calendar/hooks/useEventNavigation.d.ts +4 -0
  61. package/dist-lib/npm/types/features/calendar/hooks/useHostController.d.ts +2 -0
  62. package/dist-lib/npm/types/features/calendar/hooks/useLiveEvents.d.ts +11 -0
  63. package/dist-lib/npm/types/features/calendar/hooks/useSegmentAttributes.d.ts +2 -0
  64. package/dist-lib/npm/types/features/calendar/utils/eventLabels.d.ts +4 -0
  65. package/dist-lib/npm/types/features/calendars/components/settings/ShareSection.d.ts +4 -0
  66. package/dist-lib/npm/types/features/calendars/components/settings/TrashSection.d.ts +4 -0
  67. package/dist-lib/npm/types/features/calendars/index.d.ts +1 -1
  68. package/dist-lib/npm/types/features/calendars/repositories/RemoteCalendarRepository.d.ts +3 -0
  69. package/dist-lib/npm/types/features/calendars/types/calendar.d.ts +3 -0
  70. package/dist-lib/npm/types/features/calendars/utils/permissions.d.ts +4 -0
  71. package/dist-lib/npm/types/features/categories/components/CategoriesSection.d.ts +6 -0
  72. package/dist-lib/npm/types/features/categories/components/CategoryField.d.ts +9 -0
  73. package/dist-lib/npm/types/features/categories/components/CategoryFilterModal.d.ts +10 -0
  74. package/dist-lib/npm/types/features/categories/hooks/useCategories.d.ts +9 -0
  75. package/dist-lib/npm/types/features/categories/index.d.ts +4 -0
  76. package/dist-lib/npm/types/features/events/components/DeleteEventModal.d.ts +2 -1
  77. package/dist-lib/npm/types/features/events/components/EventModal.d.ts +11 -3
  78. package/dist-lib/npm/types/features/events/hooks/useEvents.d.ts +4 -1
  79. package/dist-lib/npm/types/features/events/index.d.ts +2 -2
  80. package/dist-lib/npm/types/features/events/utils/icalExchange.d.ts +4 -1
  81. package/dist-lib/npm/types/features/storage/index.d.ts +6 -1
  82. package/dist-lib/npm/types/features/storage/repositories/LocalCategoryRepository.d.ts +14 -0
  83. package/dist-lib/npm/types/features/storage/repositories/LocalEventRepository.d.ts +8 -2
  84. package/dist-lib/npm/types/features/storage/repositories/RemoteAttachmentRepository.d.ts +11 -0
  85. package/dist-lib/npm/types/features/storage/repositories/RemoteCategoryRepository.d.ts +10 -0
  86. package/dist-lib/npm/types/features/storage/repositories/RemoteChatRepository.d.ts +2 -1
  87. package/dist-lib/npm/types/features/storage/repositories/RemoteEventRepository.d.ts +9 -3
  88. package/dist-lib/npm/types/features/storage/repositories/RemoteSharedCalendarRepository.d.ts +9 -0
  89. package/dist-lib/npm/types/features/storage/types/storage.d.ts +30 -2
  90. package/dist-lib/npm/types/features/storage/utils/liveSocket.d.ts +10 -0
  91. package/dist-lib/npm/types/i18n/messages/en/calendar.d.ts +9 -0
  92. package/dist-lib/npm/types/i18n/messages/en/calendars.d.ts +44 -0
  93. package/dist-lib/npm/types/i18n/messages/en/core.d.ts +1 -0
  94. package/dist-lib/npm/types/i18n/messages/en/events.d.ts +37 -0
  95. package/dist-lib/npm/types/i18n/messages/en/index.d.ts +99 -1
  96. package/dist-lib/npm/types/i18n/messages/en/settings.d.ts +7 -0
  97. package/dist-lib/npm/types/i18n/messages/index.d.ts +99 -1
  98. package/dist-lib/npm/types/lib/CalendarWidget.d.ts +1 -1
  99. package/dist-lib/npm/types/lib/IsolatedRoot.d.ts +3 -1
  100. package/dist-lib/npm/types/lib/appearance.d.ts +3 -0
  101. package/dist-lib/npm/types/lib/config.d.ts +16 -27
  102. package/dist-lib/npm/types/lib/configFile.d.ts +6 -0
  103. package/dist-lib/npm/types/lib/defaults.d.ts +29 -1
  104. package/dist-lib/npm/types/lib/element.d.ts +15 -1
  105. package/dist-lib/npm/types/lib/handle.d.ts +15 -0
  106. package/dist-lib/npm/types/lib/index.d.ts +6 -2
  107. package/dist-lib/npm/types/lib/options.d.ts +47 -0
  108. package/dist-lib/npm/types/lib/useCalendarOptions.d.ts +11 -0
  109. package/dist-lib/npm/types/pages/SharedCalendarPage.d.ts +1 -0
  110. package/dist-lib/npm/types/utils/api.d.ts +1 -0
  111. package/dist-lib/npm/types/utils/appError.d.ts +1 -1
  112. package/dist-lib/npm/types/utils/attachment.d.ts +31 -0
  113. package/dist-lib/npm/types/utils/calendarView.d.ts +1 -0
  114. package/dist-lib/npm/types/utils/category.d.ts +18 -0
  115. package/dist-lib/npm/types/utils/conflict.d.ts +1 -0
  116. package/dist-lib/npm/types/utils/dataExport.d.ts +13 -0
  117. package/dist-lib/npm/types/utils/event.d.ts +6 -1
  118. package/dist-lib/npm/types/utils/eventChange.d.ts +13 -0
  119. package/dist-lib/npm/types/utils/ical.d.ts +6 -1
  120. package/dist-lib/npm/types/utils/sharedCalendar.d.ts +13 -0
  121. package/dist-lib/npm/types/utils/trash.d.ts +14 -0
  122. package/package.json +8 -2
  123. package/schema/calendar-config.schema.json +297 -0
  124. package/dist-lib/cdn/de-BjzK4Pgn.js +0 -2
  125. package/dist-lib/cdn/de-BjzK4Pgn.js.map +0 -1
  126. package/dist-lib/cdn/es-TA5DvEsw.js +0 -2
  127. package/dist-lib/cdn/es-TA5DvEsw.js.map +0 -1
  128. package/dist-lib/cdn/fr-Dx-nmhQ7.js +0 -2
  129. package/dist-lib/cdn/fr-Dx-nmhQ7.js.map +0 -1
  130. package/dist-lib/cdn/it-D_2eA3dT.js +0 -2
  131. package/dist-lib/cdn/it-D_2eA3dT.js.map +0 -1
  132. package/dist-lib/cdn/nl-dC1zae2Z.js +0 -2
  133. package/dist-lib/cdn/nl-dC1zae2Z.js.map +0 -1
  134. package/dist-lib/cdn/pl-9TYRPoy1.js +0 -2
  135. package/dist-lib/cdn/pl-9TYRPoy1.js.map +0 -1
  136. package/dist-lib/cdn/pt-CvBN-qx1.js +0 -2
  137. package/dist-lib/cdn/pt-CvBN-qx1.js.map +0 -1
  138. package/dist-lib/npm/de-Cuz-uz3s.js.map +0 -1
  139. package/dist-lib/npm/es-BnRzdU90.js.map +0 -1
  140. package/dist-lib/npm/fr-B-nmvStg.js.map +0 -1
  141. package/dist-lib/npm/it-DMTpE4GO.js.map +0 -1
  142. package/dist-lib/npm/nl-DQkyEt9Z.js.map +0 -1
  143. package/dist-lib/npm/pl-CcjU41yx.js.map +0 -1
  144. package/dist-lib/npm/pt-Dulais2f.js.map +0 -1
package/api/openapi.yaml CHANGED
@@ -37,9 +37,36 @@ tags:
37
37
  - name: Chat
38
38
  description: |
39
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”.
40
+ Live updates come over a WebSocket at `{base}/chat/socket`, see the Developer Guide section “Event chat”.
41
+ The same WebSocket carries `{ type: 'event.changed', calendarId, eventId, version, changedBy }` after every change
42
+ to an event (`version` is `null` when it was deleted), see the Developer Guide section “Live updates”.
41
43
  - name: Holidays
44
+ - name: Trash
45
+ description: Deleted events stay in the trash of their calendar for 30 days and can be restored.
46
+ - name: Categories
47
+ description: Categories belong to one calendar. Events carry their ids in `categoryIds`.
48
+ - name: Attachments
49
+ description: Files on events. Only for members of the event's calendar, never through public links or subscriptions.
50
+ - name: Sharing
51
+ description: Public read-only links to a calendar. The `/shared` paths need no session.
42
52
  paths:
53
+ /auth/me/export:
54
+ get:
55
+ tags: [Auth]
56
+ summary: Download the own data (GDPR Art. 20)
57
+ description: |
58
+ Everything stored for the signed-in user as one JSON file: profile, preferences, colors, memberships,
59
+ calendars, the categories of the personal calendar, the events of the personal calendar and those the user
60
+ created elsewhere (also in the trash), own reminders on other events, attendee responses, own chat messages
61
+ and the details of own attachments (without their content). Never password hashes, sessions or tokens,
62
+ and no events or messages of other people. Served with `Content-Disposition: attachment`.
63
+ responses:
64
+ '200':
65
+ description: The export
66
+ content:
67
+ application/json:
68
+ schema: { $ref: '#/components/schemas/AccountExport' }
69
+ '401': { $ref: '#/components/responses/Problem' }
43
70
  /auth/me:
44
71
  get:
45
72
  tags: [Auth]
@@ -375,6 +402,9 @@ paths:
375
402
  description: |
376
403
  The calendar stays the same. Needs `update_any_entry` or, for own events, `update_own_entry`.
377
404
  `409` with `seriesHasDetached` when the recurrence is removed while detached events exist.
405
+ `412` with `eventChanged` when `If-Match` names an older `version`. The response carries the new `version`.
406
+ parameters:
407
+ - $ref: '#/components/parameters/IfMatch'
378
408
  requestBody:
379
409
  required: true
380
410
  content:
@@ -386,14 +416,70 @@ paths:
386
416
  '403': { $ref: '#/components/responses/Problem' }
387
417
  '404': { $ref: '#/components/responses/Problem' }
388
418
  '409': { $ref: '#/components/responses/Problem' }
419
+ '412': { $ref: '#/components/responses/Problem' }
389
420
  delete:
390
421
  tags: [Events]
391
422
  summary: Delete an event
392
- description: Also deletes detached events of a series. Needs `delete_any_entry` or, for own events, `delete_own_entry`.
423
+ description: |
424
+ Moves the event, and the detached events of a series, to the trash of its calendar. They can be restored
425
+ for 30 days, then they are deleted for good with their attachments and chat.
426
+ Needs `delete_any_entry` or, for own events, `delete_own_entry`.
427
+ `412` with `eventChanged` when `If-Match` names an older `version`.
428
+ parameters:
429
+ - $ref: '#/components/parameters/IfMatch'
393
430
  responses:
394
431
  '204': { description: Deleted }
395
432
  '403': { $ref: '#/components/responses/Problem' }
396
433
  '404': { $ref: '#/components/responses/Problem' }
434
+ '412': { $ref: '#/components/responses/Problem' }
435
+ /calendars/{calendarId}/trash:
436
+ parameters:
437
+ - $ref: '#/components/parameters/CalendarId'
438
+ get:
439
+ tags: [Trash]
440
+ summary: Deleted events of a calendar
441
+ description: |
442
+ Newest first, one entry per deletion. Detached events deleted together with their series are not listed on
443
+ their own but counted in `detachedCount`. Entries older than 30 days are deleted for good and no longer listed.
444
+ responses:
445
+ '200':
446
+ description: Deleted events
447
+ content:
448
+ application/json:
449
+ schema:
450
+ type: array
451
+ items: { $ref: '#/components/schemas/TrashedEvent' }
452
+ '404': { $ref: '#/components/responses/Problem' }
453
+ /events/{id}/restore:
454
+ parameters:
455
+ - { name: id, in: path, required: true, schema: { type: string } }
456
+ post:
457
+ tags: [Trash]
458
+ summary: Restore an event from the trash
459
+ description: |
460
+ Restores the event with the same id, its attachments and chat, together with the detached events deleted with it.
461
+ `version` goes up by one. Needs the right to delete the event.
462
+ `409` with `seriesDeleted` when the event is a detached occurrence whose series is still in the trash.
463
+ responses:
464
+ '200': { $ref: '#/components/responses/Event' }
465
+ '403': { $ref: '#/components/responses/Problem' }
466
+ '404': { $ref: '#/components/responses/Problem' }
467
+ '409': { $ref: '#/components/responses/Problem' }
468
+ /trash/{id}:
469
+ parameters:
470
+ - name: id
471
+ in: path
472
+ required: true
473
+ description: Id of the deleted event.
474
+ schema: { type: string }
475
+ delete:
476
+ tags: [Trash]
477
+ summary: Delete an event for good
478
+ description: Removes it from the trash with its detached events, attachments and chat. Needs the right to delete the event.
479
+ responses:
480
+ '204': { description: Deleted for good }
481
+ '403': { $ref: '#/components/responses/Problem' }
482
+ '404': { $ref: '#/components/responses/Problem' }
397
483
  /calendars:
398
484
  get:
399
485
  tags: [Calendars]
@@ -548,7 +634,7 @@ paths:
548
634
  get:
549
635
  tags: [Calendars]
550
636
  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.
637
+ description: No session needed. The calendar as iCalendar with the subscriber's own reminders as alarms and the category names as `CATEGORIES`. `404` when the token is unknown or the user is no longer a member.
552
638
  security: []
553
639
  responses:
554
640
  '200':
@@ -910,6 +996,212 @@ paths:
910
996
  schema: { type: string, pattern: '^[0-9a-fA-F]{6}$' }
911
997
  responses:
912
998
  '200': { $ref: '#/components/responses/Colors' }
999
+ /categories:
1000
+ get:
1001
+ tags: [Categories]
1002
+ summary: Categories of one or more calendars
1003
+ parameters:
1004
+ - name: calendarId
1005
+ in: query
1006
+ required: true
1007
+ description: Repeat the parameter for several calendars.
1008
+ schema: { type: array, items: { type: string } }
1009
+ responses:
1010
+ '200':
1011
+ description: Categories
1012
+ content:
1013
+ application/json:
1014
+ schema: { type: array, items: { $ref: '#/components/schemas/Category' } }
1015
+ '404': { $ref: '#/components/responses/Problem' }
1016
+ /calendars/{calendarId}/categories:
1017
+ parameters:
1018
+ - { $ref: '#/components/parameters/CalendarId' }
1019
+ post:
1020
+ tags: [Categories]
1021
+ summary: Create a category
1022
+ description: Needs `manage_calendars`. `409` with `categoryExists` when the name is taken in this calendar (compared without case), `409` with `tooManyCategories` from 30 categories.
1023
+ requestBody:
1024
+ required: true
1025
+ content:
1026
+ application/json:
1027
+ schema: { $ref: '#/components/schemas/CategoryName' }
1028
+ responses:
1029
+ '201':
1030
+ description: Created
1031
+ content:
1032
+ application/json:
1033
+ schema: { $ref: '#/components/schemas/Category' }
1034
+ '400': { $ref: '#/components/responses/Problem' }
1035
+ '403': { $ref: '#/components/responses/Problem' }
1036
+ '409': { $ref: '#/components/responses/Problem' }
1037
+ /categories/{categoryId}:
1038
+ parameters:
1039
+ - { name: categoryId, in: path, required: true, schema: { type: string } }
1040
+ patch:
1041
+ tags: [Categories]
1042
+ summary: Rename a category
1043
+ description: Needs `manage_calendars`. `409` with `categoryExists` when the name is taken.
1044
+ requestBody:
1045
+ required: true
1046
+ content:
1047
+ application/json:
1048
+ schema: { $ref: '#/components/schemas/CategoryName' }
1049
+ responses:
1050
+ '200':
1051
+ description: Renamed
1052
+ content:
1053
+ application/json:
1054
+ schema: { $ref: '#/components/schemas/Category' }
1055
+ '400': { $ref: '#/components/responses/Problem' }
1056
+ '403': { $ref: '#/components/responses/Problem' }
1057
+ '404': { $ref: '#/components/responses/Problem' }
1058
+ '409': { $ref: '#/components/responses/Problem' }
1059
+ delete:
1060
+ tags: [Categories]
1061
+ summary: Delete a category
1062
+ description: Needs `manage_calendars`. Also removes the category from all events.
1063
+ responses:
1064
+ '204': { description: Deleted }
1065
+ '403': { $ref: '#/components/responses/Problem' }
1066
+ '404': { $ref: '#/components/responses/Problem' }
1067
+ /events/{eventId}/attachments:
1068
+ parameters:
1069
+ - { name: eventId, in: path, required: true, schema: { type: string } }
1070
+ get:
1071
+ tags: [Attachments]
1072
+ summary: Attachments of an event
1073
+ description: For every member who can see the event. A series has one set of attachments for all its occurrences; a detached occurrence has its own.
1074
+ responses:
1075
+ '200':
1076
+ description: Attachments in upload order
1077
+ content:
1078
+ application/json:
1079
+ schema: { type: array, items: { $ref: '#/components/schemas/Attachment' } }
1080
+ '404': { $ref: '#/components/responses/Problem' }
1081
+ post:
1082
+ tags: [Attachments]
1083
+ summary: Upload an attachment
1084
+ description: |
1085
+ Needs `update_any_entry`, or `update_own_entry` for own events. One file per request in the form field `file`.
1086
+ At most 10 MB per file (`413` with `attachmentTooLarge`) and 20 files per event (`409` with `tooManyAttachments`).
1087
+ Keep only the file name from the upload, never a path.
1088
+ requestBody:
1089
+ required: true
1090
+ content:
1091
+ multipart/form-data:
1092
+ schema:
1093
+ type: object
1094
+ required: [file]
1095
+ properties:
1096
+ file: { type: string, format: binary }
1097
+ responses:
1098
+ '201':
1099
+ description: Uploaded
1100
+ content:
1101
+ application/json:
1102
+ schema: { $ref: '#/components/schemas/Attachment' }
1103
+ '400': { $ref: '#/components/responses/Problem' }
1104
+ '403': { $ref: '#/components/responses/Problem' }
1105
+ '404': { $ref: '#/components/responses/Problem' }
1106
+ '409': { $ref: '#/components/responses/Problem' }
1107
+ '413': { $ref: '#/components/responses/Problem' }
1108
+ /attachments/{attachmentId}/content:
1109
+ parameters:
1110
+ - { name: attachmentId, in: path, required: true, schema: { type: string } }
1111
+ get:
1112
+ tags: [Attachments]
1113
+ summary: Download an attachment
1114
+ description: |
1115
+ The file as uploaded. Uploaded files are untrusted: always answer with
1116
+ `Content-Disposition: attachment; filename*=UTF-8''<name>`, `X-Content-Type-Options: nosniff`
1117
+ and `Content-Security-Policy: default-src 'none'; sandbox`, so a browser never shows an uploaded HTML or SVG file as a page of your domain.
1118
+ responses:
1119
+ '200':
1120
+ description: File content
1121
+ content:
1122
+ application/octet-stream:
1123
+ schema: { type: string, format: binary }
1124
+ '404': { $ref: '#/components/responses/Problem' }
1125
+ /attachments/{attachmentId}:
1126
+ parameters:
1127
+ - { name: attachmentId, in: path, required: true, schema: { type: string } }
1128
+ delete:
1129
+ tags: [Attachments]
1130
+ summary: Delete an attachment
1131
+ description: Same rights as uploading. Deleting an event, calendar or team deletes its attachments too.
1132
+ responses:
1133
+ '204': { description: Deleted }
1134
+ '403': { $ref: '#/components/responses/Problem' }
1135
+ '404': { $ref: '#/components/responses/Problem' }
1136
+ /calendars/{calendarId}/share:
1137
+ parameters:
1138
+ - { $ref: '#/components/parameters/CalendarId' }
1139
+ get:
1140
+ tags: [Sharing]
1141
+ summary: Public link of the calendar
1142
+ description: Needs `manage_calendars`. There is one link per calendar, shared by everyone who may manage it.
1143
+ responses:
1144
+ '200':
1145
+ description: Token or null
1146
+ content:
1147
+ application/json:
1148
+ schema: { type: object, required: [token], properties: { token: { oneOf: [{ type: string }, { type: 'null' }] } } }
1149
+ '403': { $ref: '#/components/responses/Problem' }
1150
+ '404': { $ref: '#/components/responses/Problem' }
1151
+ post:
1152
+ tags: [Sharing]
1153
+ summary: Create a new public link
1154
+ description: Replaces an existing link, which stops working at once. The token must not be guessable.
1155
+ responses:
1156
+ '201':
1157
+ description: New token
1158
+ content:
1159
+ application/json:
1160
+ schema: { type: object, required: [token], properties: { token: { type: string } } }
1161
+ '403': { $ref: '#/components/responses/Problem' }
1162
+ delete:
1163
+ tags: [Sharing]
1164
+ summary: Stop sharing
1165
+ responses:
1166
+ '204': { description: Stopped }
1167
+ '403': { $ref: '#/components/responses/Problem' }
1168
+ /shared/{token}:
1169
+ parameters:
1170
+ - { name: token, in: path, required: true, schema: { type: string } }
1171
+ get:
1172
+ tags: [Sharing]
1173
+ summary: A shared calendar
1174
+ description: No session needed. `404` with `shareNotFound` when the token is unknown or sharing was stopped.
1175
+ security: []
1176
+ responses:
1177
+ '200':
1178
+ description: Name, color and categories
1179
+ content:
1180
+ application/json:
1181
+ schema: { $ref: '#/components/schemas/SharedCalendar' }
1182
+ '404': { $ref: '#/components/responses/Problem' }
1183
+ /shared/{token}/events:
1184
+ parameters:
1185
+ - { name: token, in: path, required: true, schema: { type: string } }
1186
+ get:
1187
+ tags: [Sharing]
1188
+ summary: Events of a shared calendar
1189
+ description: |
1190
+ No session needed. Same rules for the range as `GET /events`.
1191
+ Leave out everything personal: `attendees` and `reminders` are always empty, `createdBy` is omitted or null.
1192
+ Chat messages are never available through a public link.
1193
+ security: []
1194
+ parameters:
1195
+ - { name: from, in: query, required: true, schema: { $ref: '#/components/schemas/ISODate' } }
1196
+ - { name: to, in: query, required: true, schema: { $ref: '#/components/schemas/ISODate' } }
1197
+ responses:
1198
+ '200':
1199
+ description: Events
1200
+ content:
1201
+ application/json:
1202
+ schema: { type: array, items: { $ref: '#/components/schemas/CalendarEvent' } }
1203
+ '400': { $ref: '#/components/responses/Problem' }
1204
+ '404': { $ref: '#/components/responses/Problem' }
913
1205
  components:
914
1206
  securitySchemes:
915
1207
  sessionCookie:
@@ -926,6 +1218,14 @@ components:
926
1218
  required: false
927
1219
  description: Public tenant id. Sent by `tenantDataSource` on every request.
928
1220
  schema: { type: string }
1221
+ IfMatch:
1222
+ name: If-Match
1223
+ in: header
1224
+ required: false
1225
+ description: |
1226
+ The `version` the client last saw, in quotes (`"3"`). The server answers `412` with `eventChanged`
1227
+ when the event has a newer version. Missing or `*` skips the check, for example for "save anyway".
1228
+ schema: { type: string, example: '"3"' }
929
1229
  CalendarId:
930
1230
  name: calendarId
931
1231
  in: path
@@ -1053,6 +1353,12 @@ components:
1053
1353
  default: []
1054
1354
  items: { $ref: '#/components/schemas/EventLink' }
1055
1355
  description: Website and other links. Only http and https addresses are accepted.
1356
+ categoryIds:
1357
+ type: array
1358
+ maxItems: 5
1359
+ default: []
1360
+ items: { type: string }
1361
+ description: Categories of the event. Every id must belong to the calendar of the event, otherwise `400`.
1056
1362
  startDate: { $ref: '#/components/schemas/ISODate' }
1057
1363
  start: { $ref: '#/components/schemas/Time' }
1058
1364
  endDate: { $ref: '#/components/schemas/ISODate' }
@@ -1088,6 +1394,28 @@ components:
1088
1394
  maxItems: 100
1089
1395
  default: []
1090
1396
  items: { $ref: '#/components/schemas/Attendee' }
1397
+ Category:
1398
+ type: object
1399
+ required: [id, calendarId, name]
1400
+ properties:
1401
+ id: { type: string }
1402
+ calendarId: { type: string }
1403
+ name: { type: string, minLength: 1, maxLength: 40 }
1404
+ CategoryName:
1405
+ type: object
1406
+ required: [name]
1407
+ properties:
1408
+ name: { type: string, minLength: 1, maxLength: 40 }
1409
+ SharedCalendar:
1410
+ type: object
1411
+ required: [id, name, color, categories]
1412
+ properties:
1413
+ id: { type: string }
1414
+ name: { type: string }
1415
+ color: { type: string }
1416
+ categories:
1417
+ type: array
1418
+ items: { $ref: '#/components/schemas/Category' }
1091
1419
  EventLink:
1092
1420
  type: object
1093
1421
  required: [url]
@@ -1108,13 +1436,76 @@ components:
1108
1436
  allOf:
1109
1437
  - $ref: '#/components/schemas/EventInput'
1110
1438
  - type: object
1111
- required: [id, calendarId, createdBy, createdAt, updatedAt]
1439
+ required: [id, calendarId, createdBy, createdAt, updatedAt, version]
1112
1440
  properties:
1113
1441
  id: { type: string }
1442
+ version:
1443
+ type: integer
1444
+ minimum: 1
1445
+ description: |
1446
+ Starts at 1 and goes up on every change by a person (PUT, attendee response, removed category).
1447
+ Own reminders do not change it. Read-only, ignored on input.
1114
1448
  calendarId: { type: string }
1115
1449
  createdBy: { oneOf: [{ type: string }, { type: 'null' }] }
1116
1450
  createdAt: { type: string, format: date-time }
1117
1451
  updatedAt: { type: string, format: date-time }
1452
+ attachmentCount:
1453
+ type: integer
1454
+ minimum: 0
1455
+ default: 0
1456
+ description: Number of attachments of this event. Read-only, ignored on input. 0 in public links.
1457
+ AccountExport:
1458
+ type: object
1459
+ required: [format, version, exportedAt, user]
1460
+ properties:
1461
+ format: { type: string, const: calendar-account-export }
1462
+ version: { type: integer, const: 1 }
1463
+ exportedAt: { type: string, format: date-time }
1464
+ user: { $ref: '#/components/schemas/User' }
1465
+ preferences: { type: object }
1466
+ colors: { type: array, items: { type: string } }
1467
+ memberships: { type: array, items: { type: object } }
1468
+ calendars: { type: array, items: { type: object } }
1469
+ categories: { type: array, items: { type: object } }
1470
+ events: { type: array, items: { $ref: '#/components/schemas/CalendarEvent' } }
1471
+ trash: { type: array, items: { type: object } }
1472
+ reminders: { type: array, items: { type: object } }
1473
+ responses: { type: array, items: { type: object } }
1474
+ chatMessages: { type: array, items: { type: object } }
1475
+ attachments: { type: array, items: { type: object } }
1476
+ additionalProperties: true
1477
+ TrashedEvent:
1478
+ type: object
1479
+ required: [event, deletedAt, deletedBy, deletedByName, expiresAt, detachedCount]
1480
+ properties:
1481
+ event: { $ref: '#/components/schemas/CalendarEvent' }
1482
+ deletedAt: { type: string, format: date-time }
1483
+ deletedBy: { oneOf: [{ type: string }, { type: 'null' }] }
1484
+ deletedByName: { oneOf: [{ type: string }, { type: 'null' }] }
1485
+ expiresAt:
1486
+ type: string
1487
+ format: date-time
1488
+ description: When the event is deleted for good, 30 days after `deletedAt`.
1489
+ detachedCount:
1490
+ type: integer
1491
+ minimum: 0
1492
+ description: Detached events that were deleted together with this series and come back with it.
1493
+ Attachment:
1494
+ type: object
1495
+ required: [id, eventId, name, type, size, createdAt, uploadedBy]
1496
+ properties:
1497
+ id: { type: string }
1498
+ eventId: { type: string }
1499
+ name: { type: string, maxLength: 200, description: 'File name without any path' }
1500
+ type: { type: string, description: 'Media type as uploaded, application/octet-stream when unknown' }
1501
+ size: { type: integer, minimum: 1, maximum: 10485760 }
1502
+ createdAt: { type: string, format: date-time }
1503
+ uploadedBy:
1504
+ oneOf:
1505
+ - type: object
1506
+ required: [id, name]
1507
+ properties: { id: { type: string }, name: { type: string } }
1508
+ - type: 'null'
1118
1509
  TeamRole:
1119
1510
  type: string
1120
1511
  enum: [owner, admin, manager, editor, member, contributor, viewer]
@@ -0,0 +1,183 @@
1
+ {
2
+ "$schema": "https://unpkg.com/@rokoyfa/calendar/schema/calendar-config.schema.json",
3
+
4
+ // Example configuration for @rokoyfa/calendar.
5
+ //
6
+ // <calendar-widget config="/calendar.config.jsonc"></calendar-widget>
7
+ // <Calendar config="/calendar.config.jsonc" />
8
+ //
9
+ // Every entry is optional. Leave out what you do not need, the value shown here is
10
+ // the default unless a comment says otherwise. Props and attributes on the page win
11
+ // over this file. The file is public like everything a browser loads: no secrets.
12
+ //
13
+ // Comments are allowed in .json and .jsonc files. The last entry of an object must
14
+ // not end with a comma.
15
+
16
+ // ── Data ──────────────────────────────────────────────────────────────────────
17
+
18
+ // Where events are stored.
19
+ // local in the visitor's browser, no backend needed
20
+ // remote in your backend (see the Developer Guide, "Backend")
21
+ // With features.auth the sign-in decides: signed-in users use the backend, guests the browser.
22
+ "storageMode": "local",
23
+
24
+ // Base URL of your backend. Relative ("/api") or absolute ("https://api.example.com").
25
+ // Only used with storageMode "remote" or features.auth.
26
+ "apiBaseUrl": "/api",
27
+
28
+ // How long a request to the backend may take, in milliseconds.
29
+ "apiTimeoutMs": 10000,
30
+
31
+ // Multi-tenant backends: sent with every request as the X-Calendar-Tenant header.
32
+ // Setting it turns sign-in on. Default: not set.
33
+ // "tenant": "acme",
34
+
35
+ // ── Features ──────────────────────────────────────────────────────────────────
36
+ // Everything beyond the core calendar can be switched off. A feature that is off
37
+ // disappears from the interface and makes no requests to the backend.
38
+
39
+ "features": {
40
+ // Sign-in, registration and account pages. Needs the /auth endpoints.
41
+ "auth": false,
42
+
43
+ // Team calendars with members, roles and invitations. Needs sign-in.
44
+ "teams": true,
45
+
46
+ // Chat per event in team calendars. Needs teams, the chat endpoints and the WebSocket.
47
+ "chat": true,
48
+
49
+ // Inviting team members to events and answering with yes, maybe or no. Needs teams.
50
+ "attendees": true,
51
+
52
+ // Creating and editing recurring events. Existing series are still shown when off.
53
+ "recurrence": true,
54
+
55
+ // Reminders on events, shown as browser notifications or notices in the calendar.
56
+ "reminders": true,
57
+
58
+ // Website and other links on events.
59
+ "links": true,
60
+
61
+ // Opening an event's location in a map service (see mapUrl).
62
+ "mapLinks": true,
63
+
64
+ // Public holidays in the views, and their setting.
65
+ "holidays": true,
66
+
67
+ // Event search.
68
+ "search": true,
69
+
70
+ // Undo after moving or deleting an event. When off, deleting asks for confirmation.
71
+ "undo": true,
72
+
73
+ // "Duplicate" in the event dialog.
74
+ "duplicate": true,
75
+
76
+ // Keyboard shortcuts (T today, N new event, / search, D W M Y views, arrow keys).
77
+ "shortcuts": true,
78
+
79
+ // Subscription links for other calendar apps. Needs the feed endpoints.
80
+ "subscriptions": true,
81
+
82
+ // Import and export of .ics files in the calendar settings.
83
+ "importExport": true,
84
+
85
+ // The "Notifications" tab where signed-in users choose which e-mails they get.
86
+ // Your backend sends the e-mails.
87
+ "emailNotifications": true,
88
+
89
+ // Time zone per event and in the settings. When off, the automatic zone is always used.
90
+ "timeZones": true,
91
+
92
+ // Letting users add their own event colors.
93
+ "customColors": true,
94
+
95
+ // Categories per calendar: assigning them to events and filtering the views by them.
96
+ // Needs the category endpoints.
97
+ "categories": true,
98
+
99
+ // Public read-only links to a calendar, and the page they open. Needs the share endpoints.
100
+ "publicLinks": true,
101
+
102
+ // Files on events: upload in the event dialog, download by anyone who can see the event.
103
+ // Needs the attachment endpoints. Not available in local mode.
104
+ "attachments": true,
105
+
106
+ // Shows changes made by other people, or in other tabs, at once without reloading.
107
+ // Uses the WebSocket of the backend (the same one as the chat). In local mode it follows other tabs.
108
+ "liveUpdates": true,
109
+
110
+ // Trash in the calendar settings: deleted events can be restored for 30 days.
111
+ // Needs the trash endpoints with a backend.
112
+ "trash": true,
113
+
114
+ // "Data" tab in the settings to download one's own data as a JSON file (GDPR Art. 20).
115
+ // Signed in it needs GET /auth/me/export; in local mode it exports what the browser stores.
116
+ "dataExport": true
117
+ },
118
+
119
+ // Shows events without letting anyone create, change, move, delete or import them.
120
+ "readOnly": false,
121
+
122
+ // ── Appearance ────────────────────────────────────────────────────────────────
123
+
124
+ // Views the user can switch between, any of: day, week, month, year.
125
+ // With a single view the switch disappears.
126
+ "views": ["day", "week", "month", "year"],
127
+
128
+ // View shown first. Default: the user's own start view (week on desktop, day on phones).
129
+ // "initialView": "month",
130
+
131
+ // Language and region, e.g. en-US, de-DE, fr-FR, pt-BR. Default: the browser's language.
132
+ // Users can change it in the settings.
133
+ // "locale": "de-DE",
134
+
135
+ // Theme while the user has chosen "system": light or dark. Default: follows the device.
136
+ // "theme": "dark",
137
+
138
+ // IANA time zone the calendar is shown in while the user has chosen "automatic".
139
+ // Default: the browser's zone.
140
+ // "timeZone": "Europe/Berlin",
141
+
142
+ // Region for public holidays: a country (DE, AT, US) or a region (DE-NW, US-CA), or "off".
143
+ // Default: derived from the language. Users can override it in the settings.
144
+ // "holidays": "DE-NW",
145
+
146
+ // Where public holidays come from.
147
+ // library computed in the browser
148
+ // backend asked from your backend (GET /holidays), falling back to the library
149
+ "holidaySource": "library",
150
+
151
+ // Map service for locations. {query} is replaced by the place. Default: Google Maps.
152
+ // "mapUrl": "https://www.openstreetmap.org/search?query={query}",
153
+
154
+ // Look of the calendar. The same can be set from your CSS with --calendar-accent,
155
+ // --calendar-font and --calendar-radius on the element. Default: not set.
156
+ // accentColor buttons, links, today, selection
157
+ // fontFamily your page has to load the font
158
+ // radius corner radius in pixels, 0 to 24
159
+ // density comfortable or compact (smaller text, rows and spacing)
160
+ // "appearance": { "accentColor": "#e63946", "fontFamily": "Inter, sans-serif", "radius": 10, "density": "comfortable" },
161
+
162
+ // Own texts per language. Only plain texts can be set here. Texts that are functions
163
+ // (for example with a count) need the "messages" prop or property instead.
164
+ // "messages": { "de": { "calendar": { "newEvent": "Neuer Eintrag" } } },
165
+
166
+ // ── Navigation ────────────────────────────────────────────────────────────────
167
+
168
+ // How the calendar's own pages (settings, sign-in, …) are addressed.
169
+ // memory inside the widget, the address bar stays untouched (right for embedding)
170
+ // browser in the address bar, when the calendar is the whole page
171
+ "routing": "memory",
172
+
173
+ // Path prefix for routing "browser", when the calendar does not live at "/". Default: none.
174
+ // "basename": "/calendar",
175
+
176
+ // Page the widget opens on. Default: the calendar itself.
177
+ // "initialPath": "/settings",
178
+
179
+ // Query parameter of your page that links from e-mails use to open a page of the widget,
180
+ // e.g. https://example.com/team?calendarPath=%2Freset-password%3Ftoken%3D…
181
+ // Set to false to turn it off. Only used with routing "memory".
182
+ "linkParam": "calendarPath"
183
+ }