diff --git a/README.md b/README.md index 85f2073..de872b5 100644 --- a/README.md +++ b/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: 'yorkiefixer@gmail.com', + 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 \ No newline at end of file diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..7c530be --- /dev/null +++ b/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: '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 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. 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); diff --git a/lib/imapsession.js b/lib/imapsession.js index 9451886..913cd58 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) { - 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) { 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;