@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
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 William Tallis Falch
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,15 @@
1
+ # calendar
2
+
3
+ `@wtfalch/calendar` is a JMAP calendar client for Agora, the wtfalch communications app.
4
+ It reads and writes a person's own events, invites, sharing between colleagues and free/busy straight from Stalwart, with no server code of its own.
5
+ It exports `./calendar` (`createCalendarClient`), `./calendar/react` (the `Calendar` component), `./calendar/fake` (`fakeCalendar()`) and `./calendar/calendar.css`, mirroring `@wtfalch/email` and `@wtfalch/messaging`.
6
+ See the [calendar plan](https://github.com/wtfalch/messaging/blob/main/.plans/2026-09-17-calendar.md) for the design and [wtfalch/messaging#156](https://github.com/wtfalch/messaging/issues/156) for this package's own ticket.
7
+
8
+ ## Development
9
+
10
+ ```bash
11
+ pnpm install
12
+ pnpm check
13
+ ```
14
+
15
+ `pnpm check` is the whole gate: build, lint, typecheck, tests and the tarball contract. [CLAUDE.md](CLAUDE.md) explains the rules it enforces.
@@ -0,0 +1,7 @@
1
+ /**
2
+ * `createCalendarClient`: the `CalendarClient` implementation, wiring the
3
+ * transport (`client.ts`), the wire mapping (`wire.ts`) and push
4
+ * (`push.ts`) together against the fixed contract in `types.ts`.
5
+ */
6
+ import type { CalendarClient, CalendarClientOptions } from './types.ts';
7
+ export declare function createCalendarClient(options: CalendarClientOptions): CalendarClient;
@@ -0,0 +1,242 @@
1
+ /**
2
+ * `createCalendarClient`: the `CalendarClient` implementation, wiring the
3
+ * transport (`client.ts`), the wire mapping (`wire.ts`) and push
4
+ * (`push.ts`) together against the fixed contract in `types.ts`.
5
+ */
6
+ import { CalendarConnection } from "./client.js";
7
+ import { guard } from "./errors.js";
8
+ import { push } from "./push.js";
9
+ import { CalendarError } from "./types.js";
10
+ import { CALENDAR_GET_PROPERTIES, EVENT_GET_PROPERTIES, availabilityFromWire, calendarFromWire, draftToWire, eventFromWire, patchToWire, principalFromWire, rightsToWire, } from "./wire.js";
11
+ /** The first refusal in a `notCreated`/`notUpdated`/`notDestroyed` map, or
12
+ * `undefined` when the operation actually succeeded. */
13
+ function firstRefusal(errors) {
14
+ return errors ? Object.values(errors)[0] : undefined;
15
+ }
16
+ async function listCalendars(connection) {
17
+ return guard('calendars.list', async () => {
18
+ const accountId = await connection.accountId();
19
+ const result = await connection.request('Calendar/get', { accountId, ids: null, properties: CALENDAR_GET_PROPERTIES });
20
+ return result.list.map(calendarFromWire);
21
+ });
22
+ }
23
+ /**
24
+ * Always sends `expandRecurrences: true` with the caller's bounds -- without
25
+ * it, `CalendarEvent/query` returns master events only, and a month view
26
+ * silently drops recurring occurrences (`CalendarRange`'s own doc comment;
27
+ * MSG-053 acceptance criteria; #137 "Recurrence", confirmed live by #145
28
+ * check 2). `CalendarRange` requires both `after` and `before` at the type
29
+ * level, but a caller who bypasses that (an untyped consumer, or a value
30
+ * assembled from optional URL params) must not reach the server with either
31
+ * one missing -- refused here, before any request goes out, rather than
32
+ * relying on the server's own `invalidArguments` for a mistake this package
33
+ * can catch for free.
34
+ */
35
+ async function listEvents(connection, range) {
36
+ return guard('events.list', async () => {
37
+ if (!range.after || !range.before) {
38
+ throw new CalendarError('listEvents requires both range.after and range.before', {
39
+ type: 'invalidArguments',
40
+ operation: 'events.list',
41
+ });
42
+ }
43
+ const accountId = await connection.accountId();
44
+ const query = await connection.request('CalendarEvent/query', {
45
+ accountId,
46
+ filter: { after: range.after, before: range.before },
47
+ expandRecurrences: true,
48
+ });
49
+ if (query.ids.length === 0)
50
+ return [];
51
+ const result = await connection.request('CalendarEvent/get', { accountId, ids: query.ids, properties: EVENT_GET_PROPERTIES });
52
+ return result.list.map((wire) => eventFromWire(wire));
53
+ });
54
+ }
55
+ async function getEvent(connection, id) {
56
+ return guard('events.get', async () => {
57
+ const accountId = await connection.accountId();
58
+ const result = await connection.request('CalendarEvent/get', { accountId, ids: [id], properties: EVENT_GET_PROPERTIES });
59
+ const wire = result.list[0];
60
+ if (!wire) {
61
+ throw new CalendarError(`no event ${id} on this account`, {
62
+ type: 'notFound',
63
+ operation: 'events.get',
64
+ });
65
+ }
66
+ return eventFromWire(wire);
67
+ });
68
+ }
69
+ async function createEvent(connection, calendarId, event, options) {
70
+ return guard('events.create', async () => {
71
+ const accountId = await connection.accountId();
72
+ const result = await connection.request('CalendarEvent/set', {
73
+ accountId,
74
+ create: { new: draftToWire(calendarId, event) },
75
+ sendSchedulingMessages: options?.sendSchedulingMessages ?? false,
76
+ });
77
+ const refused = firstRefusal(result.notCreated);
78
+ if (refused) {
79
+ throw new CalendarError(refused.description ?? 'the server refused to create the event', {
80
+ type: refused.type ?? 'unknown',
81
+ operation: 'events.create',
82
+ });
83
+ }
84
+ const created = result.created?.new;
85
+ if (!created) {
86
+ throw new CalendarError('the server reported neither a created event nor a refusal', {
87
+ operation: 'events.create',
88
+ });
89
+ }
90
+ // `created` echoes only server-assigned properties on some JMAP set
91
+ // implementations (mirroring `Email/set`'s own convention) -- refetch
92
+ // for the canonical object rather than guessing which fields came back.
93
+ return getEvent(connection, created.id);
94
+ });
95
+ }
96
+ async function updateEvent(connection, id, patch, options) {
97
+ return guard('events.update', async () => {
98
+ const accountId = await connection.accountId();
99
+ const result = await connection.request('CalendarEvent/set', {
100
+ accountId,
101
+ update: { [id]: patchToWire(patch) },
102
+ sendSchedulingMessages: options?.sendSchedulingMessages ?? false,
103
+ });
104
+ const refused = firstRefusal(result.notUpdated);
105
+ if (refused) {
106
+ throw new CalendarError(refused.description ?? 'the server refused to update the event', {
107
+ type: refused.type ?? 'unknown',
108
+ operation: 'events.update',
109
+ });
110
+ }
111
+ return getEvent(connection, id);
112
+ });
113
+ }
114
+ async function deleteEvent(connection, id, options) {
115
+ return guard('events.delete', async () => {
116
+ const accountId = await connection.accountId();
117
+ const result = await connection.request('CalendarEvent/set', {
118
+ accountId,
119
+ destroy: [id],
120
+ sendSchedulingMessages: options?.sendSchedulingMessages ?? false,
121
+ });
122
+ const refused = firstRefusal(result.notDestroyed);
123
+ if (refused) {
124
+ throw new CalendarError(refused.description ?? 'the server refused to delete the event', {
125
+ type: refused.type ?? 'unknown',
126
+ operation: 'events.delete',
127
+ });
128
+ }
129
+ });
130
+ }
131
+ /**
132
+ * Add or replace one grant in a calendar's `shareWith` ACL, via a JSON
133
+ * Pointer patch on that one grantee rather than replacing the whole map --
134
+ * so sharing with a second person never drops the first (plan §5's ACL
135
+ * *patch* pattern; #138 §1).
136
+ */
137
+ async function shareCalendar(connection, calendarId, grant) {
138
+ return guard('calendars.share', async () => {
139
+ const accountId = await connection.accountId();
140
+ const pointer = `shareWith/${grant.accountId.replaceAll('~', '~0').replaceAll('/', '~1')}`;
141
+ const result = await connection.request('Calendar/set', { accountId, update: { [calendarId]: { [pointer]: rightsToWire(grant.rights) } } });
142
+ const refused = firstRefusal(result.notUpdated);
143
+ if (refused) {
144
+ throw new CalendarError(refused.description ?? 'the server refused the share', {
145
+ type: refused.type ?? 'unknown',
146
+ operation: 'calendars.share',
147
+ });
148
+ }
149
+ });
150
+ }
151
+ /**
152
+ * Turn a calendar address into the account id `shareWith` demands as its key
153
+ * -- live-confirmed against Stalwart v0.16.20 as an ordinary user, no admin
154
+ * rights needed: `Principal/query` filtered by `email` returns at most one
155
+ * id, so this is one lookup, not a scan, followed by one `Principal/get` for
156
+ * the display fields (MSG-055 slice 3 plan). `undefined` for an address
157
+ * nobody has -- an unknown address is an ordinary outcome, not an error.
158
+ */
159
+ async function resolvePrincipal(connection, email) {
160
+ return guard('principals.resolve', async () => {
161
+ const accountId = await connection.accountId();
162
+ const query = await connection.request('Principal/query', { accountId, filter: { email } });
163
+ const id = query.ids[0];
164
+ if (!id)
165
+ return undefined;
166
+ const result = await connection.request('Principal/get', { accountId, ids: [id] });
167
+ const wire = result.list[0];
168
+ return wire ? principalFromWire(wire) : undefined;
169
+ });
170
+ }
171
+ /**
172
+ * The principals behind a set of account ids -- one `Principal/get`, so a
173
+ * share list with six grants costs one call rather than six. An id the server
174
+ * does not know comes back in its `notFound` and is simply absent here.
175
+ */
176
+ async function lookupPrincipals(connection, ids) {
177
+ if (ids.length === 0)
178
+ return [];
179
+ return guard('principals.lookup', async () => {
180
+ const accountId = await connection.accountId();
181
+ const result = await connection.request('Principal/get', { accountId, ids: [...ids] });
182
+ return result.list.map(principalFromWire);
183
+ });
184
+ }
185
+ /**
186
+ * Revoke one grantee's whole grant, via a JSON-Pointer patch to `null` --
187
+ * live-confirmed to remove the `shareWith` key entirely, which
188
+ * `rightsToWire([])` cannot do: that writes `{}` for the grantee, an empty
189
+ * rights object, not a removed one (MSG-055 slice 3 plan). Mirrors
190
+ * `shareCalendar`'s own pointer escaping and refusal handling.
191
+ */
192
+ async function unshareCalendar(connection, calendarId, grantAccountId) {
193
+ return guard('calendars.unshare', async () => {
194
+ const callerAccountId = await connection.accountId();
195
+ const pointer = `shareWith/${grantAccountId.replaceAll('~', '~0').replaceAll('/', '~1')}`;
196
+ const result = await connection.request('Calendar/set', { accountId: callerAccountId, update: { [calendarId]: { [pointer]: null } } });
197
+ const refused = firstRefusal(result.notUpdated);
198
+ if (refused) {
199
+ throw new CalendarError(refused.description ?? 'the server refused to revoke the share', {
200
+ type: refused.type ?? 'unknown',
201
+ operation: 'calendars.unshare',
202
+ });
203
+ }
204
+ });
205
+ }
206
+ /**
207
+ * `principalId`'s busy periods over `range`, gated by the ACL share alone --
208
+ * live-confirmed to need only `mayReadItems`, not also `mayReadFreeBusy`,
209
+ * and to need no `includeInAvailability` opt-in (#145 check 5, amending
210
+ * #137). `principalId` is the JMAP `accountId` argument here: the method
211
+ * reads a *different* account's calendars, authorized by the caller's own
212
+ * token and that account's `shareWith` grants, the same secondary-account
213
+ * pattern JMAP mail already uses for a shared mailbox.
214
+ */
215
+ async function getAvailability(connection, principalId, range) {
216
+ return guard('availability.get', async () => {
217
+ const result = await connection.request('Principal/getAvailability', {
218
+ accountId: principalId,
219
+ after: range.after,
220
+ before: range.before,
221
+ });
222
+ return availabilityFromWire(result.list ?? []);
223
+ });
224
+ }
225
+ export function createCalendarClient(options) {
226
+ const connection = new CalendarConnection(options);
227
+ return {
228
+ identity: () => guard('client.identity', () => connection.identity()),
229
+ listCalendars: () => listCalendars(connection),
230
+ listEvents: (range) => listEvents(connection, range),
231
+ getEvent: (id) => getEvent(connection, id),
232
+ createEvent: (calendarId, event, options) => createEvent(connection, calendarId, event, options),
233
+ updateEvent: (id, patch, options) => updateEvent(connection, id, patch, options),
234
+ deleteEvent: (id, options) => deleteEvent(connection, id, options),
235
+ shareCalendar: (calendarId, grant) => shareCalendar(connection, calendarId, grant),
236
+ resolvePrincipal: (email) => resolvePrincipal(connection, email),
237
+ lookupPrincipals: (accountIds) => lookupPrincipals(connection, accountIds),
238
+ unshareCalendar: (calendarId, accountId) => unshareCalendar(connection, calendarId, accountId),
239
+ getAvailability: (principalId, range) => getAvailability(connection, principalId, range),
240
+ subscribe: (handler) => push(connection, handler),
241
+ };
242
+ }