feat: Favorite timeline wrappers

Author: alkihis

changelog.md

@@ -1,3 +1,8 @@
+PENDING
+-------
+- Feat: .favoriteTimeline for API v1 #296 (thanks to @AuroraDysis)
+- Feat: `duration_millis` property for v1 medias (thanks to @RyoshiKayo)
+
 1.12.2
 ------
 - Feat: .homeTimeline for API v2 #288

doc/v1.md

@@ -21,6 +21,9 @@ For streaming API, see [Streaming part](./streaming.md).
 	* [User timeline](#Usertimeline)
 		* [By user ID](#ByuserID)
 		* [By username](#Byusername)
+	* [Favorites timeline](#Favoritestimeline)
+		* [By user ID](#ByuserID-1)
+		* [By username](#Byusername-1)
 * [Post and retrieve tweets](#Postandretrievetweets)
 	* [Create a tweet](#Createatweet)
 	* [Reply to a tweet](#Replytoatweet)
@@ -217,6 +220,58 @@ const userTimeline = await client.v1.userTimelineByUsername('plhery');
 const fetchedTweets = userTimeline.tweets;
 ```
 
+### <a name='Favoritestimeline'></a>Favorites timeline
+
+#### <a name='ByuserID-1'></a>By user ID
+
+Last favorited tweets of `userId` user.
+Get to know how [paginators work here](./paginators.md).
+
+Tweet mode is `extended` by default.
+
+**Method**: `.favoriteTimeline()`
+
+**Endpoint**: `favorites/list.json`
+
+**Right level**: `Read-only`
+
+**Arguments**:
+  - `userId: string`
+  - `options?: TweetV1UserTimelineParams`
+
+**Returns**: `UserFavoritesV1Paginator`
+
+**Example**
+```ts
+const favoritesTimeline = await client.v1.favoriteTimeline('12');
+const fetchedTweets = favoritesTimeline.tweets;
+```
+
+#### <a name='Byusername-1'></a>By username
+
+Last favorited tweets of @`username` user.
+Get to know how [paginators work here](./paginators.md).
+
+Tweet mode is `extended` by default.
+
+**Method**: `.favoriteTimelineByUsername()`
+
+**Endpoint**: `favorites/list.json`
+
+**Right level**: `Read-only`
+
+**Arguments**:
+  - `username: string`
+  - `options?: TweetV1UserTimelineParams`
+
+**Returns**: `UserFavoritesV1Paginator`
+
+**Example**
+```ts
+const favoritesTimeline = await client.v1.favoriteTimelineByUsername('plhery');
+const fetchedTweets = favoritesTimeline.tweets;
+```
+
 ## <a name='Postandretrievetweets'></a>Post and retrieve tweets
 
 ### <a name='Createatweet'></a>Create a tweet

src/paginators/tweet.paginator.v1.ts

@@ -85,3 +85,8 @@ export class UserTimelineV1Paginator extends TweetTimelineV1Paginator<TweetV1Tim
 export class ListTimelineV1Paginator extends TweetTimelineV1Paginator<TweetV1TimelineResult, ListStatusesV1Params> {
   protected _endpoint = 'lists/statuses.json';
 }
+
+// Favorites
+export class UserFavoritesV1Paginator extends TweetTimelineV1Paginator<TweetV1TimelineResult, TweetV1UserTimelineParams> {
+  protected _endpoint = 'favorites/list.json';
+}

src/v1/client.v1.read.ts

@@ -58,7 +58,7 @@ import {
   ListStatusesV1Params,
   ListSubscriptionsV1Params,
 } from '../types';
-import { HomeTimelineV1Paginator, ListTimelineV1Paginator, MentionTimelineV1Paginator, UserTimelineV1Paginator } from '../paginators/tweet.paginator.v1';
+import { HomeTimelineV1Paginator, ListTimelineV1Paginator, MentionTimelineV1Paginator, UserFavoritesV1Paginator, UserTimelineV1Paginator } from '../paginators/tweet.paginator.v1';
 import { MuteUserIdsV1Paginator, MuteUserListV1Paginator } from '../paginators/mutes.paginator.v1';
 import { FriendshipsIncomingV1Paginator, FriendshipsOutgoingV1Paginator, UserSearchV1Paginator } from '../paginators/user.paginator.v1';
 import { ListMembershipsV1Paginator, ListMembersV1Paginator, ListOwnershipsV1Paginator, ListSubscribersV1Paginator, ListSubscriptionsV1Paginator } from '../paginators/list.paginator.v1';
@@ -191,6 +191,48 @@ export default class TwitterApiv1ReadOnly extends TwitterApiSubClient {
     });
   }
 
+  /**
+   * Returns the most recent Tweets liked by the authenticating or specified user, 20 tweets by default.
+   * Note: favorites are now known as likes.
+   * https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-favorites-list
+   */
+  public async favoriteTimeline(userId: string, options: Partial<TweetV1UserTimelineParams> = {}) {
+    const queryParams: Partial<TweetV1UserTimelineParams> = {
+      tweet_mode: 'extended',
+      user_id: userId,
+      ...options,
+    };
+    const initialRq = await this.get<TweetV1TimelineResult>('favorites/list.json', queryParams, { fullResponse: true });
+
+    return new UserFavoritesV1Paginator({
+      realData: initialRq.data,
+      rateLimit: initialRq.rateLimit!,
+      instance: this,
+      queryParams,
+    });
+  }
+
+  /**
+   * Returns the most recent Tweets liked by the authenticating or specified user, 20 tweets by default.
+   * Note: favorites are now known as likes.
+   * https://developer.twitter.com/en/docs/twitter-api/v1/tweets/post-and-engage/api-reference/get-favorites-list
+   */
+  public async favoriteTimelineByUsername(username: string, options: Partial<TweetV1UserTimelineParams> = {}) {
+    const queryParams: Partial<TweetV1UserTimelineParams> = {
+      tweet_mode: 'extended',
+      screen_name: username,
+      ...options,
+    };
+    const initialRq = await this.get<TweetV1TimelineResult>('favorites/list.json', queryParams, { fullResponse: true });
+
+    return new UserFavoritesV1Paginator({
+      realData: initialRq.data,
+      rateLimit: initialRq.rateLimit!,
+      instance: this,
+      queryParams,
+    });
+  }
+
   /* Users */
 
   /**