Merge pull request #13 from phillipj/feature/authenticator

Replaced ./auth.js with options.authenticator

Author: phillipj

Readme.md

@@ -8,7 +8,7 @@ Small module which helps you query the Plex Media Server HTTP API.
 
 Instantiate a PlexAPI client.
 
-The parameter can be a string representing the server's hostname, or an object with the following properties: 
+The parameter can be a string representing the server's hostname, or an object with the following properties:
 
 Options:
 - **hostname**: hostname where Plex Server runs
@@ -53,7 +53,7 @@ client.query("/").then(function (result) {
 
 **postQuery(uri) : Send a POST request and retrieve the response**
 
-This is identical to ```query(uri)```, except that the request will be a POST rather than a GET. 
+This is identical to ```query(uri)```, except that the request will be a POST rather than a GET.
 
 Note that the parameters can only be passed as a query string as part of the uri, which is all Plex requires. (```Content-Length``` will always be zero)
 
@@ -120,6 +120,45 @@ client.find("/").then(function (directories) {
 });
 ```
 
+## Authenticators
+
+An authenticator is used by plex-api to authenticate its request against Plex Servers with a PlexHome setup. The most common authentication mechanism is by username and password.
+
+You can provide your own custom authentication mechanism, read more about custom authenticators below.
+
+### Credentials: username and password
+
+Comes bundled with plex-api. Just provide `options.username` and `options.password` when creating a PlexAPI instance and you are good to go.
+
+See the [plex-api-credentials](https://www.npmjs.com/package/plex-api-credentials) module for more information about its inner workings.
+
+### Custom authenticator
+
+In its simplest form an `authenticator` is an object with **one required** function `authenticate()` which should return the autentication token needed by plex-api to satisfy Plex Server.
+
+An optional method `initialize()` could be implemented if you need reference to the created PlexAPI instance when it's created.
+
+```js
+{
+  // OPTIONAL
+  initialize: function(plexApi) {
+    // plexApi === the PlexAPI instance just created
+  },
+  // REQUIRED
+  authenticate: function(plexApi, callback) {
+    // plexApi === the PlexAPI instance requesting the authentication token
+
+    // invoke callback if something fails
+    if (somethingFailed) {
+      return callback(new Error('I haz no cluez about token!'));
+    }
+
+    // or when you have a token
+    callback(null, 'I-found-this-token');
+  }
+}
+```
+
 ## HTTP API Documentation
 For more information about the API capabilities, see the [unofficial Plex API documentation](https://code.google.com/p/plex-api/w/list).
 

lib/api.js

@@ -4,9 +4,9 @@ var url = require('url');
 var request = require('request');
 var Q = require('q');
 var xml2js = require('xml2js');
+var headers = require('plex-api-headers');
 
 var uri = require('./uri');
-var auth = require('./auth');
 
 var PLEX_SERVER_PORT = 32400;
 
@@ -18,6 +18,7 @@ function PlexAPI(options, deprecatedPort) {
     this.port = deprecatedPort || opts.port || PLEX_SERVER_PORT;
     this.username = opts.username;
     this.password = opts.password;
+    this.authenticator = opts.authenticator || this._credentialsAuthenticator();
     this.options = opts.options || {};
     this.options.identifier = this.options.identifier || uuid.v4();
     this.options.product = this.options.product || 'Node.js App';
@@ -35,6 +36,7 @@ function PlexAPI(options, deprecatedPort) {
     }
 
     this.serverUrl = 'http://' + hostname + ':' + this.port;
+    this._initializeAuthenticator();
 }
 
 PlexAPI.prototype.getHostname = function getHostname() {
@@ -91,32 +93,23 @@ PlexAPI.prototype._request = function _request(relativeUrl, method, parseRespons
         url: url.parse(reqUrl),
         encoding: null,
         method: method || 'GET',
-        headers: {
+        headers: headers(this, {
             'Accept': 'application/json',
-            'X-Plex-Client-Identifier': self.getIdentifier(),
-            'X-Plex-Product': self.options.product,
-            'X-Plex-Version': self.options.version,
-            'X-Plex-Device': self.options.device,
-            'X-Plex-Device-Name': self.options.deviceName,
-            'X-Plex-Platform': self.options.platform,
-            'X-Plex-Platform-Version': self.options.platformVersion,
-            'X-Plex-Provides': 'controller'
-        }
+            'X-Plex-Token': this.authToken,
+            'X-Plex-Username': this.username
+        })
     };
 
-    if (this.authToken) {
-        reqOpts.headers['X-Plex-Token'] = this.authToken;
-    }
-
-    if (this.username) {
-        reqOpts.headers['X-Plex-Username'] = this.username;
-    }
-
     request(reqOpts, function onResponse(err, response, body) {
         if (err) {
             return deferred.reject(err);
         }
         if (response.statusCode === 401) {
+            if (self.authenticator === undefined) {
+                return deferred.reject(new Error('Plex Server denied request, you must provide a way to authenticate! ' +
+                    'Read more about plex-api authenticators on https://www.npmjs.com/package/plex-api#authenticators'));
+            }
+
             return deferred.resolve(self._authenticate()
                 .then(function() {
                     return self._request(relativeUrl, method, parseResponse);
@@ -157,15 +150,35 @@ PlexAPI.prototype._authenticate = function _authenticate() {
         return deferred.reject(new Error('Permission denied even after attempted authentication :( Wrong username and/or password maybe?'));
     }
 
-    auth.retrieveAuthToken(self.username, self.password, self.options)
-        .then(function onAuthResult(token) {
-            self.authToken = token;
-            deferred.resolve();
-        });
+    this.authenticator.authenticate(this.options, function(err, token) {
+        if (err) {
+            return deferred.reject(new Error('Authentication failed, reason: ' + err.message));
+        }
+        self.authToken = token;
+        deferred.resolve();
+    });
 
     return deferred.promise;
 };
 
+PlexAPI.prototype._credentialsAuthenticator = function _credentialsAuthenticator() {
+    if (this.username && this.password) {
+        var credentials = require('plex-api-credentials');
+
+        return credentials({
+            username: this.username,
+            password: this.password
+        });
+    }
+    return undefined;
+};
+
+PlexAPI.prototype._initializeAuthenticator = function _initializeAuthenticator() {
+    if (this.authenticator && typeof this.authenticator.initialize === 'function') {
+        this.authenticator.initialize(this);
+    }
+};
+
 function filterChildrenByCriterias(children, criterias) {
     var context = {
         criterias: criterias || {}

lib/auth.js

@@ -7,6 +7,8 @@
     "test": "test"
   },
   "dependencies": {
+    "plex-api-credentials": "^2.0.0",
+    "plex-api-headers": "^1.0.0",
     "q": "^1.0.1",
     "request": "^2.36.0",
     "uuid": "^2.0.1",
@@ -17,10 +19,12 @@
     "jscs": "^1.11.3",
     "jshint": "^2.6.3",
     "mocha": "*",
-    "nock": "^1.2.1"
+    "nock": "^1.2.1",
+    "proxyquire": "^1.6.0",
+    "sinon": "^1.15.4"
   },
   "scripts": {
-    "test": "jshint lib/* && jscs lib/* && mocha --reporter list test/*-test.js"
+    "test": "jshint lib/* && jscs lib/* && mocha test/*-test.js"
   },
   "files": [
     "lib"