From 204f2b5072b771da9e565e9a18e1a7724cbf1765 Mon Sep 17 00:00:00 2001
From: Yazhong Liu <yorkiefixer@gmail.com>
Date: Sun, 29 Jun 2014 14:11:49 +0800
Subject: [PATCH 1/5] imap, doc: documented stuffs on imapsession

---
 README.md    | 136 +++++++++++++++++++++++++++++++++++++++++++++++++++
 lib/index.js |   4 ++
 2 files changed, 140 insertions(+)
 create mode 100644 lib/index.js

diff --git a/README.md b/README.md
index 85f2073..4529223 100644
--- a/README.md
+++ b/README.md
@@ -2,3 +2,139 @@ mailcore.node
 =============
 
 MailCore provide a simple API to work with e-mail protocols IMAP, POP and SMTP on NodeJS
+
+
+### Installation
+
+```sh
+$ npm install mailcore --save
+```
+
+### API
+
+#### Class: IMAPSession
+
+The IMAPSession class the class that can be implemented to handle the IMAP operators, like `LOGIN`, `FETCH`, `COPY` and etc, and this class inherits from `EventEmitter` indirectly, then you could use methods of `EventEmitter` to simplify your source code.
+
+#### Event: 'error'
+
+* err `Error` the error object
+
+When an arbitrary error is raised, it will emit a 'error' event.
+
+Because the trigger should be called once in one session, then use the best practice:
+
+```js
+imap.once('error', yourErrorHandler);
+```
+
+to avoid memroy leaks.
+
+#### Event: 'connect'
+
+When the account has been authenticated/loged in, it will emit a `connect` event.
+
+Because the trigger should be called once in one session, then use the best practice:
+
+```js
+imap.once('connect', yourErrorHandler);
+```
+
+to avoid memroy leaks.
+
+#### new IMAPSession(port, hostname, option)
+
+* port Number, the port number of IMAP server
+* hostname String, the hostname of IMAP server
+* option Object, you config the authenticate option here
+
+Constructs an instance of IMAPSession with these 3 specified arguments, and an simple example for calling this constructor just is following:
+
+```js
+var session = new IMAPSession(993, 'imap.gmail.com', {
+  secure: 'ssl',
+  auth: {
+    username: 'yorkiefixer@gmail.com',
+    password: 'xxxxxxx'
+  }
+});
+```
+
+As you have seen before, the secure has multiple values that you're able to pass, the below is the complete valided value for the `option.secure` field:
+
+* ssl
+* starttls
+* none/null
+
+The `option.auth` field before just use the plain to request the authentication, and if you want to use `XOAuth2`, then:
+
+```js
+{
+	username: 'yorkiefixer@gmail.com',
+	accessToken: 'your access_token'
+}
+```
+
+(In later version, we can support the auto fetch the token when you specified `clientId`, `clientSecret` and `refreshToken`).
+
+#### imap.connect([callback])
+
+Start to create the connection to IMAP server, once you account has been authenticated/loged in, program would call `callback` and trigger the `connect` event.
+
+#### imap.disconnect([callback])
+
+End this session.
+
+#### imap.select(folder, callback)
+
+* folder String, the path of folder
+
+Select a folder(mailbox).
+
+#### imap.fetchMessagesByNumber(start, end, option, callback)
+#### imap.fetchMessagesByUID(start, end, option, callback)
+
+* start Number|String
+* end Number|String
+* option Number|Object|null TODO
+* callback Function
+
+Fetches the messages from you selected folder.
+
+#### imap.search(query, callback)
+
+* query String
+* callback Function
+
+The `SEARCH` command implementation.
+
+#### imap.appendMessage(folder, data, flags, date, callback)
+
+* folder String
+* data String, rfc822 message data
+* flags Array
+* date Date
+* callback Function
+
+Append message to you specified folder.
+
+#### imap.copyMessages(uids, dest, options, callback)
+
+* uids Array, a uid set like: `[1000, 1001, 1003]`
+* dest String, the folder that you want this message to
+* options Object
+* callback Function
+
+Copy the messages that you specified by `uids` to `dest` folder.
+
+### TODO
+
+* API `imap.seach`
+* API `imap.fetchMessagesByNumber` and `imap.fetchMessagesByUID`
+* API `imap.search`
+* API `imap.appendMessage`
+* API `imap.copyMessages`
+
+### License
+
+MIT
\ No newline at end of file
diff --git a/lib/index.js b/lib/index.js
new file mode 100644
index 0000000..51c965f
--- /dev/null
+++ b/lib/index.js
@@ -0,0 +1,4 @@
+
+exports.IMAP 
+  = exports.IMAPSession 
+  = require('./imapsession').IMAPSession;

