Documented behaviour of getOAuthRequestToken

lib/oauth.js

@@ -459,22 +459,59 @@ exports.OAuth.prototype.post= function(url, oauth_token, oauth_token_secret, pos
   return this._putOrPost("POST", url, oauth_token, oauth_token_secret, post_body, post_content_type, callback);
 }
 
-exports.OAuth.prototype.getOAuthRequestToken= function(extraParams, callback) {
+/**
-  var httpMethod;
+ * Gets a request token from the OAuth provider and passes that information back
-  if( typeof extraParams == "function" ){
+ * to the calling code.
-    callback = extraParams;
+ *
-    extraParams = {};
+ * The callback should expect a function of the following form:
-  }
+ *
+ * function(err, token, token_secret, parsedQueryString) {} 
+ *
+ * This method has optional parameters so can be called in the following 3 ways:
+ *
+ * 1) Primary use case: Does a basic request with no extra parameters, using a POST
+ *  getOAuthRequestToken( callbackFunction )
+ *
+ * 2) As above but allows for provision of extra parameters to be sent as part of the query to the server (POST).
+ *  getOAuthRequestToken( extraParams, callbackFunction )
+ *
+ * 3) A basic request with no extra parameters, using a specified HTTP method
+ *  getOAuthRequestToken( httpMethod, callbackFunction )
+ *
+ * 4) A request with extra parameters that can using a specified HTTP method
+ *  getOAuthRequestToken(  httpMethod, extraParams, callbackFunction )
+ **/
+exports.OAuth.prototype.getOAuthRequestToken= function( httpMethod, extraParams, callback ) {
 
-  if( typeof callback == "string"){
+  if( typeof httpMethod == "function" ){ // 1
-    httpMethod = callback;
+    callback = httpMethod;
+    extraParams = {};
+    httpMethod= "POST";
+  } else {
+    if( typeof httpMethod == "string" && arguments.length == 2 ) {// 3 
+      callback= extraParams;
+      extraParams= {};
+    }
+    else if( typeof httpMethod == "string" && arguments.length == 3 ) {// 4
+      // the given arguments will match!
+    }
+    else { //2
+      if( arguments.length != 2) {
+        throw new Error("Invalid arguments passed.");
+      }
+      else {
+        callback= extraParams;
+        extraParams= httpMethod;
+        httpMethod= "GET";
+      }
+    }
   }
 
   // Callbacks are 1.0A related 
   if( this._authorize_callback ) {
     extraParams["oauth_callback"]= this._authorize_callback;
   }
-  this._performSecureRequest( null, null, httpMethod || "POST", this._requestUrl, extraParams, null, null, function(error, data, response) {
+  this._performSecureRequest( null, null, httpMethod, this._requestUrl, extraParams, null, null, function(error, data, response) {
     if( error ) callback(error);
     else {
       var results= querystring.parse(data);

tests/oauth.js

@@ -142,8 +142,12 @@ vows.describe('OAuth').addBatch({
           return oa;
         },
         'Use the provided HTTP method': function(oa) {
-          oa.getOAuthRequestToken(function() {}, "GET");
+          oa.getOAuthRequestToken("GET", function() {});
           assert.equal(oa.requestArguments[2], "GET");
+        },
+        'Use a POST by default': function(oa) {
+          oa.getOAuthRequestToken(function() {});
+          assert.equal(oa.requestArguments[2], "POST");
         }
     },
     'When get authorization header' : {