@wtfalch/email 0.13.1 → 0.14.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/README.md +66 -4
  2. package/dist/mailbox/client.d.ts +22 -1
  3. package/dist/mailbox/client.js +45 -0
  4. package/dist/mailbox/fake/mailbox.js +205 -5
  5. package/dist/mailbox/index.d.ts +11 -7
  6. package/dist/mailbox/index.js +5 -3
  7. package/dist/mailbox/mail.css +13 -0
  8. package/dist/mailbox/mailboxes.d.ts +95 -1
  9. package/dist/mailbox/mailboxes.js +243 -1
  10. package/dist/mailbox/mutate.d.ts +21 -0
  11. package/dist/mailbox/mutate.js +71 -0
  12. package/dist/mailbox/quoted.d.ts +94 -0
  13. package/dist/mailbox/quoted.js +158 -0
  14. package/dist/mailbox/react/Composer.js +13 -1
  15. package/dist/mailbox/react/Mail.js +273 -33
  16. package/dist/mailbox/react/ThreadView.d.ts +13 -1
  17. package/dist/mailbox/react/ThreadView.js +5 -4
  18. package/dist/mailbox/react/index.d.ts +3 -1
  19. package/dist/mailbox/react/index.js +2 -1
  20. package/dist/mailbox/react/quotedHtml.d.ts +105 -0
  21. package/dist/mailbox/react/quotedHtml.js +163 -0
  22. package/dist/mailbox/snooze.d.ts +48 -0
  23. package/dist/mailbox/snooze.js +176 -0
  24. package/dist/mailbox/submit.d.ts +26 -0
  25. package/dist/mailbox/submit.js +88 -7
  26. package/dist/mailbox/threads.js +2 -0
  27. package/dist/mailbox/types.d.ts +40 -0
  28. package/dist/postmaster/apply.d.ts +154 -1
  29. package/dist/postmaster/apply.js +336 -1
  30. package/dist/postmaster/audit.d.ts +22 -1
  31. package/dist/postmaster/audit.js +7 -0
  32. package/dist/postmaster/client.d.ts +49 -0
  33. package/dist/postmaster/client.js +43 -0
  34. package/dist/postmaster/index.d.ts +4 -3
  35. package/dist/postmaster/index.js +3 -2
  36. package/dist/postmaster/objects.js +11 -0
  37. package/dist/postmaster/overview.d.ts +4 -0
  38. package/dist/postmaster/queue.d.ts +111 -0
  39. package/dist/postmaster/queue.js +64 -0
  40. package/dist/postmaster/writes.d.ts +59 -0
  41. package/dist/postmaster/writes.js +106 -0
  42. package/package.json +1 -1
@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { Button, Empty, Icon, Identity, Menu, ScrollArea, Skeleton } from '@wtfalch/design';
3
3
  import { useEffect, useState } from 'react';
4
4
  import { HtmlBody } from "./HtmlBody.js";
