@wtfalch/email 0.13.1 → 0.15.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 (60) hide show
  1. package/README.md +390 -12
  2. package/dist/imip/compose.d.ts +5 -0
  3. package/dist/imip/compose.js +84 -0
  4. package/dist/imip/index.d.ts +15 -0
  5. package/dist/imip/index.js +14 -0
  6. package/dist/imip/lookup.d.ts +21 -0
  7. package/dist/imip/lookup.js +26 -0
  8. package/dist/imip/parse.d.ts +11 -0
  9. package/dist/imip/parse.js +116 -0
  10. package/dist/imip/types.d.ts +57 -0
  11. package/dist/imip/types.js +9 -0
  12. package/dist/mailbox/client.d.ts +28 -1
  13. package/dist/mailbox/client.js +51 -0
  14. package/dist/mailbox/fake/mailbox.js +567 -7
  15. package/dist/mailbox/index.d.ts +16 -8
  16. package/dist/mailbox/index.js +8 -4
  17. package/dist/mailbox/mail.css +13 -0
  18. package/dist/mailbox/mailboxes.d.ts +95 -1
  19. package/dist/mailbox/mailboxes.js +243 -1
  20. package/dist/mailbox/mutate.d.ts +21 -0
  21. package/dist/mailbox/mutate.js +71 -0
  22. package/dist/mailbox/quoted.d.ts +94 -0
  23. package/dist/mailbox/quoted.js +158 -0
  24. package/dist/mailbox/react/Composer.js +13 -1
  25. package/dist/mailbox/react/Mail.js +273 -33
  26. package/dist/mailbox/react/ThreadView.d.ts +13 -1
  27. package/dist/mailbox/react/ThreadView.js +5 -4
  28. package/dist/mailbox/react/index.d.ts +3 -1
  29. package/dist/mailbox/react/index.js +2 -1
  30. package/dist/mailbox/react/quotedHtml.d.ts +105 -0
  31. package/dist/mailbox/react/quotedHtml.js +163 -0
  32. package/dist/mailbox/sieve.d.ts +76 -0
  33. package/dist/mailbox/sieve.js +241 -0
  34. package/dist/mailbox/snooze.d.ts +48 -0
  35. package/dist/mailbox/snooze.js +176 -0
  36. package/dist/mailbox/submit.d.ts +56 -2
  37. package/dist/mailbox/submit.js +145 -11
  38. package/dist/mailbox/threads.js +2 -0
  39. package/dist/mailbox/types.d.ts +60 -0
  40. package/dist/mailbox/vacation.d.ts +32 -0
  41. package/dist/mailbox/vacation.js +79 -0
  42. package/dist/postmaster/apply.d.ts +154 -1
  43. package/dist/postmaster/apply.js +336 -1
  44. package/dist/postmaster/audit.d.ts +22 -1
  45. package/dist/postmaster/audit.js +7 -0
  46. package/dist/postmaster/client.d.ts +49 -0
  47. package/dist/postmaster/client.js +43 -0
  48. package/dist/postmaster/index.d.ts +6 -3
  49. package/dist/postmaster/index.js +5 -2
  50. package/dist/postmaster/mail-copy.d.ts +169 -0
  51. package/dist/postmaster/mail-copy.js +259 -0
  52. package/dist/postmaster/objects.js +11 -0
  53. package/dist/postmaster/org-mail.d.ts +117 -0
  54. package/dist/postmaster/org-mail.js +206 -0
  55. package/dist/postmaster/overview.d.ts +4 -0
  56. package/dist/postmaster/queue.d.ts +111 -0
  57. package/dist/postmaster/queue.js +64 -0
  58. package/dist/postmaster/writes.d.ts +59 -0
  59. package/dist/postmaster/writes.js +106 -0
  60. package/package.json +8 -3
