@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.
- package/LICENSE +21 -0
- package/README.md +15 -0
- package/dist/calendar/calendar-client.d.ts +7 -0
- package/dist/calendar/calendar-client.js +242 -0
- package/dist/calendar/calendar.css +953 -0
- package/dist/calendar/client.d.ts +87 -0
- package/dist/calendar/client.js +233 -0
- package/dist/calendar/errors.d.ts +28 -0
- package/dist/calendar/errors.js +61 -0
- package/dist/calendar/fake/index.d.ts +36 -0
- package/dist/calendar/fake/index.js +79 -0
- package/dist/calendar/fake/sample.d.ts +66 -0
- package/dist/calendar/fake/sample.js +116 -0
- package/dist/calendar/fake/store.d.ts +79 -0
- package/dist/calendar/fake/store.js +906 -0
- package/dist/calendar/index.d.ts +12 -0
- package/dist/calendar/index.js +11 -0
- package/dist/calendar/push.d.ts +38 -0
- package/dist/calendar/push.js +129 -0
- package/dist/calendar/react/AvailabilityRibbon.d.ts +40 -0
- package/dist/calendar/react/AvailabilityRibbon.js +108 -0
- package/dist/calendar/react/Calendar.d.ts +28 -0
- package/dist/calendar/react/Calendar.js +431 -0
- package/dist/calendar/react/EventDetail.d.ts +22 -0
- package/dist/calendar/react/EventDetail.js +91 -0
- package/dist/calendar/react/EventEditor.d.ts +52 -0
- package/dist/calendar/react/EventEditor.js +188 -0
- package/dist/calendar/react/ShareDialog.d.ts +25 -0
- package/dist/calendar/react/ShareDialog.js +125 -0
- package/dist/calendar/react/Toolbar.d.ts +29 -0
- package/dist/calendar/react/Toolbar.js +58 -0
- package/dist/calendar/react/index.d.ts +9 -0
- package/dist/calendar/react/index.js +8 -0
- package/dist/calendar/react/participants.d.ts +34 -0
- package/dist/calendar/react/participants.js +40 -0
- package/dist/calendar/types.d.ts +384 -0
- package/dist/calendar/types.js +40 -0
- package/dist/calendar/uri.d.ts +13 -0
- package/dist/calendar/uri.js +22 -0
- package/dist/calendar/wire.d.ts +177 -0
- package/dist/calendar/wire.js +349 -0
- 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
|
+
}
|