@chronicle.app/email 0.3.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

@@ -0,0 +1,79 @@
+# @chronicle.app/email
+
+Chronicle plugin for email
+
+## Installation
+
+```bash
+npm install @chronicle.app/email
+```
+
+## Usage
+
+### Basic extraction
+
+```bash
+chronicle extract email --input /path/to/emails.mbox
+```
+
+### With date filtering
+
+```bash
+chronicle extract email \
+  --input /path/to/emails.mbox \
+  --since 2024-01-01 \
+  --until 2024-12-31 \
+  --limit 1000
+```
+
+## Configuration
+
+The extractor supports the following options:
+
+- `--input` (required): Path to the mbox file
+- `--since`: Extract records from this date onwards
+- `--until`: Extract records up to this date
+- `--limit`: Maximum number of records to extract
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build
+
+# Run the tests
+npm test
+```
+
+## File Format
+
+This plugin processes email data in the mbox format, which is a standard format for storing email messages in a single file. Each message starts with a "From " line and contains standard email headers followed by the message body.
+
+The extractor parses the following email components:
+
+- From, To, CC, BCC addresses
+- Subject line
+- Date sent
+- Message ID
+- Full message body
+- All email headers
+
+## Schema
+
+- Each email is a `MessageAction` by the sender whose object is a `Message`.
+  The message's `name` is the subject, its `description` is the body, and its
+  `recipient`s are the To, CC and BCC addresses.
+- Each address is an `Agent` whose `handle` is the email address and whose
+  `name` is the display name, or the address when there is none.
+
+The source is `email`. A message with a Message-ID uses it as its `sourceId`;
+one without is identified by its sender, date and subject.
+
+## Tests
+
+The tests write a small synthetic mbox file with made-up addresses to a
+temporary directory and run it through the extractor and transformer. They
+never read the host's mail or accounts.

package/dist/connectors/EmailTransformer.d.ts

@@ -0,0 +1,8 @@
+import { ChronicleTransformer, Record } from '@chronicle.app/etl';
+import { ActionAndChildren } from '@chronicle.app/schema';
+export default class EmailTransformer extends ChronicleTransformer {
+    transform(record: Record): Promise<ActionAndChildren[]>;
+    private buildEmailActions;
+    private buildPersonFromEmail;
+}
+//# sourceMappingURL=EmailTransformer.d.ts.map

package/dist/connectors/EmailTransformer.js

@@ -0,0 +1,91 @@
+import { ChronicleTransformer } from '@chronicle.app/etl';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const parseEmailAddresses = require('emailjs-addressparser').default;
+export default class EmailTransformer extends ChronicleTransformer {
+    async transform(record) {
+        const actions = [];
+        if (record.extraction.recordType === 'emails') {
+            actions.push(...this.buildEmailActions(record));
+        }
+        return actions;
+    }
+    buildEmailActions(record) {
+        const actions = [];
+        const emailData = record.data;
+        // Build sender person with email address as handle
+        const sender = this.buildPersonFromEmail(emailData.from);
+        // Build recipient persons
+        const recipients = [
+            ...emailData.to.map((email) => this.buildPersonFromEmail(email)),
+            ...emailData.cc.map((email) => this.buildPersonFromEmail(email)),
+            ...emailData.bcc.map((email) => this.buildPersonFromEmail(email)),
+        ];
+        // Every action requires a valid agent
+        if (!sender) {
+            throw new Error(`Invalid or missing sender in email ${emailData.messageId ?? '(no Message-ID)'}: ${emailData.from}`);
+        }
+        // Identity. The Message-ID is the source's own id and stays `sourceId`. A
+        // message without one (common in early-2000s mail) is keyed on the natural
+        // composite of who sent it, when, and under what subject — the same three
+        // real headers the extractor's keyOf composes, read here off the
+        // transformed fields: the MessageAction carries them directly, the Message
+        // reaches the first two through its carrying action (`action.*`). Dotted
+        // paths to scalars only; a whole nested node in a key couples identity to
+        // every mutable attribute of that node.
+        const messageId = emailData.messageId || null;
+        const timestamp = emailData.date ? new Date(emailData.date) : new Date();
+        if (!messageId && (!emailData.date || Number.isNaN(timestamp.getTime()))) {
+            throw new Error(`Email without a Message-ID needs a parseable Date to be identified: ${emailData.from} / ${emailData.subject}`);
+        }
+        // Build email message entity
+        const emailMessage = {
+            '@type': 'Message',
+            source: 'email',
+            ...(messageId && { sourceId: messageId }),
+            name: emailData.subject,
+            description: emailData.body,
+            recipient: recipients.filter(Boolean),
+            author: [sender],
+            '@key': messageId
+                ? ['@type', 'source', 'sourceId']
+                : ['@type', 'source', 'action.timestamp', 'action.agent.handle', 'name'],
+        };
+        const messageAction = {
+            '@type': 'MessageAction',
+            timestamp,
+            source: 'email',
+            ...(messageId && { sourceId: messageId }),
+            '@key': messageId
+                ? ['source', 'sourceId', '@type']
+                : ['@type', 'source', 'timestamp', 'agent.handle', 'object.name'],
+            agent: sender,
+            object: emailMessage,
+        };
+        actions.push(messageAction);
+        return actions;
+    }
+    buildPersonFromEmail(emailString) {
+        if (!emailString?.trim())
+            return null;
+        try {
+            const parsed = parseEmailAddresses(emailString);
+            if (!parsed || parsed.length === 0)
+                return null;
+            // Take the first parsed address
+            const address = parsed[0];
+            return {
+                '@type': 'Agent',
+                source: 'email',
+                handle: address.address, // Clean email address
+                name: address.name || address.address, // Use name if available, fallback to email
+                '@key': ['@type', 'source', 'handle'],
+            };
+        }
+        catch {
+            // Log and skip malformed addresses
+            console.warn(`Failed to parse email address: ${emailString}`);
+            return null;
+        }
+    }
+}

package/dist/connectors/mbox/EmailMboxExtractor.d.ts

@@ -0,0 +1,54 @@
+import { Extractor, Record } from '@chronicle.app/etl';
+import { z } from 'zod';
+import EmailTransformer from '../EmailTransformer.js';
+export declare class EmailMboxExtractor extends Extractor<typeof EmailMboxExtractor> {
+    static source: string;
+    static description: string;
+    static delivery: "export";
+    static strategy: string;
+    static recordTypes: string[];
+    static default: boolean;
+    static defaultTransformer: typeof EmailTransformer;
+    static schema: z.ZodObject<{
+        since: z.ZodOptional<z.ZodDate>;
+        until: z.ZodOptional<z.ZodDate>;
+        limit: z.ZodOptional<z.ZodNumber>;
+    } & {
+        input: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        input: string;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }, {
+        input: string;
+        since?: Date | undefined;
+        until?: Date | undefined;
+        limit?: number | undefined;
+    }>;
+    /**
+     * The RFC 5322 Message-ID header — the message's own id, identical in any mail
+     * tool. A message without one is keyed on the natural composite of its From,
+     * Date, and Subject headers: real source fields, never an invented id. That
+     * needs From and a Date that parses; a message with neither has nothing to be
+     * identified by, and parseMbox never emits it. EmailTransformer keys the same
+     * records on the same three facts (sender handle, sent time, subject).
+     */
+    keyOf(record: Record): string | null;
+    /**
+     * Message-ID when present; otherwise `From␟Date␟Subject` over the raw
+     * headers (Subject may be empty and still takes part); null when there is no
+     * From or no parseable Date to compose.
+     */
+    static identityOf(headers: {
+        [key: string]: string;
+    }): string | null;
+    extract(): AsyncGenerator<Record>;
+    private parseMbox;
+    private parseMessage;
+    private extractTextContent;
+    private decodeMimeHeader;
+    private parseEmailList;
+    determineCount(): Promise<number | null>;
+}
+//# sourceMappingURL=EmailMboxExtractor.d.ts.map

package/dist/connectors/mbox/EmailMboxExtractor.js

@@ -0,0 +1,241 @@
+import { Extractor } from '@chronicle.app/etl';
+import { readFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { createRequire } from 'node:module';
+import EmailTransformer from '../EmailTransformer.js';
+const require = createRequire(import.meta.url);
+const { Libmime } = require('libmime');
+const libmime = new Libmime();
+/**
+ * Joins the parts of a composite key. A control character that RFC 5322 header
+ * text cannot carry, so no From/Date/Subject combination can collide with
+ * another by concatenation.
+ */
+const COMPOSITE_DELIMITER = '\u001F';
+export class EmailMboxExtractor extends Extractor {
+    static source = 'email';
+    static description = 'Messages from an mbox file';
+    static delivery = 'export';
+    static strategy = 'mbox';
+    static recordTypes = ['emails'];
+    static default = true;
+    static defaultTransformer = EmailTransformer;
+    static schema = Extractor.schema.extend({
+        input: z.string().describe('Path to the mbox file'),
+    });
+    /**
+     * The RFC 5322 Message-ID header — the message's own id, identical in any mail
+     * tool. A message without one is keyed on the natural composite of its From,
+     * Date, and Subject headers: real source fields, never an invented id. That
+     * needs From and a Date that parses; a message with neither has nothing to be
+     * identified by, and parseMbox never emits it. EmailTransformer keys the same
+     * records on the same three facts (sender handle, sent time, subject).
+     */
+    keyOf(record) {
+        return EmailMboxExtractor.identityOf(record.data.headers);
+    }
+    /**
+     * Message-ID when present; otherwise `From␟Date␟Subject` over the raw
+     * headers (Subject may be empty and still takes part); null when there is no
+     * From or no parseable Date to compose.
+     */
+    static identityOf(headers) {
+        const messageId = headers['message-id'];
+        if (messageId)
+            return messageId;
+        const { from, date } = headers;
+        if (!from || !date || Number.isNaN(new Date(date).getTime()))
+            return null;
+        return [from, date, headers.subject ?? ''].join(COMPOSITE_DELIMITER);
+    }
+    async *extract() {
+        const config = this.config;
+        try {
+            const content = await readFile(config.input, 'utf-8');
+            const emails = this.parseMbox(content);
+            let count = 0;
+            for (const email of emails) {
+                // Apply date filtering if configured
+                if (config.since || config.until) {
+                    const emailDate = new Date(email.date);
+                    if (config.since && emailDate < config.since)
+                        continue;
+                    if (config.until && emailDate > config.until)
+                        continue;
+                }
+                // Apply limit if configured
+                if (this.shouldStopExtracting(count))
+                    break;
+                yield this.createRecord(email, {
+                    messageId: email.messageId,
+                    from: email.from,
+                    subject: email.subject,
+                    strategy: 'mbox',
+                });
+                count++;
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to read mbox file: ${error}`);
+        }
+    }
+    parseMbox(content) {
+        const emails = [];
+        let unidentified = 0;
+        const messages = content.split(/^From /m);
+        // Skip the first element if it's empty (before the first "From " line)
+        const validMessages = messages.slice(1);
+        for (const message of validMessages) {
+            const email = this.parseMessage('From ' + message);
+            if (!email)
+                continue;
+            if (EmailMboxExtractor.identityOf(email.headers) === null) {
+                // No Message-ID, and no From + parseable Date to compose a natural key
+                // from: the source gives nothing real to identify this message by, and
+                // a fabricated id would mint a new entity on every run. Skip and say so.
+                unidentified++;
+                continue;
+            }
+            emails.push(email);
+        }
+        if (unidentified > 0) {
+            this.logger.warn(`Skipped ${unidentified} message(s) with no Message-ID and no From + Date to key on`);
+        }
+        return emails;
+    }
+    parseMessage(message) {
+        const lines = message.split('\n');
+        const headers = {};
+        let headerSection = true;
+        const bodyLines = [];
+        for (const line of lines) {
+            if (headerSection) {
+                if (line.trim() === '') {
+                    headerSection = false;
+                    continue;
+                }
+                // Handle multi-line headers
+                if (line.startsWith(' ') || line.startsWith('\t')) {
+                    const lastHeader = Object.keys(headers).pop();
+                    if (lastHeader) {
+                        headers[lastHeader] += ' ' + line.trim();
+                    }
+                    continue;
+                }
+                const colonIndex = line.indexOf(':');
+                if (colonIndex > 0) {
+                    const key = line.slice(0, Math.max(0, colonIndex)).trim().toLowerCase();
+                    const value = line.slice(Math.max(0, colonIndex + 1)).trim();
+                    headers[key] = value;
+                }
+            }
+            else {
+                bodyLines.push(line);
+            }
+        }
+        // Extract required fields
+        const from = headers.from || '';
+        const to = this.parseEmailList(headers.to || '');
+        const cc = this.parseEmailList(headers.cc || '');
+        const bcc = this.parseEmailList(headers.bcc || '');
+        const subject = this.decodeMimeHeader(headers.subject || '');
+        const date = headers.date || '';
+        const messageId = headers['message-id'] ?? null;
+        const body = this.extractTextContent(bodyLines, headers);
+        if (!from && !subject) {
+            return null; // Skip invalid messages
+        }
+        return {
+            from,
+            to,
+            cc,
+            bcc,
+            subject,
+            date,
+            messageId,
+            body,
+            headers,
+        };
+    }
+    extractTextContent(bodyLines, headers) {
+        const contentType = headers['content-type'] || '';
+        // If not multipart, return the body as-is
+        if (!contentType.toLowerCase().includes('multipart')) {
+            return bodyLines.join('\n').trim();
+        }
+        // Extract boundary from Content-Type header
+        const boundaryMatch = contentType.match(/boundary=["']?([^"';]+)["']?/i);
+        if (!boundaryMatch) {
+            return bodyLines.join('\n').trim(); // Fallback if no boundary found
+        }
+        const boundary = boundaryMatch[1];
+        const bodyText = bodyLines.join('\n');
+        // Split by boundary
+        const parts = bodyText.split(`--${boundary}`);
+        const textParts = [];
+        for (const part of parts) {
+            if (!part.trim() || part.trim() === '--')
+                continue;
+            // Parse each part's headers and content
+            const partLines = part.split('\n');
+            const partHeaders = {};
+            let partHeaderSection = true;
+            const partBodyLines = [];
+            for (const line of partLines) {
+                if (partHeaderSection) {
+                    if (line.trim() === '') {
+                        partHeaderSection = false;
+                        continue;
+                    }
+                    const colonIndex = line.indexOf(':');
+                    if (colonIndex > 0) {
+                        const key = line.slice(0, colonIndex).trim().toLowerCase();
+                        const value = line.slice(colonIndex + 1).trim();
+                        partHeaders[key] = value;
+                    }
+                }
+                else {
+                    partBodyLines.push(line);
+                }
+            }
+            // Only include text/plain parts
+            const partContentType = partHeaders['content-type'] || '';
+            if (partContentType.toLowerCase().includes('text/plain')) {
+                textParts.push(partBodyLines.join('\n').trim());
+            }
+        }
+        // Join all text parts
+        return textParts.join('\n\n').trim();
+    }
+    decodeMimeHeader(headerValue) {
+        if (!headerValue)
+            return '';
+        try {
+            return libmime.decodeWords(headerValue);
+        }
+        catch {
+            // If decoding fails, return the original value
+            this.logger.warn('Failed to decode MIME header', { headerValue });
+            return headerValue;
+        }
+    }
+    parseEmailList(emailString) {
+        if (!emailString.trim())
+            return [];
+        return emailString
+            .split(',')
+            .map(email => email.trim())
+            .filter(email => email.length > 0);
+    }
+    async determineCount() {
+        const config = this.config;
+        try {
+            const content = await readFile(config.input, 'utf-8');
+            const messages = content.split(/^From /m);
+            return Math.max(0, messages.length - 1); // Subtract 1 for the content before first "From "
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { EmailMboxExtractor } from './connectors/mbox/EmailMboxExtractor.js';
+export { default as EmailTransformer } from './connectors/EmailTransformer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,3 @@
+// Export extractors for plugin scanning
+export { EmailMboxExtractor } from './connectors/mbox/EmailMboxExtractor.js';
+export { default as EmailTransformer } from './connectors/EmailTransformer.js';

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@chronicle.app/email",
+  "version": "0.3.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"
+  ],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Chronicle plugin for email data from mbox format files",
+  "devDependencies": {
+    "@chronicle.app/etl": "0.3.0",
+    "@chronicle.app/schema": "0.3.0",
+    "@chronicle.app/tsconfig": "0.3.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": "plugins/email"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "emailjs-addressparser": "^2.0.3",
+    "libmime": "^5.3.7",
+    "zod": "^3.24.1"
+  },
+  "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"
+    }
+  },
+  "chronicle": {
+    "plugin": true,
+    "sources": {
+      "email": {
+        "strategies": {
+          "mbox": {
+            "delivery": "export",
+            "recordTypes": [
+              "emails"
+            ],
+            "default": true
+          }
+        }
+      }
+    }
+  }
+}