@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.
@@ -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 ZITADEL token, mirroring
33
- * `createChatClient`'s `getAccessToken` rather than `MailClientOptions`'s
34
- * static `bearerToken` — every first-ship feature is a live
35
- * browser-to-Stalwart call (plan §7; #143 §2), and only a callback
36
- * survives a mid-session token refresh with no host-app code.
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 5545 §3.3.10 shaped.
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 and edit the rule, not
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 master event this occurrence was expanded from, set only on an
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
- updateEvent(id: string, patch: Partial<CalendarEventDraft>, options?: SchedulingOptions): Promise<CalendarEvent>;
289
- deleteEvent(id: string, options?: SchedulingOptions): Promise<void>;
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
- /** A person's busy periods over `range`, gated by the ACL share alone —
310
- * see `AvailabilityPeriod`'s doc comment for the empty-result rule
311
- * (plan §5; #137 "Free/busy"). */
312
- getAvailability(principalId: string, range: CalendarRange): Promise<readonly AvailabilityPeriod[]>;
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.