@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.
@@ -40,8 +40,45 @@
40
40
  * **Returned by Stalwart and deliberately unmapped**, because no public type
41
41
  * needs them yet: `organizerCalendarAddress`, `recurrenceIdTimeZone`,
42
42
  * `updated`, `isDraft`, `isOrigin`.
43
+ *
44
+ * **`alerts` is live-confirmed too** (T15, issue #15, Stalwart v0.16.20). A
45
+ * relative-trigger, display-action alert -- `{trigger: {"@type":
46
+ * "OffsetTrigger", offset: "-PT15M"}, action: "display"}` -- round-trips
47
+ * through create and get with no shape change at all: no `relativeTo` filled
48
+ * in, the offset string untouched. It is one of the properties
49
+ * `EVENT_GET_PROPERTIES` must name explicitly, the same as
50
+ * `recurrenceId`/`baseEventId` above: a `get` naming this file's own property
51
+ * list, from before `alerts` joined it, came back with no `alerts` key at
52
+ * all even though the event had one.
53
+ *
54
+ * **Amendment, a refuter finding (T15).** Three more things confirmed live:
55
+ * an `AbsoluteTrigger` (`{"@type":"AbsoluteTrigger","when":"..."}`)
56
+ * round-trips too, alongside an `iCalendar.convertedProperties` block this
57
+ * file deliberately leaves unmapped; a trigger written with neither `offset`
58
+ * nor `when` is accepted on create but comes back on the next `get` with
59
+ * *no* `trigger` key at all, which crashed the first version of
60
+ * `alertFromWire` (it read `wire.trigger.offset` unconditionally) and must
61
+ * not corrupt the alert on write-back either; and `acknowledged` is a real
62
+ * stored field a client must round-trip, because `CalendarEvent/set` on
63
+ * `alerts` replaces the whole map -- the first version of `alertToWire`
64
+ * dropped it, so any update that touched `alerts` at all wiped every
65
+ * alert's acknowledgement, confirmed live.
66
+ *
67
+ * **`virtualLocations` (#16), live-confirmed against Stalwart v0.16.20.** The
68
+ * server round-trips it exactly like `locations` -- a map of objects keyed
69
+ * arbitrarily, here `{"@type":"VirtualLocation","uri":...,"name":...}` -- and
70
+ * it joins the same trap `recurrenceId`/`baseEventId` were already in: a
71
+ * `CalendarEvent/get` with an explicit `properties` list that omits it comes
72
+ * back with the property missing even though the value is still stored,
73
+ * confirmed by creating an event with it, then reading it back once with the
74
+ * old `EVENT_GET_PROPERTIES` (missing) and once with it added (present).
75
+ * `CalendarEvent/set update` was confirmed field-scoped: patching only
76
+ * `title` on an event that carries a `virtualLocations` set by a raw JMAP
77
+ * write left it untouched on the next `get` -- this file only ever writes
78
+ * the key when a caller's own patch mentions it (`patchToWire`), so that
79
+ * holds for this client's own `updateEvent` too.
43
80
  */
44
- import type { AvailabilityPeriod, Calendar, CalendarEvent, CalendarEventDraft, CalendarRight, Principal } from './types.ts';
81
+ import type { AvailabilityPeriod, Calendar, CalendarChanges, CalendarEvent, CalendarEventDraft, CalendarEventPatch, CalendarEventProjection, CalendarRecurrenceRule, CalendarRight, Principal } from './types.ts';
45
82
  type WireRights = Partial<Record<CalendarRight, boolean>>;
46
83
  export declare function rightsFromWire(wire: WireRights | null | undefined): readonly CalendarRight[];
47
84
  export declare function rightsToWire(rights: readonly CalendarRight[]): WireRights;
@@ -78,22 +115,102 @@ type WireParticipant = {
78
115
  roles?: Partial<Record<string, boolean>> | null;
79
116
  participationStatus?: string | null;
80
117
  };
118
+ /** `trigger` itself is optional: live-confirmed that a trigger with neither
119
+ * `offset` nor `when` is accepted on write but omitted entirely from the
120
+ * next `get` (T15 amendment). `offset`/`when` are each optional on the
121
+ * trigger object too, for the same reason -- reading `.offset` off a real
122
+ * `AbsoluteTrigger` (which carries `when`, not `offset`) must not crash. */
123
+ type WireAlertTrigger = {
124
+ '@type'?: string;
125
+ offset?: string;
126
+ when?: string;
127
+ relativeTo?: string | null;
128
+ };
129
+ type WireAlert = {
130
+ '@type'?: string;
131
+ trigger?: WireAlertTrigger | null;
132
+ action?: string | null;
133
+ acknowledged?: string | null;
134
+ };
81
135
  type WireLocation = {
82
136
  '@type'?: string;
83
137
  name?: string | null;
84
138
  };
139
+ type WireVirtualLocation = {
140
+ '@type'?: string;
141
+ uri: string;
142
+ name?: string | null;
143
+ };
144
+ type WireLink = {
145
+ '@type'?: string;
146
+ href: string;
147
+ title?: string | null;
148
+ contentType?: string | null;
149
+ size?: number | null;
150
+ rel?: string | null;
151
+ };
152
+ /** RFC 8984 §3.3's `NDay`, wire-shaped. `nthOfPeriod` is signed (a negative
153
+ * value counts from the end of the period), so `0` is a real, meaningful
154
+ * wire value here -- every optional field below uses `?? undefined` rather
155
+ * than `||`, the same reason `WireRecurrenceRule`'s own numeric fields do. */
156
+ type WireNDay = {
157
+ '@type'?: string;
158
+ day: string;
159
+ nthOfPeriod?: number | null;
160
+ };
161
+ /**
162
+ * RFC 8984 §3.3's `RecurrenceRule`, wire-shaped -- every part the type
163
+ * defines, mirroring `CalendarRecurrenceRule` field for field. Losing any of
164
+ * these on read is exactly wtfalch/calendar#27: a rule using `byDay`,
165
+ * `byMonthDay`, `bySetPosition` or `firstDayOfWeek` silently degrades to a
166
+ * bare frequency the moment this file round-trips it.
167
+ */
85
168
  type WireRecurrenceRule = {
86
169
  '@type'?: string;
87
170
  frequency: string;
88
171
  interval?: number | null;
172
+ rscale?: string | null;
173
+ skip?: string | null;
174
+ firstDayOfWeek?: string | null;
175
+ byDay?: readonly WireNDay[] | null;
176
+ byMonthDay?: readonly number[] | null;
177
+ byMonth?: readonly string[] | null;
178
+ byYearDay?: readonly number[] | null;
179
+ byWeekNo?: readonly number[] | null;
180
+ byHour?: readonly number[] | null;
181
+ byMinute?: readonly number[] | null;
182
+ bySecond?: readonly number[] | null;
183
+ bySetPosition?: readonly number[] | null;
89
184
  count?: number | null;
90
185
  until?: string | null;
91
186
  };
187
+ export declare function recurrenceRuleFromWire(wire: WireRecurrenceRule | null | undefined): CalendarRecurrenceRule | undefined;
92
188
  /** The event properties this package asks the server for. Naming them
93
189
  * explicitly, rather than omitting `properties` for "everything", keeps a
94
190
  * server-side addition from silently changing what `wireEventFromWire`
95
- * has to cope with. */
96
- export declare const EVENT_GET_PROPERTIES: readonly ["id", "calendarIds", "uid", "title", "description", "start", "timeZone", "duration", "showWithoutTime", "locations", "recurrenceRule", "participants", "status", "sequence", "baseEventId", "recurrenceId"];
191
+ * has to cope with.
192
+ *
193
+ * `alerts` has to be named here: live-confirmed against Stalwart v0.16.20
194
+ * that a `CalendarEvent/get` asking for this exact property list -- before
195
+ * `alerts` was added to it -- comes back with no `alerts` key at all, even
196
+ * though the event has one (T15). An unqualified `get` (no `properties` at
197
+ * all) does return `alerts` on its own, the way it also returns everything
198
+ * else this list already names, but this package never sends an
199
+ * unqualified `get`.
200
+ *
201
+ * `virtualLocations` -- live-confirmed against Stalwart v0.16.20 (#16): an
202
+ * event that carries one still comes back without it if this list omits the
203
+ * name, the same trap `recurrenceId`/`baseEventId` already set (this file's
204
+ * header comment).
205
+ *
206
+ * `freeBusyStatus` (wtfalch/calendar#29) is named here on the strength of
207
+ * that same pattern, not a fresh live capture -- every property this list
208
+ * has ever gained needed an explicit name, and nothing suggests this is the
209
+ * one exception.
210
+ *
211
+ * `mayInviteSelf`/`mayInviteOthers` (wtfalch/calendar#51) are named here on
212
+ * that same strength, not a fresh live capture either. */
213
+ export declare const EVENT_GET_PROPERTIES: readonly ["id", "calendarIds", "uid", "title", "description", "start", "timeZone", "duration", "showWithoutTime", "locations", "virtualLocations", "links", "recurrenceRule", "participants", "mayInviteSelf", "mayInviteOthers", "alerts", "status", "freeBusyStatus", "sequence", "baseEventId", "recurrenceId"];
97
214
  export type WireEvent = {
98
215
  id: string;
99
216
  calendarIds?: Record<string, boolean> | null;
@@ -105,9 +222,15 @@ export type WireEvent = {
105
222
  duration: string;
106
223
  showWithoutTime?: boolean | null;
107
224
  locations?: Record<string, WireLocation> | null;
225
+ virtualLocations?: Record<string, WireVirtualLocation> | null;
226
+ links?: Record<string, WireLink> | null;
108
227
  recurrenceRule?: WireRecurrenceRule | null;
109
228
  participants?: Record<string, WireParticipant> | null;
229
+ mayInviteSelf?: boolean | null;
230
+ mayInviteOthers?: boolean | null;
231
+ alerts?: Record<string, WireAlert> | null;
110
232
  status?: string | null;
233
+ freeBusyStatus?: string | null;
111
234
  sequence?: number | null;
112
235
  /** The master event this expansion came from -- confirmed live (#145
113
236
  * check 2). */
@@ -133,8 +256,41 @@ export declare function eventFromWire(wire: WireEvent, calendarIdFallback?: stri
133
256
  export declare function draftToWire(calendarId: string, draft: CalendarEventDraft): Record<string, unknown>;
134
257
  /** Only the properties `patch` actually carries -- `CalendarEvent/set`'s
135
258
  * `update` is a genuine patch, and a field the caller did not mention must
136
- * not be overwritten with `undefined`. */
137
- export declare function patchToWire(patch: Partial<CalendarEventDraft>): Record<string, unknown>;
259
+ * not be overwritten with `undefined`.
260
+ *
261
+ * `recurrenceRule: null` is the one field this writes a real wire `null`
262
+ * for, rather than dropping the key: `CalendarEventPatch` widens just this
263
+ * field to allow it, as the explicit "clear this" signal distinct from
264
+ * leaving the key out entirely (wtfalch/calendar#45). Writing
265
+ * `recurrenceRuleToWire(null)` here instead would have produced `undefined`
266
+ * (its own "nothing to send" answer for an absent rule), which
267
+ * `JSON.stringify` drops from the request -- exactly why no code path could
268
+ * clear a rule before this. */
269
+ export declare function patchToWire(patch: CalendarEventPatch): Record<string, unknown>;
270
+ /** RFC 8620 §5.2's own `/changes` response shape, shared verbatim by
271
+ * `CalendarEvent/changes` and `Calendar/changes` -- both map through this
272
+ * one function (wtfalch/calendar#65). */
273
+ export type WireChanges = {
274
+ newState: string;
275
+ created?: readonly string[] | null;
276
+ updated?: readonly string[] | null;
277
+ destroyed?: readonly string[] | null;
278
+ hasMoreChanges?: boolean | null;
279
+ };
280
+ export declare function changesFromWire(wire: WireChanges): CalendarChanges;
281
+ /** The properties `getEventProjections` asks the server for -- named
282
+ * explicitly, the same discipline `EVENT_GET_PROPERTIES` already follows,
283
+ * so a title, description or location is never part of the response in the
284
+ * first place (wtfalch/calendar#65; Activity holds identifiers only, per
285
+ * `activity/packages/service/src/calendar/jmap.ts:17-22`). */
286
+ export declare const EVENT_PROJECTION_PROPERTIES: readonly ["id", "status", "sequence", "participants"];
287
+ export type WireEventProjection = {
288
+ id: string;
289
+ status?: string | null;
290
+ sequence?: number | null;
291
+ participants?: Record<string, WireParticipant> | null;
292
+ };
293
+ export declare function eventProjectionFromWire(wire: WireEventProjection): CalendarEventProjection;
138
294
  /**
139
295
  * A minimal ISO 8601 / RFC 5545 duration parser: `P`, an optional week or
140
296
  * day count, an optional `T` time part with hours/minutes/seconds. Years and
@@ -40,6 +40,43 @@
40
40
  * **Returned by Stalwart and deliberately unmapped**, because no public type
41
41
  * needs them yet: `organizerCalendarAddress`, `recurrenceIdTimeZone`,
42
42
  * `updated`, `isDraft`, `isOrigin`.
43
+ *
44
+ * **`alerts` is live-confirmed too** (T15, issue #15, Stalwart v0.16.20). A
45
+ * relative-trigger, display-action alert -- `{trigger: {"@type":
46
+ * "OffsetTrigger", offset: "-PT15M"}, action: "display"}` -- round-trips
47
+ * through create and get with no shape change at all: no `relativeTo` filled
48
+ * in, the offset string untouched. It is one of the properties
49
+ * `EVENT_GET_PROPERTIES` must name explicitly, the same as
50
+ * `recurrenceId`/`baseEventId` above: a `get` naming this file's own property
51
+ * list, from before `alerts` joined it, came back with no `alerts` key at
52
+ * all even though the event had one.
53
+ *
54
+ * **Amendment, a refuter finding (T15).** Three more things confirmed live:
55
+ * an `AbsoluteTrigger` (`{"@type":"AbsoluteTrigger","when":"..."}`)
56
+ * round-trips too, alongside an `iCalendar.convertedProperties` block this
57
+ * file deliberately leaves unmapped; a trigger written with neither `offset`
58
+ * nor `when` is accepted on create but comes back on the next `get` with
59
+ * *no* `trigger` key at all, which crashed the first version of
60
+ * `alertFromWire` (it read `wire.trigger.offset` unconditionally) and must
61
+ * not corrupt the alert on write-back either; and `acknowledged` is a real
62
+ * stored field a client must round-trip, because `CalendarEvent/set` on
63
+ * `alerts` replaces the whole map -- the first version of `alertToWire`
64
+ * dropped it, so any update that touched `alerts` at all wiped every
65
+ * alert's acknowledgement, confirmed live.
66
+ *
67
+ * **`virtualLocations` (#16), live-confirmed against Stalwart v0.16.20.** The
68
+ * server round-trips it exactly like `locations` -- a map of objects keyed
69
+ * arbitrarily, here `{"@type":"VirtualLocation","uri":...,"name":...}` -- and
70
+ * it joins the same trap `recurrenceId`/`baseEventId` were already in: a
71
+ * `CalendarEvent/get` with an explicit `properties` list that omits it comes
72
+ * back with the property missing even though the value is still stored,
73
+ * confirmed by creating an event with it, then reading it back once with the
74
+ * old `EVENT_GET_PROPERTIES` (missing) and once with it added (present).
75
+ * `CalendarEvent/set update` was confirmed field-scoped: patching only
76
+ * `title` on an event that carries a `virtualLocations` set by a raw JMAP
77
+ * write left it untouched on the next `get` -- this file only ever writes
78
+ * the key when a caller's own patch mentions it (`patchToWire`), so that
79
+ * holds for this client's own `updateEvent` too.
43
80
  */
44
81
  // ---------------------------------------------------------------------------
45
82
  // Rights: array (public) <-> boolean-keyed object (wire)
@@ -150,6 +187,85 @@ function participantsToWire(participants) {
150
187
  return undefined;
151
188
  return Object.fromEntries(participants.map((p, i) => [`p${i}`, participantToWire(p)]));
152
189
  }
190
+ /** `id` is the wire's own map key for this alert -- passed in rather than
191
+ * read off `wire` because the map key lives beside the value, in
192
+ * `alertsFromWire`'s `Object.entries`, not inside it. */
193
+ function alertFromWire(id, wire) {
194
+ const trigger = wire.trigger;
195
+ return {
196
+ id,
197
+ offset: trigger?.offset,
198
+ when: trigger?.when,
199
+ relativeTo: trigger?.relativeTo ? trigger.relativeTo : undefined,
200
+ // `types.ts` fixes the action union to 'display' (email is out of scope
201
+ // for this ticket); a server that ever sends 'email' is a case this
202
+ // contract has no room for yet, not something to crash on.
203
+ action: (wire.action ?? 'display'),
204
+ acknowledged: wire.acknowledged ?? undefined,
205
+ };
206
+ }
207
+ /** Builds a trigger from whichever of `offset`/`when` the alert actually
208
+ * carries, and omits the key entirely when it has neither -- the same
209
+ * shape a live `get` sends back for an alert this package could not
210
+ * reconstruct a trigger for, rather than emit an empty or partial one
211
+ * (T15 amendment: writing back `{"@type":"OffsetTrigger"}` with no
212
+ * `offset` is what produced the trigger-less alert in the first place). */
213
+ function alertToWire(alert) {
214
+ const trigger = alert.offset !== undefined
215
+ ? {
216
+ '@type': 'OffsetTrigger',
217
+ offset: alert.offset,
218
+ ...(alert.relativeTo === undefined ? {} : { relativeTo: alert.relativeTo }),
219
+ }
220
+ : alert.when !== undefined
221
+ ? { '@type': 'AbsoluteTrigger', when: alert.when }
222
+ : undefined;
223
+ return {
224
+ '@type': 'Alert',
225
+ ...(trigger ? { trigger } : {}),
226
+ action: alert.action,
227
+ ...(alert.acknowledged === undefined ? {} : { acknowledged: alert.acknowledged }),
228
+ };
229
+ }
230
+ function alertsFromWire(wire) {
231
+ if (!wire)
232
+ return undefined;
233
+ const list = Object.entries(wire).map(([id, alert]) => alertFromWire(id, alert));
234
+ return list.length > 0 ? list : undefined;
235
+ }
236
+ /**
237
+ * An alert read off the server keeps its own wire id (`CalendarAlert.id`),
238
+ * because `CalendarEvent/set` replaces the *whole* `alerts` map on any
239
+ * write that touches it -- a client that renumbers keys on every save also
240
+ * renames them server-side (T15 amendment; `types.ts`'s own doc comment on
241
+ * `CalendarAlert.id`). An alert the caller built fresh has no id yet, so it
242
+ * gets a stable per-call index instead, the same as `participantsToWire` --
243
+ * chosen past any id already in use, so a fresh alert can never collide
244
+ * with one being carried forward.
245
+ */
246
+ function alertsToWire(alerts) {
247
+ if (!alerts)
248
+ return undefined;
249
+ // Scanned up front, not just against ids assigned so far: two alerts
250
+ // could otherwise be given the same generated id when one being carried
251
+ // forward has an id a later fresh alert would have picked, silently
252
+ // dropping the first one from the map.
253
+ const usedIds = new Set(alerts.map((alert) => alert.id).filter((id) => id !== undefined));
254
+ const wire = {};
255
+ let index = 0;
256
+ for (const alert of alerts) {
257
+ let id = alert.id;
258
+ if (id === undefined) {
259
+ do {
260
+ id = `alert${index}`;
261
+ index += 1;
262
+ } while (usedIds.has(id));
263
+ usedIds.add(id);
264
+ }
265
+ wire[id] = alertToWire(alert);
266
+ }
267
+ return wire;
268
+ }
153
269
  function locationFromWire(wire) {
154
270
  if (!wire)
155
271
  return undefined;
@@ -161,7 +277,72 @@ function locationToWire(location) {
161
277
  return undefined;
162
278
  return { main: { '@type': 'Location', name: location } };
163
279
  }
164
- function recurrenceRuleFromWire(wire) {
280
+ function virtualLocationFromWire(wire) {
281
+ return { uri: wire.uri, name: wire.name ?? undefined };
282
+ }
283
+ function virtualLocationsFromWire(wire) {
284
+ if (!wire)
285
+ return undefined;
286
+ const list = Object.values(wire).map(virtualLocationFromWire);
287
+ return list.length > 0 ? list : undefined;
288
+ }
289
+ /** Wire virtual-location ids are arbitrary and never read back, the same as
290
+ * `participantsToWire`'s own `p${i}` keys. */
291
+ function virtualLocationsToWire(locations) {
292
+ if (!locations)
293
+ return undefined;
294
+ return Object.fromEntries(locations.map((location, i) => [
295
+ `v${i}`,
296
+ {
297
+ '@type': 'VirtualLocation',
298
+ uri: location.uri,
299
+ ...(location.name === undefined ? {} : { name: location.name }),
300
+ },
301
+ ]));
302
+ }
303
+ function linksFromWire(wire) {
304
+ if (!wire)
305
+ return undefined;
306
+ const list = Object.values(wire).map((link) => ({
307
+ href: link.href,
308
+ title: link.title ?? undefined,
309
+ contentType: link.contentType ?? undefined,
310
+ size: link.size ?? undefined,
311
+ rel: link.rel ?? undefined,
312
+ }));
313
+ return list.length > 0 ? list : undefined;
314
+ }
315
+ /** Wire link ids are arbitrary and never read back, the same as
316
+ * `virtualLocationsToWire`'s own `v${i}` keys (wtfalch/calendar#32). */
317
+ function linksToWire(links) {
318
+ if (!links)
319
+ return undefined;
320
+ return Object.fromEntries(links.map((link, i) => [
321
+ `l${i}`,
322
+ {
323
+ '@type': 'Link',
324
+ href: link.href,
325
+ ...(link.title === undefined ? {} : { title: link.title }),
326
+ ...(link.contentType === undefined ? {} : { contentType: link.contentType }),
327
+ ...(link.size === undefined ? {} : { size: link.size }),
328
+ ...(link.rel === undefined ? {} : { rel: link.rel }),
329
+ },
330
+ ]));
331
+ }
332
+ function nDayFromWire(wire) {
333
+ return {
334
+ day: wire.day,
335
+ nthOfPeriod: wire.nthOfPeriod ?? undefined,
336
+ };
337
+ }
338
+ function nDayToWire(day) {
339
+ return {
340
+ '@type': 'NDay',
341
+ day: day.day,
342
+ ...(day.nthOfPeriod === undefined ? {} : { nthOfPeriod: day.nthOfPeriod }),
343
+ };
344
+ }
345
+ export function recurrenceRuleFromWire(wire) {
165
346
  if (!wire)
166
347
  return undefined;
167
348
  return {
@@ -169,6 +350,18 @@ function recurrenceRuleFromWire(wire) {
169
350
  // extension this contract has no room for, not something to crash on.
170
351
  frequency: wire.frequency,
171
352
  interval: wire.interval ?? undefined,
353
+ rscale: wire.rscale ?? undefined,
354
+ skip: (wire.skip ?? undefined),
355
+ firstDayOfWeek: (wire.firstDayOfWeek ?? undefined),
356
+ byDay: wire.byDay ? wire.byDay.map(nDayFromWire) : undefined,
357
+ byMonthDay: wire.byMonthDay ?? undefined,
358
+ byMonth: wire.byMonth ?? undefined,
359
+ byYearDay: wire.byYearDay ?? undefined,
360
+ byWeekNo: wire.byWeekNo ?? undefined,
361
+ byHour: wire.byHour ?? undefined,
362
+ byMinute: wire.byMinute ?? undefined,
363
+ bySecond: wire.bySecond ?? undefined,
364
+ bySetPosition: wire.bySetPosition ?? undefined,
172
365
  count: wire.count ?? undefined,
173
366
  until: wire.until ?? undefined,
174
367
  };
@@ -180,6 +373,18 @@ function recurrenceRuleToWire(rule) {
180
373
  '@type': 'RecurrenceRule',
181
374
  frequency: rule.frequency,
182
375
  ...(rule.interval === undefined ? {} : { interval: rule.interval }),
376
+ ...(rule.rscale === undefined ? {} : { rscale: rule.rscale }),
377
+ ...(rule.skip === undefined ? {} : { skip: rule.skip }),
378
+ ...(rule.firstDayOfWeek === undefined ? {} : { firstDayOfWeek: rule.firstDayOfWeek }),
379
+ ...(rule.byDay === undefined ? {} : { byDay: rule.byDay.map(nDayToWire) }),
380
+ ...(rule.byMonthDay === undefined ? {} : { byMonthDay: rule.byMonthDay }),
381
+ ...(rule.byMonth === undefined ? {} : { byMonth: rule.byMonth }),
382
+ ...(rule.byYearDay === undefined ? {} : { byYearDay: rule.byYearDay }),
383
+ ...(rule.byWeekNo === undefined ? {} : { byWeekNo: rule.byWeekNo }),
384
+ ...(rule.byHour === undefined ? {} : { byHour: rule.byHour }),
385
+ ...(rule.byMinute === undefined ? {} : { byMinute: rule.byMinute }),
386
+ ...(rule.bySecond === undefined ? {} : { bySecond: rule.bySecond }),
387
+ ...(rule.bySetPosition === undefined ? {} : { bySetPosition: rule.bySetPosition }),
183
388
  ...(rule.count === undefined ? {} : { count: rule.count }),
184
389
  ...(rule.until === undefined ? {} : { until: rule.until }),
185
390
  };
@@ -187,7 +392,28 @@ function recurrenceRuleToWire(rule) {
187
392
  /** The event properties this package asks the server for. Naming them
188
393
  * explicitly, rather than omitting `properties` for "everything", keeps a
189
394
  * server-side addition from silently changing what `wireEventFromWire`
190
- * has to cope with. */
395
+ * has to cope with.
396
+ *
397
+ * `alerts` has to be named here: live-confirmed against Stalwart v0.16.20
398
+ * that a `CalendarEvent/get` asking for this exact property list -- before
399
+ * `alerts` was added to it -- comes back with no `alerts` key at all, even
400
+ * though the event has one (T15). An unqualified `get` (no `properties` at
401
+ * all) does return `alerts` on its own, the way it also returns everything
402
+ * else this list already names, but this package never sends an
403
+ * unqualified `get`.
404
+ *
405
+ * `virtualLocations` -- live-confirmed against Stalwart v0.16.20 (#16): an
406
+ * event that carries one still comes back without it if this list omits the
407
+ * name, the same trap `recurrenceId`/`baseEventId` already set (this file's
408
+ * header comment).
409
+ *
410
+ * `freeBusyStatus` (wtfalch/calendar#29) is named here on the strength of
411
+ * that same pattern, not a fresh live capture -- every property this list
412
+ * has ever gained needed an explicit name, and nothing suggests this is the
413
+ * one exception.
414
+ *
415
+ * `mayInviteSelf`/`mayInviteOthers` (wtfalch/calendar#51) are named here on
416
+ * that same strength, not a fresh live capture either. */
191
417
  export const EVENT_GET_PROPERTIES = [
192
418
  'id',
193
419
  'calendarIds',
@@ -199,9 +425,15 @@ export const EVENT_GET_PROPERTIES = [
199
425
  'duration',
200
426
  'showWithoutTime',
201
427
  'locations',
428
+ 'virtualLocations',
429
+ 'links',
202
430
  'recurrenceRule',
203
431
  'participants',
432
+ 'mayInviteSelf',
433
+ 'mayInviteOthers',
434
+ 'alerts',
204
435
  'status',
436
+ 'freeBusyStatus',
205
437
  'sequence',
206
438
  'baseEventId',
207
439
  'recurrenceId',
@@ -226,9 +458,15 @@ export function eventFromWire(wire, calendarIdFallback) {
226
458
  duration: wire.duration,
227
459
  isAllDay: wire.showWithoutTime ?? false,
228
460
  location: locationFromWire(wire.locations),
461
+ virtualLocations: virtualLocationsFromWire(wire.virtualLocations),
462
+ links: linksFromWire(wire.links),
229
463
  recurrenceRule: recurrenceRuleFromWire(wire.recurrenceRule),
230
464
  participants: participantsFromWire(wire.participants),
465
+ mayInviteSelf: wire.mayInviteSelf ?? undefined,
466
+ mayInviteOthers: wire.mayInviteOthers ?? undefined,
467
+ alerts: alertsFromWire(wire.alerts),
231
468
  status: (wire.status ?? 'confirmed'),
469
+ freeBusyStatus: (wire.freeBusyStatus ?? undefined),
232
470
  sequence: wire.sequence ?? 0,
233
471
  recurrenceId: wire.recurrenceId ?? undefined,
234
472
  baseEventId: wire.baseEventId ?? undefined,
@@ -248,18 +486,35 @@ export function draftToWire(calendarId, draft) {
248
486
  duration: draft.duration,
249
487
  showWithoutTime: draft.isAllDay,
250
488
  ...(locationToWire(draft.location) ? { locations: locationToWire(draft.location) } : {}),
489
+ ...(virtualLocationsToWire(draft.virtualLocations)
490
+ ? { virtualLocations: virtualLocationsToWire(draft.virtualLocations) }
491
+ : {}),
492
+ ...(linksToWire(draft.links) ? { links: linksToWire(draft.links) } : {}),
251
493
  ...(recurrenceRuleToWire(draft.recurrenceRule)
252
494
  ? { recurrenceRule: recurrenceRuleToWire(draft.recurrenceRule) }
253
495
  : {}),
254
496
  ...(participantsToWire(draft.participants)
255
497
  ? { participants: participantsToWire(draft.participants) }
256
498
  : {}),
499
+ ...(alertsToWire(draft.alerts) ? { alerts: alertsToWire(draft.alerts) } : {}),
257
500
  status: draft.status,
501
+ ...(draft.freeBusyStatus === undefined ? {} : { freeBusyStatus: draft.freeBusyStatus }),
502
+ ...(draft.mayInviteSelf === undefined ? {} : { mayInviteSelf: draft.mayInviteSelf }),
503
+ ...(draft.mayInviteOthers === undefined ? {} : { mayInviteOthers: draft.mayInviteOthers }),
258
504
  };
259
505
  }
260
506
  /** Only the properties `patch` actually carries -- `CalendarEvent/set`'s
261
507
  * `update` is a genuine patch, and a field the caller did not mention must
262
- * not be overwritten with `undefined`. */
508
+ * not be overwritten with `undefined`.
509
+ *
510
+ * `recurrenceRule: null` is the one field this writes a real wire `null`
511
+ * for, rather than dropping the key: `CalendarEventPatch` widens just this
512
+ * field to allow it, as the explicit "clear this" signal distinct from
513
+ * leaving the key out entirely (wtfalch/calendar#45). Writing
514
+ * `recurrenceRuleToWire(null)` here instead would have produced `undefined`
515
+ * (its own "nothing to send" answer for an absent rule), which
516
+ * `JSON.stringify` drops from the request -- exactly why no code path could
517
+ * clear a rule before this. */
263
518
  export function patchToWire(patch) {
264
519
  const wire = {};
265
520
  if (patch.calendarId !== undefined)
@@ -280,15 +535,60 @@ export function patchToWire(patch) {
280
535
  wire.showWithoutTime = patch.isAllDay;
281
536
  if (patch.location !== undefined)
282
537
  wire.locations = locationToWire(patch.location);
538
+ if (patch.virtualLocations !== undefined) {
539
+ wire.virtualLocations = virtualLocationsToWire(patch.virtualLocations);
540
+ }
541
+ if (patch.links !== undefined)
542
+ wire.links = linksToWire(patch.links);
283
543
  if (patch.recurrenceRule !== undefined) {
284
- wire.recurrenceRule = recurrenceRuleToWire(patch.recurrenceRule);
544
+ wire.recurrenceRule =
545
+ patch.recurrenceRule === null ? null : recurrenceRuleToWire(patch.recurrenceRule);
285
546
  }
286
547
  if (patch.participants !== undefined)
287
548
  wire.participants = participantsToWire(patch.participants);
549
+ if (patch.mayInviteSelf !== undefined)
550
+ wire.mayInviteSelf = patch.mayInviteSelf;
551
+ if (patch.mayInviteOthers !== undefined)
552
+ wire.mayInviteOthers = patch.mayInviteOthers;
553
+ if (patch.alerts !== undefined)
554
+ wire.alerts = alertsToWire(patch.alerts);
288
555
  if (patch.status !== undefined)
289
556
  wire.status = patch.status;
557
+ if (patch.freeBusyStatus !== undefined)
558
+ wire.freeBusyStatus = patch.freeBusyStatus;
290
559
  return wire;
291
560
  }
561
+ export function changesFromWire(wire) {
562
+ return {
563
+ newState: wire.newState,
564
+ created: wire.created ?? [],
565
+ updated: wire.updated ?? [],
566
+ destroyed: wire.destroyed ?? [],
567
+ hasMoreChanges: wire.hasMoreChanges ?? false,
568
+ };
569
+ }
570
+ // ---------------------------------------------------------------------------
571
+ // CalendarEventProjection: id, status, sequence, participants' addresses
572
+ // ---------------------------------------------------------------------------
573
+ /** The properties `getEventProjections` asks the server for -- named
574
+ * explicitly, the same discipline `EVENT_GET_PROPERTIES` already follows,
575
+ * so a title, description or location is never part of the response in the
576
+ * first place (wtfalch/calendar#65; Activity holds identifiers only, per
577
+ * `activity/packages/service/src/calendar/jmap.ts:17-22`). */
578
+ export const EVENT_PROJECTION_PROPERTIES = ['id', 'status', 'sequence', 'participants'];
579
+ export function eventProjectionFromWire(wire) {
580
+ return {
581
+ id: wire.id,
582
+ // Mirrors `eventFromWire`'s own defaults: absent reads as 'confirmed'
583
+ // and 0, the same fallbacks a caller of the full `CalendarEvent` already
584
+ // relies on.
585
+ status: (wire.status ?? 'confirmed'),
586
+ sequence: wire.sequence ?? 0,
587
+ participants: wire.participants
588
+ ? Object.values(wire.participants).map((p) => ({ calendarAddress: p.calendarAddress }))
589
+ : [],
590
+ };
591
+ }
292
592
  // ---------------------------------------------------------------------------
293
593
  // Availability
294
594
  // ---------------------------------------------------------------------------
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wtfalch/calendar",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "A JMAP calendar client for Agora, the wtfalch communications app: events, invites, sharing and free/busy over Stalwart, and the React UI on react-big-calendar.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -37,7 +37,7 @@
37
37
  "dev": "vite --config dev/vite.config.ts"
38
38
  },
39
39
  "peerDependencies": {
40
- "@wtfalch/design": "0.21.0",
40
+ "@wtfalch/design": "^0.21.0",
41
41
  "react": "^19.0.0",
42
42
  "react-big-calendar": "^1.20.0",
43
43
  "react-dom": "^19.0.0"