domma-cms 0.54.2 → 0.66.0

package/plugins/_lib/mail/priority.js

@@ -0,0 +1,138 @@
+/**
+ * How urgent a sender said a message was.
+ *
+ * There is no one header for this. Three are in circulation, none is in the
+ * IMAP envelope, and senders disagree about them - so this reads all three,
+ * ranks them, and gives one answer.
+ *
+ *   `X-Priority: 1 (Highest)` … `5 (Lowest)`, 3 being normal. The oldest and
+ *   the most widely set. The parenthetical is decoration; the digit is the
+ *   header.
+ *   `Importance: high | normal | low`. RFC 2156, and what Outlook and
+ *   Thunderbird write alongside X-Priority.
+ *   `X-MSMail-Priority: High | Normal | Low`. Outlook's, written with the
+ *   other two and worth reading only when neither is present.
+ *
+ * And one that is not a header at all: mailparser RENAMES `X-Priority` to
+ * `priority` with a word value, so a parsed message has no `x-priority` key.
+ * Both spellings are read, because the list (header fetch) and the reader
+ * (parsed) must not disagree about the same message.
+ *
+ * Pure, so the disagreements can be pinned down without a mail server.
+ *
+ * @module _lib/mail/priority
+ */
+
+/** The three answers. Anything a sender writes reduces to one of these. */
+export const PRIORITIES = ['high', 'normal', 'low'];
+
+/** What a composer sets, and what each level means on the wire. */
+const OUTGOING = {
+    high: {'X-Priority': '1 (Highest)', 'Importance': 'High', 'X-MSMail-Priority': 'High'},
+    low: {'X-Priority': '5 (Lowest)', 'Importance': 'Low', 'X-MSMail-Priority': 'Low'}
+};
+
+/**
+ * Read one header value, whatever shape it arrived in.
+ *
+ * imapflow hands back a Map for a header fetch and mailparser an object, and
+ * a repeated header can be an array in either.
+ *
+ * @param   {object|Map|null} headers
+ * @param   {string} name
+ * @returns {string}
+ */
+function headerValue(headers, name) {
+    if (!headers) return '';
+    const raw = typeof headers.get === 'function'
+        ? headers.get(name)
+        : (headers[name] ?? headers[name.toLowerCase()]);
+    // A repeated header is a sender's problem, not ours: take the first and
+    // move on rather than trying to reconcile two answers.
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return String(value ?? '').trim();
+}
+
+/**
+ * Turn `X-Priority` into a level.
+ *
+ * @param   {string} value
+ * @returns {string|null}
+ */
+function fromXPriority(value) {
+    // The digit is the header; `1 (Highest)` and `1` mean the same thing, and
+    // some senders write only the word, which the digit test then ignores.
+    const digit = value.match(/\d/)?.[0];
+    if (!digit) return null;
+    const n = Number(digit);
+    if (n <= 2) return 'high';
+    if (n >= 4) return 'low';
+    return 'normal';
+}
+
+/**
+ * Turn a word-valued priority header into a level.
+ *
+ * @param   {string} value
+ * @returns {string|null}
+ */
+function fromWord(value) {
+    const word = value.toLowerCase();
+    if (word.startsWith('high') || word.startsWith('urgent')) return 'high';
+    if (word.startsWith('low') || word.startsWith('non-urgent')) return 'low';
+    if (word.startsWith('normal')) return 'normal';
+    return null;
+}
+
+/**
+ * What priority a message claims.
+ *
+ * `X-Priority` wins where it is present because it is the one nearly every
+ * sender sets; the others are read in the order they are worth trusting. A
+ * message that says nothing is normal - which is not the same as a message
+ * that says "normal", but nothing downstream needs to tell those apart.
+ *
+ * @param   {object|Map|null} headers
+ * @returns {'high' | 'normal' | 'low'}
+ */
+export function readPriority(headers) {
+    // `priority` first, and it is not a typo: mailparser RENAMES `X-Priority`
+    // to `priority` in its headers Map and gives it a word value, so a message
+    // parsed rather than header-fetched has no `x-priority` key at all. The
+    // raw name is still checked, because the IMAP header fetch path does have
+    // it - both paths have to produce the same answer or a message reads as
+    // urgent in the list and ordinary once opened.
+    const own = headerValue(headers, 'priority');
+    return fromWord(own)
+        ?? fromXPriority(own)
+        ?? fromXPriority(headerValue(headers, 'x-priority'))
+        ?? fromWord(headerValue(headers, 'importance'))
+        ?? fromWord(headerValue(headers, 'x-msmail-priority'))
+        ?? 'normal';
+}
+
+/**
+ * The headers to send for a chosen level.
+ *
+ * All three, because a recipient's client will read whichever one it knows and
+ * setting one of them is how a message looks urgent in Outlook and ordinary
+ * everywhere else. Normal sends nothing at all: the absence of the header IS
+ * normal, and saying so explicitly only adds three lines every client ignores.
+ *
+ * @param   {string} priority
+ * @returns {Object.<string, string>}
+ */
+export function priorityHeaders(priority) {
+    return OUTGOING[priority] ?? {};
+}
+
+/**
+ * Coerce anything into a level we are willing to send.
+ *
+ * @param   {unknown} value
+ * @returns {'high' | 'normal' | 'low'}
+ */
+export function normalisePriority(value) {
+    const word = String(value ?? '').toLowerCase();
+    return PRIORITIES.includes(word) ? word : 'normal';
+}