From fe68157015e7f6ca1b338cd53de5003ec929e372 Mon Sep 17 00:00:00 2001
From: Yazhong Liu <yorkiefixer@gmail.com>
Date: Mon, 30 Jun 2014 18:08:37 +0800
Subject: [PATCH 2/5] doc: split document -> README/API

---
 README.md                     | 123 +++++-----------------------------
 docs/API.md                   | 116 ++++++++++++++++++++++++++++++++
 examples/simple-imap-fetch.js |   4 +-
 3 files changed, 135 insertions(+), 108 deletions(-)
 create mode 100644 docs/API.md

diff --git a/README.md b/README.md
index 4529223..81ace6a 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+
 mailcore.node
 =============
 
@@ -10,123 +11,33 @@ MailCore provide a simple API to work with e-mail protocols IMAP, POP and SMTP o
 $ npm install mailcore --save
 ```
 
-### API
-
-#### Class: IMAPSession
-
-The IMAPSession class the class that can be implemented to handle the IMAP operators, like `LOGIN`, `FETCH`, `COPY` and etc, and this class inherits from `EventEmitter` indirectly, then you could use methods of `EventEmitter` to simplify your source code.
-
-#### Event: 'error'
-
-* err `Error` the error object
-
-When an arbitrary error is raised, it will emit a 'error' event.
-
-Because the trigger should be called once in one session, then use the best practice:
-
-```js
-imap.once('error', yourErrorHandler);
-```
-
-to avoid memroy leaks.
-
-#### Event: 'connect'
-
-When the account has been authenticated/loged in, it will emit a `connect` event.
-
-Because the trigger should be called once in one session, then use the best practice:
-
-```js
-imap.once('connect', yourErrorHandler);
-```
-
-to avoid memroy leaks.
-
-#### new IMAPSession(port, hostname, option)
-
-* port Number, the port number of IMAP server
-* hostname String, the hostname of IMAP server
-* option Object, you config the authenticate option here
-
-Constructs an instance of IMAPSession with these 3 specified arguments, and an simple example for calling this constructor just is following:
+### Usage
 
 ```js
