Introduce accessToken option to replace authorization

This is a better way to set the Authorization: request header – notice
how the usage recommendations in the README look nicer now. Fixes #32.

The old option is still supported, and you can also set both options
together as long as they’re consistent (m3api-oauth2 will do this to
stay forwards- and backwards-compatible). But as I’m not aware of any
other uses of the authorization option (i.e. cases where you’d want a
different scheme than “Bearer ${accessToken}”), I expect to remove it
later.

Author: lucaswerkmeister

CHANGES.md

@@ -7,6 +7,9 @@ but this file may sometimes contain later improvements (e.g. typo fixes).
 
 ## next (not yet released)
 
+- The new `accessToken` option can be used to set the `Authorization` header more easily.
+  The previous `authorization` option is kept for compatibility,
+  but deprecated, demoted to the internal interface, and will be removed in a future minor version.
 - m3api now includes TypeScript `.d.ts` declaration files in the `types/` directory.
   Hopefully these will be useful to some users of the library.
 - Clarified `DEFAULT_OPTIONS` conventions a bit (adding `errorHandlers` is fine).

README.md

@@ -194,10 +194,10 @@ Other features not demonstrated above:
   This is mostly useful in library code, when you don’t know the `formatversion` of the response;
   you can import the helper from `core.js` (but not `browser.js` or `node.js`).
 
-- The `authorization` request option can be used to set the `Authorization` request header.
+- The `accessToken` request option can be used to
+  send an OAuth 2.0 access token in the `Authorization` request header.
   You can use this directly with an owner-only OAuth 2.0 client,
-  by setting the option to the string `Bearer ACCESS_TOKEN`
-  (where *ACCESS_TOKEN* is the access token MediaWiki generated for you);
+  where MediaWiki will show you the access token right after registering the client;
   to use a regular OAuth 2.0 client and make requests authenticated as another user,
   use the [m3api-oauth2][] extension package.
 
@@ -378,7 +378,7 @@ const session = new Session( 'en.wikipedia.org', { // or other domain
 }, {
 	userAgent: TODO,
 	maxRetriesSeconds: 3600, // or other high value
-	authorization: `Bearer ${accessToken}`,
+	accessToken: accessToken,
 } );
 
 // ...
