postal-mime 2.1.2 → 2.2.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.2.1](https://github.com/postalsys/postal-mime/compare/v2.2.0...v2.2.1) (2024-03-31)
+
+
+### Bug Fixes
+
+* **parser:** Reply-To value must be an array, not a single address object ([280bd8d](https://github.com/postalsys/postal-mime/commit/280bd8dc1626315e1a43f35641415453c434716e))
+
+## [2.2.0](https://github.com/postalsys/postal-mime/compare/v2.1.2...v2.2.0) (2024-03-26)
+
+
+### Features
+
+* **interface:** Added statis parse() method to simplify usage (`await PostalMime.parse(email)`) ([c2faa27](https://github.com/postalsys/postal-mime/commit/c2faa276520d6551df640abe008986eebc6d99d3))
+
 ## [2.1.2](https://github.com/postalsys/postal-mime/compare/v2.1.1...v2.1.2) (2024-02-29)
 
 

package/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2021-2023 Andris Reinman
+Copyright (c) 2021-2024 Andris Reinman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,12 +1,15 @@
 # postal-mime
 
-Email parser for browser environments.
+Email parser for browser and serverless environments.
 
-PostalMime can be run in the main web thread or from Web Workers.
+PostalMime can be run in the main web thread or from Web Workers. It can also used in serverless functions.
+
+> [!TIP]
+> PostalMime is developed by the makers of **[EmailEngine](https://emailengine.app/?utm_source=github&utm_campaign=imapflow&utm_medium=readme-link)** – a self-hosted email gateway that allows making **REST requests against IMAP and SMTP servers**. EmailEngine also sends webhooks whenever something changes on the registered accounts.
 
 ## Source
 
-Source code is available from [Github](https://github.com/postalsys/postal-mime).
+The source code is available from [Github](https://github.com/postalsys/postal-mime).
 
 ## Demo
 
@@ -14,7 +17,7 @@ See this [example](https://kreata.ee/postal-mime/example/).
 
 ## Usage
 
-First install the module from npm:
+First, install the module from npm:
 
 ```
 $ npm install postal-mime
@@ -26,7 +29,7 @@ next import the PostalMime class into your script:
 import PostalMime from './node_modules/postal-mime/src/postal-mime.js';
 ```
 
-or when using from a Node.js app
+or when using from a Node.js app or in a serverless function:
 
 ```js
 import PostalMime from 'postal-mime';
@@ -34,15 +37,14 @@ import PostalMime from 'postal-mime';
 
 ### Promises
 
-All postal-mime methods use Promises, so you need to wait using `await` or wait for the `then()` method to fire until you get the response.
+PostalMime methods use Promises, so you need to wait using `await` or wait for the `then()` method to fire until you get the response.
 
 #### Browser
 
 ```js
 import PostalMime from './node_modules/postal-mime/src/postal-mime.js';
 
-const parser = new PostalMime();
-const email = await parser.parse(`Subject: My awesome email 🤓
+const email = await PostalMime.parse(`Subject: My awesome email 🤓
 Content-Type: text/html; charset=utf-8
 
 <p>Hello world 😵‍💫</p>`);
@@ -58,8 +60,7 @@ It is pretty much the same as in the browser.
 import PostalMime from 'postal-mime';
 import util from 'node:util';
 
-const parser = new PostalMime();
-const email = await parser.parse(`Subject: My awesome email 🤓
+const email = await PostalMime.parse(`Subject: My awesome email 🤓
 Content-Type: text/html; charset=utf-8
 
 <p>Hello world 😵‍💫</p>`);
@@ -76,8 +77,7 @@ import PostalMime from 'postal-mime';
 
 export default {
     async email(message, env, ctx) {
-        const parser = new PostalMime();
-        const email = await parser.parse(message.raw);
+        const email = await PostalMime.parse(message.raw);
 
         console.log('Subject: ', email.subject);
         console.log('HTML: ', email.html);
@@ -86,28 +86,28 @@ export default {
 };
 ```
 
-#### parser.parse()
+#### PostalMime.parse()
+
+`parse(email)` is a static class method to parse emails
 
 ```js
-parser.parse(email) -> Promise
+PostalMime.parse(email) -> Promise
 ```
 
 Where
 
--   **email** is the rfc822 formatted email. Either a string, an ArrayBuffer, a Blob object or a Node.js Buffer
-
-> **NB** you can call `parse()` only once. If you need to parse another message, create a new _PostalMime_ object.
+-   **email** is the rfc822 formatted email. Either a string, an ArrayBuffer/Uint8Array value, a Blob object, a Node.js Buffer, or a [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
 
 This method parses an email message into a structured object with the following properties:
 
 -   **headers** is an array of headers in the same order as found from the message (topmost headers first).
     -   **headers[].key** is lowercase key of the header line, eg. `"dkim-signature"`
     -   **headers[].value** is the unprocessed value of the header line
--   **from**, **sender**, **replyTo** includes a processed object for the corresponding headers
+-   **from**, **sender** includes a processed object for the corresponding headers
     -   **from.name** is decoded name (empty string if not set)
     -   **from.address** is the email address
 -   **deliveredTo**, **returnPath** is the email address from the corresponding header
--   **to**, **cc**, **bcc** includes an array of processed objects for the corresponding headers
+-   **to**, **cc**, **bcc**, **replyTo** includes an array of processed objects for the corresponding headers
     -   **to[].name** is decoded name (empty string if not set)
     -   **to[].address** is the email address
 -   **subject** is the email subject line
@@ -121,10 +121,10 @@ This method parses an email message into a structured object with the following
     -   **attachment[].disposition** is either "attachment", "inline" or `null` if disposition was not provided
     -   **attachment[].related** is a boolean value that indicats if this attachment should be treated as embedded image
     -   **attachment[].contentId** is the ID from Content-ID header
-    -   **attachment[].content** is an ArrayBuffer that contains the attachment file
+    -   **attachment[].content** is an Uint8Array value that contains the attachment file
 
 ## License
 
-&copy; 2021-2023 Andris Reinman
+&copy; 2021-2024 Andris Reinman
 
 `postal-mime` is licensed under the **MIT No Attribution license**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "postal-mime",
-    "version": "2.1.2",
+    "version": "2.2.1",
     "description": "Email parser for browser environments",
     "main": "./src/postal-mime.js",
     "exports": {
@@ -27,7 +27,7 @@
     "author": "Andris Reinman",
     "license": "MIT-0",
     "devDependencies": {
-        "@types/node": "20.11.22",
+        "@types/node": "20.11.30",
         "cross-blob": "3.0.2",
         "cross-env": "7.0.3",
         "eslint": "8.57.0",

package/postal-mime.d.ts

@@ -37,6 +37,7 @@ export type Email = {
 };
 
 declare class PostalMime {
+	static parse(email: RawEmail): Promise<Email>;
 	parse(email: RawEmail): Promise<Email>;
 }
 

package/src/postal-mime.js

@@ -4,6 +4,11 @@ import addressParser from './address-parser.js';
 import { decodeWords, textEncoder, blobToArrayBuffer } from './decode-strings.js';
 
 export default class PostalMime {
+    static parse(buf) {
+        const parser = new PostalMime();
+        return parser.parse(buf);
+    }
+
     constructor() {
         this.root = this.currentNode = new MimeNode({
             postalMime: this
@@ -353,32 +358,33 @@ export default class PostalMime {
 
         await this.processNodeTree();
 
-        let message = {
+        const message = {
             headers: this.root.headers.map(entry => ({ key: entry.key, value: entry.value })).reverse()
         };
 
-        for (let key of ['from', 'sender', 'reply-to']) {
-            let addressHeader = this.root.headers.find(line => line.key === key);
+        for (const key of ['from', 'sender']) {
+            const addressHeader = this.root.headers.find(line => line.key === key);
             if (addressHeader && addressHeader.value) {
-                let addresses = addressParser(addressHeader.value);
+                const addresses = addressParser(addressHeader.value);
                 if (addresses && addresses.length) {
-                    message[key.replace(/\-(.)/g, (o, c) => c.toUpperCase())] = addresses[0];
+                    message[key] = addresses[0];
                 }
             }
         }
 
-        for (let key of ['delivered-to', 'return-path']) {
-            let addressHeader = this.root.headers.find(line => line.key === key);
+        for (const key of ['delivered-to', 'return-path']) {
+            const addressHeader = this.root.headers.find(line => line.key === key);
             if (addressHeader && addressHeader.value) {
-                let addresses = addressParser(addressHeader.value);
+                const addresses = addressParser(addressHeader.value);
                 if (addresses && addresses.length && addresses[0].address) {
-                    message[key.replace(/\-(.)/g, (o, c) => c.toUpperCase())] = addresses[0].address;
+                    const camelKey = key.replace(/\-(.)/g, (o, c) => c.toUpperCase());
+                    message[camelKey] = addresses[0].address;
                 }
             }
         }
 
-        for (let key of ['to', 'cc', 'bcc']) {
-            let addressHeaders = this.root.headers.filter(line => line.key === key);
+        for (const key of ['to', 'cc', 'bcc', 'reply-to']) {
+            const addressHeaders = this.root.headers.filter(line => line.key === key);
             let addresses = [];
 
             addressHeaders
@@ -387,14 +393,16 @@ export default class PostalMime {
                 .forEach(parsed => (addresses = addresses.concat(parsed || [])));
 
             if (addresses && addresses.length) {
-                message[key] = addresses;
+                const camelKey = key.replace(/\-(.)/g, (o, c) => c.toUpperCase());
+                message[camelKey] = addresses;
             }
         }
 
-        for (let key of ['subject', 'message-id', 'in-reply-to', 'references']) {
-            let header = this.root.headers.find(line => line.key === key);
+        for (const key of ['subject', 'message-id', 'in-reply-to', 'references']) {
+            const header = this.root.headers.find(line => line.key === key);
             if (header && header.value) {
-                message[key.replace(/\-(.)/g, (o, c) => c.toUpperCase())] = decodeWords(header.value);
+                const camelKey = key.replace(/\-(.)/g, (o, c) => c.toUpperCase());
+                message[camelKey] = decodeWords(header.value);
             }
         }