Add an APIHandler to Echo notifications

This simplifies the operation of the API a bit, but more importantly
this will let us create a demo where we can manipulate the API result
and test various new notification formats while the work on the
backend API responses is ongoing, and also will allow us to have a
constant test for all notifications types, including backwards
compatibility.

Change-Id: I6081329a287cda4f5f1f1604ace5d04ff8d9fe3d

Resources.php

@@ -60,7 +60,6 @@ $wgResourceModules += array(
 			'ext.echo.dm',
 			'oojs-ui',
 			'ext.echo.logger',
-			'mediawiki.api',
 			'mediawiki.jqueryMsg',
 			'mediawiki.language',
 		),
@@ -74,7 +73,6 @@ $wgResourceModules += array(
 			'echo-notification-alert-text-only',
 			'echo-notification-message-text-only',
 			'echo-email-batch-bullet',
-			'echo-api-failure',
 			'echo-notification-placeholder',
 			'tooltip-pt-notifications-alert',
 			'tooltip-pt-notifications-message',
@@ -87,13 +85,19 @@ $wgResourceModules += array(
 		'scripts' => array(
 			'viewmodel/mw.echo.dm.js',
 			'viewmodel/mw.echo.dm.NotificationItem.js',
+			'viewmodel/mw.echo.dm.AbstractAPIHandler.js',
+			'viewmodel/mw.echo.dm.APIHandler.js',
 			'viewmodel/mw.echo.dm.List.js',
 			'viewmodel/mw.echo.dm.NotificationList.js',
 			'viewmodel/mw.echo.dm.NotificationsModel.js',
 		),
 		'dependencies' => array(
+			'mediawiki.api',
 			'oojs'
 		),
+		'messages' => array(
+			'echo-api-failure',
+		),
 		'targets' => array( 'desktop', 'mobile' ),
 	),
 	'ext.echo.base' => array(

modules/ooui/mw.echo.ui.NotificationBadgeWidget.js

@@ -58,12 +58,17 @@
 		} );
 
 		// View model