5
- export function ThreadView({ thread, loading = false, onReply, onForward, onArchive, onTrash, onMarkUnread, onFlag, flagged = false, busy = false, onDownload, downloading, fetchInline, onBack, className, }) {
5
+ export function ThreadView({ thread, loading = false, onReply, onForward, onArchive, onTrash, onMove, onMarkUnread, onFlag, flagged = false, busy = false, onDownload, downloading, fetchInline, onBack, composer, className, }) {
6
6
  if (loading && !thread) {
7
7
  return (_jsxs("div", { className: `thread${className ? ` ${className}` : ''}`, "aria-busy": "true", children: [_jsxs("header", { className: "thread-head", children: [_jsx(Skeleton, { width: "52%", height: 5 }), _jsx(Skeleton, { width: "28%", height: 2.5 })] }), _jsx("div", { className: "thread-body", children: _jsxs("div", { className: "message open", children: [_jsxs("div", { className: "message-head", children: [_jsx(Skeleton, { variant: "circular", width: "2rem", height: 8 }), _jsx(Skeleton, { width: "30%", height: 3 })] }), _jsx("div", { className: "message-body", children: _jsx(Skeleton, { lines: 6, height: 2.5 }) })] }) })] }));
8
8
  }
@@ -14,7 +14,8 @@ export function ThreadView({ thread, loading = false, onReply, onForward, onArch
14
14
  const people = [
15
15
  ...new Map(thread.messages.flatMap((message) => message.from.map((who) => [who.email, who.name?.trim() || who.email]))).values(),
16
16
  ];
17
- return (_jsxs("div", { className: `thread${className ? ` ${className}` : ''}`, children: [_jsxs("header", { className: "thread-head", children: [_jsxs("div", { className: "thread-headline", children: [onBack && (_jsx(Button, { kind: "ghost", iconOnly: true, onClick: onBack, "aria-label": "Back to the list", children: _jsx(Icon, { name: "back" }) })), _jsxs("div", { className: "thread-heading", children: [_jsx("h2", { className: "thread-title", children: thread.subject || '(no subject)' }), _jsxs("p", { className: "thread-meta", children: [people.join(', '), _jsx("span", { className: "thread-meta-sep", children: "\u00B7" }), thread.messages.length === 1 ? '1 message' : `${thread.messages.length} messages`] })] })] }), _jsx(Toolbar, { message: newest, onReply: onReply, onForward: onForward, onArchive: onArchive, onTrash: onTrash, onMarkUnread: onMarkUnread, onFlag: onFlag, flagged: flagged, busy: busy })] }), _jsxs(ScrollArea, { className: "thread-body", label: "Messages in this conversation", children: [_jsx("ol", { className: "messages", children: thread.messages.map((message, index) => (_jsx("li", { children: _jsx(MessageCard, { message: message, defaultOpen: index === last, onReply: onReply, onForward: onForward, onDownload: onDownload, downloading: downloading, fetchInline: fetchInline }) }, message.id))) }), onReply && newest && (_jsxs("div", { className: "thread-foot", children: [_jsxs(Button, { kind: "primary", onClick: () => onReply(newest, false), disabled: busy, children: [_jsx(Icon, { name: "reply" }), " Reply"] }), _jsx(Button, { kind: "ghost", onClick: () => onReply(newest, true), disabled: busy, children: "Reply all" }), onForward && (_jsx(Button, { kind: "ghost", onClick: () => onForward(newest), disabled: busy, children: "Forward" }))] }))] })] }));
17
+ return (_jsxs("div", { className: `thread${className ? ` ${className}` : ''}`, children: [_jsxs("header", { className: "thread-head", children: [_jsxs("div", { className: "thread-headline", children: [onBack && (_jsx(Button, { kind: "ghost", iconOnly: true, onClick: onBack, "aria-label": "Back to the list", children: _jsx(Icon, { name: "back" }) })), _jsxs("div", { className: "thread-heading", children: [_jsx("h2", { className: "thread-title", children: thread.subject || '(no subject)' }), _jsxs("p", { className: "thread-meta", children: [people.join(', '), _jsx("span", { className: "thread-meta-sep", children: "\u00B7" }), thread.messages.length === 1 ? '1 message' : `${thread.messages.length} messages`] })] })] }), _jsx(Toolbar, { message: newest, onReply: onReply, onForward: onForward, onArchive: onArchive, onTrash: onTrash, onMove: onMove, onMarkUnread: onMarkUnread, onFlag: onFlag, flagged: flagged, busy: busy })] }), _jsxs(ScrollArea, { className: "thread-body", label: "Messages in this conversation", children: [_jsx("ol", { className: "messages", children: thread.messages.map((message, index) => (_jsx("li", { children: _jsx(MessageCard, { message: message, defaultOpen: index === last, onReply: onReply, onForward: onForward, onDownload: onDownload, downloading: downloading, fetchInline: fetchInline }) }, message.id))) }), composer ? (_jsx("div", { className: "thread-foot thread-compose", children: composer })) : (onReply &&
18
+ newest && (_jsxs("div", { className: "thread-foot", children: [_jsxs(Button, { kind: "primary", onClick: () => onReply(newest, false), disabled: busy, children: [_jsx(Icon, { name: "reply" }), " Reply"] }), _jsx(Button, { kind: "ghost", onClick: () => onReply(newest, true), disabled: busy, children: "Reply all" }), onForward && (_jsx(Button, { kind: "ghost", onClick: () => onForward(newest), disabled: busy, children: "Forward" }))] })))] })] }));
18
19
  }
19
20
  /** A hover hint on a control that has only a glyph. `aria-hidden` on the
20
21
  * wrapper is wrong -- the button inside it has to stay in the tree -- so
@@ -41,7 +42,7 @@ function Hint({ says, children }) {
41
42
  * among them. Hovering the button hovers the span, so the hint appears
42
43
  * either way.
43
44
  */
44
- function Toolbar({ message, onReply, onForward, onArchive, onTrash, onMarkUnread, onFlag, flagged, busy, }) {
45
+ function Toolbar({ message, onReply, onForward, onArchive, onTrash, onMove, onMarkUnread, onFlag, flagged, busy, }) {
45
46
  if (!message)
46
47
  return null;
47
48
  /* Reply all lives here rather than on the bar. It has no glyph that says
@@ -73,7 +74,7 @@ function Toolbar({ message, onReply, onForward, onArchive, onTrash, onMarkUnread
73
74
  ]
74
75
  : []),
75
76
  ];
76
- return (_jsxs("div", { className: "thread-tools", children: [onReply && (_jsx(Hint, { says: "Reply \u2014 R", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: () => onReply(message, false), "aria-label": "Reply", children: _jsx(Icon, { name: "reply" }) }) })), onForward && (_jsx(Hint, { says: "Forward \u2014 F", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: () => onForward?.(message), "aria-label": "Forward", children: _jsx(Icon, { name: "forward" }) }) })), _jsx("span", { className: "thread-tools-rule", "aria-hidden": "true" }), onFlag && (_jsx(Hint, { says: flagged ? 'Unflag — S' : 'Flag — S', children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: () => onFlag(!flagged), "aria-pressed": flagged, "aria-label": flagged ? 'Unflag' : 'Flag', className: flagged ? 'is-flagged' : undefined, children: _jsx(Icon, { name: flagged ? 'star-filled' : 'star' }) }) })), onArchive && (_jsx(Hint, { says: "Archive \u2014 E", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: onArchive, "aria-label": "Archive", children: _jsx(Icon, { name: "folder" }) }) })), onTrash && (_jsx(Hint, { says: "Delete \u2014 #", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: onTrash, "aria-label": "Delete", children: _jsx(Icon, { name: "trash" }) }) })), overflow.length > 0 && (_jsx(Menu, { label: "More actions", placement: "bottom end", trigger: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, "aria-label": "More actions", children: _jsx(Icon, { name: "more" }) }), items: overflow }))] }));
77
+ return (_jsxs("div", { className: "thread-tools", children: [onReply && (_jsx(Hint, { says: "Reply \u2014 R", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: () => onReply(message, false), "aria-label": "Reply", children: _jsx(Icon, { name: "reply" }) }) })), onForward && (_jsx(Hint, { says: "Forward \u2014 F", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: () => onForward?.(message), "aria-label": "Forward", children: _jsx(Icon, { name: "forward" }) }) })), _jsx("span", { className: "thread-tools-rule", "aria-hidden": "true" }), onFlag && (_jsx(Hint, { says: flagged ? 'Unflag — S' : 'Flag — S', children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: () => onFlag(!flagged), "aria-pressed": flagged, "aria-label": flagged ? 'Unflag' : 'Flag', className: flagged ? 'is-flagged' : undefined, children: _jsx(Icon, { name: flagged ? 'star-filled' : 'star' }) }) })), onArchive && (_jsx(Hint, { says: "Archive \u2014 E", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: onArchive, "aria-label": "Archive", children: _jsx(Icon, { name: "folder" }) }) })), onTrash && (_jsx(Hint, { says: "Delete \u2014 #", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: onTrash, "aria-label": "Delete", children: _jsx(Icon, { name: "trash" }) }) })), onMove && (_jsx(Hint, { says: "Move to a folder \u2014 V", children: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, onClick: onMove, "aria-label": "Move to a folder", children: _jsx(Icon, { name: "file" }) }) })), overflow.length > 0 && (_jsx(Menu, { label: "More actions", placement: "bottom end", trigger: _jsx(Button, { kind: "ghost", iconOnly: true, disabled: busy, "aria-label": "More actions", children: _jsx(Icon, { name: "more" }) }), items: overflow }))] }));
77
78
  }
78
79
  function MessageCard({ message, defaultOpen, onReply, onForward, onDownload, downloading, fetchInline, }) {
79
80
  const [open, setOpen] = useState(defaultOpen);
@@ -6,7 +6,7 @@
6
6
  * and reused by an application with its own layout. `Mail` is the one piece
7
7
  * that holds state and calls the hooks.
8
8
  *
9
- * On `@wtfalch/design` 0.5.0 and `@wtfalch/email/mailbox`. Import `@wtfalch/email/mailbox/mail.css`
9
+ * On `@wtfalch/design` >=0.16.0 and `@wtfalch/email/mailbox`. Import `@wtfalch/email/mailbox/mail.css`
10
10
  * after the design stylesheet.
11
11
  */
12
12
  export { MailProvider, useMailClient, useOptionalMailClient } from './context.tsx';
@@ -20,6 +20,8 @@ export { ThreadView, bytes } from './ThreadView.tsx';
20
20
  export type { ThreadActions, ThreadViewProps } from './ThreadView.tsx';
21
21
  export { HtmlBody } from './HtmlBody.tsx';
22
22
  export type { HtmlBodyProps } from './HtmlBody.tsx';
23
+ export { htmlQuoteBoundary, splitQuotedHtml } from './quotedHtml.ts';
24
+ export type { HtmlQuoteBoundary } from './quotedHtml.ts';
23
25
  export { Composer, parseAddresses } from './Composer.tsx';
24
26
  export type { AttachmentLimits, ComposerProps } from './Composer.tsx';
25
27
  export { Mail } from './Mail.tsx';
@@ -6,7 +6,7 @@
6
6
  * and reused by an application with its own layout. `Mail` is the one piece
7
7
  * that holds state and calls the hooks.
8
8
  *
9
- * On `@wtfalch/design` 0.5.0 and `@wtfalch/email/mailbox`. Import `@wtfalch/email/mailbox/mail.css`
9
+ * On `@wtfalch/design` >=0.16.0 and `@wtfalch/email/mailbox`. Import `@wtfalch/email/mailbox/mail.css`
10
10
  * after the design stylesheet.
11
11
  */
12
12
  export { MailProvider, useMailClient, useOptionalMailClient } from "./context.js";
@@ -15,6 +15,7 @@ export { MailboxTree, flatMailboxes, orderForReading } from "./MailboxTree.js";
15
15
  export { ThreadList, dayGroup, shortTime } from "./ThreadList.js";
16
16
  export { ThreadView, bytes } from "./ThreadView.js";
17
17
  export { HtmlBody } from "./HtmlBody.js";
18
+ export { htmlQuoteBoundary, splitQuotedHtml } from "./quotedHtml.js";
18
19
  export { Composer, parseAddresses } from "./Composer.js";
19
20
  export { Mail } from "./Mail.js";
20
21
  export { usePanes } from "./layout.js";
@@ -0,0 +1,105 @@
1
+ /**
2
+ * Finding the line where a received HTML message's own markup ends and the
3
+ * quoted history it carries begins.
4
+ *
5
+ * This is the HTML half of `splitQuoted` (`../quoted.ts`), which does the
6
+ * same job for a plain-text body and explains, in its own doc comment, why
7
+ * the two live apart: HTML quote detection wants the inert `DOMParser` walk
8
+ * that `./sanitise.ts` already has, and `sanitise.ts` is browser-only, while
9
+ * `../quoted.ts` is exported from the JMAP core and has to run with no DOM
10
+ * at all. So this module sits beside `sanitise.ts`, under `mailbox/react/`,
11
+ * and is exported from the react entry, not the core.
12
+ *
13
+ * **The result is a boundary, not a summary**, mirroring `QuoteBoundary`'s
14
+ * field names on purpose: a caller collapsing the thread view renders `body`
15
+ * and offers `quoted` behind a disclosure, same as the text half. A message
16
+ * with no quoted history returns the whole thing as `body` and `''` as
17
+ * `quoted`; a bare forward that is nothing but quoted history returns `''`
18
+ * (or, depending on incidental whitespace around the marker, whitespace
19
+ * that renders as nothing) as `body` and the rest as `quoted`.
20
+ *
21
+ * **Unlike the text half, `body + quoted` is not guaranteed to equal the
22
+ * original string.** When no marker is found, `body` is the input `html`
23
+ * untouched — that case is a byte-exact round trip. When a marker is found,
24
+ * both halves are serialised back out of the parsed document
25
+ * (`Element.innerHTML` / `outerHTML`), and a parser-serialiser cycle does
26
+ * not promise to reproduce the source byte for byte: attribute quoting and
27
+ * order, self-closing spelling, and incidental whitespace can all change.
28
+ * What holds instead is structural: every node from the parsed body ends up
29
+ * in exactly one of the two halves, nothing is dropped, and rendering each
30
+ * half (through `mailDocument`, same as the original `html` — neither half
31
+ * is sanitised here) reproduces what the reader would see.
32
+ *
33
+ * **What counts as a quote marker, and why a bare `<blockquote>` does not.**
34
+ * Three shapes, each a real client's own convention rather than a guess:
35
+ * - `<blockquote type="cite">` — the attribute mail composers (Apple Mail,
36
+ * Thunderbird, and others going back to Netscape Communicator) set
37
+ * specifically to mean "this is quoted history", not a styling choice. A
38
+ * `<blockquote>` with no `type` — the shape a pull-quote in the body of a
39
+ * message would actually use — is left alone and stays in `body`. That is
40
+ * the false positive that matters, and it is the same safe direction the
41
+ * text half takes when unsure: nothing is hidden, it is just not
42
+ * collapsed.
43
+ * - Gmail's `gmail_quote` class, on whichever element carries it (the
44
+ * wrapping `<div class="gmail_quote gmail_quote_container">` in current
45
+ * Gmail, or a bare `<blockquote class="gmail_quote">` in older markup).
46
+ * - Outlook's plain-text-era divider, translated to HTML: a `<div>` whose
47
+ * inline `style` sets `border-top` to something other than `none`. Real
48
+ * Outlook markup leaves this `<div>` empty and puts the actual
49
+ * `From:`/`Sent:`/`To:`/`Subject:` header block and the quoted body in
50
+ * its *following siblings*, not inside it — unlike the other two shapes,
51
+ * which wrap the quoted content. Marker detection and extraction are
52
+ * unified over this by treating every marker as "itself and everything
53
+ * that follows it, at its own level": the marker's later siblings (and
54
+ * only its own siblings — an ancestor's later siblings are not swept in)
55
+ * join it in `quoted`. For Gmail and `blockquote[type=cite]` that set is
56
+ * almost always just the marker itself, since nothing meaningful trails
57
+ * them in practice.
58
+ *
59
+ * **Not covered, deliberately**, for the same reason the text half draws
60
+ * its own line: a localised divider or attribution; Outlook's Web/desktop
61
+ * markup when it skips the `border-top` divider entirely (`id` values such
62
+ * as `divRplyFwdMsg` are not matched, since they are less stable across
63
+ * versions than the inline style); a marker nested inside a `<template>`
64
+ * (its content lives outside `.children` and is never walked); a second,
65
+ * unrelated quote block once the first marker has been found — only the
66
+ * first marker's *own* later siblings join it in `quoted` (as above), so a
67
+ * second block that is itself one of those siblings is swept in too, but
68
+ * one that instead sits at an outer level — a root-level sibling of a
69
+ * wrapper the first marker is nested inside, as Gmail's `gmail_quote` div
70
+ * often is — is left exactly where it was, inside `body`, not collapsed;
71
+ * and a quote marker a sender's own composer emits without following any
72
+ * of the three conventions above.
73
+ */
74
+ import type { Message } from '../types.ts';
75
+ /** The boundary between an HTML message's own markup and the quoted history
76
+ * under it. Field names match `QuoteBoundary` (`../quoted.ts`) so the two
77
+ * read as one feature; the type is its own because the guarantee is
78
+ * different — see this module's doc comment on round-tripping. */
79
+ export type HtmlQuoteBoundary = {
80
+ /** The reader's own markup, serialised from the document with the quote
81
+ * marker (and its later siblings) removed. Unsanitised, like the input. */
82
+ body: string;
83
+ /** The quoted history: the first quote marker found, and everything that
84
+ * follows it among its own siblings, serialised back out. `''` when no
85
+ * marker was found. Unsanitised, like the input. */
86
+ quoted: string;
87
+ };
88
+ /**
89
+ * Where a received HTML body's own markup ends and its quoted history
90
+ * begins. See the module doc comment for the three marker shapes covered,
91
+ * what is deliberately not, and what the returned halves do and do not
92
+ * guarantee about reconstructing the original string.
93
+ *
94
+ * A nullish `html` is treated the same as an empty one rather than thrown
95
+ * at `.trim()`: the parameter type says `string`, but `Message.html` is
96
+ * `string | null`, and a caller that reaches this function directly
97
+ * instead of through `htmlQuoteBoundary` should not crash a mail client
98
+ * over one message it cannot collapse a quote in.
99
+ */
100
+ export declare function splitQuotedHtml(html: string): HtmlQuoteBoundary;
101
+ /** `splitQuotedHtml` against a received message's own HTML body. A message
102
+ * with no HTML body (text-only) has nothing to split: the whole boundary
103
+ * is empty, not a guess — the same answer `quoteBoundary` (`../quoted.ts`)
104
+ * gives a text-only message with no text body, mirrored the other way. */
105
+ export declare function htmlQuoteBoundary(message: Pick<Message, 'html'>): HtmlQuoteBoundary;
@@ -0,0 +1,163 @@
1
+ /**
2
+ * Finding the line where a received HTML message's own markup ends and the
3
+ * quoted history it carries begins.
4
+ *
5
+ * This is the HTML half of `splitQuoted` (`../quoted.ts`), which does the
6
+ * same job for a plain-text body and explains, in its own doc comment, why
7
+ * the two live apart: HTML quote detection wants the inert `DOMParser` walk
8
+ * that `./sanitise.ts` already has, and `sanitise.ts` is browser-only, while
9
+ * `../quoted.ts` is exported from the JMAP core and has to run with no DOM
10
+ * at all. So this module sits beside `sanitise.ts`, under `mailbox/react/`,
11
+ * and is exported from the react entry, not the core.
12
+ *
13
+ * **The result is a boundary, not a summary**, mirroring `QuoteBoundary`'s
14
+ * field names on purpose: a caller collapsing the thread view renders `body`
15
+ * and offers `quoted` behind a disclosure, same as the text half. A message
16
+ * with no quoted history returns the whole thing as `body` and `''` as
17
+ * `quoted`; a bare forward that is nothing but quoted history returns `''`
18
+ * (or, depending on incidental whitespace around the marker, whitespace
19
+ * that renders as nothing) as `body` and the rest as `quoted`.
20
+ *
21
+ * **Unlike the text half, `body + quoted` is not guaranteed to equal the
22
+ * original string.** When no marker is found, `body` is the input `html`
23
+ * untouched — that case is a byte-exact round trip. When a marker is found,
24
+ * both halves are serialised back out of the parsed document
25
+ * (`Element.innerHTML` / `outerHTML`), and a parser-serialiser cycle does
26
+ * not promise to reproduce the source byte for byte: attribute quoting and
27
+ * order, self-closing spelling, and incidental whitespace can all change.
28
+ * What holds instead is structural: every node from the parsed body ends up
29
+ * in exactly one of the two halves, nothing is dropped, and rendering each
30
+ * half (through `mailDocument`, same as the original `html` — neither half
31
+ * is sanitised here) reproduces what the reader would see.
32
+ *
33
+ * **What counts as a quote marker, and why a bare `<blockquote>` does not.**
34
+ * Three shapes, each a real client's own convention rather than a guess:
35
+ * - `<blockquote type="cite">` — the attribute mail composers (Apple Mail,
36
+ * Thunderbird, and others going back to Netscape Communicator) set
37
+ * specifically to mean "this is quoted history", not a styling choice. A
38
+ * `<blockquote>` with no `type` — the shape a pull-quote in the body of a
39
+ * message would actually use — is left alone and stays in `body`. That is
40
+ * the false positive that matters, and it is the same safe direction the
41
+ * text half takes when unsure: nothing is hidden, it is just not
42
+ * collapsed.
43
+ * - Gmail's `gmail_quote` class, on whichever element carries it (the
44
+ * wrapping `<div class="gmail_quote gmail_quote_container">` in current
45
+ * Gmail, or a bare `<blockquote class="gmail_quote">` in older markup).
46
+ * - Outlook's plain-text-era divider, translated to HTML: a `<div>` whose
47
+ * inline `style` sets `border-top` to something other than `none`. Real
48
+ * Outlook markup leaves this `<div>` empty and puts the actual
49
+ * `From:`/`Sent:`/`To:`/`Subject:` header block and the quoted body in
50
+ * its *following siblings*, not inside it — unlike the other two shapes,
51
+ * which wrap the quoted content. Marker detection and extraction are
52
+ * unified over this by treating every marker as "itself and everything
53
+ * that follows it, at its own level": the marker's later siblings (and
54
+ * only its own siblings — an ancestor's later siblings are not swept in)
55
+ * join it in `quoted`. For Gmail and `blockquote[type=cite]` that set is
56
+ * almost always just the marker itself, since nothing meaningful trails
57
+ * them in practice.
58
+ *
59
+ * **Not covered, deliberately**, for the same reason the text half draws
60
+ * its own line: a localised divider or attribution; Outlook's Web/desktop
61
+ * markup when it skips the `border-top` divider entirely (`id` values such
62
+ * as `divRplyFwdMsg` are not matched, since they are less stable across
63
+ * versions than the inline style); a marker nested inside a `<template>`
64
+ * (its content lives outside `.children` and is never walked); a second,
65
+ * unrelated quote block once the first marker has been found — only the
66
+ * first marker's *own* later siblings join it in `quoted` (as above), so a
67
+ * second block that is itself one of those siblings is swept in too, but
68
+ * one that instead sits at an outer level — a root-level sibling of a
69
+ * wrapper the first marker is nested inside, as Gmail's `gmail_quote` div
70
+ * often is — is left exactly where it was, inside `body`, not collapsed;
71
+ * and a quote marker a sender's own composer emits without following any
72
+ * of the three conventions above.
73
+ */
74
+ /** A `<div>` is Outlook's divider when its inline style sets a `border-top`
75
+ * that is not `none` — a regex over one attribute's value, the same grain
76
+ * `sanitise.ts` itself reads CSS at (`HOSTILE_VALUE`, `FETCHES`), not over
77
+ * the markup this module is meant to parse rather than pattern-match. */
78
+ const OUTLOOK_DIVIDER = /(?:^|;)\s*border-top\s*:\s*(?!none\b)\S/i;
79
+ function isOutlookDivider(element) {
80
+ return element.localName === 'div' && OUTLOOK_DIVIDER.test(element.getAttribute('style') ?? '');
81
+ }
82
+ /** Whether `element` opens a quoted block, by one of the three conventions
83
+ * this module covers. See the module doc comment for what each means and
84
+ * why a bare `<blockquote>` does not qualify. */
85
+ function isQuoteMarker(element) {
86
+ const type = (element.getAttribute('type') ?? '').toLowerCase();
87
+ if (element.localName === 'blockquote' && type === 'cite')
88
+ return true;
89
+ if (element.classList.contains('gmail_quote'))
90
+ return true;
91
+ return isOutlookDivider(element);
92
+ }
93
+ /**
94
+ * The first element in document order that opens a quoted block, or `null`.
95
+ *
96
+ * Iterative, not recursive, for the same reason `sanitise.ts`'s `sweep` is:
97
+ * a message is a stranger's choice of nesting depth, and the stack is not.
98
+ * A matched element is never descended into, so an inner `<blockquote
99
+ * type="cite">` nested inside an outer `gmail_quote` div never overrides
100
+ * the outer match — the outermost marker wins, since it is the one that
101
+ * actually bounds the quoted content.
102
+ */
103
+ function findMarker(root) {
104
+ const stack = [];
105
+ for (let i = root.children.length - 1; i >= 0; i--)
106
+ stack.push(root.children[i]);
107
+ while (stack.length > 0) {
108
+ const element = stack.pop();
109
+ if (isQuoteMarker(element))
110
+ return element;
111
+ for (let i = element.children.length - 1; i >= 0; i--) {
112
+ stack.push(element.children[i]);
113
+ }
114
+ }
115
+ return null;
116
+ }
117
+ /**
118
+ * Moves `marker` and every node after it among its own siblings — elements,
119
+ * text, comments alike, nothing skipped — into a detached wrapper, and
120
+ * returns that wrapper's serialised contents. The move itself is what
121
+ * prunes those nodes out of `root`, so the caller reads `root.innerHTML`
122
+ * afterwards for `body`.
123
+ */
124
+ function extractQuoted(marker, doc) {
125
+ const wrapper = doc.createElement('div');
126
+ let node = marker;
127
+ while (node) {
128
+ const next = node.nextSibling;
129
+ wrapper.append(node);
130
+ node = next;
131
+ }
132
+ return wrapper.innerHTML;
133
+ }
134
+ /**
135
+ * Where a received HTML body's own markup ends and its quoted history
136
+ * begins. See the module doc comment for the three marker shapes covered,
137
+ * what is deliberately not, and what the returned halves do and do not
138
+ * guarantee about reconstructing the original string.
139
+ *
140
+ * A nullish `html` is treated the same as an empty one rather than thrown
141
+ * at `.trim()`: the parameter type says `string`, but `Message.html` is
142
+ * `string | null`, and a caller that reaches this function directly
143
+ * instead of through `htmlQuoteBoundary` should not crash a mail client
144
+ * over one message it cannot collapse a quote in.
145
+ */
146
+ export function splitQuotedHtml(html) {
147
+ if (!html?.trim())
148
+ return { body: html ?? '', quoted: '' };
149
+ const doc = new DOMParser().parseFromString(html, 'text/html');
150
+ const root = doc.body ?? doc.createElement('body');
151
+ const marker = findMarker(root);
152
+ if (!marker)
153
+ return { body: html, quoted: '' };
154
+ const quoted = extractQuoted(marker, doc);
155
+ return { body: root.innerHTML, quoted };
156
+ }
157
+ /** `splitQuotedHtml` against a received message's own HTML body. A message
158
+ * with no HTML body (text-only) has nothing to split: the whole boundary
159
+ * is empty, not a guess — the same answer `quoteBoundary` (`../quoted.ts`)
160
+ * gives a text-only message with no text body, mirrored the other way. */
161
+ export function htmlQuoteBoundary(message) {
162
+ return splitQuotedHtml(message.html ?? '');
163
+ }
@@ -0,0 +1,48 @@
1
+ import { type MailClient } from './client.ts';
2
+ import type { MailboxNode } from './types.ts';
3
+ /**
4
+ * Snooze: take a thread out of the Inbox until a time, then put it back.
5
+ *
6
+ * **JMAP has no snooze, so this is two halves.** `snoozeThread` moves the
7
+ * thread into a top-level mailbox named Snoozed (made on first use) and
8
+ * stamps each message with a keyword holding the wake time.
9
+ * `wakeSnoozed` moves every thread whose time has come back to the Inbox,
10
+ * unread. Nothing in a mail server calls `wakeSnoozed`; the host runs it on
11
+ * a timer. That is the part of snooze that is server work, and a library
12
+ * cannot own a clock.
13
+ *
14
+ * **The wake time is a keyword, `$snoozed:<unix seconds>`.** A message has
15
+ * no free-form property to hold a date, and a keyword is stored, searchable
16
+ * and survives every client. RFC 8621 keywords may contain `:` and digits.
17
+ */
18
+ /** The name the Snoozed mailbox is found and made by. */
19
+ export declare const SNOOZED_MAILBOX = "Snoozed";
20
+ export type SnoozeOptions = {
21
+ /** The mailbox tree, when the caller already has it. Saves a `Mailbox/get`. */
22
+ mailboxes?: readonly MailboxNode[];
23
+ };
24
+ /**
25
+ * Snooze a thread until `until`: out of every mailbox, into Snoozed.
26
+ *
27
+ * Messages in Sent or Drafts stay where they are. They are my own copies,
28
+ * not mail waiting for me, and waking files into the Inbox: a sent reply
29
+ * moved into Snoozed would come back as if it had been received.
30
+ *
31
+ * Snoozing a thread that is already snoozed moves its wake time; the old
32
+ * one is removed rather than left beside it. A time in the past is allowed
33
+ * and simply wakes on the next `wakeSnoozed`, since what "now" is belongs
34
+ * to the host's clock, not this call's.
35
+ *
36
+ * Returns the ids of the messages that moved.
37
+ */
38
+ export declare function snoozeThread(client: MailClient, threadId: string, until: Date, options?: SnoozeOptions): Promise<readonly string[]>;
39
+ /**
40
+ * Wake every snoozed thread whose time is at or before `now`: back to the
41
+ * Inbox, unread, wake time removed.
42
+ *
43
+ * Meant for a timer the host runs, every minute or so. `now` is a
44
+ * parameter so the host's clock decides, and a test can pass its own.
45
+ * Returns the ids of the threads that woke; an account that has never
46
+ * snoozed anything returns none without making a mailbox.
47
+ */
48
+ export declare function wakeSnoozed(client: MailClient, now?: Date, options?: SnoozeOptions): Promise<readonly string[]>;
@@ -0,0 +1,176 @@
1
+ import { JAM_FETCH } from "./client.js";
2
+ import { MailError, guard } from "./errors.js";
3
+ import { findRole, mailboxes } from "./mailboxes.js";
4
+ /**
5
+ * Snooze: take a thread out of the Inbox until a time, then put it back.
6
+ *
7
+ * **JMAP has no snooze, so this is two halves.** `snoozeThread` moves the
8
+ * thread into a top-level mailbox named Snoozed (made on first use) and
9
+ * stamps each message with a keyword holding the wake time.
10
+ * `wakeSnoozed` moves every thread whose time has come back to the Inbox,
11
+ * unread. Nothing in a mail server calls `wakeSnoozed`; the host runs it on
12
+ * a timer. That is the part of snooze that is server work, and a library
13
+ * cannot own a clock.
14
+ *
15
+ * **The wake time is a keyword, `$snoozed:<unix seconds>`.** A message has
16
+ * no free-form property to hold a date, and a keyword is stored, searchable
17
+ * and survives every client. RFC 8621 keywords may contain `:` and digits.
18
+ */
19
+ /** The name the Snoozed mailbox is found and made by. */
20
+ export const SNOOZED_MAILBOX = 'Snoozed';
21
+ const WAKE = '$snoozed:';
22
+ /** RFC 6901 §3: `~` and `/` inside a pointer segment are escaped. A keyword
23
+ * read back from the server may hold either, so a patch key built from one
24
+ * must escape. */
25
+ function pointer(segment) {
26
+ return segment.replaceAll('~', '~0').replaceAll('/', '~1');
27
+ }
28
+ function wakeKeyword(until) {
29
+ return `${WAKE}${Math.floor(until.getTime() / 1000)}`;
30
+ }
31
+ /** The wake time a message carries, in milliseconds, or `null`. */
32
+ function wakeTime(keywords) {
33
+ for (const keyword of Object.keys(keywords ?? {})) {
34
+ if (!keyword.startsWith(WAKE))
35
+ continue;
36
+ const seconds = Number(keyword.slice(WAKE.length));
37
+ if (Number.isInteger(seconds))
38
+ return seconds * 1000;
39
+ }
40
+ return null;
41
+ }
42
+ function refused(result, operation) {
43
+ const notUpdated = result.notUpdated;
44
+ const first = notUpdated ? Object.values(notUpdated)[0] : undefined;
45
+ if (first) {
46
+ throw new MailError(first.description ?? `the server refused to ${operation}`, {
47
+ type: first.type ?? 'unknown',
48
+ operation,
49
+ });
50
+ }
51
+ }
52
+ function findSnoozed(tree) {
53
+ return tree.find((box) => box.name === SNOOZED_MAILBOX && box.parentId === null);
54
+ }
55
+ /**
56
+ * Snooze a thread until `until`: out of every mailbox, into Snoozed.
57
+ *
58
+ * Messages in Sent or Drafts stay where they are. They are my own copies,
59
+ * not mail waiting for me, and waking files into the Inbox: a sent reply
60
+ * moved into Snoozed would come back as if it had been received.
61
+ *
62
+ * Snoozing a thread that is already snoozed moves its wake time; the old
63
+ * one is removed rather than left beside it. A time in the past is allowed
64
+ * and simply wakes on the next `wakeSnoozed`, since what "now" is belongs
65
+ * to the host's clock, not this call's.
66
+ *
67
+ * Returns the ids of the messages that moved.
68
+ */
69
+ export async function snoozeThread(client, threadId, until, options = {}) {
70
+ if (Number.isNaN(until.getTime())) {
71
+ throw new MailError('snooze needs a valid date', {
72
+ type: 'invalidArguments',
73
+ operation: 'snooze',
74
+ });
75
+ }
76
+ const { jam, accountId } = await client.connect();
77
+ const tree = options.mailboxes ?? (await mailboxes(client));
78
+ return guard('snooze', async () => {
79
+ let snoozedId = findSnoozed(tree)?.id;
80
+ if (!snoozedId) {
81
+ const [made] = await jam.api.Mailbox.set({ accountId, create: { snoozed: { name: SNOOZED_MAILBOX, parentId: null } } }, JAM_FETCH);
82
+ snoozedId = made.created?.snoozed?.id;
83
+ if (!snoozedId) {
84
+ const failure = Object.values((made.notCreated ?? {}))[0];
85
+ throw new MailError(failure?.description ?? 'the server would not make a Snoozed mailbox', {
86
+ type: failure?.type ?? 'unknown',
87
+ operation: 'snooze',
88
+ });
89
+ }
90
+ }
91
+ const [thread] = await jam.api.Thread.get({ accountId, ids: [threadId] }, JAM_FETCH);
92
+ const ids = thread.list?.[0]?.emailIds ?? [];
93
+ if (ids.length === 0) {
94
+ throw new MailError(`no thread ${threadId} on this account`, {
95
+ type: 'notFound',
96
+ operation: 'snooze',
97
+ });
98
+ }
99
+ const [found] = await jam.api.Email.get({ accountId, ids, properties: ['keywords', 'mailboxIds'] }, JAM_FETCH);
100
+ const mine = new Set([findRole(tree, 'sent')?.id, findRole(tree, 'drafts')?.id]);
101
+ const moving = [];
102
+ const stale = new Set();
103
+ for (const email of found.list) {
104
+ if (Object.keys(email.mailboxIds ?? {}).some((box) => mine.has(box)))
105
+ continue;
106
+ moving.push(email.id);
107
+ for (const keyword of Object.keys(email.keywords ?? {})) {
108
+ if (keyword.startsWith(WAKE))
109
+ stale.add(keyword);
110
+ }
111
+ }
112
+ if (moving.length === 0)
113
+ return [];
114
+ const patch = { mailboxIds: { [snoozedId]: true } };
115
+ for (const keyword of stale)
116
+ patch[`keywords/${pointer(keyword)}`] = null;
117
+ patch[`keywords/${pointer(wakeKeyword(until))}`] = true;
118
+ const update = {};
119
+ for (const id of moving)
120
+ update[id] = patch;
121
+ const [result] = await jam.api.Email.set({ accountId, update: update }, JAM_FETCH);
122
+ refused(result, 'snooze');
123
+ return moving;
124
+ });
125
+ }
126
+ /**
127
+ * Wake every snoozed thread whose time is at or before `now`: back to the
128
+ * Inbox, unread, wake time removed.
129
+ *
130
+ * Meant for a timer the host runs, every minute or so. `now` is a
131
+ * parameter so the host's clock decides, and a test can pass its own.
132
+ * Returns the ids of the threads that woke; an account that has never
133
+ * snoozed anything returns none without making a mailbox.
134
+ */
135
+ export async function wakeSnoozed(client, now = new Date(), options = {}) {
136
+ const { jam, accountId } = await client.connect();
137
+ const tree = options.mailboxes ?? (await mailboxes(client));
138
+ const snoozed = findSnoozed(tree);
139
+ if (!snoozed)
140
+ return [];
141
+ const inbox = findRole(tree, 'inbox');
142
+ if (!inbox) {
143
+ throw new MailError('the account has no Inbox to wake mail into', {
144
+ type: 'notFound',
145
+ operation: 'wake',
146
+ });
147
+ }
148
+ return guard('wake', async () => {
149
+ const [query] = await jam.api.Email.query({ accountId, filter: { inMailbox: snoozed.id } }, JAM_FETCH);
150
+ if (query.ids.length === 0)
151
+ return [];
152
+ const [found] = await jam.api.Email.get({ accountId, ids: query.ids, properties: ['threadId', 'keywords'] }, JAM_FETCH);
153
+ const update = {};
154
+ const woke = new Set();
155
+ for (const email of found.list) {
156
+ const at = wakeTime(email.keywords);
157
+ if (at === null || at > now.getTime())
158
+ continue;
159
+ const patch = {
160
+ mailboxIds: { [inbox.id]: true },
161
+ 'keywords/$seen': null,
162
+ };
163
+ for (const keyword of Object.keys(email.keywords ?? {})) {
164
+ if (keyword.startsWith(WAKE))
165
+ patch[`keywords/${pointer(keyword)}`] = null;
166
+ }
167
+ update[email.id] = patch;
168
+ woke.add(email.threadId);
169
+ }
170
+ if (woke.size === 0)
171
+ return [];
172
+ const [result] = await jam.api.Email.set({ accountId, update: update }, JAM_FETCH);
173
+ refused(result, 'wake');
174
+ return [...woke];
175
+ });
176
+ }
@@ -29,12 +29,38 @@ export type SendOptions = {
29
29
  * byte-identical to a plain send. Travels as RFC 4865's `holdFor` SMTP
30
30
  * parameter, which the server validates as 1..=999999999. */
31
31
  delay?: number;
32
+ /** A draft `saveDraft()` stored. It is replaced by the message sent, so
33
+ * Drafts is left without it. What goes out is always the `Draft` passed
34
+ * to `send()`, never what was last saved. */
35
+ draftId?: string;
36
+ };
37
+ export type SaveDraftOptions = {
38
+ /** The identity to fill `from` with, when the caller already has it. */
39
+ identity?: MailIdentity;
40
+ /** The mailbox tree, when the caller already has it. */
41
+ mailboxes?: readonly MailboxNode[];
32
42
  };
33
43
  export type CancelOptions = {
34
44
  /** The mailbox tree, when the caller already has it. Saves a
35
45
  * `Mailbox/get`. */
36
46
  mailboxes?: readonly MailboxNode[];
37
47
  };
48
+ /**
49
+ * Store a draft in Drafts, so it survives the compose sheet closing.
50
+ *
51
+ * Called with the id it returned last time, it replaces that draft rather
52
+ * than adding a second. RFC 8621 messages are immutable, so "replace" is a
53
+ * create followed by a destroy; the id changes every save,
54
+ * which is why the new one is returned. The thread does not change, because
55
+ * the draft keeps its `inReplyTo` and `references`.
56
+ *
57
+ * `from` is filled from the identity when the draft has none, as `send()`
58
+ * does, so a saved draft reads the same as the message it becomes.
59
+ */
60
+ export declare function saveDraft(client: MailClient, draft: Draft, draftId?: string, options?: SaveDraftOptions): Promise<{
61
+ id: string;
62
+ threadId: string;
63
+ }>;
38
64
  /**
39
65
  * Send a draft.
40
66
  *