page: add pageViews() to interface with Pageviews API for WMF projects

README.md

@@ -16,7 +16,7 @@ Mwn uses [JSON with formatversion 2](https://www.mediawiki.org/wiki/API:JSON_ver
 
 Versioning: while mwn is in version 0, changes may be made to the public interface with a change in the minor version number.
 
-Complete API documentation is available **[here](https://tools-static.wmflabs.org/mwn/docs/classes/_bot_.mwn.html)** ([alternative link](https://mwn.toolforge.org/docs/classes/_bot_.mwn.html)). In addition to the MediaWiki Action API, the library also provides methods to talk to the Wikimedia EventStreams API, the ORES API and WikiWho API.
+Complete API documentation is available **[here](https://tools-static.wmflabs.org/mwn/docs/classes/_bot_.mwn.html)** ([alternative link](https://mwn.toolforge.org/docs/classes/_bot_.mwn.html)). In addition to the MediaWiki Action API, the library also provides methods to talk to the Wikimedia EventStreams API, the ORES API, Pageviews API and WikiWho API.
 
 Amongst the major highlights are `batchOperation` and `seriesBatchOperation` which allow you run a large number of tasks with control over concurrency and sleep time between tasks. Failing actions are automatically retried.
 

src/page.ts

@@ -38,6 +38,23 @@ export type logprop =
 	| 'tags'
 	| 'userid';
 
+export interface PageViewOptions {
+	access?: 'all-access' | 'desktop' | 'mobile-app' | 'mobile-web';
+	agent?: 'all-agents' | 'user' | 'spider' | 'automated';
+	granularity?: 'daily' | 'monthly';
+	start?: Date;
+	end?: Date;
+}
+export interface PageViewData {
+	project: string;
+	article: string;
+	granularity: string;
+	timestamp: string;
+	access: string;
+	agent: string;
+	views: number;
+}
+
 export interface ApiPage {
 	pageid: number;
 	ns: number;
@@ -135,6 +152,7 @@ export interface MwnPage extends MwnTitle {
 		type?: string,
 		customOptions?: ApiQueryLogEventsParams,
 	): AsyncGenerator<LogEvent>;
+	pageViews(options?: PageViewOptions): Promise<PageViewData[]>;
 	edit(transform: (rev: { content: string; timestamp: string }) => string | ApiEditPageParams): Promise<any>;
 	save(text: string, summary?: string, options?: ApiEditPageParams): Promise<any>;
 	newSection(header: string, message: string, additionalParams?: ApiEditPageParams): Promise<any>;
@@ -548,6 +566,50 @@ export default function (bot: mwn): MwnPageStatic {
 			}
 		}
 
+		/**
+		 * Get page views data (only for Wikimedia wikis)
+		 * @see https://wikitech.wikimedia.org/wiki/Analytics/AQS/Pageviews
+		 * @param options
+		 */
+		async pageViews(options: PageViewOptions = {}): Promise<PageViewData[]> {
+			let project = bot.options.apiUrl.match(/.*\/(.*?)\.(?:org|com|net)/)?.[1];
+			if (!project) {
+				throw new Error('Invalid API URL for using pageViews(). Only Wikimedia wikis are supported.');
+			}
+
+			// Set defaults
+			let { access, agent, granularity, start, end } = options;
+			access = access || 'all-access';
+			agent = agent || 'all-agents';
+			granularity = granularity || 'monthly';
+			if (granularity === 'daily') {
+				let date = new bot.date();
+				date.setUTCDate(date.getUTCDate() - 1);
+				start = start || date;
+				end = end || new bot.date();
+			} else if (granularity === 'monthly') {
+				let date = new bot.date();
+				date.setUTCDate(1);
+				date.setUTCMonth(date.getUTCMonth() - 1);
+				start = start || date;
+				end = end || new bot.date().setUTCDate(1);
+			}
+
+			let startString = new bot.date(start).format('YYYYMMDD'),
+				endString = new bot.date(end).format('YYYYMMDD');
+
+			return bot
+				.rawRequest({
+					url: `https://wikimedia.org/api/rest_v1/metrics/pageviews/per-article/${project}/${access}/${agent}/${this.toString()}/${granularity}/${startString}/${endString}`,
+					headers: {
+						'User-Agent': bot.options.userAgent,
+					},
+				})
+				.then((response) => {
+					return response.data.items;
+				});
+		}
+
 		/**** Post operations *****/
 		// Defined in bot.js
 

tests/suppl.bot.test.js

@@ -3,8 +3,9 @@ const { mwn, expect, sinon } = require('./test_base');
 describe('supplementary functions', function () {
 	this.timeout(5000);
 
-	var bot = new mwn({
+	const bot = new mwn({
 		apiUrl: 'https://en.wikipedia.org/w/api.php',
+		userAgent: 'https://github.com/siddharthvp/mwn (CI testing)'
 	});
 
 	it('ores (enwiki)', function () {
@@ -81,4 +82,24 @@ describe('supplementary functions', function () {
 			}
 		}, 500);
 	});
+
+	it('pageviews', async function () {
+		this.timeout(20000);
+		await bot.getSiteInfo();
+		let page = new bot.page('Albert Einstein');
+		let views = await page.pageViews();
+		expect(views).to.be.instanceOf(Array).of.length(1);
+		expect(views[0]).to.be.an('object').with.property('article').that.equals('Albert_Einstein');
+
+		views = await page.pageViews({
+			agent: 'user',
+			start: new bot.date('1 January 2021'),
+			end: new bot.date('5 March 2021')
+		});
+		expect(views).to.be.instanceOf(Array).of.length(2);
+		expect(views[0]).to.be.an('object').with.property('agent').that.equals('user');
+		expect(views[0]).to.be.an('object').with.property('timestamp').that.equals('2021010100');
+		expect(views[1]).to.be.an('object').with.property('timestamp').that.equals('2021020100');
+	});
+
 });