Merge pull request #35 from friendofdog/34-featured-content

Add method to get featured content by date

docs/optionTypes.md

@@ -7,6 +7,7 @@
 - [searchOptions](#searchOptions)
 - [geoOptions](#geoOptions)
 - [eventOptions](#eventOptions)
+- [fcOptions](#fcOptions)
 - [pdfOptions](#pdfOptions)
 
 ### pageOptions
@@ -79,6 +80,20 @@ The options for the onThisDay function on wiki object.
 - `month : string`(default = date.getMonth()) - Use this to pass the month you want as a string. By default, it will take current month.
 - `day : string`(default = date.getDay()) - Use this to pass the day you want as a string. By default, it will take current day.
 
+### fcOptions
+```js
+interface fcOptions {
+    year?: string,
+    month?: string,
+    day?: string
+}
+```
+The options for the featured content function on wiki object.
+
+- `year : string`(default = date.getYear()) - Use this to pass the year you want as a string. By default, it will take current year.
+- `month : string`(default = date.getMonth()) - Use this to pass the month you want as a string. By default, it will take current month.
+- `day : string`(default = date.getDay()) - Use this to pass the day you want as a string. By default, it will take current day.
+
 ### pdfOptions
 ```js
 interface pdfOptions {

docs/resultTypes.md

@@ -11,6 +11,7 @@
 - [languageResult](#languageResult)
 - [wikiMediaResult](#wikiMediaResult)
 - [eventResult](#eventResult)
+- [fcResult](#fcResult)
 - [relatedResult](#relatedResult)
 - [titleItem](#titleItem)
 - [mobileSections](#mobileSections)
@@ -211,6 +212,59 @@ interface eventResult {
 }
 ```
 
+### fcResult
+
+The result for the `featuredContent` function call.
+```js
+interface fcResult {
+  tfa: wikiSummary;
+  mostread: {
+    date: string;
+    articles: Array<wikiSummary>
+  };
+  image: {
+    title: string;
+    thumbnail: {
+      source: string;
+      width: number;
+      height: number;
+    };
+    image: {
+      source: string;
+      width: number;
+      height: number;
+    };
+    file_page: string;
+    artist: Artist;
+    credit: htmlText;
+    license: {
+      type: string;
+      code: string;
+    };
+    description: Description;
+    wb_entity_id: string;
+    structured: {
+      captions: {
+        [key: string]: string;
+      }
+    };
+  };
+  news: [
+    {
+      links: Array<wikiSummary>;
+      story: string;
+    }
+  ];
+  onthisday: [
+    {
+      text: string;
+      pages: Array<wikiSummary>;
+      year: number;
+    }
+  ]
+}
+```
+
 ### relatedResult
 
 The related result.

docs/wiki.md

@@ -7,6 +7,7 @@
     - [page()](#page)
     - [geoSearch()](#geoSearch)
     - [onThisDay()](#onThisDay)
+    - [featuredContent()](#featuredContent)
     - [languages()](#languages)
     - [setLang()](#setLang)
     - [suggest()](#suggest)
@@ -70,6 +71,28 @@ console.log(events); // returns all the events which happened today
 console.log(deaths); // returns all deaths which happened on Feb 28
 ```
 
+### featuredContent()
+
+Returns featured content of a given day, depending on input `year`, `month`, `day` arguments. By default, it will return featured content of the current day. Returns a array of [fcResult][27] object.
+
+```js
+featuredContent = async ({year: string, month: string, day: string}): Promise<fcResult>
+```
+- @param year - The year to search for. Takes current year by default.
+- @param month - The month to search for. Takes current month by default.
+- @param day - The day to search for. Takes current day by default.
+- @result [fcResult][27] - a fcResult object.
+
+```js
+//example
+const content = await wiki.featuredContent();
+const contentNewYear2020 = await wiki.featuredContent({year:'2020', month:'01', day:'01'});
+const contentNewYear = await wiki.featuredContent({month:'01', day:'01'});
+console.log(content); // returns featured content from today
+console.log(contentNewYear2020); // returns featured content from 2020-01-01
+console.log(contentNewYear); // returns featured content from 01-01 of this year
+```
+
 ### geoSearch()
 
 Searches for a page based on input `latitude`, `longitude` coordinates. Optionally takes a `limit` and `radius`(the search radius in meters) parameter in the [geoOptions][5] object. Returns an array of [geoSearchResult][6] object.
@@ -210,5 +233,6 @@ console.log(html); //Returns html for the environmentalist
 [24]: https://github.com/dopecodez/wikipedia/blob/master/docs/resultTypes.md#eventResult
 [25]: https://github.com/dopecodez/wikipedia/blob/master/docs/PAGE.md#mobileHtml
 [26]: https://github.com/dopecodez/wikipedia/blob/master/docs/PAGE.md#pdf
+[27]: https://github.com/dopecodez/wikipedia/blob/master/docs/resultTypes.md#fcResult
 
 

source/errors.ts

@@ -119,6 +119,13 @@ export class eventsError extends wikiError {
     }
 }
 
+export class fcError extends wikiError {
+    constructor(message: string) {
+        super(message);
+        this.name = 'featuredContentError';
+    }
+}
+
 export class pdfError extends wikiError {
     constructor(message: string) {
         super(message);

source/index.ts

@@ -1,21 +1,21 @@
 import request, { makeRestRequest, setAPIUrl } from './request'
-import { pageOptions, searchOptions, geoOptions, listOptions, eventOptions, randomFormats, pdfOptions, citationFormat } from './optionTypes';
+import { pageOptions, searchOptions, geoOptions, listOptions, eventOptions, fcOptions, randomFormats, pdfOptions, citationFormat } from './optionTypes';
 import Page, {
     intro, images, html, content, categories, links, coordinates, langLinks,
     references, infobox, tables, summary, related, media, mobileHtml, pdf, citation
 } from './page';
-import { coordinatesResult, eventResult, geoSearchResult, imageResult, langLinksResult, languageResult, 
+import { coordinatesResult, eventResult, featuredContentResult, geoSearchResult, imageResult, langLinksResult, languageResult, 
     mobileSections, relatedResult, 
     title, wikiMediaResult, wikiSearchResult, wikiSummary, notFound } from './resultTypes';
 import {
     categoriesError,
-    contentError, coordinatesError, eventsError, geoSearchError, htmlError, imageError, infoboxError,
+    contentError, coordinatesError, eventsError, fcError, geoSearchError, htmlError, imageError, infoboxError,
     introError, linksError, mediaError, pageError, relatedError, searchError, summaryError, wikiError,
     pdfError,
     citationError
 } from './errors';
 import { MSGS } from './messages';
-import { getCurrentDay, getCurrentMonth, setPageId, setPageIdOrTitleParam, setTitleForPage } from './utils';
+import { getCurrentDay, getCurrentMonth, getCurrentYear, setPageId, setPageIdOrTitleParam, setTitleForPage } from './utils';
 
 /**
  * The default wiki export
@@ -529,6 +529,28 @@ wiki.onThisDay = async (eventOptions: eventOptions = {}): Promise<eventResult> =
     }
 }
 
+/**
+ * Returns featured content for a given day
+ *
+ * @remarks
+ * The api returns content featured at a particular date
+ *
+ * @param fcOptions - the year/month/day of featured content by {@link fcOptions | eventOptions}
+ * @returns Returns the results as array of {@link fcResult | fcResult}
+ */
+wiki.featuredContent = async (fcOptions: fcOptions = {}): Promise<featuredContentResult> => {
+    try {
+        const yyyy = (fcOptions.year || getCurrentYear()).toString()
+        const mm = (fcOptions.month || getCurrentMonth()).toString().padStart(2, "0")
+        const dd = (fcOptions.day || getCurrentDay()).toString().padStart(2, "0")
+        const path = `feed/featured/${yyyy}/${mm}/${dd}`;
+        const result = await makeRestRequest(path, true);
+        return result;
+    } catch (error) {
+        throw new fcError(error);
+    }
+}
+
 /**
  * Returns a random page
  *

source/optionTypes.ts

@@ -31,6 +31,12 @@ export interface eventOptions {
     day?: string
 }
 
+export interface fcOptions {
+    year?: string,
+    month?: string,
+    day?: string
+}
+
 export type eventTypes =
     'all' | 'selected' | 'births' | 'deaths' | 'events' | 'holidays'
 

source/resultTypes.ts

@@ -106,6 +106,17 @@ export interface wikiSummary {
   }
 }
 
+export interface MostRead extends wikiSummary {
+  views: number;
+  rank: number;
+  view_history: [
+    {
+      date: string;
+      views: number;
+    }
+  ]
+}
+
 export interface wikiMediaResult {
   revision: string,
   tid: string,
@@ -239,10 +250,67 @@ export interface htmlText {
   text: string
 }
 
+export interface Artist extends htmlText {
+  name: string;
+  user_page?: string;
+}
+
+export interface Description extends htmlText {
+  lang: string;
+}
+
 export interface notFound {
   type: string,
   title: string,
   method: string,
   detail: string,
   uri: string
 }
+
+export interface featuredContentResult {
+  tfa: wikiSummary;
+  mostread: {
+    date: string;
+    articles: Array<wikiSummary>
+  };
+  image: {
+    title: string;
+    thumbnail: {
+      source: string;
+      width: number;
+      height: number;
+    };
+    image: {
+      source: string;
+      width: number;
+      height: number;
+    };
+    file_page: string;
+    artist: Artist;
+    credit: htmlText;
+    license: {
+      type: string;
+      code: string;
+    };
+    description: Description;
+    wb_entity_id: string;
+    structured: {
+      captions: {
+        [key: string]: string;
+      }
+    };
+  };
+  news: [
+    {
+      links: Array<wikiSummary>;
+      story: string;
+    }
+  ];
+  onthisday: [
+    {
+      text: string;
+      pages: Array<wikiSummary>;
+      year: number;
+    }
+  ]
+}

source/utils.ts

@@ -40,6 +40,13 @@ export function setPageId(params: any, results: any): number {
     return pageId;
 }
 
+//Get current year
+export function getCurrentYear(): number {
+    const date = new Date();
+    const year = date.getFullYear();
+    return (year);
+}
+
 //Get current month
 export function getCurrentMonth(): number {
     const date = new Date();

test/featuredContent.test.ts

@@ -0,0 +1,39 @@
+import { fcError } from '../source/errors';
+import * as request from '../source/request';
+import wiki from "../source/index";
+import { fcData } from './samples';
+const requestMock = jest.spyOn(request, "makeRestRequest");
+
+const fcMock = fcData;
+
+afterAll(() => {
+    requestMock.mockRestore();
+})
+
+test('Throws featured content error if response is error', async () => {
+    requestMock.mockImplementation(async () => { throw new Error("This is an error") });
+    const result = async () => {
+        await wiki.featuredContent({})
+    };
+    expect(result).rejects.toThrowError(fcError);
+});
+
+test('Returns with results as fcResult', async () => {
+    requestMock.mockImplementation(async () => { return fcMock });
+    const result = await wiki.featuredContent();
+    expect(result).toStrictEqual(fcMock);
+});
+
+test('Featured content method call with params passed and no padding', async () => {
+    requestMock.mockImplementation(async () => { return fcMock });
+    const result = await wiki.featuredContent({ year: '2020', month: '1', day: '1' });
+    expect(result).toStrictEqual(fcMock);
+    expect(requestMock).toBeCalledWith(`feed/featured/2020/01/01`, true);
+});
+
+test('Featured content method call with params passed', async () => {
+    requestMock.mockImplementation(async () => { return fcMock });
+    const result = await wiki.featuredContent({ year: '2020', month: '01', day: '01' });
+    expect(result).toStrictEqual(fcMock);
+    expect(requestMock).toBeCalledWith(`feed/featured/2020/01/01`, true);
+});