v1.0.4

grgbrasil · Jan 15, 2021 · bc33c35 · bc33c35
1 parent 8aba315
commit bc33c35
Show file tree

Hide file tree

Showing 4 changed files with 67 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -2,12 +2,18 @@
 
 Email parser for browser environments.
 
-PostalMime can be run in the main web thread or from Web Workers. Expects emails as ArrayBufer values.
+PostalMime can be run in the main web thread or from Web Workers.
+
+PostalMime can be bundled using WebPack. In fact the distribution file is also built with WebPack.
 
 ## Source
 
 Source code is available from [Github](https://github.com/postalsys/postal-mime).
 
+## Demo
+
+See this [example](https://kreata.ee/postal-mime/example/).
+
 ## Usage
 
 ### Free, AGPL-licensed version
@@ -68,16 +74,52 @@ All postal-mime methods use Promises, so you need to wait using `await` or wait
 ```js
 const { PostalMime } = require('postal-mime');
 const parser = new PostalMime();
-const email = await parser.parse(emailAsAnArrayBuffer);
+const email = await parser.parse(email);
 console.log(email.subject);
 console.log(email.html);
 ```
 
+#### parser.parse()
+
+```js
+parser.parse(email) -> Promise
+```
+
+Where
+
+-   **email** is the rfc822 formatted email. Either a string, an ArrayBuffer or a Blob object
+
+> **NB** you can call `parse()` only once. If you need to parse another message, create a new _PostalMime_ object.
+
+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.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[].name** is decoded name (empty string if not set)
+    -   **to[].address** is the email address
+-   **subject** is the email subject line
+-   **messageId**, **inReplyTo**, **references** includes the value as found from the corresponding header without any processing
+-   **date** is the email sending time formatted as an ISO date string (unless parsing failed and in this case the original value is used)
+-   **html** is the HTML content of the message as a string
+-   **text** is the plaintext content of the message as a string
+-   **attachments** is an array that includes message attachments
+    -   **attachment[].filename** is the file name if provided
+    -   **attachment[].mimeType** is the MIME type of the attachment
+    -   **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
+
 ## License
 
-&copy; 2020 Andris Reinman
+&copy; 2021 Andris Reinman
 
 Licensed under GNU Affero General Public License v3.0 or later.
 
 MIT-licensed version of postal-mime is available for [Postal Systems subscribers](https://postalsys.com/).
-
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "postal-mime",
-    "version": "1.0.3",
+    "version": "1.0.4",
     "description": "Email parser for browser environments",
     "main": "dist/postal-mime.js",
     "scripts": {

diff --git a/src/decode-strings.js b/src/decode-strings.js
@@ -1,4 +1,5 @@
-const textEncoder = new TextEncoder();
+export const textEncoder = new TextEncoder();
+
 const decoders = new Map();
 
 const base64Chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';

diff --git a/src/postal-mime.js b/src/postal-mime.js
@@ -1,7 +1,7 @@
 import MimeNode from './mime-node';
 import { textToHtml, htmlToText } from './text-format';
 import addressParser from './address-parser';
-import { decodeWords } from './decode-strings';
+import { decodeWords, textEncoder, blobToArrayBuffer } from './decode-strings';
 
 export default class PostalMime {
     constructor() {
@@ -12,6 +12,8 @@ export default class PostalMime {
 
         this.textContent = {};
         this.attachments = [];
+
+        this.started = false;
     }
 
     async finalize() {
@@ -193,6 +195,21 @@ export default class PostalMime {
     }
 
     async parse(buf) {
+        if (this.started) {
+            throw new Error('Can not reuse parser, create a new PostalMime object');
+        }
+        this.started = true;
+
+        if (typeof buf === 'string') {
+            // cast string input to ArrayBuffer
+            buf = textEncoder.encode(buf);
+        }
+
+        if (buf instanceof Blob) {
+            // can't process blob directly, cast to ArrayBuffer
+            buf = await blobToArrayBuffer(buf);
+        }
+
         this.buf = buf;
         this.av = new Uint8Array(buf);
         this.readPos = 0;