m3api-rest 0.1.0 → 0.1.1

package/CHANGES.md

@@ -5,6 +5,16 @@ This file records the changes in each m3api-rest release.
 The annotated tag (and GitLab release) for each version also lists the changes,
 but this file may sometimes contain later improvements (e.g. typo fixes).
 
+## v0.1.1 (2026-04-05)
+
+- Updated the library for the new network interface of m3api v1.1.0,
+  so that it can be used together with that version.
+  (This also unlocks many new features in m3api-rest,
+  which will be implemented in a subsequent release.)
+- Introduced a new error type, `IncompatibleResponseType`,
+  thrown if the server responds with an incompatible response type.
+- Updated dependencies.
+
 ## v0.1.0 (2026-01-01)
 
 Initial release, including:

package/index.js

@@ -114,6 +114,58 @@ export class UnexpectedResponseStatus extends Error {
 
 }
 
+/**
+ * An error representing a HTTP response with a content type incompatible with that requested.
+ * For example, if the API responded with HTML despite JSON having been requested.
+ * Note that, depending on server behavior, this condition may also be represented
+ * by a {@link RestApiClientError} with the status 406 Not Acceptable;
+ * {@link IncompatibleResponseType} is thrown by m3api-rest if the server responded
+ * with a successful status that nevertheless does not match the requested type.
+ */
+export class IncompatibleResponseType extends Error {
+
+	/**
+	 * @param {string} expectedType The expected MIME type.
+	 * @param {string} actualType The actual Content-Type response header.
+	 * @param {*} body The response body received from the API.
+	 */
+	constructor( expectedType, actualType, body ) {
+		super( `Incompatible REST API response type: expected ${ expectedType }, got ${ actualType }` );
+
+		if ( Error.captureStackTrace ) {
+			Error.captureStackTrace( this, IncompatibleResponseType );
+		}
+
+		this.name = 'IncompatibleResponseType';
+
+		/**
+		 * The MIME type expected by m3api-rest based on the method,
+		 * e.g. 'application/json' for {@link getJson} and related functions.
+		 *
+		 * @member {string}
+		 */
+		this.expectedType = expectedType;
+
+		/**
+		 * The actual Content-Type header returned by the server,
+		 * e.g. 'text/html; charset=utf-8; profile="https://www.mediawiki.org/wiki/Specs/HTML/2.8.0"'.
+		 *
+		 * @member {string}
+		 */
+		this.actualType = actualType;
+
+		/**
+		 * The response body.
+		 * The type of this member will depend on the Content-Type returned by the server
+		 * and on whether m3api-rest is able to decode that content type or not.
+		 *
+		 * @member {*}
+		 */
+		this.body = body;
+	}
+
+}
+
 /**
  * An Error representing an invalid body in the REST API response.
  */
@@ -241,25 +293,55 @@ export class InvalidPathParams extends Error {
 }
 
 /**
- * Check the status code of the response and potentially throw an error based on it.
+ * Determine whether this response contains JSON
+ * according to its headers.
  *
  * @private
- * @param {Object} internalResponse
+ * @param {Response} response
+ * @return {boolean}
  */