-var session = new IMAPSession(993, 'imap.gmail.com', {
+var imap = new IMAPSession(993, 'imap.gmail.com', {
   secure: 'ssl',
   auth: {
     username: 'yorkiefixer@gmail.com',
-    password: 'xxxxxxx'
+    password: 'xxxxxxxxx'
   }
 });
-```
-
-As you have seen before, the secure has multiple values that you're able to pass, the below is the complete valided value for the `option.secure` field:
-
-* ssl
-* starttls
-* none/null
 
-The `option.auth` field before just use the plain to request the authentication, and if you want to use `XOAuth2`, then:
+imap.connect();
+imap.once('error', function(err) {
+  throw err;
+});
+imap.once('connect', function() {
+  console.log('connected');
+  imap.select('INBOX', function(inbox) {
+    console.log(inbox);
+  });
+  imap.fetchMessagesByNumber(0, 2, null, function(messages) {
+    console.log(messages);
+  });
+});
 
-```js
-{
-	username: 'yorkiefixer@gmail.com',
-	accessToken: 'your access_token'
-}
 ```
 
-(In later version, we can support the auto fetch the token when you specified `clientId`, `clientSecret` and `refreshToken`).
-
-#### imap.connect([callback])
-
-Start to create the connection to IMAP server, once you account has been authenticated/loged in, program would call `callback` and trigger the `connect` event.
-
-#### imap.disconnect([callback])
-
-End this session.
-
-#### imap.select(folder, callback)
-
-* folder String, the path of folder
-
-Select a folder(mailbox).
-
-#### imap.fetchMessagesByNumber(start, end, option, callback)
-#### imap.fetchMessagesByUID(start, end, option, callback)
-
-* start Number|String
-* end Number|String
-* option Number|Object|null TODO
-* callback Function
-
-Fetches the messages from you selected folder.
-
-#### imap.search(query, callback)
-
-* query String
-* callback Function
-
-The `SEARCH` command implementation.
-
-#### imap.appendMessage(folder, data, flags, date, callback)
-
-* folder String
-* data String, rfc822 message data
-* flags Array
-* date Date
-* callback Function
-
-Append message to you specified folder.
-
-#### imap.copyMessages(uids, dest, options, callback)
-
-* uids Array, a uid set like: `[1000, 1001, 1003]`
-* dest String, the folder that you want this message to
-* options Object
-* callback Function
-
-Copy the messages that you specified by `uids` to `dest` folder.
-
 ### TODO
 
 * API `imap.seach`
diff --git a/docs/API.md b/docs/API.md
new file mode 100644
index 0000000..fe5773b
--- /dev/null
+++ b/docs/API.md
@@ -0,0 +1,116 @@
+### API
+
+#### Class: IMAPSession
+
+The IMAPSession class the class that can be implemented to handle the IMAP operators, like `LOGIN`, `FETCH`, `COPY` and etc, and this class inherits from `EventEmitter` indirectly, then you could use methods of `EventEmitter` to simplify your source code.
+
+#### Event: 'error'
+
+* err `Error` the error object
+
+When an arbitrary error is raised, it will emit a 'error' event.
+
+Because the trigger should be called once in one session, then use the best practice:
+
+```js
+imap.once('error', yourErrorHandler);
+```
+
+to avoid memroy leaks.
+
+#### Event: 'connect'
+
+When the account has been authenticated/loged in, it will emit a `connect` event.
+
+Because the trigger should be called once in one session, then use the best practice:
+
+```js
+imap.once('connect', yourErrorHandler);
+```
+
+to avoid memroy leaks.
+
+#### new IMAPSession(port, hostname, option)
+
+* port Number, the port number of IMAP server
+* hostname String, the hostname of IMAP server
+* option Object, you config the authenticate option here
+
+Constructs an instance of IMAPSession with these 3 specified arguments, and an simple example for calling this constructor just is following:
+
+```js
+var session = new IMAPSession(993, 'imap.gmail.com', {
+  secure: 'ssl',
+  auth: {
+    username: 'yorkiefixer@gmail.com',
+    password: 'xxxxxxx'
+  }
+});
+```
+
+As you have seen before, the secure has multiple values that you're able to pass, the below is the complete valided value for the `option.secure` field:
+
+* ssl
+* starttls
+* none/null
+
+The `option.auth` field before just use the plain to request the authentication, and if you want to use `XOAuth2`, then:
+
+```js
+{
+	username: 'yorkiefixer@gmail.com',
+	accessToken: 'your access_token'
+}
+```
+
+(In later version, we can support the auto fetch the token when you specified `clientId`, `clientSecret` and `refreshToken`).
+
+#### imap.connect([callback])
+
+Start to create the connection to IMAP server, once you account has been authenticated/loged in, program would call `callback` and trigger the `connect` event.
+
+#### imap.disconnect([callback])
+
+End this session.
+
+#### imap.select(folder, callback)
+
+* folder String, the path of folder
+
+Select a folder(mailbox).
+
+#### imap.fetchMessagesByNumber(start, end, option, callback)
+#### imap.fetchMessagesByUID(start, end, option, callback)
+
+* start Number|String
+* end Number|String
+* option Number|Object|null TODO
+* callback Function
+
+Fetches the messages from you selected folder.
+
+#### imap.search(query, callback)
+
+* query String
+* callback Function
+
+The `SEARCH` command implementation.
+
+#### imap.appendMessage(folder, data, flags, date, callback)
+
+* folder String
+* data String, rfc822 message data
+* flags Array
+* date Date
+* callback Function
+
+Append message to you specified folder.
+
+#### imap.copyMessages(uids, dest, options, callback)
+
+* uids Array, a uid set like: `[1000, 1001, 1003]`
+* dest String, the folder that you want this message to
+* options Object
+* callback Function
+
+Copy the messages that you specified by `uids` to `dest` folder.
\ No newline at end of file
diff --git a/examples/simple-imap-fetch.js b/examples/simple-imap-fetch.js
index ab25a8d..f316c2e 100644
--- a/examples/simple-imap-fetch.js
+++ b/examples/simple-imap-fetch.js
@@ -9,10 +9,10 @@ var imap = new IMAPSession(993, 'imap.gmail.com', {
 });
 
 imap.connect();
-imap.on('error', function(err) {
+imap.once('error', function(err) {
   throw err;
 });
-imap.on('connect', function() {
+imap.once('connect', function() {
   console.log('connected');
   imap.select('INBOX', function(inbox) {
     console.log(inbox);

From 4cc6bc4d7be45e87c21ddcfbd456662acfb4c297 Mon Sep 17 00:00:00 2001
From: Yazhong Liu <yorkiefixer@gmail.com>
Date: Mon, 30 Jun 2014 18:29:36 +0800
Subject: [PATCH 3/5] doc: fix some comments

---
 README.md   |  2 ++
 docs/API.md | 24 ++++++++++++++++--------
 2 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 81ace6a..de872b5 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@ imap.once('connect', function() {
 
 ```
 
+If you want to get more details, you could go to [API.md](docs/API.md).
+
 ### TODO
 
 * API `imap.seach`
diff --git a/docs/API.md b/docs/API.md
index fe5773b..c4365a7 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -6,7 +6,7 @@ The IMAPSession class the class that can be implemented to handle the IMAP opera
 
 #### Event: 'error'
 
-* err `Error` the error object
+* err `Error` the error object, an instance of `Error` class
 
 When an arbitrary error is raised, it will emit a 'error' event.
 
@@ -35,6 +35,14 @@ to avoid memroy leaks.
 * port Number, the port number of IMAP server
 * hostname String, the hostname of IMAP server
 * option Object, you config the authenticate option here
+  * `option.secure` String, the value of `ssl`, `starttls` and `none`(null)
+  * `option.auth` Object, the authenticate option you should defined
+    * `option.auth.username`, String
+    * `option.auth.password`, String, if you provide this field, then use `LOGIN` to authenticate, otherwise do `AUTHENTICATE`
+    * `option.auth.accessToken`, String, used by `AUTHENTICATE` command
+    * `option.auth.refreshToken`, String reversed
+    * `option.auth.clientId`, String reversed
+    * `option.auth.clientSecret`, String reversed
 
 Constructs an instance of IMAPSession with these 3 specified arguments, and an simple example for calling this constructor just is following:
 
@@ -58,8 +66,8 @@ The `option.auth` field before just use the plain to request the authentication,
 
 ```js
 {
-	username: 'yorkiefixer@gmail.com',
-	accessToken: 'your access_token'
+  username: 'yorkiefixer@gmail.com',
+  accessToken: 'your access_token'
 }
 ```
 
@@ -67,7 +75,9 @@ The `option.auth` field before just use the plain to request the authentication,
 
 #### imap.connect([callback])
 
-Start to create the connection to IMAP server, once you account has been authenticated/loged in, program would call `callback` and trigger the `connect` event.
+Start to create the connection to IMAP server, once your account has been authenticated/loged in, program would call `callback` and trigger the `connect` event.
+
+Theese `callback` and `connect` functions are zero-arguments function, then feel free to call them.
 
 #### imap.disconnect([callback])
 
@@ -96,21 +106,19 @@ Fetches the messages from you selected folder.
 
 The `SEARCH` command implementation.
 
-#### imap.appendMessage(folder, data, flags, date, callback)
+#### imap.appendMessage(folder, data, flags, callback)
 
 * folder String
 * data String, rfc822 message data
 * flags Array
-* date Date
 * callback Function
 
 Append message to you specified folder.
 
-#### imap.copyMessages(uids, dest, options, callback)
+#### imap.copyMessages(uids, dest, callback)
 
 * uids Array, a uid set like: `[1000, 1001, 1003]`
 * dest String, the folder that you want this message to
-* options Object
 * callback Function
 
 Copy the messages that you specified by `uids` to `dest` folder.
\ No newline at end of file

From 93021c1b63cd3ea15493b3dc63d5201c93acd75a Mon Sep 17 00:00:00 2001
From: Yazhong Liu <yorkiefixer@gmail.com>
Date: Mon, 30 Jun 2014 18:32:11 +0800
Subject: [PATCH 4/5] imap: remove options parameter of copyMessages: use only
 UID.

---
 lib/imapsession.js | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/imapsession.js b/lib/imapsession.js
index 9451886..239671c 100644
--- a/lib/imapsession.js
+++ b/lib/imapsession.js
@@ -109,12 +109,12 @@ IMAPSession.prototype.search = function(query, callback) {
   this.base.search(query, this.makeTrigger(callback));
 }
 
-IMAPSession.prototype.appendMessage = function(folder, data, flags, date, callback) {
+IMAPSession.prototype.appendMessage = function(folder, data, flags, callback) {
   this.base.appendMessage(folder, data, flags, date, this.makeTrigger(callback));
 }
 
-IMAPSession.prototype.copyMessages = function(uids, dest, options, callback) {
-  this.base.copy(uids, dest, options, this.makeTrigger(callback));
+IMAPSession.prototype.copyMessages = function(uids, dest, callback) {
+  this.base.copy(uids, dest, {}, this.makeTrigger(callback));
 }
 
 IMAPSession.prototype.makeTrigger = function(callback) {

From 4e5965ee523991b15bba69b9677c3d57c14ab10e Mon Sep 17 00:00:00 2001
From: Yazhong Liu <yorkiefixer@gmail.com>
Date: Tue, 1 Jul 2014 23:17:08 +0800
Subject: [PATCH 5/5] document the fetch* functions

---
 docs/API.md        | 45 ++++++++++++++++++++++++++++++---------------
 lib/imapsession.js |  2 +-
 2 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/docs/API.md b/docs/API.md
index c4365a7..7c530be 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -35,14 +35,13 @@ to avoid memroy leaks.
 * port Number, the port number of IMAP server
 * hostname String, the hostname of IMAP server
 * option Object, you config the authenticate option here
-  * `option.secure` String, the value of `ssl`, `starttls` and `none`(null)
-  * `option.auth` Object, the authenticate option you should defined
-    * `option.auth.username`, String
-    * `option.auth.password`, String, if you provide this field, then use `LOGIN` to authenticate, otherwise do `AUTHENTICATE`
-    * `option.auth.accessToken`, String, used by `AUTHENTICATE` command
-    * `option.auth.refreshToken`, String reversed
-    * `option.auth.clientId`, String reversed
-    * `option.auth.clientSecret`, String reversed
+  * `option.secure` String, the value of `ssl`, `starttls` and `none`. Default value is none.
+  * `option.auth.username`, String
+  * `option.auth.password`, String, if you provide this field, then use `LOGIN` to authenticate, otherwise do `AUTHENTICATE`
+  * `option.auth.accessToken`, String, used by `AUTHENTICATE` command
+  * `option.auth.refreshToken`, String reversed
+  * `option.auth.clientId`, String reversed
+  * `option.auth.clientSecret`, String reversed
 
 Constructs an instance of IMAPSession with these 3 specified arguments, and an simple example for calling this constructor just is following:
 
@@ -75,12 +74,14 @@ The `option.auth` field before just use the plain to request the authentication,
 
 #### imap.connect([callback])
 
-Start to create the connection to IMAP server, once your account has been authenticated/loged in, program would call `callback` and trigger the `connect` event.
+Start to create the connection to IMAP server, once your account has been authenticated/loged in, `callback` will be called and the `connect` event will be emitted.
 
-Theese `callback` and `connect` functions are zero-arguments function, then feel free to call them.
+These `callback` and `connect` functions are zero-arguments function: `function() { /* ... */ }`
 
 #### imap.disconnect([callback])
 
+* callback Function, `function() { /* ... */ }`
+
 End this session.
 
 #### imap.select(folder, callback)
@@ -94,10 +95,24 @@ Select a folder(mailbox).
 
 * start Number|String
 * end Number|String
-* option Number|Object|null TODO
+* option Array|String, default value: `["uid", "flags", "headers", "internal-date"]`
 * callback Function
 
-Fetches the messages from you selected folder.
+Fetches the messages from your selected folder. The element of `option` array could be the below listed string:
+
+* uid
+* flags
+* headers
+* structure
+* internal-date
+* full-headers
+* header-subject
+* gmail-labels
+* gmail-message-id
+* gmail-thread-id
+* size
+
+And the element of `option` could also be custom header string like `X-Mailer`, `X-Envelope-Sender`, `X-Mailing-List` and etc.
 
 #### imap.search(query, callback)
 
@@ -106,11 +121,11 @@ Fetches the messages from you selected folder.
 
 The `SEARCH` command implementation.
 
-#### imap.appendMessage(folder, data, flags, callback)
+#### imap.appendMessage(folder, data, [flags,] callback)
 
 * folder String
 * data String, rfc822 message data
-* flags Array
+* flags Array, the element of this array should be a string of `answered`, `flagged`, `deleted`, `seen` and `draft`.
 * callback Function
 
 Append message to you specified folder.
@@ -121,4 +136,4 @@ Append message to you specified folder.
 * dest String, the folder that you want this message to
 * callback Function
 
-Copy the messages that you specified by `uids` to `dest` folder.
\ No newline at end of file
+Copy the messages that you specified by `uids` to `dest` folder.
diff --git a/lib/imapsession.js b/lib/imapsession.js
index 239671c..913cd58 100644
--- a/lib/imapsession.js
+++ b/lib/imapsession.js
@@ -110,7 +110,7 @@ IMAPSession.prototype.search = function(query, callback) {
 }
 
 IMAPSession.prototype.appendMessage = function(folder, data, flags, callback) {
-  this.base.appendMessage(folder, data, flags, date, this.makeTrigger(callback));
+  this.base.appendMessage(folder, data, flags, this.makeTrigger(callback));
 }
 
 IMAPSession.prototype.copyMessages = function(uids, dest, callback) {