[MAJOR] SUBSCRIBE and UNSUBSCRIBE (#235)

Support for SUBSCRIBE and UNSUBSCRIBE commands.

http://tools.ietf.org/html/rfc3501#section-6.3.6
http://tools.ietf.org/html/rfc3501#section-6.3.7

Author: ltgorm

README.md

@@ -239,9 +239,39 @@ client.listNamespaces().then((namespaces) => { ... })
 }
 ```
 
+## Subscribe to mailbox
+
+Subscribe to a mailbox with the given path with `subscribeMailbox(path)`.
+
+Subscribing to a mailbox that is already subscribed is redundant and does return an OK just as when subscribing to unsubscribed mailbox.
+
+Command: [SUBSCRIBE](http://tools.ietf.org/html/rfc3501#section-6.3.6)
+
+Example
+
+```javascript
+// On a server with unsubscribed Sent mailbox
+client.subscribeMailbox('Sent').then(() => { ... });
+```
+
+## Unsubscribe from mailbox
+
+Unsubscribe from a mailbox with the given path with `unsubscribeMailbox(path)`.
+
+Unsubscribing from a mailbox that is already unsubscribed is redundant and does return an OK just as when unsubscribing from a subscribed mailbox.
+
+Command: [UNSUBSCRIBE](http://tools.ietf.org/html/rfc3501#section-6.3.7)
+
+Example
+
+```javascript
+// On a server with subscribed Sent mailbox
+client.unsubscribeMailbox('Sent').then(() => { ... });
+```
+
 ## Create mailbox
 
-Create a folder with the given path with `createMailbox(path)`, automatically handling utf-7 encoding. You currently need to manually build the path string yourself.
+Create a folder with the given path with `createMailbox(path)`. You currently need to manually build the path string yourself.
 
 If the server indicates a failure that the folder already exists, but responds with the ALREADYEXISTS response code, the request will be treated as a success.
 
@@ -260,7 +290,7 @@ client.createMailbox('Foo').then(() => { ... });
 ```
 ## Delete mailbox
 
-Delete a folder with the given path with `deleteMailbox(path)`, automatically handling utf-7 encoding.
+Delete a folder with the given path with `deleteMailbox(path)`.
 
 Command: [DELETE](http://tools.ietf.org/html/rfc3501#section-6.3.4)
 

src/client-integration.js

@@ -1,7 +1,7 @@
 /* eslint-disable no-unused-expressions */
 
 import hoodiecrow from 'hoodiecrow-imap'
-import ImapClient, { LOG_LEVEL_NONE as logLevel } from '..'
+import ImapClient, { LOG_LEVEL_NONE as logLevel } from '../src/index'
 import { parseSEARCH } from './command-parser'
 import { buildSEARCHCommand } from './command-builder'
 
@@ -199,6 +199,22 @@ describe('browserbox integration tests', () => {
       })
     })
 
