feat: add v2 user endpoints and types (#16)

Squashed commit of the following:

commit 727d7cf
Author: Paul-Louis Hery <[email protected]>
Date:   Sun Dec 13 01:06:17 2020 +0100

    Add some examples to the readme

commit c5ea1bf
Author: Paul-Louis Hery <[email protected]>
Date:   Sun Dec 13 00:52:19 2020 +0100

    feat: add v2 user endpoints and types

Author: PLhery

README.md

@@ -31,10 +31,22 @@ const { usertoken, userSecret } = twitterClient.login('<THE_OAUTH_VERIFIER>');
 // Tell typescript it's a readonly app
 const twitterClient = new TwitterApi(xxx).readOnly;
 
-// Manually call the API
-const tweets = await twitterClient.v2.get('tweets/search/recent', {query: 'nodeJS', max_results: '100'});
-const tweets = await twitterClient.v1.tweet('Hello, this is a test.'),
-const tweets = await twitterClient.v1.uploadMedia(await fs.promises.readFile(path), { type: 'jpg' })
+// Play with the built in methods
+
+await twitterClient.v2.userByUsername('plhery').data.id;
+await twitterClient.v1.tweet('Hello, this is a test.');
+await twitterClient.v1.uploadMedia(await fs.promises.readFile(path), { type: 'jpg' })
+
+// the search utils
+
+const results = await twitterClient.v2.search('hello');
+console.log(results.tweets); // 10 tweets
+await results.fetchNext(100);
+await results.fetchNext(100);
+console.log(results.tweets, results.rateLimit); // 210 tweets
+
+// Or manually call the API
+await twitterClient.v2.get('tweets/search/recent', {query: 'nodeJS', max_results: '100'});
 const tweets = await twitterClient.get('https://api.twitter.com/2/tweets/search/recent?query=nodeJS&max_results=100');
 ```
 
@@ -59,7 +71,7 @@ They caused me some frustration:
 - [x] read/write/DM aware typing
 - [x] get/post methods
 - [ ] Twitter API V2 tweets methods
-- [ ] Twitter API V2 users methods
+- [x] Twitter API V2 users methods
 - [ ] Auto pagination
 - [ ] Error code enums
 

src/client.subclient.ts

@@ -23,11 +23,12 @@ export default abstract class TwitterApiSubClient extends TwitterApiBase {
     this._oauth = inst._oauth;
   }
 
-  public async get<T = any>(url: string, full_response?: boolean) : Promise<T | TwitterResponse<T>>;
-  public async get<T = any>(url: string, parameters?: Record<string, string | number | undefined>, full_response?: false, prefix?: string) : Promise<T>;
-  public async get<T = any>(url: string, parameters?: Record<string, string | number | undefined>, full_response?: true, prefix?: string) : Promise<TwitterResponse<T>>;
+  public async get<T = any>(url: string, full_response?: false) : Promise<T>;
+  public async get<T = any>(url: string, full_response: true) : Promise<TwitterResponse<T>>;
+  public async get<T = any>(url: string, parameters: Record<string, string | number | undefined>, full_response?: false, prefix?: string) : Promise<T>;
+  public async get<T = any>(url: string, parameters: Record<string, string | number | undefined>, full_response: true, prefix?: string) : Promise<TwitterResponse<T>>;
 
-  public async get<T = any>(url: string, parameters?: Record<string, string | number | undefined> | boolean, full_response = false, prefix = this._prefix) : Promise<T | TwitterResponse<T>> {
+  public async get<T = any>(url: string, parameters?: Record<string, string | number | undefined> | boolean, full_response = false, prefix = this._prefix) : Promise<T | TwitterResponse<T>> {
     if (typeof parameters === 'boolean') {
       full_response = parameters;
       parameters = undefined;
@@ -38,9 +39,10 @@ export default abstract class TwitterApiSubClient extends TwitterApiBase {
   }
 
 
-  public async delete<T = any>(url: string, full_response?: boolean) : Promise<T | TwitterResponse<T>>;
-  public async delete<T = any>(url: string, parameters?: Record<string, string | number | undefined>, full_response?: false, prefix?: string) : Promise<T>;
-  public async delete<T = any>(url: string, parameters?: Record<string, string | number | undefined>, full_response?: true, prefix?: string) : Promise<TwitterResponse<T>>;
+  public async delete<T = any>(url: string, full_response?: false) : Promise<T>;
+  public async delete<T = any>(url: string, full_response: true) : Promise<TwitterResponse<T>>;
+  public async delete<T = any>(url: string, parameters: Record<string, string | number | undefined>, full_response?: false, prefix?: string) : Promise<T>;
+  public async delete<T = any>(url: string, parameters: Record<string, string | number | undefined>, full_response: true, prefix?: string) : Promise<TwitterResponse<T>>;
 
   public async delete<T = any>(url: string, parameters?: Record<string, string | number | undefined> | boolean, full_response = false, prefix = this._prefix) : Promise<T | TwitterResponse<T>> {
     if (typeof parameters === 'boolean') {

src/v2/client.v2.read.ts

@@ -1,7 +1,7 @@
 import TwitterApiSubClient from '../client.subclient';
 import { API_V2_PREFIX } from '../globals';
 import TweetPaginator from './TweetPaginator';
-import { Tweetv2SearchParams, Tweetv2SearchResult } from './types.v2';
+import {Tweetv2SearchParams, Tweetv2SearchResult, User, UserResult, UsersResult, UsersV2Params} from './types.v2';
 
 /**
  * Base Twitter v2 client with only read right.
@@ -15,4 +15,22 @@ export default class TwitterApiv2ReadOnly extends TwitterApiSubClient {
 
     return new TweetPaginator(initialRq.data, initialRq.rateLimit!, this, queryParams);
   }
+
+  public user(userId: string, options: Partial<UsersV2Params> = {}) {
+    return this.get<UserResult>(`users/${userId}`, options);
+  }
+
+  public users(userIds: string | string[], options: Partial<UsersV2Params> = {}) {
+    const ids = Array.isArray(userIds) ? userIds.join(',') : userIds;
+    return this.get<UsersResult>(`users`, {...options, ids});
+  }
+
+  public userByUsername(username: string, options: Partial<UsersV2Params> = {}) {
+    return this.get<UserResult>(`users/by/username/${username}`, options);
+  }
+
+  public usersByUsernames(usernames: string | string[], options: Partial<UsersV2Params> = {}) {
+    usernames = Array.isArray(usernames) ? usernames.join(',') : usernames;
+    return this.get<UsersResult>(`users/by`, {...options, usernames});
+  }
 }

src/v2/types.v2.ts

@@ -1,4 +1,4 @@
-
+// Tweets
 export interface Tweetv2SearchParams extends Partial<Tweetv2FieldsParams> {
   /** ISO date string */
   end_time?: string;
@@ -22,7 +22,7 @@ export interface Tweetv2FieldsParams {
 
 // TODO type
 export interface Tweet {
-  [query: string]: any;
+  [field: string]: any;
 }
 
 export interface Tweetv2SearchResult {
@@ -34,3 +34,78 @@ export interface Tweetv2SearchResult {
     next_token: string;
   };
 }
+
+// Entities
+interface Entity {
+  start: number;
+  end: number;
+}
+interface UrlEntity extends Entity {
+  url: string; // https;//t.co/...
+  expanded_url: string; // https://unfollow.ninja/
+  display_url: string; // unfollow.ninja
+}
+interface HashtagEntity extends Entity {
+  hashtag: string;
+}
+interface CashtagEntity extends Entity {
+  cashtag: string;
+}
+interface MentionEntity extends Entity {
+  username: string;
+}
+
+// Users
+export interface UsersV2Params {
+  expansions: 'pinned_tweet_id';
+  'tweet.fields': string;
+  'user.fields': string;
+}
+
+
+export interface User {
+  id: string;
+  name: string;
+  username: string;
+  created_at?: string; // ISO 8601 date
+  protected?: boolean;
+  withheld?: {
+    country_codes?: string[];
+    scope?: 'user';
+  }
+  location?: string;
+  url?: string;
+  description?: string;
+  verified?: boolean;
+  entities?: {
+    url?: { urls: UrlEntity[] };
+    description: {
+      urls?: UrlEntity[];
+      hashtags?: HashtagEntity[];
+      cashtags?: CashtagEntity[];
+      mentions?: MentionEntity[];
+    }
+  }
+  profile_image_url?: string;
+  public_metrics?: {
+    followers_count?: number;
+    following_count?: number;
+    tweet_count?: number;
+    listed_count?: number;
+  },
+  pinned_tweet_id?: string;
+}
+
+export interface UserResult {
+  data: User
+  includes?: {
+    tweets: [Tweet]; // pinned tweet
+  }
+}
+
+export interface UsersResult {
+  data: User[]
+  includes?: {
+    tweets: Tweet[]; // pinned tweets
+  }
+}