imap, doc: documented stuffs on imapsession

README.md

@@ -1,4 +1,53 @@
+
 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
+```
+
+### Usage
+
+```js
+var imap = new IMAPSession(993, 'imap.gmail.com', {
+  secure: 'ssl',
+  auth: {
+    username: '[email protected]',
+    password: 'xxxxxxxxx'
+  }
+});
+
+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);
+  });
+});
+
+```
+
+If you want to get more details, you could go to [API.md](docs/API.md).
+
+### TODO
+
+* API `imap.seach`
+* API `imap.fetchMessagesByNumber` and `imap.fetchMessagesByUID`
+* API `imap.search`
+* API `imap.appendMessage`
+* API `imap.copyMessages`
+
+### License
+
+MIT

docs/API.md

@@ -0,0 +1,139 @@
+### 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, an instance of `Error` class
+
+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
+  * `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:
+
+```js
+var session = new IMAPSession(993, 'imap.gmail.com', {
+  secure: 'ssl',
+  auth: {
+    username: '[email protected]',
+    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: '[email protected]',
+  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 your account has been authenticated/loged in, `callback` will be called and the `connect` event will be emitted.
+
+These `callback` and `connect` functions are zero-arguments function: `function() { /* ... */ }`
+
+#### imap.disconnect([callback])
+
+* callback Function, `function() { /* ... */ }`
+
+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 Array|String, default value: `["uid", "flags", "headers", "internal-date"]`
+* callback Function
+
+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)
+
+* query String
+* callback Function
+
+The `SEARCH` command implementation.
+
+#### imap.appendMessage(folder, data, [flags,] callback)
+
+* folder String
+* data String, rfc822 message data
+* 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.
+
+#### imap.copyMessages(uids, dest, callback)
+
+* uids Array, a uid set like: `[1000, 1001, 1003]`
+* dest String, the folder that you want this message to
+* callback Function
+
+Copy the messages that you specified by `uids` to `dest` folder.

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);

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) {
-  this.base.appendMessage(folder, data, flags, date, this.makeTrigger(callback));
+IMAPSession.prototype.appendMessage = function(folder, data, flags, callback) {
+  this.base.appendMessage(folder, data, flags, 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) {

lib/index.js

@@ -0,0 +1,4 @@
+
+exports.IMAP 
+  = exports.IMAPSession 
+  = require('./imapsession').IMAPSession;