+    describe('#subscribe', () => {
+      it('should succeed', () => {
+        return imap.subscribeMailbox('inbox').then(response => {
+          expect(response.command).to.equal('OK')
+        })
+      })
+    })
+
+    describe('#unsubscribe', () => {
+      it('should succeed', () => {
+        return imap.unsubscribeMailbox('inbox').then(response => {
+          expect(response.command).to.equal('OK')
+        })
+      })
+    })
+
     describe('#upload', () => {
       it('should succeed', () => {
         var msgCount

src/client-unit.js

@@ -582,18 +582,6 @@ describe('browserbox unit tests', () => {
       })
     })
 
-    it('should call mutf7 encode the argument', () => {
-      // From RFC 3501
-      br.exec.withArgs({
-        command: 'CREATE',
-        attributes: ['~peter/mail/&U,BTFw-/&ZeVnLIqe-']
-      }).returns(Promise.resolve())
-
-      return br.createMailbox('~peter/mail/\u53f0\u5317/\u65e5\u672c\u8a9e').then(() => {
-        expect(br.exec.callCount).to.equal(1)
-      })
-    })
-
     it('should treat an ALREADYEXISTS response as success', () => {
       var fakeErr = {
         code: 'ALREADYEXISTS'
@@ -624,18 +612,6 @@ describe('browserbox unit tests', () => {
         expect(br.exec.callCount).to.equal(1)
       })
     })
-
-    it('should call mutf7 encode the argument', () => {
-      // From RFC 3501
-      br.exec.withArgs({
-        command: 'DELETE',
-        attributes: ['~peter/mail/&U,BTFw-/&ZeVnLIqe-']
-      }).returns(Promise.resolve())
-
-      return br.deleteMailbox('~peter/mail/\u53f0\u5317/\u65e5\u672c\u8a9e').then(() => {
-        expect(br.exec.callCount).to.equal(1)
-      })
-    })
   })
 
   describe.skip('#listMessages', () => {
@@ -1001,6 +977,34 @@ describe('browserbox unit tests', () => {
     })
   })
 
+  describe('#subscribe and unsubscribe', () => {
+    beforeEach(() => {
+      sinon.stub(br, 'exec')
+    })
+
+    it('should call SUBSCRIBE with a string payload', () => {
+      br.exec.withArgs({
+        command: 'SUBSCRIBE',
+        attributes: ['mailboxname']
+      }).returns(Promise.resolve())
+
+      return br.subscribeMailbox('mailboxname').then(() => {
+        expect(br.exec.callCount).to.equal(1)
+      })
+    })
+
+    it('should call UNSUBSCRIBE with a string payload', () => {
+      br.exec.withArgs({
+        command: 'UNSUBSCRIBE',
+        attributes: ['mailboxname']
+      }).returns(Promise.resolve())
+
+      return br.unsubscribeMailbox('mailboxname').then(() => {
+        expect(br.exec.callCount).to.equal(1)
+      })
+    })
+  })
+
   describe('#hasCapability', () => {
     it('should detect existing capability', () => {
       br._capability = ['ZZZ']

src/client.js

@@ -1,5 +1,5 @@
 import { map, pipe, union, zip, fromPairs, propOr, pathOr, flatten } from 'ramda'
-import { imapEncode, imapDecode } from 'emailjs-utf7'
+import { imapDecode } from 'emailjs-utf7'
 import {
   parseAPPEND,
   parseCOPY,
@@ -281,6 +281,38 @@ export default class Client {
     return mailboxInfo
   }
 
+  /**
+   * Subscribe to a mailbox with the given path
+   *
+   * SUBSCRIBE details:
+   *   https://tools.ietf.org/html/rfc3501#section-6.3.6
+   *
+   * @param {String} path
+   *     The path of the mailbox you would like to subscribe to.
+   * @returns {Promise}
+   *     Promise resolves if mailbox is now subscribed to or was so already.
+   */
+  async subscribeMailbox (path) {
+    this.logger.debug('Subscribing to mailbox', path, '...')
+    return this.exec({ command: 'SUBSCRIBE', attributes: [path] })
+  }
+
+  /**
+   * Unsubscribe from a mailbox with the given path
+   *
+   * UNSUBSCRIBE details:
+   *   https://tools.ietf.org/html/rfc3501#section-6.3.7
+   *
+   * @param {String} path
+   *     The path of the mailbox you would like to unsubscribe from.
+   * @returns {Promise}
+   *     Promise resolves if mailbox is no longer subscribed to or was not before.
+   */
+  async unsubscribeMailbox (path) {
+    this.logger.debug('Unsubscribing to mailbox', path, '...')
+    return this.exec({ command: 'UNSUBSCRIBE', attributes: [path] })
+  }
+
   /**
    * Runs NAMESPACE command
    *
@@ -348,16 +380,15 @@ export default class Client {
    *   http://tools.ietf.org/html/rfc3501#section-6.3.3
    *
    * @param {String} path
-   *     The path of the mailbox you would like to create.  This method will
-   *     handle utf7 encoding for you.
+   *     The path of the mailbox you would like to create.
    * @returns {Promise}
    *     Promise resolves if mailbox was created.
    *     In the event the server says NO [ALREADYEXISTS], we treat that as success.
    */
   async createMailbox (path) {
     this.logger.debug('Creating mailbox', path, '...')
     try {
-      await this.exec({ command: 'CREATE', attributes: [imapEncode(path)] })
+      await this.exec({ command: 'CREATE', attributes: [path] })
     } catch (err) {
       if (err && err.code === 'ALREADYEXISTS') {
         return
@@ -373,14 +404,13 @@ export default class Client {
    *   https://tools.ietf.org/html/rfc3501#section-6.3.4
    *
    * @param {String} path
-   *     The path of the mailbox you would like to delete.  This method will
-   *     handle utf7 encoding for you.
+   *     The path of the mailbox you would like to delete.
    * @returns {Promise}
    *     Promise resolves if mailbox was deleted.
    */
   deleteMailbox (path) {
     this.logger.debug('Deleting mailbox', path, '...')
-    return this.exec({ command: 'DELETE', attributes: [imapEncode(path)] })
+    return this.exec({ command: 'DELETE', attributes: [path] })
   }
 
   /**