Merge pull request #391 from Abdullah-Malik/master

feat: get friends/followers objects list V1

Author: alkihis

doc/v1.md

@@ -41,6 +41,8 @@ For streaming API, see [Streaming part](./streaming.md).
 	* [List muted users (IDs)](#ListmutedusersIDs)
   	* [Get Ids of followers of a user](#GetIdsoffollowersofauser)
   	* [Get Ids of friends of a user](#GetIdsoffriendsofauser)
+    * [List of followers of the specified user (objects)](#Getlistoffollowersofauser)
+  	* [List of friends of the specified user (objects)](#Getlistoffriendsofauser)
 	* [Get sizes of profile banner of a user](#Getsizesofprofilebannerofauser)
 	* [Get detailed relationship between two users](#Getdetailedrelationshipbetweentwousers)
 	* [Update relationship between you and other user](#Updaterelationshipbetweenyouandotheruser)
@@ -642,6 +644,56 @@ console.log('First page of friend ids of "WSJ" user:', friends.ids);
 console.log('Second page of friend ids of "WSJ" user:', (await friends.next()).ids);
 ```
 
+### <a name='Getlistoffollowersofauser'></a>List of followers of the specified user (objects)
+
+Get an array of user objects for users following the specified user.
+Get to know how [paginators work here](./paginators.md).
+
+To access user IDs from the paginator, use `.users` property.
+
+**Method**: `.userFollowerList()`
+
+**Endpoint**: `followers/list.json`
+
+**Right level**: `Read-only`
+
+**Arguments**:
+  - `options?: UserFollowerListV1Params`
+
+**Returns**: `UserFollowerListV1Paginator` (containing `string` items)
+
+**Example**
+```ts
+const followers = await client.v1.userFollowerList({ screen_name: 'WSJ' });
+console.log('First page of follower of "WSJ" user:', followers.users);
+console.log('Second page of follower of "WSJ" user:', (await followers.next()).users);
+```
+
+### <a name='Getlistoffriendsofauser'></a>List of friends of the specified user (objects)
+
+Get an array of user objects for every user the specified user is following (otherwise known as their "friends").
+Get to know how [paginators work here](./paginators.md).
+
+To access user IDs from the paginator, use `.users` property.
+
+**Method**: `.userFriendList()`
+
+**Endpoint**: `friends/list.json`
+
+**Right level**: `Read-only`
+
+**Arguments**:
+  - `options?: UserFriendListV1Params`
+
+**Returns**: `UserFriendListV1Paginator` (containing `string` items)
+
+**Example**
+```ts
+const friends = await client.v1.userFriendList({ screen_name: 'WSJ' });
+console.log('First page of friends of "WSJ" user:', friends.users);
+console.log('Second page of friends of "WSJ" user:', (await friends.next()).users);
+```
+
 ### <a name='Getsizesofprofilebannerofauser'></a>Get sizes of profile banner of a user
 
 **Method**: `.userProfileBannerSizes()`

src/paginators/followers.paginator.v1.ts

@@ -1,5 +1,34 @@
 import { CursoredV1Paginator } from './paginator.v1';
-import type { UserFollowerIdsV1Params, UserFollowerIdsV1Result, TwitterResponse } from '../types';
+import type { UserFollowerIdsV1Params, UserFollowerIdsV1Result, UserFollowerListV1Params, UserFollowerListV1Result, TwitterResponse, UserV1 } from '../types';
+
+export class UserFollowerListV1Paginator extends CursoredV1Paginator<UserFollowerListV1Result, UserFollowerListV1Params, UserV1> {
+  protected _endpoint = 'followers/list.json';
+
+  protected refreshInstanceFromResult(response: TwitterResponse<UserFollowerListV1Result>, isNextPage: true) {
+    const result = response.data;
+    this._rateLimit = response.rateLimit!;
+
+    if (isNextPage) {
+      this._realData.users.push(...result.users);
+      this._realData.next_cursor = result.next_cursor;
+    }
+  }
+
+  protected getPageLengthFromRequest(result: TwitterResponse<UserFollowerListV1Result>) {
+    return result.data.users.length;
+  }
+
+  protected getItemArray() {
+    return this.users;
+  }
+
+  /**
+   * Users returned by paginator.
+   */
+  get users() {
+    return this._realData.users;
+  }
+}
 
 export class UserFollowerIdsV1Paginator extends CursoredV1Paginator<UserFollowerIdsV1Result, UserFollowerIdsV1Params, string> {
   protected _endpoint = 'followers/ids.json';

src/paginators/friends.paginator.v1.ts

@@ -1,5 +1,34 @@
 import { CursoredV1Paginator } from './paginator.v1';
-import type { UserFollowerIdsV1Params, UserFollowerIdsV1Result, TwitterResponse } from '../types';
+import type { UserFollowerIdsV1Params, UserFollowerIdsV1Result, UserFriendListV1Params, UserFriendListV1Result, UserV1, TwitterResponse } from '../types';
+
+export class UserFriendListV1Paginator extends CursoredV1Paginator<UserFriendListV1Result, UserFriendListV1Params, UserV1> {
+  protected _endpoint = 'friends/list.json';
+
+  protected refreshInstanceFromResult(response: TwitterResponse<UserFriendListV1Result>, isNextPage: true) {
+    const result = response.data;
+    this._rateLimit = response.rateLimit!;
+
+    if (isNextPage) {
+      this._realData.users.push(...result.users);
+      this._realData.next_cursor = result.next_cursor;
+    }
+  }
+
+  protected getPageLengthFromRequest(result: TwitterResponse<UserFriendListV1Result>) {
+    return result.data.users.length;
+  }
+
+  protected getItemArray() {
+    return this.users;
+  }
+
+  /**
+   * Users returned by paginator.
+   */
+  get users() {
+    return this._realData.users;
+  }
+}
 
 export class UserFollowersIdsV1Paginator extends CursoredV1Paginator<UserFollowerIdsV1Result, UserFollowerIdsV1Params, string> {
   protected _endpoint = 'friends/ids.json';

src/types/v1/user.v1.types.ts

@@ -66,6 +66,19 @@ export interface UserFollowerIdsV1Params extends DoubleEndedIdCursorV1Params {
   count?: number;
 }
 
+interface UserListV1Params {
+  screen_name?: string;
+  user_id?: string;
+  count?: number;
+  cursor?: string;
+  skip_status?: boolean;
+  include_user_entities: boolean;
+}
+
+export type UserFollowerListV1Params = UserListV1Params;
+
+export type UserFriendListV1Params = UserListV1Params;
+
 export interface VerifyCredentialsV1Params {
   include_entities?: boolean;
   skip_status?: boolean;
@@ -190,6 +203,18 @@ export type UserFollowerIdsV1Result = DoubleEndedIdCursorV1Result;
 
 export type UserFollowingIdsV1Result = DoubleEndedIdCursorV1Result;
 
+interface UserListV1Result {
+  next_cursor?: string;
+  next_cursor_str?: string;
+  previous_cursor?: string;
+  previous_cursor_str?: string;
+  users: UserV1[];
+}
+
+export type UserFollowerListV1Result = UserListV1Result;
+
+export type UserFriendListV1Result = UserListV1Result;
+
 // GET users/profile_banner
 export interface BannerSizeV1 {
   h: number;

src/v1/client.v1.read.ts

@@ -33,6 +33,10 @@ import {
   UserFollowerIdsV1Result,
   UserFollowingsIdsV1Params,
   UserFollowingIdsV1Result,
+  UserFriendListV1Params,
+  UserFriendListV1Result,
+  UserFollowerListV1Params,
+  UserFollowerListV1Result,
   UserSearchV1Params,
   AccountSettingsV1,
   ProfileBannerSizeV1,
@@ -64,8 +68,8 @@ import {
 } from '../types';
 import { HomeTimelineV1Paginator, ListTimelineV1Paginator, MentionTimelineV1Paginator, UserFavoritesV1Paginator, UserTimelineV1Paginator } from '../paginators/tweet.paginator.v1';
 import { MuteUserIdsV1Paginator, MuteUserListV1Paginator } from '../paginators/mutes.paginator.v1';
-import { UserFollowerIdsV1Paginator } from '../paginators/followers.paginator.v1';
-import { UserFollowersIdsV1Paginator } from '../paginators/friends.paginator.v1';
+import { UserFollowerIdsV1Paginator, UserFollowerListV1Paginator } from '../paginators/followers.paginator.v1';
+import { UserFollowersIdsV1Paginator, UserFriendListV1Paginator } from '../paginators/friends.paginator.v1';
 import { FriendshipsIncomingV1Paginator, FriendshipsOutgoingV1Paginator, UserSearchV1Paginator } from '../paginators/user.paginator.v1';
 import { ListMembershipsV1Paginator, ListMembersV1Paginator, ListOwnershipsV1Paginator, ListSubscribersV1Paginator, ListSubscriptionsV1Paginator } from '../paginators/list.paginator.v1';
 import TweetStream from '../stream/TweetStream';
@@ -307,6 +311,42 @@ export default class TwitterApiv1ReadOnly extends TwitterApiSubClient {
     });
   }
 
+  /**
+   * Returns an array of user objects of friends of the specified user.
+   * https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-friends-list
+   */
+   public async userFriendList(options: Partial<UserFriendListV1Params> = {}) {
+    const queryParams: Partial<UserFriendListV1Params> = {
+      ...options,
+    };
+    const initialRq = await this.get<UserFriendListV1Result>('friends/list.json', queryParams, { fullResponse: true });
+
+    return new UserFriendListV1Paginator({
+      realData: initialRq.data,
+      rateLimit: initialRq.rateLimit!,
+      instance: this,
+      queryParams,
+    });
+  }
+
+  /**
+   * Returns an array of user objects of followers of the specified user.
+   * https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-list
+   */
+   public async userFollowerList(options: Partial<UserFollowerListV1Params> = {}) {
+    const queryParams: Partial<UserFollowerListV1Params> = {
+      ...options,
+    };
+    const initialRq = await this.get<UserFollowerListV1Result>('followers/list.json', queryParams, { fullResponse: true });
+
+    return new UserFollowerListV1Paginator({
+      realData: initialRq.data,
+      rateLimit: initialRq.rateLimit!,
+      instance: this,
+      queryParams,
+    });
+  }
+
   /**
    * Returns an array of numeric user ids of followers of the specified user.
    * https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/follow-search-get-users/api-reference/get-followers-ids