-function checkResponseStatus( internalResponse ) {
-	const { status, body } = internalResponse;
-	if ( !Number.isInteger( status ) || status < 100 || status > 599 ) {
-		// invalid status: RFC 9110 section 15 says treat it like 5xx
-		throw new RestApiServerError( status, body );
+function isResponseJson( response ) {
+	const contentType = response.headers.get( 'Content-Type' );
+	const [ mimeType ] = contentType.split( ';', 1 ); // split off ;charset=utf-8 and suchlike
+	return mimeType === 'application/json' ||
+		( mimeType.startsWith( 'application/' ) && mimeType.endsWith( '+json' ) );
+	// this accepts some technically invalid Content-Type headers
+	// (we don’t check if the part before +json is a valid subtype / token,
+	// cf. https://httpwg.org/specs/rfc9110.html#media.type)
+	// because there’s no reason to reject them
+}
+
+/**
+ * Get a version of the body of the response to put in an error.
+ *
+ * @private
+ * @param {Response} response
+ * @return {string|Object}
+ */
+async function getResponseBodyForError( response ) {
+	if ( isResponseJson( response ) ) {
+		return await response.json();
+	} else {
+		return await response.text();
 	}
+}
+
+/**
+ * Check the status code of the response and potentially throw an error based on it.
+ *
+ * @private
+ * @param {Response} response
+ */
+async function checkResponseStatus( response ) {
+	const { status } = response;
 	if ( status >= 500 ) {
-		throw new RestApiServerError( status, body );
+		throw new RestApiServerError( status, await getResponseBodyForError( response ) );
 	}
 	if ( status >= 400 ) {
-		throw new RestApiClientError( status, body );
+		throw new RestApiClientError( status, await getResponseBodyForError( response ) );
 	}
-	if ( status < 200 || status >= 300 ) {
-		throw new UnexpectedResponseStatus( status, body );
+	if ( status >= 300 ) {
+		throw new UnexpectedResponseStatus( status, await getResponseBodyForError( response ) );
 	}
 }
 
@@ -271,7 +353,7 @@ const responseStatuses = new WeakMap();
  * @param {Object|Array} response A response object returned by one of the request functions
  * ({@link getJson} etc.). Note that it must be exactly the object returned by the function
  * (compared by identity, i.e. `===`), not a serialization of it or anything similar.
- * @return {number} The HTTP status code, i.e. an integer between 100 and 599.
+ * @return {number} The HTTP status code, i.e. an integer between 200 and 599.
  * (And for a successful response, really only between 200 and 299.)
  */
 export function getResponseStatus( response ) {
@@ -286,16 +368,24 @@ export function getResponseStatus( response ) {
  * Get the body of the response and check that it’s valid JSON.
  *
  * @private
- * @param {Object} internalResponse
+ * @param {Response} response
  * @return {Object|Array}
  */
-function getResponseJson( internalResponse ) {
-	const { status, body } = internalResponse;
-	if ( typeof body === 'object' && body !== null ) {
-		responseStatuses.set( body, status );
-		return body;
+async function getResponseJson( response ) {
+	if ( isResponseJson( response ) ) {
+		const body = await response.json();
+		if ( typeof body === 'object' && body !== null ) {
+			responseStatuses.set( body, response.status );
+			return body;
+		} else {
+			throw new InvalidResponseBody( body );
+		}
 	} else {
-		throw new InvalidResponseBody( body );
+		throw new IncompatibleResponseType(
+			'application/json',
+			response.headers.get( 'Content-Type' ),
+			await response.text(),
+		);
 	}
 }
 
@@ -347,6 +437,7 @@ export function path( strings, ...values ) {
  * Substitute template expressions in the path,
  * taking values from the given params.
  *
+ * @private
  * @param {string} path The path with optional `{param}` expressions.
  * @param {Object|URLSearchParams} params The input params. Not modified.
  * @return {Object} The potentially modified path and params.
@@ -393,22 +484,6 @@ function substitutePathParams( path, params ) {
 	return { path: substitutedPath, params: copiedParams || params };
 }
 
-/**
- * Split a given URL for the m3api internal interface.
- *
- * @param {string} url
- * @return {Object}
- */
-function splitUrlForInternalInterface( url ) {
-	url = new URL( url );
-	const urlParams = {};
-	for ( const [ key, value ] of url.searchParams.entries() ) {
-		urlParams[ key ] = value;
-	}
-	url.search = '';
-	return { url: String( url ), urlParams };
-}
-
 /**
  * Make a GET request to a REST API endpoint and return the JSON-decoded body.
  *
@@ -424,22 +499,27 @@ function splitUrlForInternalInterface( url ) {
 export async function getJson( session, path, params, options = {} ) {
 	( { path, params } = substitutePathParams( path, params ) );
 	const restUrl = session.apiUrl.replace( /api\.php$/, 'rest.php' );
-	const { url, urlParams } = splitUrlForInternalInterface( restUrl + path );
-	params = { ...urlParams, ...params };
+	const url = new URL( restUrl + path );
+	for ( const [ name, value ] of Object.entries( params || {} ) ) {
+		url.searchParams.append( name, value );
+	}
 	const headers = {
 		accept: 'application/json',
 		...session.getRequestHeaders( options ),
 	};
-	const internalResponse = await session.internalGet( url, params, headers );
-	checkResponseStatus( internalResponse );
-	return getResponseJson( internalResponse );
+	const response = await session.fetch( url, {
+		method: 'GET',
+		headers,
+	} );
+	await checkResponseStatus( response );
+	return await getResponseJson( response );
 }
 
 /**
  * Make a POST request to a REST API endpoint and return the JSON-decoded body.
  *
  * @param {Session} session The m3api session to use for this request.
- * @param {string} path The resourcee path, e.g. `/v1/page`.
+ * @param {string} path The resource path, e.g. `/v1/page`.
  * Does not include the domain, script path, or `rest.php` endpoint.
  * Use the {@link path} tag function to build the path.
  * @param {URLSearchParams} params The request body.
@@ -453,19 +533,16 @@ export async function getJson( session, path, params, options = {} ) {
 export async function postForJson( session, path, params, options = {} ) {
 	( { path, params } = substitutePathParams( path, params ) );
 	const restUrl = session.apiUrl.replace( /api\.php$/, 'rest.php' );
-	const { url, urlParams } = splitUrlForInternalInterface( restUrl + path );
-	const bodyParams = {};
-	for ( const [ key, value ] of params ) {
-		if ( Object.prototype.hasOwnProperty.call( bodyParams, key ) ) {
-			throw new Error( `Duplicate param name not yet supported: ${ key }` );
-		}
-		bodyParams[ key ] = value;
-	}
+	const url = new URL( restUrl + path );
 	const headers = {
 		// accept: 'application/json', // skip this for now due to T412610
 		...session.getRequestHeaders( options ),
 	};
-	const internalResponse = await session.internalPost( url, urlParams, bodyParams, headers );
-	checkResponseStatus( internalResponse );
-	return getResponseJson( internalResponse );
+	const response = await session.fetch( url, {
+		method: 'POST',
+		headers,
+		body: params,
+	} );
+	await checkResponseStatus( response );
+	return await getResponseJson( response );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "m3api-rest",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"description": "m3api extension package to interact with the MediaWiki REST API.",
 	"main": "index.js",
 	"type": "module",
@@ -26,7 +26,7 @@
 		"node": ">=18.2.0"
 	},
 	"peerDependencies": {
-		"m3api": "~1.0.0"
+		"m3api": "~1.1.0"
 	},
 	"devDependencies": {
 		"chai": "^6.0.1",
@@ -36,7 +36,7 @@
 		"eslint-config-wikimedia": "^0.31.0",
 		"eslint-plugin-chai-friendly": "^1.0.1",
 		"jsdoc": "^4.0.3",
-		"m3api": "~1.0.0",
+		"m3api": "~1.1.0",
 		"mocha": "^11.1.0",
 		"npm-run-all": "^4.1.5"
 	},