@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,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[];