Merge branch 'release/v0.9.0'

History.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.9.0
+* Add automatic retries to session authorisation.
+* Deprecated session.authorise() in favour of supplying a token at creation.
+
 ## 0.8.4
 * Added some user functions to list of signed methods (maxkueng)
 * Added some library functions to list of write methods (maxkueng)

README.md

@@ -118,11 +118,36 @@ Events:
 
 ### LastFmSession
 
-    lastfm.session([user], [key]);
+    lastfm.session(options);
 
 Returns: a `LastFmSession` instance.
 
-If no key is supplied then the authorise() method must be used before the session can be used to make authenticated calls. See the last.fm API documentation for more info.
+If the user and session key are already known supply these in the options. Otherwise supply a token for authorisation. When a token is supplied the session will be authorised with Last.fm. If the user has not yet approved the token (desktop application flow) then authorisation will be automatically retried.
+
+See the last.fm API documentation for more info on Last.fm authorisation flow.
+
+Options:
+
+- *user*
+
+        User name, if known.
+
+- *key*
+
+        Session key, if known.
+
+- *token*
+
+        Token supplied by auth.getToken or web flow callback.
+
+- *retryInterval*
+
+        Time in milliseconds to leave between retries. Defaults to 10 seconds.
+
+- *handlers*
+
+        Default event handlers to attach to the session object on creation.
+
 
 Public properties:
 
@@ -138,6 +163,7 @@ Methods:
 
 - *authorise(token, [options])*
 
+        Deprecated. Use lastfm.session({ token: token }) instead.
         Authorises user with Last.fm api. See last.fm documentation. Options argument has handlers property that has default event handlers to attach to the LastFmSession instance.
 
 - *on(event, handler)*
@@ -152,16 +178,32 @@ Methods:
 
         Returns true if the session has been authorised or a key was specified in the constructor.
 
+- *cancel()*
+
+        Prevent any further authorisation retries. Only applies if token supplied.
+
 Events:
 
+- *success(session)*
+
+        Authorisation of session was successful.
+        Note: Only emitted if a token was supplied in options. Username/key combinations supplied in options are assumed to be valid.
+
 - *authorised(session)*
 
+        Deprecated: Use success instead.
         Authorisation of session was successful.
-        Note: Only emitted after a call to authorise(). Keys supplied in the constructor are assumed to be valid.
+
+- *retrying(retry)*
+
+       Authorisation request was not successful but will be retried after a delay. Retry object contains the following properties:  
+       `delay` - The time in milliseconds before the request will be retried.  
+       `error` - The error code returned by the Last.fm API.  
+       `message` - The error message returned by the Last.fm API.
 
 - *error(track, error)*
 
-        Ruh-roh.
+        The authorisation was not successful and will not be retried.
 
 ### LastFmUpdate
 
@@ -270,10 +312,10 @@ When requesting track info the `track` param can be either the track name or a t
 
     trackStream.start();
 
-    var session = lastfm.session();
-    session.authorise(token, {
+    var session = lastfm.session({
+       token: token,
        handlers: {
-          authorised: function(session) {
+          success: function(session) {
              lastfm.update('nowplaying', session, { track: track } );
              lastfm.update('scrobble', session, { track: track, timestamp: 12345678 });
           }

lib/lastfm/lastfm-session.js

@@ -1,15 +1,27 @@
 var LastFmBase = require("./lastfm-base");
 
-var LastFmSession = function(lastfm, user, key) {
-  var that = this;
-  LastFmBase.call(this);
-  user = user || "";
-  key = key || "";
+var LastFmSession = function(lastfm, options, key) {
+  options = options || { };
+  var that = this,
+      retry = true;
 
-  this.user = user;
+  LastFmBase.call(this);
+  if (typeof options !== "object") {
+    this.user = options || "";
+    this.key = key || "";
+  }
+  else {
+    this.user = options.user || "";
+    this.key = options.key || "";
+  }
 
-  this.key = key;
+  if (options.token) {
+    authorise(options.token, options);
+  }
 
+  /**
+   * @deprecated
+   */
   this.authorise = function(token, options) {
     authorise(token, options);
   };
@@ -18,19 +30,24 @@ var LastFmSession = function(lastfm, user, key) {
     return isAuthorised();
   }
 
+  this.cancel = function() {
+    retry = false;
+  }
+
   function authorise(token, options) {
     options = options || { };
 
     registerEventHandlers(options);
 
-    validateToken(token);
+    validateToken(token, options);
   }
 
   function registerEventHandlers(options) {
     that.registerHandlers(options.handlers);
   }
 
-  function validateToken(token) {
+  function validateToken(token, options) {
+    options = options || { };
     if (!token) {
       that.emit("error", new Error("No token supplied"));
       return;
@@ -41,11 +58,34 @@ var LastFmSession = function(lastfm, user, key) {
 
     request.on("success", authoriseSession);
 
-    request.on("error", bubbleError);
+    request.on("error", function handleError(error) {
+      if (shouldBeRetried(error)) {
+        if (!retry) {
+          return;
+        }
+        var delay = options.retryInterval || 10000;
+        that.emit("retrying", {
+          error: error.error,
+          message: error.message,
+          delay: delay
+        });
+        that.scheduleCallback(function() {
+          validateToken(token, options);
+        }, delay);
+        return;
+      }
+      bubbleError(error);
+    });
+  }
+
+  function shouldBeRetried(error) {
+    return error.error == 14 ||
+        error.error == 16 ||
+        error.error == 11;
   }
 
   function isAuthorised() {
-    return that.key && that.key !== '';
+    return that.key !== '';
   }
 
   function authoriseSession(result) {
@@ -55,6 +95,7 @@ var LastFmSession = function(lastfm, user, key) {
     }
     setSessionDetails(result.session);
     that.emit("authorised", that);
+    that.emit("success", that);
   }
 
   function setSessionDetails(session) {

package.json

@@ -1,7 +1,7 @@
 {
   "name": "lastfm",
   "description": "Read and write to Last.fm",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "author": "James Scott <jammus@gmail.com>",
   "contributors": [
     "Garrett Wilkin <garrett.wilkin@gmail.com> (http://geethink.com)",

tests/index.js

@@ -1,6 +1,7 @@
 require("./lastfm-node-test.js");
 require("./lastfm-recenttracks-stream-test.js");
 require("./lastfm-session-test.js");
+require("./lastfm-session-deprecatedflow-test.js");
 require("./lastfm-info-test.js");
 require("./lastfm-read-test.js");
 require("./lastfm-info-track-test.js");