@wtfalch/calendar 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +15 -0
  3. package/dist/calendar/calendar-client.d.ts +7 -0
  4. package/dist/calendar/calendar-client.js +242 -0
  5. package/dist/calendar/calendar.css +953 -0
  6. package/dist/calendar/client.d.ts +87 -0
  7. package/dist/calendar/client.js +233 -0
  8. package/dist/calendar/errors.d.ts +28 -0
  9. package/dist/calendar/errors.js +61 -0
  10. package/dist/calendar/fake/index.d.ts +36 -0
  11. package/dist/calendar/fake/index.js +79 -0
  12. package/dist/calendar/fake/sample.d.ts +66 -0
  13. package/dist/calendar/fake/sample.js +116 -0
  14. package/dist/calendar/fake/store.d.ts +79 -0
  15. package/dist/calendar/fake/store.js +906 -0
  16. package/dist/calendar/index.d.ts +12 -0
  17. package/dist/calendar/index.js +11 -0
  18. package/dist/calendar/push.d.ts +38 -0
  19. package/dist/calendar/push.js +129 -0
  20. package/dist/calendar/react/AvailabilityRibbon.d.ts +40 -0
  21. package/dist/calendar/react/AvailabilityRibbon.js +108 -0
  22. package/dist/calendar/react/Calendar.d.ts +28 -0
  23. package/dist/calendar/react/Calendar.js +431 -0
  24. package/dist/calendar/react/EventDetail.d.ts +22 -0
  25. package/dist/calendar/react/EventDetail.js +91 -0
  26. package/dist/calendar/react/EventEditor.d.ts +52 -0
  27. package/dist/calendar/react/EventEditor.js +188 -0
  28. package/dist/calendar/react/ShareDialog.d.ts +25 -0
  29. package/dist/calendar/react/ShareDialog.js +125 -0
  30. package/dist/calendar/react/Toolbar.d.ts +29 -0
  31. package/dist/calendar/react/Toolbar.js +58 -0
  32. package/dist/calendar/react/index.d.ts +9 -0
  33. package/dist/calendar/react/index.js +8 -0
  34. package/dist/calendar/react/participants.d.ts +34 -0
  35. package/dist/calendar/react/participants.js +40 -0
  36. package/dist/calendar/types.d.ts +384 -0
  37. package/dist/calendar/types.js +40 -0
  38. package/dist/calendar/uri.d.ts +13 -0
  39. package/dist/calendar/uri.js +22 -0
  40. package/dist/calendar/wire.d.ts +177 -0
  41. package/dist/calendar/wire.js +349 -0
  42. package/package.json +82 -0
