@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
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Session negotiation and the low-level JMAP request, copied from
|
|
3
|
+
* `@wtfalch/email/mailbox/client.ts` with the capability constant swapped to
|
|
4
|
+
* `urn:ietf:params:jmap:calendars` (plan §7; MSG-053 acceptance criteria) --
|
|
5
|
+
* not imported, so this package carries no runtime dependency on
|
|
6
|
+
* `@wtfalch/email`.
|
|
7
|
+
*
|
|
8
|
+
* **`jmap-jam` versus plain `fetch`, decided for this package: plain
|
|
9
|
+
* `fetch`.** `@wtfalch/email` depends on `jmap-jam` for its typed
|
|
10
|
+
* `jam.api.Mailbox.get`/`Email.set`-style calls, but `jmap-jam`'s method
|
|
11
|
+
* table (`Requests`/`Responses`/`ProxyAPI` in its `dist/index.d.ts`) is
|
|
12
|
+
* hard-coded to RFC 8621 Mail entities -- `Mailbox`, `Email`, `Thread`,
|
|
13
|
+
* `Identity`, `EmailSubmission`, `VacationResponse`, `PushSubscription`,
|
|
14
|
+
* `Blob`, `Core/echo` -- and has no generic escape hatch for a method it
|
|
15
|
+
* does not already know about. `Calendar`, `CalendarEvent` and
|
|
16
|
+
* `Principal/getAvailability` are not in that table, so calling them through
|
|
17
|
+
* `jmap-jam` would mean casting every call through `as never`/`as any`,
|
|
18
|
+
* which defeats the point of a typed client. Plain `fetch` sends the same
|
|
19
|
+
* JSON envelope RFC 8620 §3.3 defines either way, and it is what
|
|
20
|
+
* `client.ts`'s own session fetch and `push.ts`'s SSE loop already use for
|
|
21
|
+
* the same reason (a browser `EventSource` cannot carry an `Authorization`
|
|
22
|
+
* header). It also happens to be what `./calendar/fake` needs: intercepting
|
|
23
|
+
* `fetch` is the only way a fake transport can answer real JMAP without a
|
|
24
|
+
* second, `jmap-jam`-shaped fake underneath it.
|
|
25
|
+
*/
|
|
26
|
+
export declare const CALENDAR_CAPABILITY = "urn:ietf:params:jmap:calendars";
|
|
27
|
+
export declare const CORE_CAPABILITY = "urn:ietf:params:jmap:core";
|
|
28
|
+
export type CalendarConnectionOptions = {
|
|
29
|
+
sessionUrl: string;
|
|
30
|
+
getAccessToken: () => string | Promise<string>;
|
|
31
|
+
accountId?: string;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* A connection to one JMAP calendars account.
|
|
35
|
+
*
|
|
36
|
+
* **The access token is never cached.** `getAccessToken()` is called again
|
|
37
|
+
* on every session negotiation, every method call and every push reconnect,
|
|
38
|
+
* so a mid-session token refresh needs no `setToken`-style call from host
|
|
39
|
+
* code (`CalendarClientOptions.getAccessToken`'s own doc comment; plan §7;
|
|
40
|
+
* #143 §2) -- unlike `MailClient`, which caches a bearer token until told
|
|
41
|
+
* otherwise. What *is* cached is the negotiated session document and account
|
|
42
|
+
* id, which do not change with the token; a 401 on a live request still
|
|
43
|
+
* drops that cache, in case the account itself needs renegotiating.
|
|
44
|
+
*/
|
|
45
|
+
export declare class CalendarConnection {
|
|
46
|
+
#private;
|
|
47
|
+
constructor(options: CalendarConnectionOptions);
|
|
48
|
+
/** The account id this connection reads and writes. */
|
|
49
|
+
accountId(): Promise<string>;
|
|
50
|
+
/**
|
|
51
|
+
* Who this connection is, as the session document already says.
|
|
52
|
+
*
|
|
53
|
+
* No `Principal/get` call: the session names the account it just handed
|
|
54
|
+
* over, and a live run against Stalwart v0.16.20 shows the address sitting
|
|
55
|
+
* in `accounts.<id>.name` ("alice@example.org", `isPersonal: true`) on the
|
|
56
|
+
* same document `#negotiate` already caches for `accountId()`. Asking the
|
|
57
|
+
* server a second question it has already answered would be a round trip
|
|
58
|
+
* bought with nothing.
|
|
59
|
+
*
|
|
60
|
+
* The invite UI needs this to tell the viewer's own participant row from
|
|
61
|
+
* everyone else's, which is what makes an RSVP answerable at all.
|
|
62
|
+
*/
|
|
63
|
+
identity(): Promise<{
|
|
64
|
+
accountId: string;
|
|
65
|
+
calendarAddress: string;
|
|
66
|
+
}>;
|
|
67
|
+
/**
|
|
68
|
+
* One JMAP method call, as a single-call request. Fetches a fresh access
|
|
69
|
+
* token every time (see the class doc comment).
|
|
70
|
+
*/
|
|
71
|
+
request<A extends object, R>(method: string, args: A): Promise<R>;
|
|
72
|
+
/** The event source URL for `subscribe`, with its template expanded. */
|
|
73
|
+
eventSourceUrl(options: {
|
|
74
|
+
types: string;
|
|
75
|
+
ping: number;
|
|
76
|
+
closeAfter?: 'state' | 'no';
|
|
77
|
+
}): Promise<string>;
|
|
78
|
+
/**
|
|
79
|
+
* A fresh `Authorization` header value. The browser `EventSource` object
|
|
80
|
+
* cannot set headers at all, so `push.ts` reads the stream with `fetch`
|
|
81
|
+
* instead and needs this for every (re)connection attempt -- mirroring
|
|
82
|
+
* `@wtfalch/email/mailbox/push.ts`'s use of `client.authorization`, made
|
|
83
|
+
* async here so every reconnect asks for the current token rather than one
|
|
84
|
+
* cached at construction time.
|
|
85
|
+
*/
|
|
86
|
+
authorization(): Promise<string>;
|
|
87
|
+
}
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Session negotiation and the low-level JMAP request, copied from
|
|
3
|
+
* `@wtfalch/email/mailbox/client.ts` with the capability constant swapped to
|
|
4
|
+
* `urn:ietf:params:jmap:calendars` (plan §7; MSG-053 acceptance criteria) --
|
|
5
|
+
* not imported, so this package carries no runtime dependency on
|
|
6
|
+
* `@wtfalch/email`.
|
|
7
|
+
*
|
|
8
|
+
* **`jmap-jam` versus plain `fetch`, decided for this package: plain
|
|
9
|
+
* `fetch`.** `@wtfalch/email` depends on `jmap-jam` for its typed
|
|
10
|
+
* `jam.api.Mailbox.get`/`Email.set`-style calls, but `jmap-jam`'s method
|
|
11
|
+
* table (`Requests`/`Responses`/`ProxyAPI` in its `dist/index.d.ts`) is
|
|
12
|
+
* hard-coded to RFC 8621 Mail entities -- `Mailbox`, `Email`, `Thread`,
|
|
13
|
+
* `Identity`, `EmailSubmission`, `VacationResponse`, `PushSubscription`,
|
|
14
|
+
* `Blob`, `Core/echo` -- and has no generic escape hatch for a method it
|
|
15
|
+
* does not already know about. `Calendar`, `CalendarEvent` and
|
|
16
|
+
* `Principal/getAvailability` are not in that table, so calling them through
|
|
17
|
+
* `jmap-jam` would mean casting every call through `as never`/`as any`,
|
|
18
|
+
* which defeats the point of a typed client. Plain `fetch` sends the same
|
|
19
|
+
* JSON envelope RFC 8620 §3.3 defines either way, and it is what
|
|
20
|
+
* `client.ts`'s own session fetch and `push.ts`'s SSE loop already use for
|
|
21
|
+
* the same reason (a browser `EventSource` cannot carry an `Authorization`
|
|
22
|
+
* header). It also happens to be what `./calendar/fake` needs: intercepting
|
|
23
|
+
* `fetch` is the only way a fake transport can answer real JMAP without a
|
|
24
|
+
* second, `jmap-jam`-shaped fake underneath it.
|
|
25
|
+
*/
|
|
26
|
+
import { toCalendarError } from "./errors.js";
|
|
27
|
+
import { CalendarError } from "./types.js";
|
|
28
|
+
import { expandTemplate } from "./uri.js";
|
|
29
|
+
export const CALENDAR_CAPABILITY = 'urn:ietf:params:jmap:calendars';
|
|
30
|
+
export const CORE_CAPABILITY = 'urn:ietf:params:jmap:core';
|
|
31
|
+
/** See `@wtfalch/email/mailbox/client.ts`'s identical constant: declining
|
|
32
|
+
* ambient browser credentials keeps a refused token from popping the
|
|
33
|
+
* browser's native Basic-auth prompt over the application's own error. */
|
|
34
|
+
const NO_BROWSER_CREDENTIALS = { credentials: 'omit' };
|
|
35
|
+
function looksLikeSession(value) {
|
|
36
|
+
return (typeof value === 'object' &&
|
|
37
|
+
value !== null &&
|
|
38
|
+
typeof value.apiUrl === 'string' &&
|
|
39
|
+
typeof value.eventSourceUrl === 'string' &&
|
|
40
|
+
typeof value.accounts === 'object');
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* A connection to one JMAP calendars account.
|
|
44
|
+
*
|
|
45
|
+
* **The access token is never cached.** `getAccessToken()` is called again
|
|
46
|
+
* on every session negotiation, every method call and every push reconnect,
|
|
47
|
+
* so a mid-session token refresh needs no `setToken`-style call from host
|
|
48
|
+
* code (`CalendarClientOptions.getAccessToken`'s own doc comment; plan §7;
|
|
49
|
+
* #143 §2) -- unlike `MailClient`, which caches a bearer token until told
|
|
50
|
+
* otherwise. What *is* cached is the negotiated session document and account
|
|
51
|
+
* id, which do not change with the token; a 401 on a live request still
|
|
52
|
+
* drops that cache, in case the account itself needs renegotiating.
|
|
53
|
+
*/
|
|
54
|
+
export class CalendarConnection {
|
|
55
|
+
#sessionUrl;
|
|
56
|
+
#getAccessToken;
|
|
57
|
+
#wantedAccountId;
|
|
58
|
+
#negotiation;
|
|
59
|
+
constructor(options) {
|
|
60
|
+
this.#sessionUrl = options.sessionUrl;
|
|
61
|
+
this.#getAccessToken = options.getAccessToken;
|
|
62
|
+
this.#wantedAccountId = options.accountId;
|
|
63
|
+
}
|
|
64
|
+
async #negotiate() {
|
|
65
|
+
this.#negotiation ??= this.#open();
|
|
66
|
+
try {
|
|
67
|
+
return await this.#negotiation;
|
|
68
|
+
}
|
|
69
|
+
catch (error) {
|
|
70
|
+
// A failed negotiation must not be cached, or a token refresh could
|
|
71
|
+
// never recover: the next call would replay the same rejection.
|
|
72
|
+
this.#negotiation = undefined;
|
|
73
|
+
throw error;
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
async #open() {
|
|
77
|
+
const token = await this.#getAccessToken();
|
|
78
|
+
const doc = await this.#fetchSession(token);
|
|
79
|
+
const accountId = this.#wantedAccountId ?? doc.primaryAccounts?.[CALENDAR_CAPABILITY];
|
|
80
|
+
if (!accountId) {
|
|
81
|
+
throw new CalendarError(`the session document names no primary account for ${CALENDAR_CAPABILITY}; the server may not offer JMAP Calendars to this login`, { operation: 'client.connect' });
|
|
82
|
+
}
|
|
83
|
+
if (!doc.accounts[accountId]) {
|
|
84
|
+
throw new CalendarError(`the session document has no account ${accountId}`, {
|
|
85
|
+
operation: 'client.connect',
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
return { doc, accountId };
|
|
89
|
+
}
|
|
90
|
+
async #fetchSession(token) {
|
|
91
|
+
let response;
|
|
92
|
+
try {
|
|
93
|
+
response = await fetch(this.#sessionUrl, {
|
|
94
|
+
headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
|
|
95
|
+
cache: 'no-cache',
|
|
96
|
+
...NO_BROWSER_CREDENTIALS,
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
catch (cause) {
|
|
100
|
+
throw new CalendarError(`could not reach ${this.#sessionUrl}`, {
|
|
101
|
+
operation: 'client.connect',
|
|
102
|
+
cause,
|
|
103
|
+
});
|
|
104
|
+
}
|
|
105
|
+
if (response.status === 401 || response.status === 403) {
|
|
106
|
+
throw new CalendarError(`the server rejected the credential for ${this.#sessionUrl} (${response.status})`, { status: response.status, operation: 'client.connect' });
|
|
107
|
+
}
|
|
108
|
+
const body = await response.text();
|
|
109
|
+
let parsed;
|
|
110
|
+
try {
|
|
111
|
+
parsed = JSON.parse(body);
|
|
112
|
+
}
|
|
113
|
+
catch {
|
|
114
|
+
parsed = undefined;
|
|
115
|
+
}
|
|
116
|
+
if (!looksLikeSession(parsed)) {
|
|
117
|
+
throw new CalendarError(`${this.#sessionUrl} did not answer with a JMAP session document (${response.status}): ${body.slice(0, 200)}`, { status: response.status, operation: 'client.connect' });
|
|
118
|
+
}
|
|
119
|
+
return parsed;
|
|
120
|
+
}
|
|
121
|
+
/** The account id this connection reads and writes. */
|
|
122
|
+
async accountId() {
|
|
123
|
+
return (await this.#negotiate()).accountId;
|
|
124
|
+
}
|
|
125
|
+
/**
|
|
126
|
+
* Who this connection is, as the session document already says.
|
|
127
|
+
*
|
|
128
|
+
* No `Principal/get` call: the session names the account it just handed
|
|
129
|
+
* over, and a live run against Stalwart v0.16.20 shows the address sitting
|
|
130
|
+
* in `accounts.<id>.name` ("alice@example.org", `isPersonal: true`) on the
|
|
131
|
+
* same document `#negotiate` already caches for `accountId()`. Asking the
|
|
132
|
+
* server a second question it has already answered would be a round trip
|
|
133
|
+
* bought with nothing.
|
|
134
|
+
*
|
|
135
|
+
* The invite UI needs this to tell the viewer's own participant row from
|
|
136
|
+
* everyone else's, which is what makes an RSVP answerable at all.
|
|
137
|
+
*/
|
|
138
|
+
async identity() {
|
|
139
|
+
const { doc, accountId } = await this.#negotiate();
|
|
140
|
+
return { accountId, calendarAddress: doc.accounts[accountId]?.name ?? '' };
|
|
141
|
+
}
|
|
142
|
+
/**
|
|
143
|
+
* Every capability the session advertises, so a request never has to
|
|
144
|
+
* guess which URN a given method needs. RFC 8620 §3.1 allows a client to
|
|
145
|
+
* declare a capability it ends up not using in a given call, so declaring
|
|
146
|
+
* everything the session lists is free -- and no live transcript states
|
|
147
|
+
* `Principal/getAvailability`'s own required capability string, only that
|
|
148
|
+
* the method exists (#137 "Methods implemented"). Decision, not sourced
|
|
149
|
+
* from a ticket: this sidesteps that gap entirely instead of guessing.
|
|
150
|
+
*/
|
|
151
|
+
async #using() {
|
|
152
|
+
const { doc } = await this.#negotiate();
|
|
153
|
+
const advertised = Object.keys(doc.capabilities ?? {});
|
|
154
|
+
return advertised.length > 0 ? advertised : [CORE_CAPABILITY, CALENDAR_CAPABILITY];
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* One JMAP method call, as a single-call request. Fetches a fresh access
|
|
158
|
+
* token every time (see the class doc comment).
|
|
159
|
+
*/
|
|
160
|
+
async request(method, args) {
|
|
161
|
+
const { doc } = await this.#negotiate();
|
|
162
|
+
const using = await this.#using();
|
|
163
|
+
const token = await this.#getAccessToken();
|
|
164
|
+
let response;
|
|
165
|
+
try {
|
|
166
|
+
response = await fetch(doc.apiUrl, {
|
|
167
|
+
method: 'POST',
|
|
168
|
+
headers: {
|
|
169
|
+
Authorization: `Bearer ${token}`,
|
|
170
|
+
'Content-Type': 'application/json',
|
|
171
|
+
Accept: 'application/json',
|
|
172
|
+
},
|
|
173
|
+
body: JSON.stringify({ using, methodCalls: [[method, args, '0']] }),
|
|
174
|
+
...NO_BROWSER_CREDENTIALS,
|
|
175
|
+
});
|
|
176
|
+
}
|
|
177
|
+
catch (cause) {
|
|
178
|
+
throw new CalendarError(`could not reach ${doc.apiUrl}`, { operation: method, cause });
|
|
179
|
+
}
|
|
180
|
+
if (response.status === 401 || response.status === 403) {
|
|
181
|
+
// Not just the token: the negotiated session itself may be stale.
|
|
182
|
+
// The next call renegotiates from scratch rather than replaying it.
|
|
183
|
+
this.#negotiation = undefined;
|
|
184
|
+
throw new CalendarError(`the server rejected the credential for ${method} (${response.status})`, { status: response.status, operation: method });
|
|
185
|
+
}
|
|
186
|
+
if (!response.ok) {
|
|
187
|
+
throw new CalendarError(`${method} failed with ${response.status}`, {
|
|
188
|
+
status: response.status,
|
|
189
|
+
operation: method,
|
|
190
|
+
});
|
|
191
|
+
}
|
|
192
|
+
let body;
|
|
193
|
+
try {
|
|
194
|
+
body = await response.json();
|
|
195
|
+
}
|
|
196
|
+
catch (cause) {
|
|
197
|
+
throw new CalendarError(`${method} did not answer with JSON`, {
|
|
198
|
+
status: response.status,
|
|
199
|
+
operation: method,
|
|
200
|
+
cause,
|
|
201
|
+
});
|
|
202
|
+
}
|
|
203
|
+
const first = body.methodResponses?.[0];
|
|
204
|
+
if (!first) {
|
|
205
|
+
throw new CalendarError(`${method} produced no method response`, { operation: method });
|
|
206
|
+
}
|
|
207
|
+
const [name, data] = first;
|
|
208
|
+
if (name === 'error') {
|
|
209
|
+
throw toCalendarError(data, method, response.status);
|
|
210
|
+
}
|
|
211
|
+
return data;
|
|
212
|
+
}
|
|
213
|
+
/** The event source URL for `subscribe`, with its template expanded. */
|
|
214
|
+
async eventSourceUrl(options) {
|
|
215
|
+
const { doc } = await this.#negotiate();
|
|
216
|
+
return expandTemplate(doc.eventSourceUrl, {
|
|
217
|
+
types: options.types,
|
|
218
|
+
ping: String(options.ping),
|
|
219
|
+
closeafter: options.closeAfter ?? 'no',
|
|
220
|
+
});
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* A fresh `Authorization` header value. The browser `EventSource` object
|
|
224
|
+
* cannot set headers at all, so `push.ts` reads the stream with `fetch`
|
|
225
|
+
* instead and needs this for every (re)connection attempt -- mirroring
|
|
226
|
+
* `@wtfalch/email/mailbox/push.ts`'s use of `client.authorization`, made
|
|
227
|
+
* async here so every reconnect asks for the current token rather than one
|
|
228
|
+
* cached at construction time.
|
|
229
|
+
*/
|
|
230
|
+
async authorization() {
|
|
231
|
+
return `Bearer ${await this.#getAccessToken()}`;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A JMAP server, and a `fetch` that never reaches one, throw all sorts of
|
|
3
|
+
* things: a `ProblemDetails` object (RFC 8620 §3.6.1), a method-level error
|
|
4
|
+
* response (`["error", {...}, id]`), a plain `Error`, or a string. Nothing a
|
|
5
|
+
* caller of this package should have to sniff apart -- everything this
|
|
6
|
+
* package throws is a `CalendarError` (the fixed contract, `types.ts`).
|
|
7
|
+
*
|
|
8
|
+
* Mirrors `@wtfalch/email/mailbox/errors.ts`'s `MailError`/`guard`, copied
|
|
9
|
+
* rather than imported for the same reason as the rest of the transport
|
|
10
|
+
* (MSG-053 acceptance criteria).
|
|
11
|
+
*/
|
|
12
|
+
import { CalendarError } from './types.ts';
|
|
13
|
+
/** The shape a JMAP server returns for a failed request or method call. */
|
|
14
|
+
export type ProblemDetails = {
|
|
15
|
+
type?: string;
|
|
16
|
+
status?: number;
|
|
17
|
+
title?: string;
|
|
18
|
+
detail?: string;
|
|
19
|
+
description?: string;
|
|
20
|
+
[key: string]: unknown;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Turn anything thrown or received into a `CalendarError`. A `CalendarError`
|
|
24
|
+
* passes through unchanged so a rethrow up a call stack does not re-wrap.
|
|
25
|
+
*/
|
|
26
|
+
export declare function toCalendarError(thrown: unknown, operation?: string, status?: number): CalendarError;
|
|
27
|
+
/** Run `fn`, and make sure anything it throws is a `CalendarError` naming `operation`. */
|
|
28
|
+
export declare function guard<T>(operation: string, fn: () => Promise<T>): Promise<T>;
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A JMAP server, and a `fetch` that never reaches one, throw all sorts of
|
|
3
|
+
* things: a `ProblemDetails` object (RFC 8620 §3.6.1), a method-level error
|
|
4
|
+
* response (`["error", {...}, id]`), a plain `Error`, or a string. Nothing a
|
|
5
|
+
* caller of this package should have to sniff apart -- everything this
|
|
6
|
+
* package throws is a `CalendarError` (the fixed contract, `types.ts`).
|
|
7
|
+
*
|
|
8
|
+
* Mirrors `@wtfalch/email/mailbox/errors.ts`'s `MailError`/`guard`, copied
|
|
9
|
+
* rather than imported for the same reason as the rest of the transport
|
|
10
|
+
* (MSG-053 acceptance criteria).
|
|
11
|
+
*/
|
|
12
|
+
import { CalendarError } from "./types.js";
|
|
13
|
+
function isProblem(value) {
|
|
14
|
+
return (typeof value === 'object' &&
|
|
15
|
+
value !== null &&
|
|
16
|
+
!Array.isArray(value) &&
|
|
17
|
+
!(value instanceof Error));
|
|
18
|
+
}
|
|
19
|
+
/** The most useful sentence a problem carries, in the order JMAP servers
|
|
20
|
+
* actually populate the fields. */
|
|
21
|
+
function describe(problem) {
|
|
22
|
+
const detail = problem.detail ?? problem.description ?? problem.title;
|
|
23
|
+
const type = typeof problem.type === 'string' ? problem.type : undefined;
|
|
24
|
+
if (typeof detail === 'string' && detail.length > 0) {
|
|
25
|
+
return type ? `${type}: ${detail}` : detail;
|
|
26
|
+
}
|
|
27
|
+
return type ?? 'the server reported an error with no description';
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Turn anything thrown or received into a `CalendarError`. A `CalendarError`
|
|
31
|
+
* passes through unchanged so a rethrow up a call stack does not re-wrap.
|
|
32
|
+
*/
|
|
33
|
+
export function toCalendarError(thrown, operation, status) {
|
|
34
|
+
if (thrown instanceof CalendarError)
|
|
35
|
+
return thrown;
|
|
36
|
+
if (isProblem(thrown)) {
|
|
37
|
+
return new CalendarError(describe(thrown), {
|
|
38
|
+
type: typeof thrown.type === 'string' ? thrown.type : undefined,
|
|
39
|
+
status: typeof thrown.status === 'number' ? thrown.status : status,
|
|
40
|
+
operation,
|
|
41
|
+
cause: thrown,
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
if (thrown instanceof Error) {
|
|
45
|
+
return new CalendarError(thrown.message, { operation, status, cause: thrown });
|
|
46
|
+
}
|
|
47
|
+
return new CalendarError(typeof thrown === 'string' ? thrown : 'the request failed', {
|
|
48
|
+
operation,
|
|
49
|
+
status,
|
|
50
|
+
cause: thrown,
|
|
51
|
+
});
|
|
52
|
+
}
|
|
53
|
+
/** Run `fn`, and make sure anything it throws is a `CalendarError` naming `operation`. */
|
|
54
|
+
export async function guard(operation, fn) {
|
|
55
|
+
try {
|
|
56
|
+
return await fn();
|
|
57
|
+
}
|
|
58
|
+
catch (thrown) {
|
|
59
|
+
throw toCalendarError(thrown, operation);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@wtfalch/calendar/calendar/fake` — a fake transport, not a fake API.
|
|
3
|
+
*
|
|
4
|
+
* `fakeCalendar()` answers real JMAP over an intercepted `fetch`, the same
|
|
5
|
+
* discipline as `@wtfalch/email/mailbox/fake`, so a story or test runs
|
|
6
|
+
* through this package's real code — including the `expandRecurrences`,
|
|
7
|
+
* `sendSchedulingMessages` and free/busy ACL gates — rather than a stub
|
|
8
|
+
* (plan §7; MSG-053 acceptance criteria).
|
|
9
|
+
*/
|
|
10
|
+
import type { CalendarClient } from '../types.ts';
|
|
11
|
+
import { BOB, CAROL, ME, OTHER_PRINCIPALS } from './sample.ts';
|
|
12
|
+
import type { SeedCalendar, SeedEvent, SeedPrincipal } from './sample.ts';
|
|
13
|
+
import { FakeCalendarStore, type FakeOptions } from './store.ts';
|
|
14
|
+
export type { CalendarClient, CalendarClientOptions } from '../types.ts';
|
|
15
|
+
export { FakeCalendarStore };
|
|
16
|
+
export type { FakeOptions, SeedCalendar, SeedEvent, SeedPrincipal };
|
|
17
|
+
export { BOB, CAROL, ME, OTHER_PRINCIPALS };
|
|
18
|
+
export type FakeCalendar = {
|
|
19
|
+
/** A real `CalendarClient`. Everything this package exports works against
|
|
20
|
+
* it unchanged, through the real wire code. */
|
|
21
|
+
client: CalendarClient;
|
|
22
|
+
/** The universe behind it, to seed more data, to drive the other side of
|
|
23
|
+
* a scheduling exchange, or to assert on what was sent. */
|
|
24
|
+
store: FakeCalendarStore;
|
|
25
|
+
/** Stop intercepting. Call it when a story or a test is done; leaving it
|
|
26
|
+
* installed leaves the fake answering for the rest of the process. */
|
|
27
|
+
dispose: () => void;
|
|
28
|
+
};
|
|
29
|
+
/**
|
|
30
|
+
* A client and the calendar universe it talks to.
|
|
31
|
+
*
|
|
32
|
+
* Seeded with `ME`'s two calendars (one of them recurring) unless told
|
|
33
|
+
* otherwise, plus `BOB` and `CAROL` for the sharing and free/busy demos —
|
|
34
|
+
* see `./sample.ts`.
|
|
35
|
+
*/
|
|
36
|
+
export declare function fakeCalendar(options?: FakeOptions): FakeCalendar;
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `@wtfalch/calendar/calendar/fake` — a fake transport, not a fake API.
|
|
3
|
+
*
|
|
4
|
+
* `fakeCalendar()` answers real JMAP over an intercepted `fetch`, the same
|
|
5
|
+
* discipline as `@wtfalch/email/mailbox/fake`, so a story or test runs
|
|
6
|
+
* through this package's real code — including the `expandRecurrences`,
|
|
7
|
+
* `sendSchedulingMessages` and free/busy ACL gates — rather than a stub
|
|
8
|
+
* (plan §7; MSG-053 acceptance criteria).
|
|
9
|
+
*/
|
|
10
|
+
import { createCalendarClient } from "../index.js";
|
|
11
|
+
import { BOB, CAROL, ME, OTHER_PRINCIPALS } from "./sample.js";
|
|
12
|
+
import { FakeCalendarStore } from "./store.js";
|
|
13
|
+
export { FakeCalendarStore };
|
|
14
|
+
export { BOB, CAROL, ME, OTHER_PRINCIPALS };
|
|
15
|
+
/** The origin the fake answers for. Anything else goes to the real `fetch`
|
|
16
|
+
* untouched, mirroring `@wtfalch/email/mailbox/fake`'s own delegation
|
|
17
|
+
* discipline. */
|
|
18
|
+
const ORIGIN = 'https://calendar.example.com';
|
|
19
|
+
/**
|
|
20
|
+
* The interception, copied from `@wtfalch/email/mailbox/fake` rather than
|
|
21
|
+
* shared with it: `jmap-jam`-style clients call the bare global `fetch` with
|
|
22
|
+
* no way to pass another one, so the global is replaced once, by a function
|
|
23
|
+
* that delegates anything not addressed to the fake's own origin to the real
|
|
24
|
+
* `fetch`. A count keeps several fakes — this one and `@wtfalch/email`'s, or
|
|
25
|
+
* two of this one in the same process — from uninstalling each other.
|
|
26
|
+
*/
|
|
27
|
+
let installed = null;
|
|
28
|
+
let live = 0;
|
|
29
|
+
function install(route) {
|
|
30
|
+
live += 1;
|
|
31
|
+
if (installed)
|
|
32
|
+
return;
|
|
33
|
+
const original = globalThis.fetch;
|
|
34
|
+
installed = original;
|
|
35
|
+
globalThis.fetch = ((input, init) => {
|
|
36
|
+
const answered = route(input, init);
|
|
37
|
+
return answered ?? original(input, init);
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
function uninstall() {
|
|
41
|
+
live -= 1;
|
|
42
|
+
if (live > 0 || !installed)
|
|
43
|
+
return;
|
|
44
|
+
globalThis.fetch = installed;
|
|
45
|
+
installed = null;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* A client and the calendar universe it talks to.
|
|
49
|
+
*
|
|
50
|
+
* Seeded with `ME`'s two calendars (one of them recurring) unless told
|
|
51
|
+
* otherwise, plus `BOB` and `CAROL` for the sharing and free/busy demos —
|
|
52
|
+
* see `./sample.ts`.
|
|
53
|
+
*/
|
|
54
|
+
export function fakeCalendar(options = {}) {
|
|
55
|
+
const store = new FakeCalendarStore(options);
|
|
56
|
+
install((input, init) => {
|
|
57
|
+
const url = String(typeof input === 'object' && input !== null && 'url' in input
|
|
58
|
+
? input.url
|
|
59
|
+
: input);
|
|
60
|
+
if (!url.startsWith(ORIGIN))
|
|
61
|
+
return null;
|
|
62
|
+
return store.fetch(url, init);
|
|
63
|
+
});
|
|
64
|
+
const client = createCalendarClient({
|
|
65
|
+
sessionUrl: `${ORIGIN}/.well-known/jmap`,
|
|
66
|
+
getAccessToken: () => 'fake',
|
|
67
|
+
});
|
|
68
|
+
let disposed = false;
|
|
69
|
+
return {
|
|
70
|
+
client,
|
|
71
|
+
store,
|
|
72
|
+
dispose: () => {
|
|
73
|
+
if (disposed)
|
|
74
|
+
return;
|
|
75
|
+
disposed = true;
|
|
76
|
+
uninstall();
|
|
77
|
+
},
|
|
78
|
+
};
|
|
79
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A small, fixed calendar universe.
|
|
3
|
+
*
|
|
4
|
+
* `ME` is the signed-in person `fakeCalendar()` speaks for. `BOB` and `CAROL`
|
|
5
|
+
* are never returned by `listCalendars()` — nothing in `CalendarClient` lists
|
|
6
|
+
* someone else's own calendars — they exist only so `getAvailability` has two
|
|
7
|
+
* principals to tell apart: one who shared a calendar with `ME` (busy periods
|
|
8
|
+
* come back) and one who shared nothing (an empty list comes back), per
|
|
9
|
+
* MSG-053's fourth load-bearing behaviour
|
|
10
|
+
* (https://github.com/wtfalch/messaging/issues/145).
|
|
11
|
+
*
|
|
12
|
+
* `ME`'s own "Work" calendar carries the one recurring event the rules ask
|
|
13
|
+
* for, so a month view has a whole series to draw, not just a single day.
|
|
14
|
+
*/
|
|
15
|
+
import type { AvailabilityInclusion, CalendarEventStatus, CalendarRecurrenceRule, CalendarRight } from '../types.ts';
|
|
16
|
+
export type SeedEvent = {
|
|
17
|
+
/** Stable across every copy of the same invite — the organiser's and each
|
|
18
|
+
* attendee's own (#137 "Scheduling"). Also used as this fake's event id,
|
|
19
|
+
* since seed data never collides. */
|
|
20
|
+
uid: string;
|
|
21
|
+
title: string;
|
|
22
|
+
description?: string;
|
|
23
|
+
/** Minutes from the fake's fixed "now" to the event's start. Negative is
|
|
24
|
+
* in the past. */
|
|
25
|
+
startOffsetMinutes: number;
|
|
26
|
+
durationMinutes: number;
|
|
27
|
+
isAllDay?: boolean;
|
|
28
|
+
location?: string;
|
|
29
|
+
recurrenceRule?: CalendarRecurrenceRule;
|
|
30
|
+
status?: CalendarEventStatus;
|
|
31
|
+
};
|
|
32
|
+
export type SeedCalendar = {
|
|
33
|
+
id: string;
|
|
34
|
+
name: string;
|
|
35
|
+
description?: string;
|
|
36
|
+
color?: string;
|
|
37
|
+
isVisible?: boolean;
|
|
38
|
+
includeInAvailability?: AvailabilityInclusion;
|
|
39
|
+
/** Grantee accountId -> the rights this calendar's owner has given them
|
|
40
|
+
* (#138 §1, `shareWith`). */
|
|
41
|
+
shareWith?: Record<string, readonly CalendarRight[]>;
|
|
42
|
+
events?: readonly SeedEvent[];
|
|
43
|
+
};
|
|
44
|
+
export type SeedPrincipal = {
|
|
45
|
+
accountId: string;
|
|
46
|
+
email: string;
|
|
47
|
+
name?: string;
|
|
48
|
+
calendars: readonly SeedCalendar[];
|
|
49
|
+
};
|
|
50
|
+
/** "Me": one plain calendar with a single event, one with a recurring weekly
|
|
51
|
+
* series. Both visible. Personal starts shared with Bob at the quieter of
|
|
52
|
+
* the two levels -- `mayReadFreeBusy` without `mayReadItems` -- so the
|
|
53
|
+
* sharing dialog opens onto a real grant rather than only an empty state,
|
|
54
|
+
* and so the level a row reads back is exercised rather than assumed. */
|
|
55
|
+
export declare const ME: SeedPrincipal;
|
|
56
|
+
/** Bob has shared his calendar with "me" — `mayReadItems` only, no
|
|
57
|
+
* `mayReadFreeBusy` — because live testing found the first right alone is
|
|
58
|
+
* what unlocks `Principal/getAvailability`; the second right changed
|
|
59
|
+
* nothing (#145 amendment). He is also the invitee the scheduling tests
|
|
60
|
+
* send an invite to. */
|
|
61
|
+
export declare const BOB: SeedPrincipal;
|
|
62
|
+
/** Carol has shared nothing. `getAvailability('carol', ...)` must come back
|
|
63
|
+
* empty even though she has a real, confirmed event on the calendar — no
|
|
64
|
+
* share means no data, not even an aggregated blob (#137 "Free/busy"). */
|
|
65
|
+
export declare const CAROL: SeedPrincipal;
|
|
66
|
+
export declare const OTHER_PRINCIPALS: readonly SeedPrincipal[];
|