@@ -0,0 +1,116 @@
1
+ import ICAL from 'ical.js';
2
+ /**
3
+ * An `ICAL.Time` as a `Date`, the instant it names.
4
+ *
5
+ * **A floating time is read as UTC, not the machine's own zone.** `ical.js`
6
+ * defaults an unzoned time to `ICAL.Timezone.localTimezone`, and its own
7
+ * `toJSDate()` then builds the `Date` from wall-clock numbers read as
8
+ * *local* time -- which would make parsing the same message answer
9
+ * differently depending on where the code runs. RFC 5545 §3.3.5 gives a
10
+ * floating time no zone at all; UTC is this module's own choice of how to
11
+ * anchor it deterministically, not a rule the RFC states. A `TZID` that
12
+ * *did* resolve -- against the message's own `VTIMEZONE`, which is how
13
+ * `ical.js` hydrates one (`Component.getTimeZoneByID` walks up to the
14
+ * `VCALENDAR` and matches on the embedded component, no registration
15
+ * needed) -- carries a real zone other than `localTimezone`, so it still
16
+ * goes through `toJSDate()` on the line below.
17
+ */
18
+ function toDate(time) {
19
+ if (time.zone === ICAL.Timezone.localTimezone) {
20
+ return new Date(Date.UTC(time.year, time.month - 1, time.day, time.hour, time.minute, time.second));
21
+ }
22
+ return time.toJSDate();
23
+ }
24
+ /** `ORGANIZER`/`ATTENDEE`: the `mailto:` URI as a plain address, with `CN`
25
+ * when the property carried one. `null` for anything that is not a
26
+ * string value -- a cal-address ical.js could not make sense of. */
27
+ function person(property) {
28
+ const value = property?.getFirstValue();
29
+ if (typeof value !== 'string')
30
+ return null;
31
+ const email = value.replace(/^mailto:/i, '').trim();
32
+ if (!email)
33
+ return null;
34
+ const name = property?.getFirstParameter('cn');
35
+ return typeof name === 'string' && name ? { email, name } : { email };
36
+ }
37
+ function text(value) {
38
+ return typeof value === 'string' && value.length > 0 ? value : undefined;
39
+ }
40
+ /**
41
+ * Read an iTIP `COUNTER` or `DECLINECOUNTER` out of its `VCALENDAR` text.
42
+ *
43
+ * **Never throws.** Malformed text, a `VCALENDAR` with no `VEVENT`, an
44
+ * event missing a property this module requires, or any other method --
45
+ * `REQUEST`, `REPLY`, `CANCEL`, all of them the server's own iTIP engine
46
+ * owns (#97) -- all answer `null` rather than raise, since this reads mail
47
+ * nobody here wrote.
48
+ */
49
+ export function parseImip(ics) {
50
+ try {
51
+ return read(ics);
52
+ }
53
+ catch {
54
+ return null;
55
+ }
56
+ }
57
+ function read(ics) {
58
+ const vcalendar = new ICAL.Component(ICAL.parse(ics));
59
+ if (vcalendar.name !== 'vcalendar')
60
+ return null;
61
+ const method = String(vcalendar.getFirstPropertyValue('method') ?? '').toUpperCase();
62
+ if (method !== 'COUNTER' && method !== 'DECLINECOUNTER')
63
+ return null;
64
+ const vevent = vcalendar.getFirstSubcomponent('vevent');
65
+ if (!vevent)
66
+ return null;
67
+ const uid = text(vevent.getFirstPropertyValue('uid'));
68
+ const sequenceValue = vevent.getFirstPropertyValue('sequence');
69
+ const dtstamp = vevent.getFirstPropertyValue('dtstamp');
70
+ const organizer = person(vevent.getFirstProperty('organizer'));
71
+ const attendee = person(vevent.getFirstProperty('attendee'));
72
+ if (uid === undefined ||
73
+ typeof sequenceValue !== 'number' ||
74
+ !(dtstamp instanceof ICAL.Time) ||
75
+ !organizer ||
76
+ !attendee) {
77
+ return null;
78
+ }
79
+ const recurrenceIdValue = vevent.getFirstPropertyValue('recurrence-id');
80
+ const recurrenceId = recurrenceIdValue instanceof ICAL.Time ? toDate(recurrenceIdValue) : undefined;
81
+ const comment = text(vevent.getFirstPropertyValue('comment'));
82
+ const stamp = toDate(dtstamp);
83
+ if (method === 'DECLINECOUNTER') {
84
+ return {
85
+ method,
86
+ uid,
87
+ sequence: sequenceValue,
88
+ organizer,
89
+ attendee,
90
+ ...(recurrenceId ? { recurrenceId } : {}),
91
+ ...(comment ? { comment } : {}),
92
+ stamp,
93
+ };
94
+ }
95
+ const summary = text(vevent.getFirstPropertyValue('summary'));
96
+ const startValue = vevent.getFirstPropertyValue('dtstart');
97
+ const endValue = vevent.getFirstPropertyValue('dtend');
98
+ if (summary === undefined ||
99
+ !(startValue instanceof ICAL.Time) ||
100
+ !(endValue instanceof ICAL.Time)) {
101
+ return null;
102
+ }
103
+ return {
104
+ method,
105
+ uid,
106
+ sequence: sequenceValue,
107
+ summary,
108
+ organizer,
109
+ attendee,
110
+ start: toDate(startValue),
111
+ end: toDate(endValue),
112
+ ...(recurrenceId ? { recurrenceId } : {}),
113
+ ...(comment ? { comment } : {}),
114
+ stamp,
115
+ };
116
+ }
@@ -0,0 +1,57 @@
1
+ /**
2
+ * The shapes `@wtfalch/email/imip` composes, parses and hands back.
3
+ *
4
+ * Plain fields in, a typed union out (#102): this module takes no
5
+ * dependency on `@wtfalch/calendar` or any other calendar model, and every
6
+ * type here is data a caller can build or read without `ical.js` --
7
+ * `ical.js` itself stays behind `compose.ts` and `parse.ts`.
8
+ */
9
+ /** One person on a proposal: the organizer of the event, or the attendee
10
+ * proposing a new time for it. */
11
+ export type ImipPerson = {
12
+ email: string;
13
+ name?: string;
14
+ };
15
+ /** What an attendee sends to propose a new time for an event they are not
16
+ * organizing. One `VEVENT`, RFC 5546 §3.2.7: the original `UID` and
17
+ * `SEQUENCE` echoed back, so the organizer can tell which event and which
18
+ * version of it this answers, and the slot being proposed. */
19
+ export type CounterInput = {
20
+ uid: string;
21
+ /** Echoed from the event being countered, not incremented -- RFC 5546
22
+ * §3.2.7 requires a `COUNTER` to carry the organizer's own `SEQUENCE`. */
23
+ sequence: number;
24
+ /** Set only when the proposal is for one instance of a recurring event,
25
+ * never the series. */
26
+ recurrenceId?: Date;
27
+ summary: string;
28
+ organizer: ImipPerson;
29
+ /** The person proposing the new time -- never the organizer. */
30
+ attendee: ImipPerson;
31
+ /** The proposed start of the slot, compared to the event's current one. */
32
+ start: Date;
33
+ end: Date;
34
+ comment?: string;
35
+ };
36
+ /** What an organizer sends back to refuse a `CounterInput`, RFC 5546 §3.2.8.
37
+ * It proposes nothing, so it carries none of the fields that would: no
38
+ * `summary`, no slot. */
39
+ export type DeclineCounterInput = Omit<CounterInput, 'start' | 'end' | 'summary'>;
40
+ /** A composed iTIP message, ready to ride as a `text/calendar` body part
41
+ * whose `Content-Type` carries `method=<method>` (see the PR for why the
42
+ * JMAP `type` field is where that parameter goes). */
43
+ export type CalendarPart = {
44
+ method: 'COUNTER' | 'DECLINECOUNTER';
45
+ ics: string;
46
+ };
47
+ /** A parsed iTIP message: the input that built it, tagged with its method
48
+ * and the `DTSTAMP` every iTIP message carries (RFC 5546 §3.2.7/§3.2.8). */
49
+ export type Imip = ({
50
+ method: 'COUNTER';
51
+ } & CounterInput & {
52
+ stamp: Date;
53
+ }) | ({
54
+ method: 'DECLINECOUNTER';
55
+ } & DeclineCounterInput & {
56
+ stamp: Date;
57
+ });
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The shapes `@wtfalch/email/imip` composes, parses and hands back.
3
+ *
4
+ * Plain fields in, a typed union out (#102): this module takes no
5
+ * dependency on `@wtfalch/calendar` or any other calendar model, and every
6
+ * type here is data a caller can build or read without `ical.js` --
7
+ * `ical.js` itself stays behind `compose.ts` and `parse.ts`.
8
+ */
9
+ export {};
@@ -1,7 +1,13 @@
1
1
  import { JamClient } from 'jmap-jam';
2
- import type { MailSession } from './types.ts';
2
+ import type { MailAccount, MailSession } from './types.ts';
3
3
  export declare const MAIL_CAPABILITY = "urn:ietf:params:jmap:mail";
4
4
  export declare const SUBMISSION_CAPABILITY = "urn:ietf:params:jmap:submission";
5
+ /** RFC 9661, "JMAP for Sieve Scripts". `jmap-jam` does not know this
6
+ * capability (its `knownCapabilities` table stops at RFC 8621), so
7
+ * `sieve.ts` supplies it by hand through `RequestOptions.using` on every
8
+ * call, the same thing `submit.ts`'s `send()` does for the mail capability
9
+ * alongside `EmailSubmission/set`. */
10
+ export declare const SIEVE_CAPABILITY = "urn:ietf:params:jmap:sieve";
5
11
  /** The parts of the JMAP session document this package uses. */
6
12
  type SessionDocument = {
7
13
  username: string;
@@ -13,6 +19,11 @@ type SessionDocument = {
13
19
  capabilities?: Record<string, Record<string, unknown> | undefined>;
14
20
  accounts: Record<string, {
15
21
  name: string;
22
+ /** False for an account this login reaches but does not own: a shared
23
+ * mailbox it is a member of, or one shared with it by an ACL. The
24
+ * server decides this, not the client (`isPersonal` in RFC 8620
25
+ * §1.6.2). */
26
+ isPersonal?: boolean;
16
27
  isReadOnly: boolean;
17
28
  accountCapabilities: Record<string, unknown>;
18
29
  }>;
@@ -56,6 +67,22 @@ export declare class MailClient {
56
67
  /** The signed-in person and the account being read. */
57
68
  session(): Promise<MailSession>;
58
69
  accountId(): Promise<string>;
70
+ /**
71
+ * Every mailbox this login can read, the personal one first.
72
+ *
73
+ * A shared mailbox — `hr@`, a team address — is an ordinary account on the
74
+ * server that the signed-in person is a member of, and the session document
75
+ * lists it beside their own with `isPersonal: false`. Only accounts
76
+ * offering JMAP Mail are returned: a session can carry an account that
77
+ * exists for contacts or a calendar and holds no mail at all, and putting
78
+ * one of those in a mailbox switcher would offer a mailbox that cannot be
79
+ * opened.
80
+ *
81
+ * This client stays on the account it was built with. Reading another one
82
+ * means another client, built with that id — which is also what keeps a
83
+ * cached connection honest.
84
+ */
85
+ accounts(): Promise<MailAccount[]>;
59
86
  /**
60
87
  * The URL that fetches a blob's bytes. It carries no credential, so the
61
88
  * request needs the same `Authorization` header as the API.
@@ -3,10 +3,32 @@ import { MailError, guard } from "./errors.js";
3
3
  import { expandTemplate } from "./uri.js";
4
4
  export const MAIL_CAPABILITY = 'urn:ietf:params:jmap:mail';
5
5
  export const SUBMISSION_CAPABILITY = 'urn:ietf:params:jmap:submission';
6
+ /** RFC 9661, "JMAP for Sieve Scripts". `jmap-jam` does not know this
7
+ * capability (its `knownCapabilities` table stops at RFC 8621), so
8
+ * `sieve.ts` supplies it by hand through `RequestOptions.using` on every
9
+ * call, the same thing `submit.ts`'s `send()` does for the mail capability
10
+ * alongside `EmailSubmission/set`. */
11
+ export const SIEVE_CAPABILITY = 'urn:ietf:params:jmap:sieve';
6
12
  /** A size limit, or `null` for anything that is not a usable one. */
7
13
  function positive(value) {
8
14
  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
9
15
  }
16
+ /**
17
+ * Whether an account in this session is the login's own.
18
+ *
19
+ * The server says so (`isPersonal`), and that is what is trusted. The
20
+ * fallback is for a session document that omits the field: the account the
21
+ * session itself names as primary for mail is the personal one, and anything
22
+ * else it lists is reached through a membership or a share. Guessing the
23
+ * other way — treating an unlabelled shared mailbox as personal — would make
24
+ * a switcher claim a team's mail belongs to whoever opened it.
25
+ */
26
+ function personal(doc, accountId) {
27
+ const said = doc.accounts[accountId]?.isPersonal;
28
+ if (typeof said === 'boolean')
29
+ return said;
30
+ return accountId === doc.primaryAccounts?.[MAIL_CAPABILITY];
31
+ }
10
32
  function maxSizeUpload(doc) {
11
33
  return positive(doc.capabilities?.['urn:ietf:params:jmap:core']?.maxSizeUpload);
12
34
  }
@@ -178,6 +200,7 @@ export class MailClient {
178
200
  username: doc.username,
179
201
  accountId,
180
202
  accountName: account?.name ?? '',
203
+ isPersonal: personal(doc, accountId),
181
204
  isReadOnly: account?.isReadOnly ?? false,
182
205
  maySubmit: Boolean(account?.accountCapabilities?.[SUBMISSION_CAPABILITY]),
183
206
  maxSizeUpload: maxSizeUpload(doc),
@@ -188,6 +211,34 @@ export class MailClient {
188
211
  async accountId() {
189
212
  return (await this.connect()).accountId;
190
213
  }
214
+ /**
215
+ * Every mailbox this login can read, the personal one first.
216
+ *
217
+ * A shared mailbox — `hr@`, a team address — is an ordinary account on the
218
+ * server that the signed-in person is a member of, and the session document
219
+ * lists it beside their own with `isPersonal: false`. Only accounts
220
+ * offering JMAP Mail are returned: a session can carry an account that
221
+ * exists for contacts or a calendar and holds no mail at all, and putting
222
+ * one of those in a mailbox switcher would offer a mailbox that cannot be
223
+ * opened.
224
+ *
225
+ * This client stays on the account it was built with. Reading another one
226
+ * means another client, built with that id — which is also what keeps a
227
+ * cached connection honest.
228
+ */
229
+ async accounts() {
230
+ const { doc } = await this.connect();
231
+ return Object.entries(doc.accounts)
232
+ .filter(([, account]) => Boolean(account.accountCapabilities?.[MAIL_CAPABILITY]))
233
+ .map(([id, account]) => ({
234
+ id,
235
+ name: account.name,
236
+ isPersonal: personal(doc, id),
237
+ isReadOnly: account.isReadOnly ?? false,
238
+ maySubmit: Boolean(account.accountCapabilities?.[SUBMISSION_CAPABILITY]),
239
+ }))
240
+ .sort((a, b) => a.isPersonal === b.isPersonal ? a.name.localeCompare(b.name) : a.isPersonal ? -1 : 1);
241
+ }
191
242
  /**
192
243
  * The URL that fetches a blob's bytes. It carries no credential, so the
193
244
  * request needs the same `Authorization` header as the API.