postal-mime 2.2.2 → 2.2.4

package/.ncurc.js

@@ -0,0 +1,7 @@
+module.exports = {
+    upgrade: true,
+    reject: [
+        // api changes, check and fix
+        'eslint'
+    ]
+};

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.2.4](https://github.com/postalsys/postal-mime/compare/v2.2.3...v2.2.4) (2024-04-11)
+
+
+### Bug Fixes
+
+* **exports:** Export addressParser and decodeWords functions ([43d3187](https://github.com/postalsys/postal-mime/commit/43d31873308d8eff61876f32614e5cc5143c90dd))
+
+## [2.2.3](https://github.com/postalsys/postal-mime/compare/v2.2.2...v2.2.3) (2024-04-11)
+
+
+### Bug Fixes
+
+* **attachments:** Added description key from Content-Description attachment header ([6e29de9](https://github.com/postalsys/postal-mime/commit/6e29de97a4dc0043587a59870d52250602801e3c))
+* **calendar-attachments:** treat text/calendar as an attachment ([2196b49](https://github.com/postalsys/postal-mime/commit/2196b497f289697e9dc72011708e4355ee7362cc))
+
 ## [2.2.2](https://github.com/postalsys/postal-mime/compare/v2.2.1...v2.2.2) (2024-04-10)
 
 

package/README.md

@@ -123,6 +123,57 @@ This method parses an email message into a structured object with the following
     -   **attachment[].contentId** is the ID from Content-ID header
     -   **attachment[].content** is an Uint8Array value that contains the attachment file
 
+### Utility functions
+
+#### addressParser
+
+Parse email address strings
+
+```js
+addressParser(addressStr, opts) -> Array
+```
+
+where
+
+-   **addressStr** is the header value for an address header
+-   **opts** is an optional options object
+    -   **flattem** is a boolean value. If set to `true`, then ignores address groups and returns a flat array of addresses. By default (`flatten` is `false`) the result might include nested groups
+
+The result is an array of objects
+
+-   **name** is the name string. An empty string is used if name value was not set.
+-   **address** is the email address value
+
+```js
+import { addressParser } from 'postal-mime';
+
+const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>';
+console.log(addressParser(addressStr));
+// [ { name: 'エポスカード', address: 'support@example.com' } ]
+```
+
+#### decodeWords
+
+Decode MIME encoded-words
+
+```js
+decodeWords(encodedStr) -> String
+```
+
+where
+
+-   **encodedStr** is a string value that _may_ include MIME encoded-words
+
+The result is a unicode string
+
+```js
+import { decodeWords } from 'postal-mime';
+
+const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
+console.log(decodeWords(encodedStr));
+// Hello, エポスカード
+```
+
 ## License
 
 &copy; 2021-2024 Andris Reinman

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "postal-mime",
-    "version": "2.2.2",
+    "version": "2.2.4",
     "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.30",
+        "@types/node": "20.12.7",
         "cross-blob": "3.0.2",
         "cross-env": "7.0.3",
         "eslint": "8.57.0",

package/postal-mime.d.ts

@@ -8,11 +8,13 @@ export type Address = {
 };
 
 export type Attachment = {
-	filename: string;
+	filename: string | null;
 	mimeType: string;
 	disposition: "attachment" | "inline" | null;
 	related?: boolean;
+    description?: string;
 	contentId?: string;
+    method?: string;
 	content: Uint8Array;
 };
 
@@ -36,9 +38,23 @@ export type Email = {
 	attachments: Attachment[];
 };
 
+declare type AddressParserOptions = {
+    flatten?: boolean
+}
+
+declare function addressParser (
+    str: string,
+    opts?: AddressParserOptions
+): Address[];
+
+declare function decodeWords (
+    str: string
+): string;
+
 declare class PostalMime {
 	static parse(email: RawEmail): Promise<Email>;
 	parse(email: RawEmail): Promise<Email>;
 }
 
+export { addressParser, decodeWords };
 export default PostalMime;

package/src/mime-node.js

@@ -226,6 +226,9 @@ export default class MimeNode {
                     case 'content-id':
                         this.contentId = value;
                         break;
+                    case 'content-description':
+                        this.contentDescription = value;
+                        break;
                 }
             }
         }

package/src/postal-mime.js

@@ -3,6 +3,8 @@ import { textToHtml, htmlToText, formatTextHeader, formatHtmlHeader } from './te
 import addressParser from './address-parser.js';
 import { decodeWords, textEncoder, blobToArrayBuffer } from './decode-strings.js';
 
+export { addressParser, decodeWords };
+
 export default class PostalMime {
     static parse(buf) {
         const parser = new PostalMime();
@@ -162,10 +164,7 @@ export default class PostalMime {
                 }
 
                 // is it text?
-                else if (
-                    (/^text\//i.test(node.contentType.parsed.value) || node.contentType.parsed.value === 'message/delivery-status') &&
-                    node.contentDisposition.parsed.value !== 'attachment'
-                ) {
+                else if (this.isInlineTextNode(node)) {
                     let textType = node.contentType.parsed.value.substr(node.contentType.parsed.value.indexOf('/') + 1);
                     if (node.contentType.parsed.value === 'message/delivery-status') {
                         textType = 'plain';
@@ -184,9 +183,9 @@ export default class PostalMime {
 
                 // is it an attachment
                 else if (node.content) {
-                    let filename = node.contentDisposition.parsed.params.filename || node.contentType.parsed.params.name || null;
-                    let attachment = {
-                        filename: decodeWords(filename),
+                    const filename = node.contentDisposition.parsed.params.filename || node.contentType.parsed.params.name || null;
+                    const attachment = {
+                        filename: filename ? decodeWords(filename) : null,
                         mimeType: node.contentType.parsed.value,
                         disposition: node.contentDisposition.parsed.value || null
                     };
@@ -195,11 +194,39 @@ export default class PostalMime {
                         attachment.related = true;
                     }
 
+                    if (node.contentDescription) {
+                        attachment.description = node.contentDescription;
+                    }
+
                     if (node.contentId) {
                         attachment.contentId = node.contentId;
                     }
 
-                    attachment.content = node.content;
+                    switch (node.contentType.parsed.value) {
+                        // Special handling for calendar events
+                        case 'text/calendar':
+                        case 'application/ics': {
+                            if (node.contentType.parsed.params.method) {
+                                attachment.method = node.contentType.parsed.params.method.toString().toUpperCase().trim();
+                            }
+
+                            // Enforce into unicode
+                            const decodedText = node.getTextContent().replace(/\r?\n/g, '\n').replace(/\n*$/, '\n');
+                            attachment.content = textEncoder.encode(decodedText);
+                            break;
+                        }
+
+                        case 'message/delivery-status': {
+                            // Enforce into unicode
+                            const decodedText = node.getTextContent().replace(/\r?\n/g, '\n').replace(/\n*$/, '\n');
+                            attachment.content = textEncoder.encode(decodedText);
+                            break;
+                        }
+
+                        // Regular attachments
+                        default:
+                            attachment.content = node.content;
+                    }
 
                     this.attachments.push(attachment);
                 }
@@ -292,6 +319,26 @@ export default class PostalMime {
         this.textContent = textContent;
     }
 
+    isInlineTextNode(node) {
+        if (node.contentDisposition.parsed.value === 'attachment') {
+            // no matter the type, this is an attachment
+            return false;
+        }
+
+        switch (node.contentType.parsed.value) {
+            case 'text/html':
+            case 'text/plain':
+            // message/delivery-status is cast into regular plaintext content
+            case 'message/delivery-status':
+                return true;
+
+            case 'text/calendar':
+            case 'text/csv':
+            default:
+                return false;
+        }
+    }
+
     async resolveStream(stream) {
         let chunkLen = 0;
         let chunks = [];
@@ -418,11 +465,11 @@ export default class PostalMime {
             message.date = date;
         }
 
-        if (this.textContent && this.textContent.html) {
+        if (this.textContent?.html) {
             message.html = this.textContent.html;
         }
 
-        if (this.textContent && this.textContent.plain) {
+        if (this.textContent?.plain) {
             message.text = this.textContent.plain;
         }