-		this.notificationsModel = new mw.echo.dm.NotificationsModel( {
+		this.notificationsModel = new mw.echo.dm.NotificationsModel(
+			new mw.echo.dm.APIHandler( {
 				type: this.type,
 				limit: 25,
 				userLang: mw.config.get( 'wgUserLanguage' ),
-			apiData: mw.echo.apiCallParams
+				baseParams: mw.echo.apiCallParams
-		} );
+			} ),
+			{
+				type: this.type
+			}
+		);
 
 		// Notifications widget
 		this.notificationsWidget = new mw.echo.ui.NotificationsWidget(

modules/viewmodel/mw.echo.dm.APIHandler.js

@@ -0,0 +1,112 @@
+( function ( mw, $ ) {
+	/**
+	 * Notification API handler
+	 *
+	 * @class
+	 * @extends mw.echo.dm.AbstractAPIHandler
+	 *
+	 * @constructor
+	 * @param {Object} [config] Configuration object
+	 */
+	mw.echo.dm.APIHandler = function MwEchoDmAPIHandler( config ) {
+		config = config || {};
+
+		// Parent constructor
+		mw.echo.dm.APIHandler.parent.call( this, config );
+
+		this.api = new mw.Api( { ajax: { cache: false } } );
+	};
+
+	/* Setup */
+
+	OO.inheritClass( mw.echo.dm.APIHandler, mw.echo.dm.AbstractAPIHandler );
+
+	/**
+	 * @inheritdoc
+	 */
+	mw.echo.dm.APIHandler.prototype.fetchNotifications = function ( apiPromise ) {
+		var helper = this,
+			params = $.extend( { notsections: this.type }, this.getBaseParams() );
+
+		if ( !this.fetchNotificationsPromise || this.isFetchingErrorState() ) {
+			this.apiErrorState = false;
+			this.fetchNotificationsPromise = ( apiPromise || this.api.get( params ) )
+				.fail( function () {
+					// Mark API error state
+					helper.apiErrorState = true;
+				} )
+				.always( function () {
+					helper.fetchNotificationsPromise = null;
+				} );
+		}
+
+		return this.fetchNotificationsPromise;
+	};
+
+	/**
+	 * @inheritdoc
+	 */
+	mw.echo.dm.APIHandler.prototype.updateSeenTime = function () {
+		return this.api.postWithToken( 'edit', {
+			action: 'echomarkseen',
+			type: this.type
+		} )
+			.then( function ( data ) {
+				return data.query.echomarkseen.timestamp;
+			} );
+	};
+
+	/**
+	 * @inheritdoc
+	 */
+	mw.echo.dm.APIHandler.prototype.markAllRead = function () {
+		var model = this,
+			data = {
+				action: 'echomarkread',
+				uselang: this.userLang,
+				sections: this.type
+			};
+
+		return this.api.postWithToken( 'edit', data )
+			.then( function ( result ) {
+				return OO.getProp( result.query, 'echomarkread', model.type, 'rawcount' ) || 0;
+			} );
+	};
+
+	/**
+	 * @inheritdoc
+	 */
+	mw.echo.dm.APIHandler.prototype.markItemRead = function ( itemId ) {
+		var model = this,
+			data = {
+				action: 'echomarkread',
+				uselang: this.userLang,
+				list: itemId
+			};
+
+		return this.api.postWithToken( 'edit', data )
+			.then( function ( result ) {
+				return OO.getProp( result.query, 'echomarkread', model.type, 'rawcount' ) || 0;
+			} );
+	};
+
+	/**
+	 * @inheritdoc
+	 */
+	mw.echo.dm.APIHandler.prototype.fetchUnreadCount = function () {
+		var apiData = {
+				action: 'query',
+				meta: 'notifications',
+				notsections: this.type,
+				notmessageunreadfirst: 1,
+				notlimit: this.limit,
+				notprop: 'index|count',
+				uselang: this.userLang
+			};
+
+		return this.api.get( apiData )
+			.then( function ( result ) {
+				return OO.getProp( result.query, 'notifications', 'rawcount' ) || 0;
+			} );
+	};
+} )( mediaWiki, jQuery );

modules/viewmodel/mw.echo.dm.AbstractAPIHandler.js

@@ -0,0 +1,118 @@
+( function ( mw ) {
+	/**
+	 * Abstract notification API handler
+	 *
+	 * @abstract
+	 * @class
+	 * @mixins OO.EventEmitter
+	 *
+	 * @constructor
+	 * @param {Object} [config] Configuration object
+	 * @cfg {Object} [baseParams] The base parameters for all API calls
+	 *  done by the API handler
+	 * @cfg {number} [limit=25] The limit on how many notifications to fetch
+	 * @cfg {string} [type='alert'] Notification type
+	 * @cfg {string} [userLang='en'] User language
+	 */
+	mw.echo.dm.AbstractAPIHandler = function MwEchoDmAPIHandler( config ) {
+		config = config || {};
+
+		// Mixin constructor
+		OO.EventEmitter.call( this );
+
+		this.fetchNotificationsPromise = null;
+		this.apiErrorState = false;
+
+		this.type = config.type || 'alert';
+		this.limit = config.limit || 25;
+		this.userLang = config.userLang || 'en';
+		this.baseParams = config.baseParams || {};
+
+		this.api = null;
+	};
+
+	/* Setup */
+
+	OO.initClass( mw.echo.dm.AbstractAPIHandler );
+	OO.mixinClass( mw.echo.dm.AbstractAPIHandler, OO.EventEmitter );
+
+	/**
+	 * Fetch notifications from the API.
+	 *
+	 * @param {jQuery.Promise} [apiPromise] An existing promise querying the API for notifications.
+	 *  This allows us to send an API request external to the DM and have the model
+	 *  handle the operation as if it asked for the request itself, updating all that
+	 *  needs to be updated and emitting all proper events.
+	 * @return {jQuery.Promise} A promise that resolves with an object containing the
+	 *  notification items
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.fetchNotifications = null;
+
+	/**
+	 * Update the seen timestamp
+	 *
+	 * @return {jQuery.Promise} A promise that resolves with the seen timestamp
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.updateSeenTime = null;
+
+	/**
+	 * Mark all notifications as read
+	 *
+	 * @return {jQuery.Promise} A promise that resolves when all notifications
+	 *  are marked as read.
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.markAllRead = null;
+
+	/**
+	 * Update the read status of a notification item in the API
+	 *
+	 * @param {string} itemId Item id
+	 * @return {jQuery.Promise} A promise that resolves when the notifications
+	 *  are marked as read.
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.markItemRead = null;
+
+	/**
+	 * Query the API for unread count of the notifications in this model
+	 *
+	 * @return {jQuery.Promise} jQuery promise that's resolved when the unread count is fetched
+	 *  and the badge label is updated.
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.fetchUnreadCount = null;
+
+	/**
+	 * Check whether the model is fetching notifications from the API
+	 *
+	 * @return {boolean} The model is in the process of fetching from the API
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.isFetchingNotifications = function () {
+		return !!this.fetchNotificationsPromise;
+	};
+
+	/**
+	 * Check whether the model has an API error state flagged
+	 *
+	 * @return {boolean} The model is in API error state
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.isFetchingErrorState = function () {
+		return !!this.apiErrorState;
+	};
+
+	/**
+	 * Return the fetch notifications promise
+	 * @return {jQuery.Promise} Promise that is resolved when notifications are
+	 *  fetched from the API.
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.getFetchNotificationPromise = function () {
+		return this.fetchNotificationsPromise;
+	};
+
+	/**
+	 * Get the base params associated with this API handler
+	 *
+	 * @return {Object} Base API params
+	 */
+	mw.echo.dm.AbstractAPIHandler.prototype.getBaseParams = function () {
+		return this.baseParams;
+	};
+} )( mediaWiki );

modules/viewmodel/mw.echo.dm.NotificationsModel.js

@@ -6,12 +6,13 @@
 	 * @mixins OO.EventEmitter
 	 *
 	 * @constructor
+	 * @param {mw.echo.dm.AbstractAPIHandler} apiHandler API handler
 	 * @param {Object} [config] Configuration object
 	 * @cfg {string} [type='alert'] Notification type 'alert', 'message' or 'all'
 	 * @cfg {number} [limit=25] Notification limit
 	 * @cfg {string} [userLang] User language
 	 */
-	mw.echo.dm.NotificationsModel = function MwEchoDmNotificationsModel( config ) {
+	mw.echo.dm.NotificationsModel = function MwEchoDmNotificationsModel( apiHandler, config ) {
 		config = config || {};
 
 		// Mixin constructor
@@ -21,14 +22,10 @@
 		mw.echo.dm.List.call( this );
 
 		this.type = config.type || 'alert';
-		this.limit = config.limit || 25;
-		this.userLang = config.userLang || 'en';
 
-		this.api = new mw.Api( { ajax: { cache: false } } );
+		this.apiHandler = apiHandler;
-		this.fetchNotificationsPromise = null;
-		this.apiErrorState = false;
 
-		this.seenTime = mw.config.get( 'wgEchoSeenTime' );
+		this.seenTime = mw.config.get( 'wgEchoSeenTime' ) || {};
 
 		// Store references to unseen and unread notifications
 		this.unseenNotifications = new mw.echo.dm.NotificationList();
@@ -198,33 +195,6 @@
 		return this.seenTime[ this.type ];
 	};
 
-	/**
-	 * Check whether the model is fetching notifications from the API
-	 *
-	 * @return {boolean} The model is in the process of fetching from the API
-	 */
-	mw.echo.dm.NotificationsModel.prototype.isFetchingNotifications = function () {
-		return !!this.fetchNotificationsPromise;
-	};
-
-	/**
-	 * Check whether the model has an api error state flagged
-	 *
-	 * @return {boolean} The model is in api error state
-	 */
-	mw.echo.dm.NotificationsModel.prototype.isFetchingErrorState = function () {
-		return !!this.apiErrorState;
-	};
-
-	/**
-	 * Return the fetch notifications promise
-	 * @return {jQuery.Promise} Promise that is resolved when notifications were
-	 *  fetched from the API.
-	 */
-	mw.echo.dm.NotificationsModel.prototype.getFetchNotificationPromise = function () {
-		return this.fetchNotificationsPromise;
-	};
-
 	/**
 	 * Update the seen timestamp
 	 *
@@ -233,7 +203,6 @@
 	 */
 	mw.echo.dm.NotificationsModel.prototype.updateSeenTime = function () {
 		var i, len,
-			model = this,
 			items = this.unseenNotifications.getItems();
 
 		// Update the notifications seen status
@@ -242,16 +211,8 @@
 		}
 		this.emit( 'updateSeenTime' );
 
-		return this.api.postWithToken( 'edit', {
+		return this.apiHandler.updateSeenTime()
-			action: 'echomarkseen',
+			.then( this.setSeenTime.bind( this ) );
-			type: this.type
-		} )
-			.then( function ( data ) {
-				var time = data.query.echomarkseen.timestamp;
-
-				// Update seen time from the server
-				model.setSeenTime( time );
-			} );
 	};
 
 	/**
@@ -261,21 +222,13 @@
 	 * were marked as read.
 	 */
 	mw.echo.dm.NotificationsModel.prototype.markAllRead = function () {
-		var model = this,
+		var model = this;
-			data = {
-				action: 'echomarkread',
-				uselang: this.userLang,
-				sections: this.type
-			};
 
 		if ( !this.unreadNotifications.getItemCount() ) {
 			return $.Deferred().resolve( 0 ).promise();
 		}
 
-		return this.api.postWithToken( 'edit', data )
+		return this.apiHandler.markAllRead()
-			.then( function ( result ) {
-				return result.query.echomarkread[model.type].rawcount || 0;
-			} )
 			.then( function () {
 				var i, len,
 					items = model.unreadNotifications.getItems();
@@ -296,21 +249,11 @@
 	 * were marked as read.
 	 */
 	mw.echo.dm.NotificationsModel.prototype.markItemReadInApi = function ( itemId ) {
-		var model = this,
-			data = {
-				action: 'echomarkread',
-				uselang: this.userLang,
-				list: itemId
-			};
-
 		if ( !this.unreadNotifications.getItemCount() ) {
 			return $.Deferred().resolve( 0 ).promise();
 		}
 
-		return this.api.postWithToken( 'edit', data )
+		return this.apiHandler.markItemRead( itemId );
-			.then( function ( result ) {
-				return result.query.echomarkread[model.type].rawcount || 0;
-			} );
 	};
 
 	/**
@@ -324,19 +267,16 @@
 	 *  id's.
 	 */
 	mw.echo.dm.NotificationsModel.prototype.fetchNotifications = function ( apiPromise ) {
-		var model = this,
+		var model = this;
-			params = $.extend( { notsections: this.type }, mw.echo.apiCallParams );
 
 		// Rebuild the notifications promise either when it is null or when
 		// it exists in a failed state
-		if ( !this.fetchNotificationsPromise || this.isFetchingErrorState() ) {
+		return this.apiHandler.fetchNotifications( apiPromise )
-			this.apiErrorState = false;
-			this.fetchNotificationsPromise = ( apiPromise || this.api.get( params ) )
 			.then( function ( result ) {
-					var notifData, i, len, $content, wasSeen, wasRead, notificationModel,
+				var notifData, i, len, $content, notificationModel,
 					optionItems = [],
 					idArray = [],
-						data = result.query.notifications[model.type];
+					data = OO.getProp( result.query, 'notifications', model.type ) || { index: [] };
 
 				for ( i = 0, len = data.index.length; i < len; i++ ) {
 					notifData = data.list[ data.index[i] ];
@@ -349,13 +289,11 @@
 					// according to its type.
 					$content = $( $.parseHTML( notifData['*'] ) );
 
-						wasRead = !!notifData.read;
-						wasSeen = notifData.timestamp.mw <= model.getSeenTime();
 					notificationModel = new mw.echo.dm.NotificationItem(
 						notifData.id,
 						{
-								read: wasRead,
+							read: !!notifData.read,
-								seen: wasRead || wasSeen,
+							seen: !!notifData.read || notifData.timestamp.mw <= model.getSeenTime(),
 							timestamp: notifData.timestamp.mw,
 							category: notifData.category,
 							content: $content,
@@ -370,19 +308,8 @@
 				}
 				model.addItems( optionItems, 0 );
 
-					return idArray;
-				} )
-				.fail( function () {
-					// Mark API error state
-					model.apiErrorState = true;
-				} )
-				.always( function ( idArray ) {
-					model.fetchNotificationsPromise = null;
-
 				return idArray;
 			} );
-		}
-		return this.fetchNotificationsPromise;
 	};
 
 	/**
@@ -443,19 +370,33 @@
 	 *  and the badge label is updated.
 	 */
 	mw.echo.dm.NotificationsModel.prototype.fetchUnreadCountFromApi = function () {
-		var apiData = {
+		return this.apiHandler.fetchUnreadCount();
-				action: 'query',
-				meta: 'notifications',
-				notsections: this.getType(),
-				notmessageunreadfirst: 1,
-				notlimit: this.limit,
-				notprop: 'index|count',
-				uselang: this.userLang
 	};
 
-		return this.api.get( apiData )
+	/**
-			.then( function ( result ) {
+	 * Check whether the model is fetching notifications from the API
-				return OO.getProp( result.query, 'notifications', 'rawcount' ) || 0;
+	 *
-			} );
+	 * @return {boolean} The model is in the process of fetching from the API
+	 */
+	mw.echo.dm.NotificationsModel.prototype.isFetchingNotifications = function () {
+		return this.apiHandler.isFetchingNotifications();
+	};
+
+	/**
+	 * Check whether the model has an api error state flagged
+	 *
+	 * @return {boolean} The model is in api error state
+	 */
+	mw.echo.dm.NotificationsModel.prototype.isFetchingErrorState = function () {
+		return this.apiHandler.isFetchingErrorState();
+	};
+
+	/**
+	 * Return the fetch notifications promise
+	 * @return {jQuery.Promise} Promise that is resolved when notifications were
+	 *  fetched from the API.
+	 */
+	mw.echo.dm.NotificationsModel.prototype.getFetchNotificationPromise = function () {
+		return this.apiHandler.getFetchNotificationPromise();
 	};
 } )( mediaWiki, jQuery );