@wtfalch/calendar 0.1.0 → 0.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.
- package/README.md +4 -0
- package/dist/calendar/calendar-client.js +574 -19
- package/dist/calendar/calendar.css +13 -0
- package/dist/calendar/client.d.ts +27 -0
- package/dist/calendar/client.js +101 -0
- package/dist/calendar/fake/sample.d.ts +2 -1
- package/dist/calendar/fake/store.d.ts +51 -8
- package/dist/calendar/fake/store.js +539 -47
- package/dist/calendar/find-time.d.ts +17 -0
- package/dist/calendar/find-time.js +198 -0
- package/dist/calendar/ics.d.ts +73 -0
- package/dist/calendar/ics.js +586 -0
- package/dist/calendar/index.d.ts +3 -1
- package/dist/calendar/index.js +1 -0
- package/dist/calendar/react/Calendar.js +36 -27
- package/dist/calendar/react/EventDetail.js +22 -1
- package/dist/calendar/react/EventEditor.js +65 -3
- package/dist/calendar/types.d.ts +550 -17
- package/dist/calendar/wire.d.ts +161 -5
- package/dist/calendar/wire.js +304 -4
- package/package.json +2 -2
package/dist/calendar/types.d.ts
CHANGED
|
@@ -29,17 +29,30 @@ export type CalendarClientOptions = {
|
|
|
29
29
|
* assembles. Mirrors `MailClientOptions.sessionUrl` (plan §7; #143 §2). */
|
|
30
30
|
sessionUrl: string;
|
|
31
31
|
/**
|
|
32
|
-
* A callback returning the current
|
|
33
|
-
* `
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
32
|
+
* A callback returning the current token, mirroring `createChatClient`'s
|
|
33
|
+
* `getAccessToken` rather than `MailClientOptions`'s static `bearerToken`
|
|
34
|
+
* — every first-ship feature is a live browser-to-Stalwart call (plan §7;
|
|
35
|
+
* #143 §2), and only a callback survives a mid-session token refresh with
|
|
36
|
+
* no host-app code.
|
|
37
|
+
*
|
|
38
|
+
* **This is also how a host constructs a client against a service
|
|
39
|
+
* credential for someone else's account** (wtfalch/calendar#65,
|
|
40
|
+
* https://github.com/wtfalch/activity's own `jmap.ts` and its per-account
|
|
41
|
+
* Stalwart credential map, issue #34 decision 1): the callback needs no
|
|
42
|
+
* refresh logic to be valid here, a plain `() => credential` closing over
|
|
43
|
+
* one held string is enough, paired with `accountId` below naming whose
|
|
44
|
+
* account it reads. This package holds no credential of its own — the
|
|
45
|
+
* caller's is a browser access token, a service credential, or anything
|
|
46
|
+
* else that answers the session's bearer check — and never caches one
|
|
47
|
+
* past a single call (`CalendarConnection`'s own doc comment).
|
|
37
48
|
*/
|
|
38
49
|
getAccessToken: () => string | Promise<string>;
|
|
39
50
|
/** Override the session's primary account. Needed because a JMAP session
|
|
40
51
|
* can carry more than one account; the client must pick the one with the
|
|
41
52
|
* `calendars` capability (plan §7; #143 §2, mirroring
|
|
42
|
-
* `MailClientOptions.accountId`).
|
|
53
|
+
* `MailClientOptions.accountId`). Also what points a service-credential
|
|
54
|
+
* connection at another person's account rather than the credential's
|
|
55
|
+
* own, when one is held at all (wtfalch/calendar#65). */
|
|
43
56
|
accountId?: string;
|
|
44
57
|
};
|
|
45
58
|
/** One JMAP ACL right a calendar's `shareWith` grant can carry (#138 §1,
|
|
@@ -124,24 +137,170 @@ export type CalendarParticipant = {
|
|
|
124
137
|
roles?: readonly CalendarParticipantRole[];
|
|
125
138
|
participationStatus?: CalendarParticipationStatus;
|
|
126
139
|
};
|
|
140
|
+
/** RFC 5545's two-letter weekday abbreviation, as JSCalendar's `NDay.day`
|
|
141
|
+
* and `RecurrenceRule.firstDayOfWeek` name it (RFC 8984 §3.3). */
|
|
142
|
+
export type CalendarWeekday = 'mo' | 'tu' | 'we' | 'th' | 'fr' | 'sa' | 'su';
|
|
143
|
+
/**
|
|
144
|
+
* One weekday entry in a rule's `byDay`: RFC 8984 §3.3's `NDay`. A bare
|
|
145
|
+
* weekday (`{day: 'tu'}`) means every occurrence of that weekday in the
|
|
146
|
+
* period the rule's `frequency` sweeps; `nthOfPeriod` narrows it to one
|
|
147
|
+
* instance -- the 2nd Tuesday of the month is `{day: 'tu', nthOfPeriod: 2}`,
|
|
148
|
+
* the last Friday is `{day: 'fr', nthOfPeriod: -1}` (RFC 5545 §3.3.10's
|
|
149
|
+
* `BYDAY`, RFC 8984 §3.3).
|
|
150
|
+
*/
|
|
151
|
+
export type CalendarNDay = {
|
|
152
|
+
day: CalendarWeekday;
|
|
153
|
+
nthOfPeriod?: number;
|
|
154
|
+
};
|
|
127
155
|
/**
|
|
128
|
-
* A recurrence rule, RFC
|
|
156
|
+
* A recurrence rule, RFC 8984 §3.3 (`RecurrenceRule`) shaped -- every part
|
|
157
|
+
* that section defines, not only the bounds (`interval`/`count`/`until`).
|
|
158
|
+
* Dropping any of these on read, or on a 'this and following' split, quietly
|
|
159
|
+
* corrupts the rule for every JMAP client sharing the account
|
|
160
|
+
* (wtfalch/calendar#27): a `BYDAY`/`BYMONTHDAY`/`BYSETPOS`/`WKST`-carrying
|
|
161
|
+
* series that loses these the moment either half of a split is written back
|
|
162
|
+
* degrades to "every N days/weeks/months/years" with none of what actually
|
|
163
|
+
* picked its occurrences.
|
|
129
164
|
*
|
|
130
165
|
* `recurrenceRule` — confirmed live: the wire uses this singular field name
|
|
131
166
|
* (one rule), not JSCalendar 2.0's plural `recurrenceRules` (MSG-053
|
|
132
167
|
* acceptance criteria; plan §7; #137 amendment). The client never expands
|
|
133
168
|
* this itself: expansion is entirely server-side (plan §7; #137
|
|
134
|
-
* "Recurrence"), so this type exists only to display
|
|
135
|
-
* to compute occurrences from it.
|
|
169
|
+
* "Recurrence"), so this type exists only to display, edit and round-trip
|
|
170
|
+
* the rule, not to compute occurrences from it.
|
|
136
171
|
*/
|
|
137
172
|
export type CalendarRecurrenceRule = {
|
|
138
173
|
frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
|
|
139
174
|
interval?: number;
|
|
175
|
+
/** The calendar scale the rule's dates are computed in (RFC 8984 §3.3);
|
|
176
|
+
* every rule seen live has been `'gregorian'`, the default, but a value
|
|
177
|
+
* another client wrote must still round-trip rather than being dropped. */
|
|
178
|
+
rscale?: string;
|
|
179
|
+
/** How an invalid date produced by `byMonthDay`/`byMonth` (e.g. Feb 30) is
|
|
180
|
+
* handled: omit that occurrence, or roll it backward/forward to the
|
|
181
|
+
* nearest valid date (RFC 8984 §3.3). */
|
|
182
|
+
skip?: 'omit' | 'backward' | 'forward';
|
|
183
|
+
/** The weekday a week is considered to start on, for `weekly`'s own
|
|
184
|
+
* interval counting and for resolving `byWeekNo` (RFC 5545 §3.3.10's
|
|
185
|
+
* `WKST`, RFC 8984 §3.3). Defaults to `'mo'` when absent. */
|
|
186
|
+
firstDayOfWeek?: CalendarWeekday;
|
|
187
|
+
/** Which weekdays, optionally the Nth one of the period (RFC 5545's
|
|
188
|
+
* `BYDAY`). */
|
|
189
|
+
byDay?: readonly CalendarNDay[];
|
|
190
|
+
/** Which days of the month, 1-31 or negative counting from the end (RFC
|
|
191
|
+
* 5545's `BYMONTHDAY`). */
|
|
192
|
+
byMonthDay?: readonly number[];
|
|
193
|
+
/** Which months, as a string so a leap month can carry an `'L'` suffix
|
|
194
|
+
* (e.g. `'3L'`) for calendar scales that have one (RFC 5545's `BYMONTH`,
|
|
195
|
+
* RFC 8984 §3.3). */
|
|
196
|
+
byMonth?: readonly string[];
|
|
197
|
+
/** Which days of the year, 1-366 or negative counting from the end (RFC
|
|
198
|
+
* 5545's `BYYEARDAY`). */
|
|
199
|
+
byYearDay?: readonly number[];
|
|
200
|
+
/** Which weeks of the year (RFC 5545's `BYWEEKNO`; `yearly` only). */
|
|
201
|
+
byWeekNo?: readonly number[];
|
|
202
|
+
byHour?: readonly number[];
|
|
203
|
+
byMinute?: readonly number[];
|
|
204
|
+
bySecond?: readonly number[];
|
|
205
|
+
/** Which of the occurrences generated by the rest of the rule to keep --
|
|
206
|
+
* "the 2nd Tuesday and last Friday of every month with a meeting" is
|
|
207
|
+
* `byDay` naming both weekdays and `bySetPosition: [1, -1]` picking the
|
|
208
|
+
* first and last of each month's matches (RFC 5545's `BYSETPOS`, RFC 8984
|
|
209
|
+
* §3.3's `bySetPosition`). */
|
|
210
|
+
bySetPosition?: readonly number[];
|
|
140
211
|
count?: number;
|
|
141
212
|
until?: string;
|
|
142
213
|
};
|
|
143
214
|
/** RFC 5545 `STATUS`, as JSCalendar's `Event.status` names it. */
|
|
144
215
|
export type CalendarEventStatus = 'confirmed' | 'cancelled' | 'tentative';
|
|
216
|
+
/**
|
|
217
|
+
* RFC 5545 §3.8.2.7 `TRANSP`, as JSCalendar's `Event.freeBusyStatus` names
|
|
218
|
+
* it (RFC 8984 §4.4.1): whether this event counts as busy time for its
|
|
219
|
+
* owner's free/busy search. `'busy'` is the default when absent -- an
|
|
220
|
+
* optional webinar or a tentative hold that should not produce a false
|
|
221
|
+
* conflict in `findTime()` is the one that sets `'free'`
|
|
222
|
+
* (wtfalch/calendar#29).
|
|
223
|
+
*/
|
|
224
|
+
export type CalendarFreeBusyStatus = 'free' | 'busy';
|
|
225
|
+
/** JSCalendar `Alert.action` (RFC 8984 §5.7). Only `'display'` is built --
|
|
226
|
+
* the ticket that added `alerts` (issue #15) scopes email out -- but an
|
|
227
|
+
* `'email'` alert another client wrote is read and written back unchanged,
|
|
228
|
+
* live-confirmed against Stalwart v0.16.20, so the type names it. */
|
|
229
|
+
export type CalendarAlertAction = 'display' | 'email';
|
|
230
|
+
/** JSCalendar `OffsetTrigger.relativeTo` (RFC 8984 §5.6): whether `offset`
|
|
231
|
+
* counts from the event's start or its end. Optional because a live
|
|
232
|
+
* `CalendarEvent/get` never sent it back when the create never sent it
|
|
233
|
+
* either -- the server does not fill in its own default (T15). */
|
|
234
|
+
export type CalendarAlertRelativeTo = 'start' | 'end';
|
|
235
|
+
/**
|
|
236
|
+
* One alert on an event: a JSCalendar `Alert`. `offset` is a relative
|
|
237
|
+
* trigger, an ISO 8601 signed duration (e.g. `-PT15M` to fire 15 minutes
|
|
238
|
+
* before `relativeTo`); `when` is an absolute one, an ISO 8601 UTC
|
|
239
|
+
* date-time. At most one of the two is meaningful for a given alert. Both
|
|
240
|
+
* are live-confirmed against Stalwart v0.16.20 to round-trip through
|
|
241
|
+
* `CalendarEvent/set`/`get` with no shape change (T15).
|
|
242
|
+
*
|
|
243
|
+
* Neither is set when this package could not read the trigger, or when
|
|
244
|
+
* there was none to read -- live-confirmed possible: a trigger written
|
|
245
|
+
* with neither `offset` nor `when` is accepted on write, but the next `get`
|
|
246
|
+
* returns that alert with no `trigger` key at all (T15 amendment, a
|
|
247
|
+
* refuter finding). Writing such an alert back must not fabricate a
|
|
248
|
+
* trigger either -- `alertToWire` omits the key entirely, the same way the
|
|
249
|
+
* server does, rather than emit an empty or partial one.
|
|
250
|
+
*/
|
|
251
|
+
export type CalendarAlert = {
|
|
252
|
+
/** The wire's own map key, present on an alert read off the server and
|
|
253
|
+
* reused on write-back. `CalendarEvent/set` replaces the *whole*
|
|
254
|
+
* `alerts` map on any write that touches it, so a client that renumbers
|
|
255
|
+
* keys on every save also renames them server-side -- out from under
|
|
256
|
+
* the dedicated `CalendarAlert` push channel
|
|
257
|
+
* (`CalendarChangedState.CalendarAlert`) and anything else that
|
|
258
|
+
* correlates by this id (T15 amendment). Absent for an alert the caller
|
|
259
|
+
* builds fresh; `alertsToWire` assigns one, the same way
|
|
260
|
+
* `participantsToWire` does for a participant. */
|
|
261
|
+
id?: string;
|
|
262
|
+
offset?: string;
|
|
263
|
+
when?: string;
|
|
264
|
+
relativeTo?: CalendarAlertRelativeTo;
|
|
265
|
+
action: CalendarAlertAction;
|
|
266
|
+
/** When the person last dismissed this alert -- an ISO 8601 UTC
|
|
267
|
+
* date-time the server stores and returns verbatim; this package never
|
|
268
|
+
* computes or clears it, only carries it forward. Because
|
|
269
|
+
* `CalendarEvent/set` replaces the whole `alerts` map, a mapper that
|
|
270
|
+
* silently drops this field on the way out wipes every alert's
|
|
271
|
+
* acknowledgement the moment anything touches `alerts` again -- live-
|
|
272
|
+
* confirmed (T15 amendment, a refuter finding). */
|
|
273
|
+
acknowledged?: string;
|
|
274
|
+
};
|
|
275
|
+
/**
|
|
276
|
+
* A join link into the call an event is, or hosts -- JSCalendar's
|
|
277
|
+
* `VirtualLocation` (RFC 8984 §4.2.6), the convention
|
|
278
|
+
* https://github.com/wtfalch/agora/issues/163 reserved. `uri` is the join
|
|
279
|
+
* link itself (a video-call URL, a SIP URI, a phone number as `tel:`); `name`
|
|
280
|
+
* is a label for it ("Join by video"). Separate from `CalendarEvent.location`
|
|
281
|
+
* on purpose: that field stays a plain string for the physical place, this
|
|
282
|
+
* one is the call (#16).
|
|
283
|
+
*/
|
|
284
|
+
export type CalendarVirtualLocation = {
|
|
285
|
+
uri: string;
|
|
286
|
+
name?: string;
|
|
287
|
+
};
|
|
288
|
+
/**
|
|
289
|
+
* A link on an event: an agenda doc, a shared file, any URL the meeting
|
|
290
|
+
* should carry. This is JSCalendar's `Link` (RFC 8984 §1.4.11), the value
|
|
291
|
+
* type of `Event.links` (§4.2.5) (wtfalch/calendar#32). `href` is the link
|
|
292
|
+
* itself. `rel: 'enclosure'` marks it as an attachment rather than a
|
|
293
|
+
* related page. `contentType`/`size` describe the linked file when known.
|
|
294
|
+
* Uploading the file is the caller's job; this package only carries the
|
|
295
|
+
* reference.
|
|
296
|
+
*/
|
|
297
|
+
export type CalendarLink = {
|
|
298
|
+
href: string;
|
|
299
|
+
title?: string;
|
|
300
|
+
contentType?: string;
|
|
301
|
+
size?: number;
|
|
302
|
+
rel?: string;
|
|
303
|
+
};
|
|
145
304
|
/**
|
|
146
305
|
* One event, or one occurrence of a recurring event.
|
|
147
306
|
*
|
|
@@ -172,18 +331,57 @@ export type CalendarEvent = {
|
|
|
172
331
|
/** An ISO 8601 duration, e.g. `PT1H`. */
|
|
173
332
|
duration: string;
|
|
174
333
|
isAllDay: boolean;
|
|
334
|
+
/** The physical place, a plain string. A join link into a call is a
|
|
335
|
+
* separate property, `virtualLocations` (#16). */
|
|
175
336
|
location?: string;
|
|
337
|
+
/**
|
|
338
|
+
* Join links into a call the event is or hosts (#16, `CalendarVirtualLocation`'s
|
|
339
|
+
* own doc comment). Live-confirmed against Stalwart v0.16.20: the server
|
|
340
|
+
* round-trips this like any other property, but only when `get`'s
|
|
341
|
+
* `properties` names it explicitly -- omitted from an explicit list (as
|
|
342
|
+
* `EVENT_GET_PROPERTIES` was before this ticket), it silently drops out of
|
|
343
|
+
* the response even though the value is still stored, the same trap
|
|
344
|
+
* `wire.ts`'s header comment already logs for `recurrenceId`/`baseEventId`.
|
|
345
|
+
* A raw `CalendarEvent/set update` that never mentions this property, from
|
|
346
|
+
* this client or any other, leaves it untouched on the server.
|
|
347
|
+
*/
|
|
348
|
+
virtualLocations?: readonly CalendarVirtualLocation[];
|
|
349
|
+
/** Links and attachments on the event (wtfalch/calendar#32,
|
|
350
|
+
* `CalendarLink`). Absent rather than empty when it has none. */
|
|
351
|
+
links?: readonly CalendarLink[];
|
|
176
352
|
recurrenceRule?: CalendarRecurrenceRule;
|
|
177
353
|
participants?: readonly CalendarParticipant[];
|
|
354
|
+
/** JSCalendar `mayInviteSelf` (draft-ietf-jmap-calendars §5.1.1): whether a
|
|
355
|
+
* participant may add themselves to the event. Off by default -- the
|
|
356
|
+
* owner's 2026-09-27 decision (wtfalch/calendar#51). */
|
|
357
|
+
mayInviteSelf?: boolean;
|
|
358
|
+
/** JSCalendar `mayInviteOthers` (draft-ietf-jmap-calendars §5.1.2): the
|
|
359
|
+
* "Guests can invite others" setting -- whether a participant may add
|
|
360
|
+
* further participants. Off by default (wtfalch/calendar#51). */
|
|
361
|
+
mayInviteOthers?: boolean;
|
|
362
|
+
/** Reminders on this event -- a JSCalendar `alerts` map, flattened to a
|
|
363
|
+
* list the way `participants` already is (`wire.ts`'s `alertsToWire`
|
|
364
|
+
* assigns the wire's arbitrary map keys, mirroring `participantsToWire`).
|
|
365
|
+
* Absent rather than empty when the event has none (T15). */
|
|
366
|
+
alerts?: readonly CalendarAlert[];
|
|
178
367
|
status: CalendarEventStatus;
|
|
368
|
+
/** Absent reads as `'busy'`, RFC 8984 §4.4.1's own default -- so an event
|
|
369
|
+
* from before this field existed, or from any other client that never
|
|
370
|
+
* set it, keeps counting as busy exactly as it always has
|
|
371
|
+
* (wtfalch/calendar#29). */
|
|
372
|
+
freeBusyStatus?: CalendarFreeBusyStatus;
|
|
179
373
|
/** RFC 5545 `SEQUENCE`, bumped on every organizer edit an attendee's
|
|
180
374
|
* client should treat as superseding its own copy. */
|
|
181
375
|
sequence: number;
|
|
182
376
|
/** Set only on an expanded occurrence (see above); absent on a master
|
|
183
377
|
* event or a non-recurring one. */
|
|
184
378
|
recurrenceId?: string;
|
|
185
|
-
/** The
|
|
186
|
-
* expanded occurrence.
|
|
379
|
+
/** The top-level event this id traces back to: the master, on an
|
|
380
|
+
* expanded occurrence -- and, live-confirmed against Stalwart v0.16.20
|
|
381
|
+
* (wtfalch/calendar#14), a plain event's own `id` right back at itself,
|
|
382
|
+
* recurring or not. An earlier version of this comment claimed the field
|
|
383
|
+
* was absent on a master; the server sends it there too. `recurrenceId`,
|
|
384
|
+
* not this field, is what actually tells an occurrence from a master.
|
|
187
385
|
*
|
|
188
386
|
* Editing a series means addressing the master, and an occurrence's own
|
|
189
387
|
* `id` is synthetic, so without this an editor can change one occurrence
|
|
@@ -194,6 +392,20 @@ export type CalendarEvent = {
|
|
|
194
392
|
* server-assigned on create (`id`, `sequence`) or query-assigned
|
|
195
393
|
* (`recurrenceId`). */
|
|
196
394
|
export type CalendarEventDraft = Omit<CalendarEvent, 'id' | 'sequence' | 'recurrenceId'>;
|
|
395
|
+
/**
|
|
396
|
+
* `updateEvent`'s patch. Every field omits its key entirely to mean "leave
|
|
397
|
+
* this alone" -- the usual `Partial<CalendarEventDraft>` meaning -- with one
|
|
398
|
+
* exception: `recurrenceRule` also accepts an explicit `null`, which removes
|
|
399
|
+
* an existing rule server-side and turns a recurring event back into a
|
|
400
|
+
* one-off. Nothing built that clearing before this type existed
|
|
401
|
+
* (wtfalch/calendar#45) -- `recurrenceRule`'s own field on `CalendarEvent`
|
|
402
|
+
* only ever reads back as the rule or `undefined`, never `null`, so a plain
|
|
403
|
+
* `Partial<CalendarEventDraft>` had no way to say "unset" rather than "not
|
|
404
|
+
* mentioned".
|
|
405
|
+
*/
|
|
406
|
+
export type CalendarEventPatch = Omit<Partial<CalendarEventDraft>, 'recurrenceRule'> & {
|
|
407
|
+
recurrenceRule?: CalendarRecurrenceRule | null;
|
|
408
|
+
};
|
|
197
409
|
/** RFC 5545 `FREEBUSY` `FBTYPE`, as JSCalendar's busy-period shape names
|
|
198
410
|
* it. */
|
|
199
411
|
export type CalendarBusyStatus = 'confirmed' | 'tentative' | 'unavailable';
|
|
@@ -209,6 +421,75 @@ export type AvailabilityPeriod = {
|
|
|
209
421
|
end: string;
|
|
210
422
|
busyStatus: CalendarBusyStatus;
|
|
211
423
|
};
|
|
424
|
+
/**
|
|
425
|
+
* One principal's answer from `getAvailability`, distinguishing a real read
|
|
426
|
+
* from the one thing the wire cannot say by itself.
|
|
427
|
+
*
|
|
428
|
+
* `Principal/getAvailability` answers `{"list": []}` for three different
|
|
429
|
+
* truths — never shared, shared then revoked, and shared but genuinely free
|
|
430
|
+
* (`.plans/msg-055-slice-4-freebusy.md`, live-confirmed against Stalwart
|
|
431
|
+
* v0.16.20) — so an empty list is folded into `'unknown'` here rather than
|
|
432
|
+
* surfaced as `'known'` with zero periods. `'known'` means real periods came
|
|
433
|
+
* back; `'unknown'` is the only honest reading of everything else, including
|
|
434
|
+
* a request that failed outright for that one principal (issue #13).
|
|
435
|
+
*/
|
|
436
|
+
export type AvailabilityResult = {
|
|
437
|
+
readonly kind: 'known';
|
|
438
|
+
readonly periods: readonly AvailabilityPeriod[];
|
|
439
|
+
} | {
|
|
440
|
+
readonly kind: 'unknown';
|
|
441
|
+
};
|
|
442
|
+
/**
|
|
443
|
+
* `findTime`'s answer: where every *known* principal is free, and who could
|
|
444
|
+
* not be read at all.
|
|
445
|
+
*
|
|
446
|
+
* `slots` never assumes an unknown principal is free — it is computed from
|
|
447
|
+
* `known` answers only — so `unknown` travels alongside it rather than being
|
|
448
|
+
* folded away. A caller that drops `unknown` on the floor is a caller that
|
|
449
|
+
* can book over somebody it never actually saw (issue #13; the same rule
|
|
450
|
+
* `AvailabilityResult`'s doc comment states for one principal).
|
|
451
|
+
*/
|
|
452
|
+
export type FindTimeResult = {
|
|
453
|
+
readonly slots: readonly CalendarRange[];
|
|
454
|
+
readonly unknown: readonly string[];
|
|
455
|
+
};
|
|
456
|
+
/**
|
|
457
|
+
* One `VEVENT` `importIcs` could not turn into an event -- kept apart from
|
|
458
|
+
* the ones it created rather than discarding the whole import over it
|
|
459
|
+
* (wtfalch/calendar#46: one malformed `VEVENT` used to abort the import and
|
|
460
|
+
* lose every otherwise-valid one alongside it).
|
|
461
|
+
*/
|
|
462
|
+
export type ImportIcsSkippedEvent = {
|
|
463
|
+
/** The failed `VEVENT`'s own `UID`, when it had one to read before parsing
|
|
464
|
+
* gave up -- e.g. a missing `DTSTART` is caught before `UID` is even
|
|
465
|
+
* read. */
|
|
466
|
+
readonly uid: string | undefined;
|
|
467
|
+
/** Why this one could not become an event, e.g. an `RRULE` `FREQ` this
|
|
468
|
+
* package does not recognise. */
|
|
469
|
+
readonly reason: string;
|
|
470
|
+
};
|
|
471
|
+
/** `importIcs`'s answer: the events it created, and the ones it had to skip
|
|
472
|
+
* and why. Mirrors `FindTimeResult`'s shape -- the answer travels alongside
|
|
473
|
+
* the partial failure rather than either one hiding the other. */
|
|
474
|
+
export type ImportIcsResult = {
|
|
475
|
+
readonly created: readonly CalendarEvent[];
|
|
476
|
+
readonly skipped: readonly ImportIcsSkippedEvent[];
|
|
477
|
+
};
|
|
478
|
+
/**
|
|
479
|
+
* One principal's own working day, for `findTime`'s per-attendee
|
|
480
|
+
* `options.workingHours` (wtfalch/calendar#31). `timeZone` is an IANA name
|
|
481
|
+
* ("America/New_York") -- this package still expands no rule and now
|
|
482
|
+
* converts no wall-clock time it was not explicitly given one for, but a
|
|
483
|
+
* caller that *does* know a participant's zone (from their own directory,
|
|
484
|
+
* a browser `Intl` read, wherever) can finally hand it in. `startHour`/
|
|
485
|
+
* `endHour` are local hours, `0`-`23`, defaulting to `9`/`17` -- the same
|
|
486
|
+
* bound `findTime` used uniformly before this option existed.
|
|
487
|
+
*/
|
|
488
|
+
export type WorkingHours = {
|
|
489
|
+
timeZone: string;
|
|
490
|
+
startHour?: number;
|
|
491
|
+
endHour?: number;
|
|
492
|
+
};
|
|
212
493
|
/** The per-type state strings a push event carries, mirroring
|
|
213
494
|
* `@wtfalch/email/mailbox`'s `ChangedState` for the four calendar-shaped
|
|
214
495
|
* `DataType`s Stalwart pushes over EventSource/WebSocket: `Calendar`,
|
|
@@ -236,6 +517,30 @@ export type CalendarSubscription = {
|
|
|
236
517
|
export type SchedulingOptions = {
|
|
237
518
|
sendSchedulingMessages?: boolean;
|
|
238
519
|
};
|
|
520
|
+
/**
|
|
521
|
+
* Which occurrences of a recurring event `updateEvent`/`deleteEvent` reach --
|
|
522
|
+
* the question every calendar UI asks the moment somebody edits a repeating
|
|
523
|
+
* event (wtfalch/calendar#14). `'occurrence'` and `'series'` were already
|
|
524
|
+
* reachable before this option existed: a synthetic occurrence id already
|
|
525
|
+
* wrote a single occurrence, a master's own id already wrote the whole
|
|
526
|
+
* series. `'following'` is the one JMAP has no verb for at all -- see
|
|
527
|
+
* `calendar-client.ts`'s `splitFollowing` for how it is built out of a rule
|
|
528
|
+
* truncation and a new event, both live-confirmed against Stalwart v0.16.20.
|
|
529
|
+
*/
|
|
530
|
+
export type RecurrenceScope = 'occurrence' | 'following' | 'series';
|
|
531
|
+
/**
|
|
532
|
+
* `updateEvent`/`deleteEvent`'s own scope option, separate from
|
|
533
|
+
* `SchedulingOptions` because `createEvent` takes the latter but has no
|
|
534
|
+
* occurrence to scope a write to.
|
|
535
|
+
*/
|
|
536
|
+
export type RecurrenceScopeOptions = {
|
|
537
|
+
/** Omitted, a write lands on whatever `id` was given, exactly as it did
|
|
538
|
+
* before this option existed -- a synthetic occurrence id already wrote
|
|
539
|
+
* an occurrence-scoped change, a master id already wrote the whole
|
|
540
|
+
* series, so the default keeps every existing caller's behaviour
|
|
541
|
+
* unchanged (wtfalch/calendar#14). */
|
|
542
|
+
scope?: RecurrenceScope;
|
|
543
|
+
};
|
|
239
544
|
/** Who the person holding a connection is, for telling their own participant
|
|
240
545
|
* row from everyone else's. `calendarAddress` is bare here — no `mailto:`
|
|
241
546
|
* scheme — because that is how the session document writes it. */
|
|
@@ -255,6 +560,80 @@ export type CalendarRange = {
|
|
|
255
560
|
after: string;
|
|
256
561
|
before: string;
|
|
257
562
|
};
|
|
563
|
+
/**
|
|
564
|
+
* What `searchEvents` takes beyond the query string.
|
|
565
|
+
*
|
|
566
|
+
* `range` is optional here, unlike every other listing method's -- the whole
|
|
567
|
+
* point of the ticket (wtfalch/calendar#17,
|
|
568
|
+
* https://github.com/wtfalch/calendar/issues/17) is answering a search
|
|
569
|
+
* across a person's calendars with no range named, the gap Agora's combined
|
|
570
|
+
* Mail/Chat/Calendar search hit (agora#216,
|
|
571
|
+
* https://github.com/wtfalch/agora/issues/216): `listEvents(range)` forced
|
|
572
|
+
* the caller to guess a range and filter client-side, silently missing a
|
|
573
|
+
* match outside whatever range happened to be loaded.
|
|
574
|
+
*/
|
|
575
|
+
export type SearchOptions = {
|
|
576
|
+
range?: CalendarRange;
|
|
577
|
+
limit?: number;
|
|
578
|
+
};
|
|
579
|
+
/**
|
|
580
|
+
* `changes()`'s own input (wtfalch/calendar#65): `sinceState` is a state
|
|
581
|
+
* string a previous `changes()` call's own `newState` handed back — there is
|
|
582
|
+
* no way to ask "what changed since the beginning," the same rule
|
|
583
|
+
* `Calendar/get`'s or `CalendarEvent/get`'s `state` and `CalendarEvent/changes`'s
|
|
584
|
+
* `sinceState` already share in RFC 8620 §5.2. `calendarId`, when given, scopes
|
|
585
|
+
* `created`/`updated` to that one calendar — `changes()`'s own doc comment
|
|
586
|
+
* explains why `destroyed` cannot be scoped the same way.
|
|
587
|
+
*/
|
|
588
|
+
export type CalendarChangesOptions = {
|
|
589
|
+
calendarId?: string;
|
|
590
|
+
sinceState: string;
|
|
591
|
+
};
|
|
592
|
+
/**
|
|
593
|
+
* `changes()`'s answer: which `CalendarEvent` ids were created, updated or
|
|
594
|
+
* destroyed since `sinceState`, and the state to remember for next time
|
|
595
|
+
* (RFC 8620 §5.2). Ids only — never event data — so a caller that only needs
|
|
596
|
+
* to know *what* moved is never handed a title or body it has no use for;
|
|
597
|
+
* `getEventProjections` is the separate, minimal fetch for a caller that does
|
|
598
|
+
* need to look at what changed.
|
|
599
|
+
*/
|
|
600
|
+
export type CalendarChanges = {
|
|
601
|
+
readonly newState: string;
|
|
602
|
+
readonly created: readonly string[];
|
|
603
|
+
readonly updated: readonly string[];
|
|
604
|
+
readonly destroyed: readonly string[];
|
|
605
|
+
/** More changes exist past `newState` than this one call returned — call
|
|
606
|
+
* `changes()` again with `newState` as the next `sinceState` before
|
|
607
|
+
* treating the sync as caught up (RFC 8620 §5.2). */
|
|
608
|
+
readonly hasMoreChanges: boolean;
|
|
609
|
+
};
|
|
610
|
+
/**
|
|
611
|
+
* The minimal slice of a `CalendarEvent` a change-feed consumer needs to
|
|
612
|
+
* decide what happened, and nothing it must not hold (wtfalch/calendar#65,
|
|
613
|
+
* modelled on Activity's own `JmapCalendarEventRecord`,
|
|
614
|
+
* `activity/packages/service/src/calendar/jmap.ts`): no title, description,
|
|
615
|
+
* location or start time. `getEventProjections` fetches exactly this shape,
|
|
616
|
+
* naming every property it wants rather than asking the server for
|
|
617
|
+
* "everything," so a title or body is never sent over the wire in the first
|
|
618
|
+
* place.
|
|
619
|
+
*/
|
|
620
|
+
export type CalendarEventProjection = {
|
|
621
|
+
readonly id: string;
|
|
622
|
+
readonly status: CalendarEventStatus;
|
|
623
|
+
/** RFC 5545 `SEQUENCE`; bumped on every organizer edit. */
|
|
624
|
+
readonly sequence: number;
|
|
625
|
+
readonly participants: readonly {
|
|
626
|
+
readonly calendarAddress: string;
|
|
627
|
+
}[];
|
|
628
|
+
};
|
|
629
|
+
/** `getEventProjections`'s answer: the projections it found, and the ids it
|
|
630
|
+
* did not — an id a caller's own index still holds but the server no
|
|
631
|
+
* longer does, the same `notFound` shape `CalendarEvent/get` always
|
|
632
|
+
* carries. */
|
|
633
|
+
export type CalendarEventProjectionsResult = {
|
|
634
|
+
readonly list: readonly CalendarEventProjection[];
|
|
635
|
+
readonly notFound: readonly string[];
|
|
636
|
+
};
|
|
258
637
|
/**
|
|
259
638
|
* A connection to one JMAP calendars account.
|
|
260
639
|
*
|
|
@@ -283,10 +662,91 @@ export interface CalendarClient {
|
|
|
283
662
|
listCalendars(): Promise<readonly Calendar[]>;
|
|
284
663
|
/** Every occurrence in `range`, recurring events expanded server-side. */
|
|
285
664
|
listEvents(range: CalendarRange): Promise<readonly CalendarEvent[]>;
|
|
665
|
+
/**
|
|
666
|
+
* One query across every calendar this account holds, for Agora's combined
|
|
667
|
+
* Mail/Chat/Calendar search (wtfalch/calendar#17; agora#216). Matches on
|
|
668
|
+
* the wire's own `text` filter, which a live Stalwart v0.16.20 searches
|
|
669
|
+
* across both `title` and `description` in one pass, case-insensitively --
|
|
670
|
+
* a single filter, not two ORed together (live-confirmed 2026-09-21, see
|
|
671
|
+
* `calendar-client.ts`'s `searchEvents`).
|
|
672
|
+
*
|
|
673
|
+
* `options.range` given: sent as `expandRecurrences: true` with
|
|
674
|
+
* `filter.after`/`filter.before`, exactly like `listEvents`, so a matching
|
|
675
|
+
* recurring event comes back as its dated occurrences. `options.range`
|
|
676
|
+
* omitted: the server refuses to expand recurrences with no bounds at all
|
|
677
|
+
* (`invalidArguments`, live-confirmed), so a matching recurring event comes
|
|
678
|
+
* back as its single master id instead -- the same fallback
|
|
679
|
+
* `CalendarEvent/query` itself uses for any other unexpanded query.
|
|
680
|
+
*/
|
|
681
|
+
searchEvents(query: string, options?: SearchOptions): Promise<readonly CalendarEvent[]>;
|
|
286
682
|
getEvent(id: string): Promise<CalendarEvent>;
|
|
287
683
|
createEvent(calendarId: string, event: CalendarEventDraft, options?: SchedulingOptions): Promise<CalendarEvent>;
|
|
288
|
-
|
|
289
|
-
|
|
684
|
+
/**
|
|
685
|
+
* Parse an RFC 5545 `.ics` document and create one event per `VEVENT` it
|
|
686
|
+
* contains, on `calendarId` (wtfalch/calendar#41; agora#159,
|
|
687
|
+
* https://github.com/wtfalch/agora/issues/159). One-way: the source the
|
|
688
|
+
* `.ics` came from is never written back to, and this is a distinct method
|
|
689
|
+
* from `subscribe`'s standing webcal poller -- a one-time copy onto an
|
|
690
|
+
* owned calendar, not a live link to the original. Each created event
|
|
691
|
+
* rides the same `CalendarEvent/set` `createEvent` already uses, under the
|
|
692
|
+
* importing person's own credential, so it is editable afterward like any
|
|
693
|
+
* other owned event.
|
|
694
|
+
*
|
|
695
|
+
* A `VEVENT` this package cannot turn into an event -- an unrecognised
|
|
696
|
+
* `RRULE`, a missing `DTSTART` -- is skipped rather than aborting the whole
|
|
697
|
+
* import: every otherwise-valid `VEVENT` in the same document still gets
|
|
698
|
+
* created, and `ImportIcsResult.skipped` says which ones did not and why
|
|
699
|
+
* (wtfalch/calendar#46).
|
|
700
|
+
*/
|
|
701
|
+
importIcs(calendarId: string, ics: string): Promise<ImportIcsResult>;
|
|
702
|
+
/**
|
|
703
|
+
* `options.scope` picks which occurrences of a recurring event this
|
|
704
|
+
* reaches -- see `RecurrenceScope`. `'following'` returns the new series'
|
|
705
|
+
* own event, the one that now carries the change from `id`'s occurrence
|
|
706
|
+
* onward, since the id the caller passed in stops being useful the moment
|
|
707
|
+
* its series ends there.
|
|
708
|
+
*
|
|
709
|
+
* **An expanded occurrence's id is positional, not stable.** It names a
|
|
710
|
+
* slot in the last listing's own order, not a fixed identity for that
|
|
711
|
+
* date -- live-confirmed against Stalwart v0.16.20 (wtfalch/calendar#14):
|
|
712
|
+
* a write here that adds or removes an occurrence (an 'occurrence'-scope
|
|
713
|
+
* edit or delete, a 'following' split) renumbers every later occurrence's
|
|
714
|
+
* own id on the next expansion. An id held across two writes can silently
|
|
715
|
+
* name a different occurrence on the second one. Re-list (`listEvents`)
|
|
716
|
+
* before reusing an id this method, or `deleteEvent`, has just touched.
|
|
717
|
+
*
|
|
718
|
+
* `patch.recurrenceRule: null` clears an existing rule server-side,
|
|
719
|
+
* turning a recurring event back into a one-off -- distinct from
|
|
720
|
+
* omitting `recurrenceRule` entirely, which leaves whatever rule the
|
|
721
|
+
* event already has untouched (`CalendarEventPatch`'s own doc comment,
|
|
722
|
+
* wtfalch/calendar#45).
|
|
723
|
+
*/
|
|
724
|
+
updateEvent(id: string, patch: CalendarEventPatch, options?: SchedulingOptions & RecurrenceScopeOptions): Promise<CalendarEvent>;
|
|
725
|
+
/** `options.scope` picks which occurrences of a recurring event this
|
|
726
|
+
* reaches -- see `RecurrenceScope`. `'following'` deletes nothing on its
|
|
727
|
+
* own id; it only truncates the series before it (`RecurrenceScope`'s own
|
|
728
|
+
* doc comment).
|
|
729
|
+
*
|
|
730
|
+
* Shares `updateEvent`'s own warning: an expanded occurrence's id is
|
|
731
|
+
* positional, not stable, so a write here can renumber every later
|
|
732
|
+
* occurrence's own id -- re-list before reusing one. */
|
|
733
|
+
deleteEvent(id: string, options?: SchedulingOptions & RecurrenceScopeOptions): Promise<void>;
|
|
734
|
+
/**
|
|
735
|
+
* Reply to an invite: accept, decline or answer tentatively.
|
|
736
|
+
*
|
|
737
|
+
* An iTIP REPLY against the caller's own copy of the event -- never
|
|
738
|
+
* `updateEvent`, the organiser's verb (#11: "`updateEvent` patches the
|
|
739
|
+
* event -- which is the organiser's verb, not a guest's"). It patches only
|
|
740
|
+
* the caller's own participant entry, found by address rather than by a
|
|
741
|
+
* wire map key the caller was never given, and it bumps nothing: a real
|
|
742
|
+
* Stalwart v0.16.20 reply left `sequence` unchanged on the replier's own
|
|
743
|
+
* copy while the organiser's copy of `participationStatus` updated on its
|
|
744
|
+
* own, with no separate write on the organiser's side (T11 live capture,
|
|
745
|
+
* `wire-live-transcript.test.ts`).
|
|
746
|
+
*/
|
|
747
|
+
respond(eventId: string, status: CalendarParticipationStatus, options?: SchedulingOptions & {
|
|
748
|
+
comment?: string;
|
|
749
|
+
}): Promise<void>;
|
|
290
750
|
/** Add or replace one grant in a calendar's `shareWith` ACL. A person
|
|
291
751
|
* shares their own calendar directly; this never touches authz (plan
|
|
292
752
|
* §5). */
|
|
@@ -306,14 +766,87 @@ export interface CalendarClient {
|
|
|
306
766
|
* empty rights object for the grantee, not remove them; this instead
|
|
307
767
|
* deletes the `shareWith` key outright (MSG-055 slice 3 plan). */
|
|
308
768
|
unshareCalendar(calendarId: string, accountId: string): Promise<void>;
|
|
309
|
-
/**
|
|
310
|
-
*
|
|
311
|
-
*
|
|
312
|
-
|
|
769
|
+
/**
|
|
770
|
+
* Every named principal's busy periods over `range`, one JMAP request no
|
|
771
|
+
* matter how many principals — `Principal/getAvailability` batches like
|
|
772
|
+
* any other JMAP method call (RFC 8620 §3.3), measured live for issue #13.
|
|
773
|
+
* See `AvailabilityResult`'s doc comment for what a missing share reads as.
|
|
774
|
+
*
|
|
775
|
+
* Used to take one `principalId` and return its periods directly; every
|
|
776
|
+
* caller needed the same "an empty answer is not free" reading in the end,
|
|
777
|
+
* so the many-principal shape replaced it rather than sitting beside it —
|
|
778
|
+
* `AvailabilityRibbon`'s own lookup now asks for every participant at once
|
|
779
|
+
* (issue #13 Decision).
|
|
780
|
+
*/
|
|
781
|
+
getAvailability(principalIds: readonly string[], range: CalendarRange): Promise<ReadonlyMap<string, AvailabilityResult>>;
|
|
782
|
+
/**
|
|
783
|
+
* Slots at least `duration` long where every principal `getAvailability`
|
|
784
|
+
* could read is free — never one it could not see, which is what
|
|
785
|
+
* `FindTimeResult.unknown` is for.
|
|
786
|
+
*
|
|
787
|
+
* `options.workingHours` clips candidate slots to a working day:
|
|
788
|
+
* `true` clips uniformly to 09:00-17:00 UTC on each day of `range`, the
|
|
789
|
+
* one timezone every busy period already arrives in (issue #13's original
|
|
790
|
+
* Decision, kept for a caller with no per-principal data). A map keyed by
|
|
791
|
+
* principal id instead clips *that* principal to *their own* zone and
|
|
792
|
+
* hours (wtfalch/calendar#31) — a slot must fall inside every named
|
|
793
|
+
* principal's own working day, not just one shared window, which is what
|
|
794
|
+
* stops a multi-timezone team from being proposed a meeting at 2am local
|
|
795
|
+
* for half the invitees. A principal in `principalIds` but absent from the
|
|
796
|
+
* map falls back to the uniform 09:00-17:00 UTC window, the same as
|
|
797
|
+
* `true`.
|
|
798
|
+
*/
|
|
799
|
+
findTime(principalIds: readonly string[], range: CalendarRange, duration: string, options?: {
|
|
800
|
+
workingHours?: boolean | ReadonlyMap<string, WorkingHours>;
|
|
801
|
+
}): Promise<FindTimeResult>;
|
|
313
802
|
/** Watch for changes on the account. The connection reconnects on its own
|
|
314
803
|
* with a backoff; only `close()` needs calling when done, mirroring
|
|
315
804
|
* `@wtfalch/email/mailbox/push.ts`'s `push()`. */
|
|
316
805
|
subscribe(handler: (changed: CalendarChangedState) => void): CalendarSubscription;
|
|
806
|
+
/**
|
|
807
|
+
* `CalendarEvent` ids created, updated or destroyed since `options.sinceState`
|
|
808
|
+
* — JMAP `CalendarEvent/changes` (RFC 8620 §5.2), for a consumer that
|
|
809
|
+
* follows a calendar without holding a live browser session (Agora's Today
|
|
810
|
+
* digest, a push-notification worker, or Activity's own feed source;
|
|
811
|
+
* wtfalch/calendar#65). Bounded, like every JMAP `/changes` method: a call
|
|
812
|
+
* with a lot to report may come back with `hasMoreChanges: true` and a
|
|
813
|
+
* `newState` short of "caught up" — call again with that state before
|
|
814
|
+
* assuming the sync finished.
|
|
815
|
+
*
|
|
816
|
+
* **`options.calendarId`, when given, scopes `created`/`updated`** to
|
|
817
|
+
* events on that one calendar — `CalendarEvent/changes` itself carries no
|
|
818
|
+
* such filter (RFC 8620 §5.2 defines no arguments beyond `sinceState`/
|
|
819
|
+
* `maxChanges`), so this is done by checking each changed id's own
|
|
820
|
+
* `calendarIds` after the fact, one extra minimal fetch. **`destroyed` is
|
|
821
|
+
* never scoped this way**, deliberately: a destroyed event carries no data
|
|
822
|
+
* to check membership against any more, so filtering it would mean
|
|
823
|
+
* silently dropping an id a `calendarId`-scoped caller's own index still
|
|
824
|
+
* has to retire. A caller that asked for one calendar gets every destroyed
|
|
825
|
+
* id regardless, and is expected to only act on the ones its own index
|
|
826
|
+
* already knows belonged there.
|
|
827
|
+
*
|
|
828
|
+
* **Throws a `CalendarError` with `type: 'cannotCalculateChanges'`** when
|
|
829
|
+
* the server cannot resolve `sinceState` at all — stale, unknown, or
|
|
830
|
+
* foreign to this account (RFC 8620 §5.2's own error for a `/changes`
|
|
831
|
+
* call). That is the caller's signal to resync: `sinceState` is gone for
|
|
832
|
+
* good, so `getEventProjections` (or a bounded `listEvents`/`searchEvents`
|
|
833
|
+
* query) is the only way forward, exactly the resync Activity's own
|
|
834
|
+
* `sync.ts` drives off `JmapCalendarError`'s `cannotCalculateChanges`
|
|
835
|
+
* (`activity/packages/service/src/calendar/sync.ts`).
|
|
836
|
+
*/
|
|
837
|
+
changes(options: CalendarChangesOptions): Promise<CalendarChanges>;
|
|
838
|
+
/**
|
|
839
|
+
* The minimal `CalendarEventProjection` for each of `ids` — `id`, `status`,
|
|
840
|
+
* `sequence` and each participant's `calendarAddress`, nothing else
|
|
841
|
+
* (wtfalch/calendar#65). Sent as an explicit `properties` list on
|
|
842
|
+
* `CalendarEvent/get`, the same discipline `EVENT_GET_PROPERTIES` already
|
|
843
|
+
* follows for `getEvent`/`listEvents` — naming exactly what is wanted,
|
|
844
|
+
* rather than filtering a full `CalendarEvent` client-side after asking the
|
|
845
|
+
* server for everything, so a title, description or location is never sent
|
|
846
|
+
* over the wire to a caller (a feed source holding identifiers only, per
|
|
847
|
+
* Activity's own `jmap.ts` doc comment) that must not receive one.
|
|
848
|
+
*/
|
|
849
|
+
getEventProjections(ids: readonly string[]): Promise<CalendarEventProjectionsResult>;
|
|
317
850
|
}
|
|
318
851
|
/**
|
|
319
852
|
* Where the reader is: which view, which date, which event is open.
|