@@ -411,7 +411,7 @@ await session.request( {
 
 - To authenticate the bot, create an owner-only OAuth 2 client,
   save the access token in a suitable secret store,
-  specify <code>Bearer <var>accessToken</var></code> as the `authorization` option,
+  set the `accessToken` option to the access token,
   and include `assert: 'user'` (and, if you like, <code>assertuser: '<var>user name</var>'</code>) in the default parameters.
   If the wiki you’re targeting doesn’t support OAuth 2,
   you may instead want to use the [m3api-botpassword][] extension package (see below).

core.js

@@ -103,11 +103,17 @@
  * you don’t need to see this warning and can use this option to suppress it.
  * This option defaults to false in {@link Session#request} (i.e. treat the warning like any other),
  * but to true in {@link Session#requestAndContinueReducingBatch}.
+ * @property {string} [accessToken] An OAuth 2.0 access token.
+ * If this option is set, the Authorization request header will be set to `Bearer ${ accessToken }`.
+ * You can get a token directly from an owner-only OAuth 2.0 client,
+ * or you can use the m3api-oauth2 extension package to authorize a user via OAuth.
+ * (In the latter case, you do not have to set this option: m3api-oauth2 will do it.)
  * @property {string} [authorization] Value for the Authorization request header.
- * This option can be used to authenticate requests using OAuth 2.0.
- * For an owner-only client / consumer, where you have an access token,
- * you can set this option to `Bearer ${ accessToken }` directly.
- * Otherwise, use the m3api-oauth2 extension package.
+ * This option is deprecated in favor of accessToken above,
+ * and only kept for backwards compatibility.
+ * It is part of the internal interface, rather than the public interface,
+ * and will be removed in a future minor version of m3api
+ * (unless someone presents a use case for it that is not covered by the accessToken option).
  * @property {Object.<string, ErrorHandler>} [errorHandlers] Internal option.
  * Define handlers for API errors, which can retry the request if appropriate.
  * This option is only part of the internal interface, not of the stable, public interface.
@@ -186,6 +192,7 @@ const DEFAULT_OPTIONS = {
 	retryAfterReadonlySeconds: 30,
 	warn: console.warn,
 	dropTruncatedResultWarning: false,
+	accessToken: null,
 	authorization: null,
 	errorHandlers: {
 		maxlag: ( session, params, options, internalResponse, error ) => {
@@ -722,11 +729,7 @@ class Session {
 		const requestHeaders = {
 			'user-agent': this.getUserAgent( options ),
 		};
-		const { authorization } = {
-			...DEFAULT_OPTIONS,
-			...this.defaultOptions,
-			...options,
-		};
+		const authorization = this.getAuthorizationHeader( options );
 		if ( authorization ) {
 			requestHeaders.authorization = authorization;
 		}
@@ -762,6 +765,43 @@ class Session {
 		}
 	}
 
+	/**
+	 * Get the Authorization: header for these options.
+	 *
+	 * @protected
+	 * @param {Options} options
+	 * @return {string|null}
+	 */
+	getAuthorizationHeader( options ) {
+		const {
+			accessToken,
+			authorization,
+		} = {
+			...DEFAULT_OPTIONS,
+			...this.defaultOptions,
+			...options,
+		};
+
+		if ( accessToken ) {
+			const expectedAuthorization = `Bearer ${ accessToken }`;
+			if ( authorization ) {
+				if ( authorization === expectedAuthorization ) {
+					return authorization;
+				} else {
+					throw new Error(
+						`Inconsistent authorization and accessToken options: ${ authorization } != ${ expectedAuthorization }`,
+					);
+				}
+			} else {
+				return expectedAuthorization;
+			}
+		} else if ( authorization ) {
+			return authorization;
+		} else {
+			return null;
+		}
+	}
+
 	/**
 	 * @private
 	 * @param {Params} params

test/unit/core.test.js

@@ -606,14 +606,14 @@ describe( 'Session', () => {
 			} );
 
 			for ( const [ name, defaultOptions, options ] of [
-				[ 'defaultOptions', { authorization: 'the-authorization-header' }, {} ],
-				[ 'options', {}, { authorization: 'the-authorization-header' } ],
+				[ 'accessToken in defaultOptions', { accessToken: 'the-access-token' }, {} ],
+				[ 'accessToken in options', {}, { accessToken: 'the-access-token' } ],
 			] ) {
-				it( `in ${ name }`, async () => {
+				it( name, async () => {
 					let called = false;
 					class TestSession extends BaseTestSession {
 						async internalGet( apiUrl, params, { authorization } ) {
-							expect( authorization ).to.equal( 'the-authorization-header' );
+							expect( authorization ).to.equal( 'Bearer the-access-token' );
 							expect( called, 'not called yet' ).to.be.false;
 							called = true;
 							return {
@@ -629,6 +629,72 @@ describe( 'Session', () => {
 					expect( called ).to.be.true;
 				} );
 			}
+
+			for ( const [ name, defaultOptions, options ] of [
+				[ 'authorization in defaultOptions', { authorization: 'the-authorization' }, {} ],
+				[ 'authorization in options', {}, { authorization: 'the-authorization' } ],
+			] ) {
+				it( name, async () => {
+					let called = false;
+					class TestSession extends BaseTestSession {
+						async internalGet( apiUrl, params, { authorization } ) {
+							expect( authorization ).to.equal( 'the-authorization' );
+							expect( called, 'not called yet' ).to.be.false;
+							called = true;
+							return {
+								status: 200,
+								headers: {},
+								body: { response: true },
+							};
+						}
+					}
+
+					const session = new TestSession( 'en.wikipedia.org', {}, defaultOptions );
+					await session.request( {}, options );
+					expect( called ).to.be.true;
+				} );
+			}
+
+			it( 'accessToken consistent with authorization', async () => {
+				let called = false;
+				class TestSession extends BaseTestSession {
+					async internalGet( apiUrl, params, { authorization } ) {
+						expect( authorization ).to.equal( 'Bearer the-access-token' );
+						expect( called, 'not called yet' ).to.be.false;
+						called = true;
+						return {
+							status: 200,
+							headers: {},
+							body: { response: true },
+						};
+					}
+				}
+
+				const session = new TestSession( 'en.wikipedia.org' );
+				await session.request( {}, {
+					authorization: 'Bearer the-access-token',
+					accessToken: 'the-access-token',
+				} );
+				expect( called ).to.be.true;
+			} );
+
+			it( 'accessToken inconsistent with authorization', async () => {
+				let called = false;
+				class TestSession extends BaseTestSession {
+					async internalGet() {
+						called = true;
+						throw new Error( 'Should not be called in this test' );
+					}
+				}
+
+				const session = new TestSession( 'en.wikipedia.org', {}, {
+					authorization: 'the-authorization',
+					accessToken: 'the-access-token',
+				} );
+				await expect( session.request( {} ) )
+					.to.be.rejected;
+				expect( called ).to.be.false;
+			} );
 		} );
 
 		describe( 'automatic retry', () => {

types/core.d.ts

@@ -109,12 +109,21 @@ export type Options = {
      * but to true in {@link Session#requestAndContinueReducingBatch}.
      */
     dropTruncatedResultWarning?: boolean;
+    /**
+     * An OAuth 2.0 access token.
+     * If this option is set, the Authorization request header will be set to `Bearer ${ accessToken }`.
+     * You can get a token directly from an owner-only OAuth 2.0 client,
+     * or you can use the m3api-oauth2 extension package to authorize a user via OAuth.
+     * (In the latter case, you do not have to set this option: m3api-oauth2 will do it.)
+     */
+    accessToken?: string;
     /**
      * Value for the Authorization request header.
-     * This option can be used to authenticate requests using OAuth 2.0.
-     * For an owner-only client / consumer, where you have an access token,
-     * you can set this option to `Bearer ${ accessToken }` directly.
-     * Otherwise, use the m3api-oauth2 extension package.
+     * This option is deprecated in favor of accessToken above,
+     * and only kept for backwards compatibility.
+     * It is part of the internal interface, rather than the public interface,
+     * and will be removed in a future minor version of m3api
+     * (unless someone presents a use case for it that is not covered by the accessToken option).
      */
     authorization?: string;
     /**
@@ -257,11 +266,17 @@ export type InternalResponse = {
  * you don’t need to see this warning and can use this option to suppress it.
  * This option defaults to false in {@link Session#request} (i.e. treat the warning like any other),
  * but to true in {@link Session#requestAndContinueReducingBatch}.
+ * @property {string} [accessToken] An OAuth 2.0 access token.
+ * If this option is set, the Authorization request header will be set to `Bearer ${ accessToken }`.
+ * You can get a token directly from an owner-only OAuth 2.0 client,
+ * or you can use the m3api-oauth2 extension package to authorize a user via OAuth.
+ * (In the latter case, you do not have to set this option: m3api-oauth2 will do it.)
  * @property {string} [authorization] Value for the Authorization request header.
- * This option can be used to authenticate requests using OAuth 2.0.
- * For an owner-only client / consumer, where you have an access token,
- * you can set this option to `Bearer ${ accessToken }` directly.
- * Otherwise, use the m3api-oauth2 extension package.
+ * This option is deprecated in favor of accessToken above,
+ * and only kept for backwards compatibility.
+ * It is part of the internal interface, rather than the public interface,
+ * and will be removed in a future minor version of m3api
+ * (unless someone presents a use case for it that is not covered by the accessToken option).
  * @property {Object.<string, ErrorHandler>} [errorHandlers] Internal option.
  * Define handlers for API errors, which can retry the request if appropriate.
  * This option is only part of the internal interface, not of the stable, public interface.
@@ -512,6 +527,14 @@ export class Session {
     protected getUserAgent(options: Options): string;
     /** @private */
     private warnedDefaultUserAgent;
+    /**
+     * Get the Authorization: header for these options.
+     *
+     * @protected
+     * @param {Options} options
+     * @return {string|null}
+     */
+    protected getAuthorizationHeader(options: Options): string | null;
     /**
      * @private
      * @param {Params} params