Implement a .setHeaders() method for WPAPI and WPRequest objects (#315)

* Implement a `.setHeaders()` method for WPAPI and WPRequest objects

In response to #299, #312, and #314, this introduces a new .setHeaders()
prototype method for both WPAPI and WPRequest. `.setHeaders()` allows a
single WPRequest, or all requests generated from a WPAPI site client
instance, to be augmented with one or more custom HTTP headers. Providing
this functionality allows consumers of the wpapi library to utilize
custom authentication schemes (such as JWT) with the Authentication
header, to specify the preferred language of the response endpoints with
the Accept-Language header, and so on. Providing a general-purpose
interface is preferred in place of specifically implementing individual
methods for JWT auth, language preferences, or other specific headers
that a consumer of this library may want to send.

Closes #299, fixes #312, fixes #314

**Usage:**

If you need to send additional HTTP headers along with your request
(for example to provide a specific `Authorization` header for use with
alternative authentication schemes), you can use the `.setHeaders()`
method to specify one or more headers to send with the dispatched request:

```js
// Specify a single header to send with the outgoing request
wp.posts().setHeaders( 'Authorization', 'Bearer xxxxx.yyyyy.zzzzz' )...

// Specify multiple headers to send with the outgoing request
wp.posts().setHeaders({
    Authorization: 'Bearer xxxxx.yyyyy.zzzzz',
    'Accept-Language': 'pt-BR'
})...
```

You can also set headers on the WPAPI instance itself, which will then
be used for all subsequent requests created from that site instance:

```js
wp.setHeaders( 'Authorization', 'Bearer xxxxx.yyyyy.zzzzz' );
wp.users().me()...
wp.posts().id( unpublishedPostId )...
```

props to @anagio, @andreasvirkus, @gnarf, @Matthewnie, @mnivoliez,
and @mzalewski for the feature request, feedback & discussion

Author: kadamwhite

README.md

@@ -25,6 +25,7 @@ This library is an isomorphic client for the [WordPress REST API](http://develop
 - [Embedding Data](#embedding-data)
 - [Collection Pagination](#collection-pagination)
 - [Customizing HTTP Request Behavior](#customizing-http-request-behavior)
+  - [Specifying HTTP Headers](#specifying-http-headers)
 - [Authentication](#authentication)
 - [API Documentation](#api-documentation)
 - [Issues](#issues)
@@ -809,6 +810,35 @@ site.transport({
 ```
 
 Note that these transport methods are the internal methods used by `create` and `.update`, so the names of these methods therefore map to the HTTP verbs "get", "post", "put", "head" and "delete"; name your transport methods accordingly or they will not be used.
+### Specifying HTTP Headers
+
+If you need to send additional HTTP headers along with your request (for example to provide a specific `Authorization` header for use with alternative authentication schemes), you can use the `.setHeaders()` method to specify one or more headers to send with the dispatched request:
+
+#### Set headers for a single request
+
+```js
+// Specify a single header to send with the outgoing request
+wp.posts().setHeaders( 'Authorization', 'Bearer xxxxx.yyyyy.zzzzz' )...
+
+// Specify multiple headers to send with the outgoing request
+wp.posts().setHeaders({
+    Authorization: 'Bearer xxxxx.yyyyy.zzzzz',
+    'Accept-Language': 'pt-BR'
+})...
+```
+
+#### Set headers globally
+
+You can also set headers globally on the WPAPI instance itself, which will then be used for all subsequent requests created from that site instance:
+
+```js
+// Specify a header to be used by all subsequent requests
+wp.setHeaders( 'Authorization', 'Bearer xxxxx.yyyyy.zzzzz' );
+
+// These will now be sent with an Authorization header
+wp.users().me()...
+wp.posts().id( unpublishedPostId )...
+```
 
 ## Authentication
 

lib/constructors/wp-request.js

@@ -38,6 +38,7 @@ function WPRequest( options ) {
 		// Whitelisted options keys
 		'auth',
 		'endpoint',
+		'headers',
 		'username',
 		'password',
 		'nonce'
@@ -652,6 +653,39 @@ WPRequest.prototype.file = function( file, name ) {
 // HTTP Methods: Public Interface
 // ==============================
 
+/**
+ * Specify one or more headers to send with the dispatched HTTP request.
+ *
+ * @example Set a single header to be used on this request
+ *
+ *     request.setHeaders( 'Authorization', 'Bearer trustme' )...
+ *
+ * @example Set multiple headers to be used by this request
+ *
+ *     request.setHeaders({
+ *       Authorization: 'Bearer comeonwereoldfriendsright',
+ *       'Accept-Language': 'en-CA'
+ *     })...
+ *
+ * @method setHeaders
+ * @chainable
+ * @param {String|Object} headers The name of the header to set, or an object of
+ *                                header names and their associated string values
+ * @param {String}        [value] The value of the header being set
+ * @return {WPRequest} The WPRequest instance (for chaining)
+ */
+WPRequest.prototype.setHeaders = function( headers, value ) {
+	// We can use the same iterator function below to handle explicit key-value
+	// pairs if we convert them into to an object we can iterate over:
+	if ( typeof headers === 'string' ) {
+		headers = keyValToObj( headers, value );
+	}
+
+	this._options.headers = Object.assign( {}, this._options.headers || {}, headers );
+
+	return this;
+};
+
 /**
  * Get (download the data for) the specified resource
  *

lib/http-transport.js

@@ -16,7 +16,27 @@ var objectReduce = require( './util/object-reduce' );
 var isEmptyObject = require( './util/is-empty-object' );
 
 /**
- * Conditionally set basic authentication on a server request object
+ * Set any provided headers on the outgoing request object. Runs after _auth.
+ *
+ * @method _setHeaders
+ * @private
+ * @param {Object} request A superagent request object
+ * @param {Object} options A WPRequest _options object
+ * @param {Object} A superagent request object, with any available headers set
+ */
+function _setHeaders( request, options ) {
+	// If there's no headers, do nothing
+	if ( ! options.headers ) {
+		return request;
+	}
+
+	return objectReduce( options.headers, function( request, value, key ) {
+		return request.set( key, value );
+	}, request );
+}
+
+/**
+ * Conditionally set basic authentication on a server request object.
  *
  * @method _auth
  * @private
@@ -265,6 +285,7 @@ function _httpGet( wpreq, callback ) {
 	var url = wpreq.toString();
 
 	var request = _auth( agent.get( url ), wpreq._options );
+	request = _setHeaders( request, wpreq._options );
 
 	return invokeAndPromisify( request, callback, returnBody.bind( null, wpreq ) );
 }
@@ -284,6 +305,7 @@ function _httpPost( wpreq, data, callback ) {
 	var url = wpreq.toString();
 	data = data || {};
 	var request = _auth( agent.post( url ), wpreq._options, true );
+	request = _setHeaders( request, wpreq._options );
 
 	if ( wpreq._attachment ) {
 		// Data must be form-encoded alongside image attachment
@@ -312,6 +334,7 @@ function _httpPut( wpreq, data, callback ) {
 	data = data || {};
 
 	var request = _auth( agent.put( url ), wpreq._options, true ).send( data );
+	request = _setHeaders( request, wpreq._options );
 
 	return invokeAndPromisify( request, callback, returnBody.bind( null, wpreq ) );
 }
@@ -333,6 +356,7 @@ function _httpDelete( wpreq, data, callback ) {
 	checkMethodSupport( 'delete', wpreq );
 	var url = wpreq.toString();
 	var request = _auth( agent.del( url ), wpreq._options, true ).send( data );
+	request = _setHeaders( request, wpreq._options );
 
 	return invokeAndPromisify( request, callback, returnBody.bind( null, wpreq ) );
 }
@@ -349,6 +373,7 @@ function _httpHead( wpreq, callback ) {
 	checkMethodSupport( 'head', wpreq );
 	var url = wpreq.toString();
 	var request = _auth( agent.head( url ), wpreq._options );
+	request = _setHeaders( request, wpreq._options );
 
 	return invokeAndPromisify( request, callback, returnHeaders );
 }

tests/integration/custom-http-headers.js

@@ -0,0 +1,65 @@
+'use strict';
+var chai = require( 'chai' );
+// Variable to use as our "success token" in promise assertions
+var SUCCESS = 'success';
+// Chai-as-promised and the `expect( prom ).to.eventually.equal( SUCCESS ) is
+// used to ensure that the assertions running within the promise chains are
+// actually run.
+chai.use( require( 'chai-as-promised' ) );
+var expect = chai.expect;
+
+var WPAPI = require( '../../' );
+
+// Inspecting the titles of the returned posts arrays is an easy way to
+// validate that the right page of results was returned
+var getTitles = require( './helpers/get-rendered-prop' ).bind( null, 'title' );
+var base64credentials = new Buffer( 'apiuser:password' ).toString( 'base64' );
+
+describe( 'integration: custom HTTP Headers', function() {
+	var wp;
+
+	beforeEach(function() {
+		wp = new WPAPI({
+			endpoint: 'http://wpapi.loc/wp-json'
+		});
+	});
+
+	// Testing basic authentication is an acceptable proxy for whether a header
+	// value (Authentication:, in this case) is being set
+	it( 'can be provided using WPRequest#setHeaders()', function() {
+		var prom = wp.posts()
+			.setHeaders( 'Authorization', 'Basic ' + base64credentials )
+			.status([ 'future', 'draft' ])
+			.get()
+			.then(function( posts ) {
+				expect( getTitles( posts ) ).to.deep.equal([
+					'Scheduled',
+					'Draft'
+				]);
+				return SUCCESS;
+			});
+		return expect( prom ).to.eventually.equal( SUCCESS );
+	});
+
+	it( 'can be provided at the WPAPI instance level using WPAPI#setHeaders()', function() {
+		var authenticated = WPAPI
+			.site( 'http://wpapi.loc/wp-json' )
+			.setHeaders( 'Authorization', 'Basic ' + base64credentials );
+		var prom = authenticated.posts()
+			.status([ 'future', 'draft' ])
+			.get()
+			.then(function( posts ) {
+				expect( getTitles( posts ) ).to.deep.equal([
+					'Scheduled',
+					'Draft'
+				]);
+				return authenticated.users().me();
+			})
+			.then(function( me ) {
+				expect( me.slug ).to.equal( 'apiuser' );
+				return SUCCESS;
+			});
+		return expect( prom ).to.eventually.equal( SUCCESS );
+	});
+
+});

tests/unit/lib/constructors/wp-request.js

@@ -671,6 +671,85 @@ describe( 'WPRequest', function() {
 
 	});
 
+	describe( '.setHeaders()', function() {
+
+		it( 'method exists', function() {
+			expect( request ).to.have.property( 'setHeaders' );
+			expect( request.setHeaders ).to.be.a( 'function' );
+		});
+
+		it( 'will have no effect if called without any arguments', function() {
+			request.setHeaders();
+			expect( request._options.headers ).to.deep.equal({});
+		});
+
+		it( 'will set a header key/value pair', function() {
+			request.setHeaders( 'Authorization', 'Bearer sometoken' );
+			expect( request._options.headers ).to.deep.equal({
+				Authorization: 'Bearer sometoken'
+			});
+		});
+
+		it( 'will replace an existing header key/value pair', function() {
+			request
+				.setHeaders( 'Authorization', 'Bearer sometoken' )
+				.setHeaders( 'Authorization', 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==' );
+			expect( request._options.headers ).to.deep.equal({
+				Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
+			});
+		});
+
+		it( 'will set multiple header key/value pairs with chained calls', function() {
+			request
+				.setHeaders( 'Accept-Language', 'en-US' )
+				.setHeaders( 'Authorization', 'Bearer sometoken' );
+			expect( request._options.headers ).to.deep.equal({
+				'Accept-Language': 'en-US',
+				Authorization: 'Bearer sometoken'
+			});
+		});
+
+		it( 'will set multiple header key/value pairs when passed an object', function() {
+			request.setHeaders({
+				'Accept-Language': 'en-US',
+				Authorization: 'Bearer sometoken'
+			});
+			expect( request._options.headers ).to.deep.equal({
+				'Accept-Language': 'en-US',
+				Authorization: 'Bearer sometoken'
+			});
+		});
+
+		it( 'will replace multiple existing header key/value pairs when passed an object', function() {
+			request
+				.setHeaders({
+					'Accept-Language': 'en-US',
+					Authorization: 'Bearer sometoken'
+				})
+				.setHeaders({
+					'Accept-Language': 'pt-BR',
+					Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
+				});
+			expect( request._options.headers ).to.deep.equal({
+				'Accept-Language': 'pt-BR',
+				Authorization: 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
+			});
+		});
+
+		it( 'inherits headers from the constructor options object', function() {
+			request = new WPRequest({
+				endpoint: '/',
+				headers: {
+					'Accept-Language': 'pt-BR'
+				}
+			});
+			expect( request._options.headers ).to.deep.equal({
+				'Accept-Language': 'pt-BR'
+			});
+		});
+
+	});
+
 	describe( '.toString()', function() {
 
 		beforeEach(function() {

tests/unit/wpapi.js

@@ -772,6 +772,61 @@ describe( 'WPAPI', function() {
 
 		});
 
+		describe( '.setHeaders()', function() {
+
+			beforeEach(function() {
+				site = new WPAPI({ endpoint: 'http://my.site.com/wp-json' });
+			});
+
+			it( 'is defined', function() {
+				expect( site ).to.have.property( 'setHeaders' );
+				expect( site.setHeaders ).to.be.a( 'function' );
+			});
+
+			it( 'initializes site-wide headers object if called with no arguments', function() {
+				expect( site._options ).not.to.have.property( 'headers' );
+				site.setHeaders();
+				expect( site._options ).to.have.property( 'headers' );
+				expect( site._options.headers ).to.deep.equal({});
+			});
+
+			it( 'sets site-wide headers when provided a name-value pair', function() {
+				site.setHeaders( 'Accept-Language', 'en-US' );
+				expect( site._options ).to.have.property( 'headers' );
+				expect( site._options.headers ).to.deep.equal({
+					'Accept-Language': 'en-US'
+				});
+			});
+
+			it( 'sets site-wide headers when provided an object of header name-value pairs', function() {
+				site.setHeaders({
+					'Accept-Language': 'en-CA',
+					Authorization: 'Bearer sometoken'
+				});
+				expect( site._options ).to.have.property( 'headers' );
+				expect( site._options.headers ).to.deep.equal({
+					'Accept-Language': 'en-CA',
+					Authorization: 'Bearer sometoken'
+				});
+			});
+
+			it( 'passes headers to all subsequently-instantiated handlers', function() {
+				site.setHeaders({
+					'Accept-Language': 'en-IL',
+					Authorization: 'Bearer chicagostylepizza'
+				});
+				var req = site.root( '' );
+				expect( req ).to.have.property( '_options' );
+				expect( req._options ).to.be.an( 'object' );
+				expect( req._options ).to.have.property( 'headers' );
+				expect( req._options.headers ).to.deep.equal({
+					'Accept-Language': 'en-IL',
+					Authorization: 'Bearer chicagostylepizza'
+				});
+			});
+
+		});
+
 		describe( '.registerRoute()', function() {
 
 			it( 'is a function', function() {