@chronicle.app/email-core 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @chronicle.app/email-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+What Chronicle's mail sources share: reading an mbox, parsing an email, identifying it, and the nodes it becomes. The [email](../../plugins/email/README.md) plugin reads any mbox with it; the [gmail](../../plugins/gmail/README.md) plugin reads Gmail's API and Takeouts with it.
+
+- `readMbox(path)` yields each message in an mbox, raw, with the date on its `From ` line, reading the file as a stream: a Takeout of a whole mailbox runs to gigabytes. A message with no Date header takes that date. `countMbox(path)` counts them the same way.
+- `parseMessage(raw)` parses an RFC 5322 message with [postal-mime](https://github.com/postalsys/postal-mime): encoded words, quoted-printable and base64 bodies, and multipart alternatives are decoded. The result, a `MailMessage`, is plain data, so it can be a raw record. It keeps only the headers a source reads (the envelope, threading, mailing-list headers, and Gmail's `X-GM-*`), not the routing and signing headers that make up most of a header block.
+- `messageBody(parts, { bulk })` is what the sender wrote, as plain text or Markdown, and is the `MailMessage`'s `text`:
+  - the text part when there's a real one, else the HTML part converted to Markdown (links, lists, and emphasis kept; hidden preheaders and images dropped), and any markup in a text part converted too;
+  - without quoted history and signatures, by [email-reply-parser](https://github.com/crisp-oss/email-reply-parser): reply headers in many languages, Outlook's quoted blocks, `-- ` and "Sent from my phone" signatures. A reply links to the message it answers, so the quote would only store it again. A message that is only a quote, like a forward with no note, keeps it;
+  - for bulk mail (one with `List-Unsubscribe`, `List-Id`, or `Precedence: bulk`), without its footer: from the first unsubscribe or "you're receiving this" line in its second half;
+  - with tracking parameters (`utm_*`, `fbclid`, …) taken off links and the padding characters newsletters fill their inbox preview with removed, by `tidyText` from `@chronicle.app/etl`. In bulk mail, click-tracking redirects (URLs over 200 characters) lose their URL but keep their words; a person's mail keeps long links, like a meeting's join link.
+- `identityOf(message)` is its Message-ID, or else its sender, date, and subject; null when it has neither, and a source skips it.
+- `messageAction(message, options)` is the sending of it: a `MessageAction` by the sender on a `Message`, with its recipients and the message it replies to, and a source's thread and labels when it has them. The sender is written in full as the action's `agent`, and as the message's `author` by key alone. A display name the mail gives an address, other than the address itself, is its `alternateName`: what that message called it, not its own name. With `account`, the message is `inAccount` it.
+- `emailAccount(address)` is the account at an address, an Agent keyed by it in the `email` namespace: what a message is `inAccount`, whatever service holds it.
+
+Identifiers the email protocol defines are keyed in its namespace (`source: 'email'`): a message by its Message-ID without the angle brackets around it (as JMAP and `mid:` URIs write it), so the same email read by any mail source is one node. A person is their lowercased address in the `email` namespace (`source: 'email'`), the identity other plugins already link an address to, so every mail source, a calendar, and those links meet on one node.
+
+## Tests
+
+The tests run the parser and builder over synthetic messages and a synthetic mbox in a temporary directory.

package/dist/body.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What a person wrote in an email, as plain text or Markdown: never the HTML
+ * it was sent as, the earlier messages it quotes, or its signature.
+ *
+ * - The text part, when there's a real one; the HTML part as Markdown when
+ *   there isn't, or when the text part is only a stub pointing at it.
+ * - Hidden preheader text and images are dropped from HTML: in mail they're
+ *   tracking pixels, spacers, and logos, not what anyone wrote.
+ * - Quoted history and the signature go, by
+ *   [email-reply-parser](https://github.com/crisp-oss/email-reply-parser):
+ *   reply headers in many languages, Outlook's quoted blocks, `-- ` and
+ *   "Sent from my phone" signatures. A reply links to the message it
+ *   answers, so the quote would only store that message again.
+ * - Bulk mail (a newsletter, a notification) loses its footer: the
+ *   unsubscribe and "you're receiving this" lines at its end.
+ * - Then `tidyText`: tracking parameters come off links, and padding
+ *   characters go. In bulk mail, click-tracking redirects lose their URL
+ *   but keep their words.
+ */
+export declare function messageBody(parts: {
+    text?: string;
+    html?: string;
+}, { bulk }?: {
+    bulk?: boolean;
+}): string;
+//# sourceMappingURL=body.d.ts.map

package/dist/body.js

@@ -0,0 +1,71 @@
+import { htmlToMarkdown, looksLikeHtml, tidyText, withoutInvisible } from '@chronicle.app/etl';
+import EmailReplyParser from 'email-reply-parser';
+/**
+ * What a person wrote in an email, as plain text or Markdown: never the HTML
+ * it was sent as, the earlier messages it quotes, or its signature.
+ *
+ * - The text part, when there's a real one; the HTML part as Markdown when
+ *   there isn't, or when the text part is only a stub pointing at it.
+ * - Hidden preheader text and images are dropped from HTML: in mail they're
+ *   tracking pixels, spacers, and logos, not what anyone wrote.
+ * - Quoted history and the signature go, by
+ *   [email-reply-parser](https://github.com/crisp-oss/email-reply-parser):
+ *   reply headers in many languages, Outlook's quoted blocks, `-- ` and
+ *   "Sent from my phone" signatures. A reply links to the message it
+ *   answers, so the quote would only store that message again.
+ * - Bulk mail (a newsletter, a notification) loses its footer: the
+ *   unsubscribe and "you're receiving this" lines at its end.
+ * - Then `tidyText`: tracking parameters come off links, and padding
+ *   characters go. In bulk mail, click-tracking redirects lose their URL
+ *   but keep their words.
+ */
+export function messageBody(parts, { bulk = false } = {}) {
+    // Some senders put markup in the text part too.
+    const raw = withoutInvisible(parts.text ?? '').trim();
+    const text = looksLikeHtml(raw) ? emailHtmlToMarkdown(raw) : raw;
+    const fromHtml = parts.html ? emailHtmlToMarkdown(parts.html) : '';
+    const body = text && !isStub(text, fromHtml) ? text : fromHtml || text;
+    const written = withoutReplyHistory(body);
+    return bulk ? tidyText(withoutFooter(written), { dropLongUrls: true }) : tidyText(written);
+}
+/** A text part that only points at the HTML one: short, and saying so, or a sliver of it. */
+function isStub(text, fromHtml) {
+    if (!fromHtml)
+        return false;
+    const pointsElsewhere = /view (this|it|the) (e-?mail|message|newsletter)? ?(online|in (a|your) (web )?browser)|html (version|email)|does not support html|enable html/i;
+    return ((text.length < 400 && pointsElsewhere.test(text)) ||
+        (text.length < 80 && fromHtml.length > text.length * 4));
+}
+/** Elements hidden from the reader: an email's preheader, and a client's own notes. */
+const HIDDEN = /<(div|span|p|td|table)\b[^>]*\bstyle\s*=\s*["'][^"']*(display\s*:\s*none|visibility\s*:\s*hidden|max-height\s*:\s*0|mso-hide\s*:\s*all)[^"']*["'][^>]*>[\s\S]*?<\/\1>/gi;
+function emailHtmlToMarkdown(html) {
+    const markdown = withoutInvisible(htmlToMarkdown(html.replaceAll(HIDDEN, '')) ?? '');
+    // An image in an email is a logo, a spacer, or a tracking pixel.
+    return markdown.replaceAll(/!\[[^\]]*\]\([^)]*\)/g, '').trim();
+}
+/**
+ * The text without quoted history or signature. A message that is nothing
+ * but a quote, like a forward with no note, keeps what it quotes.
+ */
+function withoutReplyHistory(body) {
+    const visible = new EmailReplyParser().read(body).getVisibleText().trim();
+    return visible || body;
+}
+/** A line that starts a bulk mail's footer. */
+const FOOTER = /unsubscribe|you('re| are) receiving this|you received this (e-?mail|message)|(manage|update) (your )?(e-?mail |subscription |notification )?(preferences|settings)|no longer (wish|want) to receive|this (e-?mail|message) was sent to|sent to you because|why did i get this/i;
+/**
+ * A bulk mail without its footer: from the first footer line in its second
+ * half on. Only that half is searched, so a newsletter that mentions
+ * unsubscribing near its top keeps it; a newsletter's footer, with its
+ * addresses, links, and legal lines, can run long.
+ */
+function withoutFooter(body) {
+    const lines = body.split('\n');
+    const from = Math.max(1, Math.floor(lines.length / 2));
+    for (let i = from; i < lines.length; i++) {
+        // A footer line is short; a sentence that mentions unsubscribing isn't one.
+        if (lines[i].length <= 160 && FOOTER.test(lines[i]))
+            return lines.slice(0, i).join('\n');
+    }
+    return body;
+}

package/dist/build.d.ts

@@ -0,0 +1,50 @@
+import type { Agent, MessageAction, Thread } from '@chronicle.app/schema';
+import type { MailMessage } from './parse.js';
+/**
+ * A message's own identity: its Message-ID; without one, its sender, sent
+ * time, and subject. Null when it has neither a Message-ID nor a sender and a
+ * date: nothing real identifies it, and a made-up id would mint a new message
+ * each run, so a source skips it.
+ */
+export declare function identityOf(mail: MailMessage): string | null;
+export interface MessageNodeOptions {
+    /**
+     * The mailbox owner's addresses: the sender or a recipient at one of them
+     * is the owner (`@me`).
+     */
+    me?: string[];
+    /** The source says the owner sent it (Gmail's Sent label), whatever the From says. */
+    sentByMe?: boolean;
+    /** When the message arrived, for one without a Date header. */
+    receivedAt?: Date;
+    /** The conversation the source puts it in. */
+    thread?: Thread;
+    /** The source's labels or folders for it. */
+    tags?: string[];
+    /**
+     * Other identities of the person at an address (an address book's other
+     * addresses and phone numbers for them), linked by `sameAs`.
+     */
+    identitiesOf?: (address: string) => Agent[];
+    /**
+     * The owner's other identities, such as the account the mailbox is,
+     * linked by `sameAs` from every agent that's the owner.
+     */
+    meIdentities?: Agent[];
+    /** The account the source read the message from: the message is `inAccount` it. */
+    account?: Agent;
+}
+/**
+ * The sending of a message: a `MessageAction` by its sender, whose object is
+ * the `Message`, with its recipients, the message it replies to, and its
+ * thread and labels when the source has them. The sending happened once, so
+ * the action is keyed by the Message-ID wherever the message is read, as the
+ * message is.
+ */
+export declare function messageAction(mail: MailMessage, options?: MessageNodeOptions): MessageAction;
+/**
+ * An email account by its address, keyed as a person is: the account a
+ * message is `inAccount`, whatever service holds it.
+ */
+export declare function emailAccount(address: string): Agent;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.js

@@ -0,0 +1,153 @@
+/**
+ * A message is named by its Message-ID in the `email` namespace: the
+ * protocol's own identity, so the same email from Gmail, a Takeout, or any
+ * mbox is one node, whichever plugin read it.
+ */
+const MESSAGE_KEY = ['@type', 'source', 'sourceId'];
+/** Without a Message-ID: who sent it, when, and under what subject. */
+const KEYLESS_MESSAGE_KEY = ['@type', 'source', 'action.timestamp', 'action.agent.handle', 'name'];
+const KEYLESS_ACTION_KEY = ['@type', 'source', 'timestamp', 'agent.handle', 'object.name'];
+/** Identifiers defined by the email protocol (RFC 5322) live in its namespace. */
+const EMAIL = 'email';
+/**
+ * A person is their email address, in the `email` namespace: the identity
+ * other plugins link a person's address to (iMessage, LinkedIn, Timing, …),
+ * so every mail source and every link meets on one node.
+ */
+const ADDRESS_KEY = ['@type', 'source', 'handle'];
+/**
+ * Joins the parts of a composite identity. A control character that header
+ * text cannot carry, so no From/Date/Subject combination can collide with
+ * another by concatenation.
+ */
+const COMPOSITE_DELIMITER = '\u001F';
+/**
+ * A Message-ID as an identifier: without the angle brackets RFC 5322 writes
+ * around it, as JMAP and `mid:` URIs give it, so every source keys it alike.
+ */
+function msgId(header) {
+    return header.replace(/^<(.*)>$/, '$1');
+}
+/**
+ * A message's own identity: its Message-ID; without one, its sender, sent
+ * time, and subject. Null when it has neither a Message-ID nor a sender and a
+ * date: nothing real identifies it, and a made-up id would mint a new message
+ * each run, so a source skips it.
+ */
+export function identityOf(mail) {
+    if (mail.messageId)
+        return mail.messageId;
+    if (!mail.from || !mail.date)
+        return null;
+    return [mail.from.address.toLowerCase(), mail.date, mail.subject].join(COMPOSITE_DELIMITER);
+}
+/**
+ * The sending of a message: a `MessageAction` by its sender, whose object is
+ * the `Message`, with its recipients, the message it replies to, and its
+ * thread and labels when the source has them. The sending happened once, so
+ * the action is keyed by the Message-ID wherever the message is read, as the
+ * message is.
+ */
+export function messageAction(mail, options = {}) {
+    const me = new Set((options.me ?? []).map(address => address.toLowerCase()));
+    const isMe = (address) => me.has(address.toLowerCase());
+    if (!mail.from) {
+        throw new Error(`Email ${mail.messageId ?? '(no Message-ID)'} has no sender`);
+    }
+    const sentAt = mail.date ?? options.receivedAt?.toISOString();
+    if (!sentAt) {
+        throw new Error(`Email ${mail.messageId ?? '(no Message-ID)'} has no date`);
+    }
+    const identities = options.identitiesOf ?? (() => []);
+    const person = (address, owner) => agent(address, owner, [
+        ...(owner ? (options.meIdentities ?? []) : []),
+        ...identities(address.address),
+    ]);
+    const sender = person(mail.from, options.sentByMe || isMe(mail.from.address));
+    const recipients = dedupe([...mail.to, ...mail.cc, ...mail.bcc]).map(address => person(address, isMe(address.address)));
+    const messageId = mail.messageId && msgId(mail.messageId);
+    const message = {
+        '@type': 'Message',
+        ...(messageId
+            ? { '@key': MESSAGE_KEY, source: EMAIL, sourceId: messageId }
+            : { '@key': KEYLESS_MESSAGE_KEY, source: EMAIL }),
+        ...(options.account && { inAccount: [options.account] }),
+        name: mail.subject,
+        ...(mail.text && { body: mail.text }),
+        // The sender in full is the action's agent; here, the same node by its key.
+        author: [reference(sender)],
+        ...(recipients.length > 0 && { recipient: recipients }),
+        ...(mail.inReplyTo && {
+            inReplyTo: [
+                { '@type': 'Message', '@key': MESSAGE_KEY, source: EMAIL, sourceId: msgId(mail.inReplyTo) },
+            ],
+        }),
+        ...(options.thread && { isPartOf: [options.thread] }),
+        ...(options.tags?.length && { tags: options.tags }),
+    };
+    return {
+        '@type': 'MessageAction',
+        ...(messageId
+            ? { '@key': MESSAGE_KEY, source: EMAIL, sourceId: messageId }
+            : { '@key': KEYLESS_ACTION_KEY, source: EMAIL }),
+        timestamp: new Date(sentAt),
+        agent: sender,
+        object: message,
+    };
+}
+/**
+ * An email account by its address, keyed as a person is: the account a
+ * message is `inAccount`, whatever service holds it.
+ */
+export function emailAccount(address) {
+    return {
+        '@type': 'Agent',
+        '@key': ADDRESS_KEY,
+        source: EMAIL,
+        handle: address.toLowerCase(),
+    };
+}
+/** A node written in full elsewhere in the record, by its key alone. */
+function reference(agent) {
+    return {
+        '@type': agent['@type'],
+        '@key': agent['@key'],
+        source: agent.source,
+        handle: agent.handle,
+    };
+}
+/** A person by their address, lowercased so one person is one node. */
+function agent(address, me, identities = []) {
+    const handle = address.address.toLowerCase();
+    const name = displayName(address.name, handle);
+    const sameAs = [...(me ? ['@me'] : []), ...identities];
+    return {
+        '@type': 'Agent',
+        '@key': ADDRESS_KEY,
+        source: EMAIL,
+        handle,
+        ...(name && { alternateName: [name] }),
+        ...(sameAs.length > 0 && { sameAs }),
+    };
+}
+/**
+ * The display name the mail gives an address, unless it's only the address
+ * again. It's what one message called the address, which the sender or their
+ * address book chose, so it's another name the address was shown with, not
+ * the address's own name.
+ */
+function displayName(name, handle) {
+    const trimmed = name?.trim();
+    return trimmed && trimmed.toLowerCase() !== handle ? trimmed : undefined;
+}
+/** Each address once: a person on both To and Cc is one recipient. */
+function dedupe(addresses) {
+    const seen = new Set();
+    return addresses.filter(({ address }) => {
+        const handle = address.toLowerCase();
+        if (seen.has(handle))
+            return false;
+        seen.add(handle);
+        return true;
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { parseMessage, type MailAddress, type MailMessage } from './parse.js';
+export { readMbox, countMbox, type MboxMessage } from './mbox.js';
+export { emailAccount, identityOf, messageAction, type MessageNodeOptions } from './build.js';
+export { messageBody } from './body.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,4 @@
+export { parseMessage } from './parse.js';
+export { readMbox, countMbox } from './mbox.js';
+export { emailAccount, identityOf, messageAction } from './build.js';
+export { messageBody } from './body.js';

package/dist/mbox.d.ts

@@ -0,0 +1,19 @@
+/** A message in an mbox: its raw bytes, and when its `From ` line says it arrived. */
+export interface MboxMessage {
+    raw: Buffer;
+    /** The envelope date as an ISO instant; null when the line has none. */
+    envelopeDate: string | null;
+}
+/**
+ * The messages in an mbox file, raw, one at a time: a Takeout of a whole
+ * mailbox runs to gigabytes, so it's read as a stream, never whole.
+ *
+ * A message starts at a `From ` line at the top of the file or after a blank
+ * line. A body line that began with `From ` was written as `>From `
+ * (mboxrd), and gets its `>` back. Lines are read as latin1, which keeps
+ * every byte as it was, so the parser sees the message's own bytes.
+ */
+export declare function readMbox(path: string): AsyncGenerator<MboxMessage>;
+/** How many messages an mbox file holds, by its `From ` lines, read as a stream. */
+export declare function countMbox(path: string): Promise<number>;
+//# sourceMappingURL=mbox.d.ts.map

package/dist/mbox.js

@@ -0,0 +1,59 @@
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+/**
+ * The messages in an mbox file, raw, one at a time: a Takeout of a whole
+ * mailbox runs to gigabytes, so it's read as a stream, never whole.
+ *
+ * A message starts at a `From ` line at the top of the file or after a blank
+ * line. A body line that began with `From ` was written as `>From `
+ * (mboxrd), and gets its `>` back. Lines are read as latin1, which keeps
+ * every byte as it was, so the parser sees the message's own bytes.
+ */
+export async function* readMbox(path) {
+    const lines = createInterface({
+        input: createReadStream(path, { encoding: 'latin1' }),
+        crlfDelay: Number.POSITIVE_INFINITY,
+    });
+    let message;
+    let envelopeDate = null;
+    let blank = true;
+    for await (const line of lines) {
+        if (blank && line.startsWith('From ')) {
+            if (message)
+                yield { raw: Buffer.from(message.join('\n'), 'latin1'), envelopeDate };
+            message = [];
+            envelopeDate = envelopeDateOf(line);
+        }
+        else if (message) {
+            message.push(/^>+From /.test(line) ? line.slice(1) : line);
+        }
+        blank = line === '';
+    }
+    if (message)
+        yield { raw: Buffer.from(message.join('\n'), 'latin1'), envelopeDate };
+}
+/**
+ * The date on a `From sender date` line: `Mon Mar 03 00:00:00 +0000 2025`
+ * (Takeout) or `Mon Jan  6 10:00:00 2025` (asctime, read as UTC).
+ */
+function envelopeDateOf(line) {
+    const date = line.split(/\s+/).slice(2).join(' ');
+    const zoned = /[+-]\d{4}|UTC|GMT/.test(date) ? date : `${date} UTC`;
+    const at = Date.parse(zoned);
+    return Number.isNaN(at) ? null : new Date(at).toISOString();
+}
+/** How many messages an mbox file holds, by its `From ` lines, read as a stream. */
+export async function countMbox(path) {
+    let count = 0;
+    let blank = true;
+    const lines = createInterface({
+        input: createReadStream(path, { encoding: 'latin1' }),
+        crlfDelay: Number.POSITIVE_INFINITY,
+    });
+    for await (const line of lines) {
+        if (blank && line.startsWith('From '))
+            count++;
+        blank = line === '';
+    }
+    return count;
+}

package/dist/parse.d.ts

@@ -0,0 +1,46 @@
+/** A person on a message: their address, and the name they gave, if any. */
+export interface MailAddress {
+    address: string;
+    name?: string;
+}
+/**
+ * One email, as a mail source reads it: its envelope, its text, and the names
+ * of its attachments. Plain data, so it can be a raw record.
+ */
+export interface MailMessage {
+    /** The Message-ID header, angle brackets and all; null when there is none. */
+    messageId: string | null;
+    /** The Date header as an ISO instant; null when there is none or it doesn't parse. */
+    date: string | null;
+    subject: string;
+    from: MailAddress | null;
+    to: MailAddress[];
+    cc: MailAddress[];
+    bcc: MailAddress[];
+    /** The Message-ID this replies to (In-Reply-To). */
+    inReplyTo: string | null;
+    /** The conversation's earlier Message-IDs, oldest first (References). */
+    references: string[];
+    /**
+     * What the sender wrote, as plain text or Markdown: no HTML, quoted
+     * history, or signature. See `messageBody`.
+     */
+    text: string;
+    attachments: {
+        filename: string | null;
+        mimeType: string;
+    }[];
+    /**
+     * The headers a source reads, by lowercase name: the envelope, threading,
+     * mailing list, and Gmail's own. Routing and signing headers (`Received`,
+     * `DKIM-Signature`, …) are left out: they're most of a header block, and
+     * nothing reads them.
+     */
+    headers: Record<string, string>;
+}
+/**
+ * Parse an RFC 5322 message, MIME and all: encoded words, quoted-printable
+ * and base64 bodies, and multipart alternatives are decoded.
+ */
+export declare function parseMessage(raw: Uint8Array | string): Promise<MailMessage>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.js

@@ -0,0 +1,75 @@
+import PostalMime, { decodeWords } from 'postal-mime';
+import { messageBody } from './body.js';
+/**
+ * Parse an RFC 5322 message, MIME and all: encoded words, quoted-printable
+ * and base64 bodies, and multipart alternatives are decoded.
+ */
+export async function parseMessage(raw) {
+    const email = await PostalMime.parse(raw, { attachmentEncoding: 'base64' });
+    const date = email.date && !Number.isNaN(Date.parse(email.date)) ? email.date : null;
+    return {
+        messageId: email.messageId?.trim() || null,
+        date: date && new Date(date).toISOString(),
+        subject: email.subject ?? '',
+        from: mailboxes(email.from ? [email.from] : [])[0] ?? null,
+        to: mailboxes(email.to),
+        cc: mailboxes(email.cc),
+        bcc: mailboxes(email.bcc),
+        // The Message-ID in it: some clients write words around it.
+        inReplyTo: email.inReplyTo?.match(/<[^>]+>/)?.[0] ?? (email.inReplyTo?.trim() || null),
+        references: email.references?.match(/<[^>]+>/g) ?? [],
+        text: messageBody(email, { bulk: isBulk(email.headers) }),
+        attachments: email.attachments
+            .filter(attachment => attachment.disposition === 'attachment' || attachment.filename)
+            .map(({ filename, mimeType }) => ({ filename, mimeType })),
+        headers: keptHeaders(email.headers),
+    };
+}
+/**
+ * The headers kept, decoded (a Takeout writes a label like `Café` as an
+ * encoded word). Where one repeats, the first is kept: it's the one added
+ * last, on arrival in this mailbox, so a forwarded message's `Delivered-To`
+ * is this mailbox's address, not the one it was forwarded from.
+ */
+function keptHeaders(headers) {
+    const kept = {};
+    for (const { key, value } of headers) {
+        if (Object.hasOwn(kept, key))
+            continue;
+        if (KEPT_HEADERS.has(key) || key.startsWith('x-gm'))
+            kept[key] = decodeWords(value);
+    }
+    return kept;
+}
+const KEPT_HEADERS = new Set([
+    'from',
+    'to',
+    'cc',
+    'bcc',
+    'reply-to',
+    'delivered-to',
+    'subject',
+    'date',
+    'message-id',
+    'in-reply-to',
+    'references',
+    'list-id',
+    'list-unsubscribe',
+    'precedence',
+]);
+/** Mail sent to a list: a newsletter or a notification, by its list headers. */
+function isBulk(headers) {
+    return headers.some(({ key, value }) => key === 'list-unsubscribe' ||
+        key === 'list-id' ||
+        (key === 'precedence' && /bulk|list/i.test(value)));
+}
+/** Addresses, with groups opened up, and a name only where one was given. */
+function mailboxes(addresses) {
+    return (addresses ?? [])
+        .flatMap(address => address.group ?? [address])
+        .filter(mailbox => mailbox.address)
+        .map(mailbox => ({
+        address: mailbox.address,
+        ...(mailbox.name && { name: mailbox.name }),
+    }));
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@chronicle.app/email-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [
+    "chronicle",
+    "email",
+    "mbox"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Email parsing, mbox reading, and message nodes shared by Chronicle mail sources",
+  "devDependencies": {
+    "@chronicle.app/etl": "0.4.0",
+    "@chronicle.app/schema": "0.4.0",
+    "@chronicle.app/tsconfig": "0.4.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "core/email"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "email-reply-parser": "^2.3.9",
+    "postal-mime": "^4.0.2"
+  },
+  "peerDependencies": {
+    "@chronicle.app/etl": ">=0.1.0 <1.0.0",
+    "@chronicle.app/schema": ">=0.1.0 <1.0.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}