@@ -0,0 +1,384 @@
1
+ /**
2
+ * The package's whole public type surface, and nothing else.
3
+ *
4
+ * This file is the contract MSG-054 (mounting `Calendar` into Agora) and
5
+ * MSG-055 (the event-editing, sharing and free/busy behaviour) build against
6
+ * in parallel, so it has to compile alone and say everything the shape of
7
+ * `@wtfalch/calendar` needs before either of those exists.
8
+ *
9
+ * Nothing here comes from `jmap-jam` or the JMAP wire types: those stay
10
+ * behind the client, mirroring `@wtfalch/email/mailbox/types.ts`'s own
11
+ * "nothing here comes from `jmap-jam`" rule.
12
+ *
13
+ * Sources: the calendar plan
14
+ * (https://github.com/wtfalch/messaging/blob/main/.plans/2026-09-17-calendar.md,
15
+ * "the plan") §7, this package's own ticket
16
+ * (https://github.com/wtfalch/messaging/issues/156, "MSG-053"), the decision
17
+ * that shaped the ticket (https://github.com/wtfalch/messaging/issues/143,
18
+ * "#143"), and the live JMAP findings it rests on
19
+ * (https://github.com/wtfalch/messaging/issues/137, "#137";
20
+ * https://github.com/wtfalch/messaging/issues/138, "#138").
21
+ */
22
+ import type { ReactNode } from 'react';
23
+ /**
24
+ * What `createCalendarClient` takes from Agora — and nothing else (plan
25
+ * §7, "Nothing else. No exchange service, no device state").
26
+ */
27
+ export type CalendarClientOptions = {
28
+ /** Stalwart's JMAP session URL, project config the surrounding app
29
+ * assembles. Mirrors `MailClientOptions.sessionUrl` (plan §7; #143 §2). */
30
+ sessionUrl: string;
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.
37
+ */
38
+ getAccessToken: () => string | Promise<string>;
39
+ /** Override the session's primary account. Needed because a JMAP session
40
+ * can carry more than one account; the client must pick the one with the
41
+ * `calendars` capability (plan §7; #143 §2, mirroring
42
+ * `MailClientOptions.accountId`). */
43
+ accountId?: string;
44
+ };
45
+ /** One JMAP ACL right a calendar's `shareWith` grant can carry (#138 §1,
46
+ * `CalendarRight` — `MayReadFreeBusy`, `MayReadItems`, `MayWriteAll`,
47
+ * `MayWriteOwn`, `MayUpdatePrivate`, `MayRSVP`, `MayShare`, `MayDelete`,
48
+ * `crates/jmap-proto/src/object/calendar.rs:58-67`). Named lowerCamel here
49
+ * to match the JMAP property names `shareWith`/`myRights` carry them as. */
50
+ export type CalendarRight = 'mayReadFreeBusy' | 'mayReadItems' | 'mayWriteAll' | 'mayWriteOwn' | 'mayUpdatePrivate' | 'mayRSVP' | 'mayShare' | 'mayDelete';
51
+ /**
52
+ * One grant in a calendar's `shareWith` ACL: an account, and the rights it
53
+ * holds on this calendar (#138 §1). JMAP `shareWith` and CalDAV `ACL` write
54
+ * and read the identical stored `acls: Vec<AclGrant>` — one ACL, not two
55
+ * (#138 §1, `crates/dav/src/common/acl.rs`).
56
+ */
57
+ export type ShareGrant = {
58
+ /** The account being granted access — `shareWith`'s key (#138 §1,
59
+ * `crates/jmap/src/api/acl.rs:31-40`). Can name a `Group` account, which
60
+ * reaches every member (#138 §2). */
61
+ accountId: string;
62
+ rights: readonly CalendarRight[];
63
+ };
64
+ /**
65
+ * One JMAP principal -- what `Principal/get` returns, and what
66
+ * `resolvePrincipal` turns a calendar address into so a share dialog never
67
+ * has to know the wire shape. Live-confirmed against Stalwart v0.16.20 as an
68
+ * ordinary user, no admin rights (MSG-055 slice 3 plan): `Principal/query`
69
+ * with `filter: {email}` returns at most one id, and `Principal/get` on it
70
+ * carries `{id, type, name, description, email}`.
71
+ */
72
+ export type Principal = {
73
+ /** From the wire's `id` -- the account id `shareWith`'s key demands. */
74
+ accountId: string;
75
+ /** From the wire's `email`, verbatim. */
76
+ email: string;
77
+ /** The display name -- from the wire's `description`, which is where
78
+ * Stalwart puts the human-readable name ("Bob"); the wire's own `name`
79
+ * carries the address again, not a friendlier label, so it is not used
80
+ * here. */
81
+ name?: string;
82
+ };
83
+ /** A calendar's own opt-in into `Principal/getAvailability` results. Live
84
+ * testing found this need not be set for a shared calendar to contribute
85
+ * busy periods (#137 amendment), but the property still exists on the
86
+ * object and a person can still see it on their own calendar. */
87
+ export type AvailabilityInclusion = 'all' | 'attending' | 'none';
88
+ /** One calendar. The `Calendar` groupware object carries no owner field —
89
+ * it lives in whichever account's data collection created it (#138 §4) —
90
+ * so nothing here names an owner either. */
91
+ export type Calendar = {
92
+ id: string;
93
+ name: string;
94
+ description?: string;
95
+ color?: string;
96
+ /** Whether events on this calendar currently show in views. */
97
+ isVisible: boolean;
98
+ /** This account's own rights on the calendar — full on one you created,
99
+ * whatever `shareWith` granted on one shared with you (#138 §1). */
100
+ myRights: readonly CalendarRight[];
101
+ /** Every grant this calendar's owner has made. Empty on a calendar shared
102
+ * with you but not owned by you — you see your own `myRights`, not the
103
+ * owner's whole list. */
104
+ shareWith: readonly ShareGrant[];
105
+ includeInAvailability: AvailabilityInclusion;
106
+ };
107
+ /** RFC 5545 participation roles, as JSCalendar's `Participant.roles` names
108
+ * them (plan §7; #143 §4's `CalendarParticipant` needs a role to tell an
109
+ * organizer from an attendee for the invite UI). */
110
+ export type CalendarParticipantRole = 'owner' | 'attendee' | 'optional' | 'chair' | 'informational';
111
+ /** RFC 5545's `PARTSTAT`, as JSCalendar's `Participant.participationStatus`
112
+ * names it. */
113
+ export type CalendarParticipationStatus = 'needs-action' | 'accepted' | 'declined' | 'tentative';
114
+ /**
115
+ * One person on an event's invite list.
116
+ *
117
+ * `calendarAddress` — confirmed live against a running Stalwart v0.16.20:
118
+ * the wire uses this singular field name, not JSCalendar's `email` (MSG-053
119
+ * acceptance criteria; plan §7; #137 amendment, 2026-09-17).
120
+ */
121
+ export type CalendarParticipant = {
122
+ calendarAddress: string;
123
+ name?: string;
124
+ roles?: readonly CalendarParticipantRole[];
125
+ participationStatus?: CalendarParticipationStatus;
126
+ };
127
+ /**
128
+ * A recurrence rule, RFC 5545 §3.3.10 shaped.
129
+ *
130
+ * `recurrenceRule` — confirmed live: the wire uses this singular field name
131
+ * (one rule), not JSCalendar 2.0's plural `recurrenceRules` (MSG-053
132
+ * acceptance criteria; plan §7; #137 amendment). The client never expands
133
+ * 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.
136
+ */
137
+ export type CalendarRecurrenceRule = {
138
+ frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
139
+ interval?: number;
140
+ count?: number;
141
+ until?: string;
142
+ };
143
+ /** RFC 5545 `STATUS`, as JSCalendar's `Event.status` names it. */
144
+ export type CalendarEventStatus = 'confirmed' | 'cancelled' | 'tentative';
145
+ /**
146
+ * One event, or one occurrence of a recurring event.
147
+ *
148
+ * A query with `expandRecurrences: true` returns a synthetic id per
149
+ * occurrence, distinct from the master event's id (#137 "Recurrence",
150
+ * `CalendarSyntheticId`); `recurrenceId` is set only on such an occurrence.
151
+ * The wire shape behind this type has now been diffed field by field against
152
+ * a live `CalendarEvent/get` on Stalwart v0.16.20 (MSG-055). `wire.ts`'s own
153
+ * header comment records the result and the one field still open, `sequence`,
154
+ * which the server accepts as a name but never sent a value for.
155
+ */
156
+ export type CalendarEvent = {
157
+ id: string;
158
+ /** The calendar this event's master lives on. First-ship views overlay
159
+ * every visible calendar rather than selecting one, but a create/update
160
+ * still targets exactly one (plan §7's `CalendarLocation` has no
161
+ * `calendarId`, for that reason). */
162
+ calendarId: string;
163
+ /** The iCalendar `UID`, stable across an event's whole recurring series
164
+ * and across the organizer's and each attendee's own copies. */
165
+ uid: string;
166
+ title: string;
167
+ description?: string;
168
+ /** A local date-time (no offset); `timeZone` says which zone it is local
169
+ * to, `null` for a floating time. */
170
+ start: string;
171
+ timeZone: string | null;
172
+ /** An ISO 8601 duration, e.g. `PT1H`. */
173
+ duration: string;
174
+ isAllDay: boolean;
175
+ location?: string;
176
+ recurrenceRule?: CalendarRecurrenceRule;
177
+ participants?: readonly CalendarParticipant[];
178
+ status: CalendarEventStatus;
179
+ /** RFC 5545 `SEQUENCE`, bumped on every organizer edit an attendee's
180
+ * client should treat as superseding its own copy. */
181
+ sequence: number;
182
+ /** Set only on an expanded occurrence (see above); absent on a master
183
+ * event or a non-recurring one. */
184
+ recurrenceId?: string;
185
+ /** The master event this occurrence was expanded from, set only on an
186
+ * expanded occurrence.
187
+ *
188
+ * Editing a series means addressing the master, and an occurrence's own
189
+ * `id` is synthetic, so without this an editor can change one occurrence
190
+ * and has no way to reach the other eleven. */
191
+ baseEventId?: string;
192
+ };
193
+ /** The fields a new event's caller supplies; everything else is
194
+ * server-assigned on create (`id`, `sequence`) or query-assigned
195
+ * (`recurrenceId`). */
196
+ export type CalendarEventDraft = Omit<CalendarEvent, 'id' | 'sequence' | 'recurrenceId'>;
197
+ /** RFC 5545 `FREEBUSY` `FBTYPE`, as JSCalendar's busy-period shape names
198
+ * it. */
199
+ export type CalendarBusyStatus = 'confirmed' | 'tentative' | 'unavailable';
200
+ /**
201
+ * One busy period from `Principal/getAvailability`.
202
+ *
203
+ * The booking UI must treat a person with none of these as "can't tell,"
204
+ * never as "they're free": a calendar with no share at all is skipped with
205
+ * no data, not even an aggregated blob (plan §5; #137 "Free/busy").
206
+ */
207
+ export type AvailabilityPeriod = {
208
+ start: string;
209
+ end: string;
210
+ busyStatus: CalendarBusyStatus;
211
+ };
212
+ /** The per-type state strings a push event carries, mirroring
213
+ * `@wtfalch/email/mailbox`'s `ChangedState` for the four calendar-shaped
214
+ * `DataType`s Stalwart pushes over EventSource/WebSocket: `Calendar`,
215
+ * `CalendarEvent`, `CalendarEventNotification` and the dedicated
216
+ * `CalendarAlert` reminder variant (#137 "Push"). A value that differs
217
+ * from a previous read means that type changed and its list should be
218
+ * refetched. */
219
+ export type CalendarChangedState = {
220
+ Calendar?: string;
221
+ CalendarEvent?: string;
222
+ CalendarEventNotification?: string;
223
+ CalendarAlert?: string;
224
+ [type: string]: string | undefined;
225
+ };
226
+ /** Stop listening. The connection closes and no handler runs again,
227
+ * mirroring `@wtfalch/email/mailbox/push.ts`'s `PushHandle`. */
228
+ export type CalendarSubscription = {
229
+ close: () => void;
230
+ };
231
+ /** Whether a mutating call also sends iTIP messages through Stalwart's own
232
+ * scheduling engine. Opt-in per request — unlike CalDAV, which fires
233
+ * whenever the server-wide default is on — so a client that forgets this
234
+ * silently sends no invites (plan §6; #137 "Scheduling"). Applies to
235
+ * create, update and delete alike: all three ride `CalendarEvent/set`. */
236
+ export type SchedulingOptions = {
237
+ sendSchedulingMessages?: boolean;
238
+ };
239
+ /** Who the person holding a connection is, for telling their own participant
240
+ * row from everyone else's. `calendarAddress` is bare here — no `mailto:`
241
+ * scheme — because that is how the session document writes it. */
242
+ export type CalendarIdentity = {
243
+ accountId: string;
244
+ calendarAddress: string;
245
+ name?: string;
246
+ };
247
+ /** A bounded time range. Every event-listing method takes one explicitly:
248
+ * `CalendarEvent/query` with `expandRecurrences: true` requires both
249
+ * `after` and `before`, or it returns master events only and a month view
250
+ * silently drops recurring occurrences (MSG-053 acceptance criteria; plan
251
+ * §7; #137 "Recurrence"). The client always passes `expandRecurrences:
252
+ * true` itself — it is never a caller-supplied option, so a consumer of
253
+ * this interface cannot forget it. */
254
+ export type CalendarRange = {
255
+ after: string;
256
+ before: string;
257
+ };
258
+ /**
259
+ * A connection to one JMAP calendars account.
260
+ *
261
+ * The methods below are exactly the ones the ticket and plan §7 name: list
262
+ * calendars, list events for a bounded range, get/create/update/delete an
263
+ * event, share a calendar, read a person's availability, and subscribe to
264
+ * changes. No RRULE library and no session/transport primitives are part of
265
+ * this surface — those stay behind the implementation (plan §7 "JMAP
266
+ * transport: copied, not shared").
267
+ */
268
+ export interface CalendarClient {
269
+ /**
270
+ * Who the person holding this connection is.
271
+ *
272
+ * Needed to answer an invite: an RSVP writes one participant's
273
+ * `participationStatus`, and picking the wrong row answers for somebody
274
+ * else. `@wtfalch/email`'s `Mail` reads its identity off the client the
275
+ * same way (`useIdentities(client)`) rather than taking it as a prop, so a
276
+ * host cannot forget to supply it or supply the wrong one.
277
+ *
278
+ * Free rather than a round trip: the address is already in the JMAP session
279
+ * document the connection caches, at `accounts.<id>.name` — confirmed live
280
+ * against Stalwart v0.16.20.
281
+ */
282
+ identity(): Promise<CalendarIdentity>;
283
+ listCalendars(): Promise<readonly Calendar[]>;
284
+ /** Every occurrence in `range`, recurring events expanded server-side. */
285
+ listEvents(range: CalendarRange): Promise<readonly CalendarEvent[]>;
286
+ getEvent(id: string): Promise<CalendarEvent>;
287
+ 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>;
290
+ /** Add or replace one grant in a calendar's `shareWith` ACL. A person
291
+ * shares their own calendar directly; this never touches authz (plan
292
+ * §5). */
293
+ shareCalendar(calendarId: string, grant: ShareGrant): Promise<void>;
294
+ /** Turn a calendar address into the account id `shareWith` demands as its
295
+ * key — an ordinary user can do this, no admin rights needed. `undefined`
296
+ * for an address nobody has: an unknown address is an ordinary outcome a
297
+ * share dialog checks for, not a failure (MSG-055 slice 3 plan). */
298
+ resolvePrincipal(email: string): Promise<Principal | undefined>;
299
+ /** The principals behind a set of account ids, for putting a name and an
300
+ * address on grants that carry only ids. Ids nobody claims are simply
301
+ * absent from the result rather than an error, the way `Principal/get`'s
302
+ * own `notFound` reports them. */
303
+ lookupPrincipals(accountIds: readonly string[]): Promise<readonly Principal[]>;
304
+ /** Revoke one grantee's whole grant in a calendar's `shareWith` ACL — the
305
+ * counterpart `shareCalendar` never had. `rightsToWire([])` would write an
306
+ * empty rights object for the grantee, not remove them; this instead
307
+ * deletes the `shareWith` key outright (MSG-055 slice 3 plan). */
308
+ 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[]>;
313
+ /** Watch for changes on the account. The connection reconnects on its own
314
+ * with a backoff; only `close()` needs calling when done, mirroring
315
+ * `@wtfalch/email/mailbox/push.ts`'s `push()`. */
316
+ subscribe(handler: (changed: CalendarChangedState) => void): CalendarSubscription;
317
+ }
318
+ /**
319
+ * Where the reader is: which view, which date, which event is open.
320
+ *
321
+ * Unlike `MailLocation`'s `mailboxId` (one list at a time), first-ship
322
+ * calendars overlay every visible calendar rather than switching between
323
+ * them, so there is no `calendarId` field here (plan §7). `view`/`date`
324
+ * exist because react-big-calendar is itself a controlled component on
325
+ * them, with its own internal `onNavigate`/`onView` callbacks; `Calendar`
326
+ * translates those into an update to this type and fires its own
327
+ * `onNavigate` once — react-big-calendar's callback names never surface
328
+ * here (plan §7; #143 §4).
329
+ */
330
+ export type CalendarLocation = {
331
+ view: 'month' | 'week' | 'day' | 'agenda';
332
+ date: Date;
333
+ /** The event open in detail, playing `MailLocation.threadId`'s role.
334
+ * `null`, not absent, for "none" — this field is always present on a
335
+ * controlled location (plan §7; #143 §4). */
336
+ eventId: string | null;
337
+ };
338
+ /** Fires when any of the fetches behind `Calendar` fails, mirroring
339
+ * `@wtfalch/email/mailbox/errors.ts`'s `MailError` and its `MailError`
340
+ * class shape (#143 §4's `onError?: (error: CalendarError) => void`). */
341
+ export declare class CalendarError extends Error {
342
+ /** The JMAP error type, e.g. a method-level `invalidArguments`. `unknown`
343
+ * when the server sent something unparseable. */
344
+ readonly type: string;
345
+ /** The HTTP status, when the failure was request-level. */
346
+ readonly status: number | undefined;
347
+ /** The operation this package was performing, e.g. `events.list`. */
348
+ readonly operation: string | undefined;
349
+ constructor(message: string, options?: {
350
+ type?: string;
351
+ status?: number;
352
+ operation?: string;
353
+ cause?: unknown;
354
+ });
355
+ }
356
+ /**
357
+ * `Calendar`'s props, against `Mail.tsx`'s own seams
358
+ * (`packages/email/src/mailbox/react/Mail.tsx:69-106` on `email`'s
359
+ * `origin/main`; plan §7; #143 §4).
360
+ */
361
+ export type CalendarProps = {
362
+ client: CalendarClient;
363
+ /** Drive the selection from outside — from the URL, almost always. Omit
364
+ * it and the component keeps its own. All-or-nothing with `onNavigate`,
365
+ * the same rule `Mail.tsx:76-81` documents for `MailProps.location`. */
366
+ location?: CalendarLocation;
367
+ /** Called when something in here wants to move. Required with
368
+ * `location`, because without it the controlled selection could never
369
+ * change (`Mail.tsx:85`). */
370
+ onNavigate?: (to: CalendarLocation) => void;
371
+ /** The right-hand end of the header: who is signed in, and the way out.
372
+ * A slot rather than anything this component builds (`Mail.tsx:94`). */
373
+ account?: ReactNode;
374
+ /** Called when any of the fetches behind this view fails, for the class
375
+ * of failure only the host app can act on — a 401 above all
376
+ * (`Mail.tsx:96-103`). */
377
+ onError?: (error: CalendarError) => void;
378
+ /** Now, so a story or test holds still (`Mail.tsx:105`). */
379
+ now?: Date;
380
+ /** Dropped from the ticket's own seam list (#143 body); kept here since
381
+ * nothing argues for dropping a seam `Mail` has (`Mail.tsx:106`; #143
382
+ * §4). */
383
+ className?: string;
384
+ };
@@ -0,0 +1,40 @@
1
+ /**
2
+ * The package's whole public type surface, and nothing else.
3
+ *
4
+ * This file is the contract MSG-054 (mounting `Calendar` into Agora) and
5
+ * MSG-055 (the event-editing, sharing and free/busy behaviour) build against
6
+ * in parallel, so it has to compile alone and say everything the shape of
7
+ * `@wtfalch/calendar` needs before either of those exists.
8
+ *
9
+ * Nothing here comes from `jmap-jam` or the JMAP wire types: those stay
10
+ * behind the client, mirroring `@wtfalch/email/mailbox/types.ts`'s own
11
+ * "nothing here comes from `jmap-jam`" rule.
12
+ *
13
+ * Sources: the calendar plan
14
+ * (https://github.com/wtfalch/messaging/blob/main/.plans/2026-09-17-calendar.md,
15
+ * "the plan") §7, this package's own ticket
16
+ * (https://github.com/wtfalch/messaging/issues/156, "MSG-053"), the decision
17
+ * that shaped the ticket (https://github.com/wtfalch/messaging/issues/143,
18
+ * "#143"), and the live JMAP findings it rests on
19
+ * (https://github.com/wtfalch/messaging/issues/137, "#137";
20
+ * https://github.com/wtfalch/messaging/issues/138, "#138").
21
+ */
22
+ /** Fires when any of the fetches behind `Calendar` fails, mirroring
23
+ * `@wtfalch/email/mailbox/errors.ts`'s `MailError` and its `MailError`
24
+ * class shape (#143 §4's `onError?: (error: CalendarError) => void`). */
25
+ export class CalendarError extends Error {
26
+ /** The JMAP error type, e.g. a method-level `invalidArguments`. `unknown`
27
+ * when the server sent something unparseable. */
28
+ type;
29
+ /** The HTTP status, when the failure was request-level. */
30
+ status;
31
+ /** The operation this package was performing, e.g. `events.list`. */
32
+ operation;
33
+ constructor(message, options = {}) {
34
+ super(message, { cause: options.cause });
35
+ this.name = 'CalendarError';
36
+ this.type = options.type ?? 'unknown';
37
+ this.status = options.status;
38
+ this.operation = options.operation;
39
+ }
40
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The session document's `eventSourceUrl` is an RFC 6570 level-1 template,
3
+ * and RFC 8620 §6.2 requires a client to URI-encode the values it
4
+ * substitutes. Copied from `@wtfalch/email/mailbox/uri.ts` (plan §7) rather
5
+ * than imported, so this package carries no runtime dependency on
6
+ * `@wtfalch/email` (MSG-053 acceptance criteria).
7
+ */
8
+ /**
9
+ * Expand an RFC 6570 level-1 template, percent-encoding every value.
10
+ *
11
+ * @throws {Error} when the template names a variable `params` does not supply.
12
+ */
13
+ export declare function expandTemplate(template: string, params: Record<string, string>): string;
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The session document's `eventSourceUrl` is an RFC 6570 level-1 template,
3
+ * and RFC 8620 §6.2 requires a client to URI-encode the values it
4
+ * substitutes. Copied from `@wtfalch/email/mailbox/uri.ts` (plan §7) rather
5
+ * than imported, so this package carries no runtime dependency on
6
+ * `@wtfalch/email` (MSG-053 acceptance criteria).
7
+ */
8
+ const VARIABLE = /\{([^{}]+)\}/g;
9
+ /**
10
+ * Expand an RFC 6570 level-1 template, percent-encoding every value.
11
+ *
12
+ * @throws {Error} when the template names a variable `params` does not supply.
13
+ */
14
+ export function expandTemplate(template, params) {
15
+ return template.replace(VARIABLE, (_match, name) => {
16
+ const value = params[name];
17
+ if (value === undefined) {
18
+ throw new Error(`the URI template needs a value for {${name}}: ${template}`);
19
+ }
20
+ return encodeURIComponent(value);
21
+ });
22
+ }
@@ -0,0 +1,177 @@
1
+ /**
2
+ * The wire <-> public-type mapping. Nothing in `types.ts` (the fixed
3
+ * contract) is JSON-shaped exactly like the JMAP wire, so every method in
4
+ * `calendar-client.ts` goes through here rather than passing server JSON
5
+ * straight through.
6
+ *
7
+ * **What is live-confirmed** (#137, #145; MSG-053 acceptance criteria):
8
+ * `recurrenceRule` is singular (one object, not RFC 8984's plural
9
+ * `recurrenceRules`); a participant's address property is `calendarAddress`,
10
+ * not RFC 8984's `email`; `shareWith`/`myRights` are objects keyed by
11
+ * `CalendarRight` name with boolean values (`shareWith:{"d":{mayReadItems:
12
+ * true,...}}}`, #145 check 4); `busyStatus` on a `Principal/getAvailability`
13
+ * result is a lowercase string (`"confirmed"`, #145 check 5); `participants`
14
+ * is a map keyed by an arbitrary id, not an array (`CalendarEvent/set update
15
+ * {"participants/bob/participationStatus":...}`, #145 check 3); an expanded
16
+ * occurrence carries a `baseEventId` back-reference (#145 check 2).
17
+ *
18
+ * **The rest is now live-confirmed too** (MSG-055, Stalwart v0.16.20). Every
19
+ * name this file had guessed from RFC 8984 came back verbatim off a real
20
+ * `CalendarEvent/get`: `title`, `start`, `timeZone`, `duration`, `status`,
21
+ * `uid`, the all-day flag as `showWithoutTime` (not `isAllDay`), `locations`
22
+ * as a map of `Location` objects (`{"main":{"name":"...","@type":"Location"}}`),
23
+ * `roles` as a map of booleans (`{"owner":true,"chair":true}`), and
24
+ * `recurrenceId` on an expanded occurrence alongside `baseEventId`. The
25
+ * response `availability.test.ts` pins is the transcript this paragraph
26
+ * describes.
27
+ *
28
+ * **Two things the live run changed.** `Principal/getAvailability` does not
29
+ * use any of the names guessed for it -- see `WireBusyPeriod` below. And
30
+ * `recurrenceId`/`baseEventId` are returned only when named explicitly in
31
+ * `properties`; a `get` with no filter omits both. `EVENT_GET_PROPERTIES`
32
+ * already names them, so the client is unaffected, but a caller who asks for
33
+ * "everything" gets less than a caller who asks for a list.
34
+ *
35
+ * **Still open: `sequence`.** The server accepts the name -- asking for it is
36
+ * not an `invalidProperties` error -- but no response in the run ever carried
37
+ * a value, not even `0`, including after an update. `eventFromWire` defaults
38
+ * it to `0`, which is the safe reading either way.
39
+ *
40
+ * **Returned by Stalwart and deliberately unmapped**, because no public type
41
+ * needs them yet: `organizerCalendarAddress`, `recurrenceIdTimeZone`,
42
+ * `updated`, `isDraft`, `isOrigin`.
43
+ */
44
+ import type { AvailabilityPeriod, Calendar, CalendarEvent, CalendarEventDraft, CalendarRight, Principal } from './types.ts';
45
+ type WireRights = Partial<Record<CalendarRight, boolean>>;
46
+ export declare function rightsFromWire(wire: WireRights | null | undefined): readonly CalendarRight[];
47
+ export declare function rightsToWire(rights: readonly CalendarRight[]): WireRights;
48
+ type WireShareWith = Record<string, WireRights> | null | undefined;
49
+ export type WireCalendar = {
50
+ id: string;
51
+ name: string;
52
+ description?: string | null;
53
+ color?: string | null;
54
+ isVisible?: boolean;
55
+ myRights?: WireRights | null;
56
+ shareWith?: WireShareWith;
57
+ includeInAvailability?: string | null;
58
+ };
59
+ export declare function calendarFromWire(wire: WireCalendar): Calendar;
60
+ export declare const CALENDAR_GET_PROPERTIES: readonly ["id", "name", "description", "color", "isVisible", "myRights", "shareWith", "includeInAvailability"];
61
+ /** `Principal/get`'s own object shape -- live-confirmed against Stalwart
62
+ * v0.16.20 (MSG-055 slice 3 plan): `{id, type, name, description, email}`. */
63
+ export type WirePrincipal = {
64
+ id: string;
65
+ type?: string | null;
66
+ name?: string | null;
67
+ description?: string | null;
68
+ email?: string | null;
69
+ };
70
+ /** `description` carries the friendly display name ("Bob"); the wire's own
71
+ * `name` field carries the address again, so `description` is preferred and
72
+ * `name` is only the fallback. */
73
+ export declare function principalFromWire(wire: WirePrincipal): Principal;
74
+ type WireParticipant = {
75
+ '@type'?: string;
76
+ calendarAddress: string;
77
+ name?: string | null;
78
+ roles?: Partial<Record<string, boolean>> | null;
79
+ participationStatus?: string | null;
80
+ };
81
+ type WireLocation = {
82
+ '@type'?: string;
83
+ name?: string | null;
84
+ };
85
+ type WireRecurrenceRule = {
86
+ '@type'?: string;
87
+ frequency: string;
88
+ interval?: number | null;
89
+ count?: number | null;
90
+ until?: string | null;
91
+ };
92
+ /** The event properties this package asks the server for. Naming them
93
+ * explicitly, rather than omitting `properties` for "everything", keeps a
94
+ * 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"];
97
+ export type WireEvent = {
98
+ id: string;
99
+ calendarIds?: Record<string, boolean> | null;
100
+ uid: string;
101
+ title: string;
102
+ description?: string | null;
103
+ start: string;
104
+ timeZone?: string | null;
105
+ duration: string;
106
+ showWithoutTime?: boolean | null;
107
+ locations?: Record<string, WireLocation> | null;
108
+ recurrenceRule?: WireRecurrenceRule | null;
109
+ participants?: Record<string, WireParticipant> | null;
110
+ status?: string | null;
111
+ sequence?: number | null;
112
+ /** The master event this expansion came from -- confirmed live (#145
113
+ * check 2). */
114
+ baseEventId?: string | null;
115
+ recurrenceId?: string | null;
116
+ /**
117
+ * Per-occurrence changes, keyed by an occurrence's `recurrenceId`.
118
+ *
119
+ * A client never writes this map directly. Sending a patch to a synthetic
120
+ * occurrence id is what writes it, and destroying a synthetic occurrence id
121
+ * is what puts `{excluded: true}` in it -- both confirmed live against
122
+ * Stalwart v0.16.20 for MSG-055. It is typed here because the fake has to
123
+ * model the same storage to be worth testing against.
124
+ */
125
+ recurrenceOverrides?: Record<string, Record<string, unknown>> | null;
126
+ };
127
+ /** `calendarId` is a fallback for a freshly created event whose response
128
+ * echoes only server-assigned properties; the caller already knows which
129
+ * calendar it asked for. */
130
+ export declare function eventFromWire(wire: WireEvent, calendarIdFallback?: string): CalendarEvent;
131
+ /** The properties a create sends: everything `CalendarEventDraft` carries,
132
+ * translated to their wire names. */
133
+ export declare function draftToWire(calendarId: string, draft: CalendarEventDraft): Record<string, unknown>;
134
+ /** Only the properties `patch` actually carries -- `CalendarEvent/set`'s
135
+ * `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>;
138
+ /**
139
+ * A minimal ISO 8601 / RFC 5545 duration parser: `P`, an optional week or
140
+ * day count, an optional `T` time part with hours/minutes/seconds. Years and
141
+ * months are deliberately not handled -- a busy period is never months
142
+ * long, and a calendar-aware year/month addition needs a timezone this
143
+ * function does not have. Returns `null` rather than throwing: one
144
+ * unparseable duration should not take down a whole availability read.
145
+ *
146
+ * Exported for `./react`'s own use turning an event's `duration` into a grid
147
+ * end time (`Calendar.tsx`) -- the same parser, not a second one that could
148
+ * drift from this one's idea of what a duration string means.
149
+ */
150
+ export declare function parseDurationMs(duration: string): number | null;
151
+ export type WireBusyPeriod = {
152
+ utcStart: string;
153
+ utcEnd: string;
154
+ busyStatus?: string | null;
155
+ event?: unknown;
156
+ };
157
+ /**
158
+ * `Principal/getAvailability` returns a busy period as `utcStart`/`utcEnd`,
159
+ * both always present, both already UTC -- confirmed live against Stalwart
160
+ * v0.16.20 for MSG-055:
161
+ *
162
+ * ```json
163
+ * {"utcStart":"2026-10-05T13:00:00Z","utcEnd":"2026-10-05T14:00:00Z",
164
+ * "busyStatus":"confirmed","event":null}
165
+ * ```
166
+ *
167
+ * This is neither of the two shapes the earlier guess handled: there is no
168
+ * `start`, no `end` and no `duration` on the wire at all. Reading the old
169
+ * names produced an undefined start and an end derived from it, so every
170
+ * real busy period arrived as garbage.
171
+ *
172
+ * `event` rides along and was `null` for every period in the transcript.
173
+ * Nothing reads it yet; it is typed so a later reader does not have to widen
174
+ * the type to find out it exists.
175
+ */
176
+ export declare function availabilityFromWire(list: readonly WireBusyPeriod[]): readonly AvailabilityPeriod[];
177
+ export {};