Merge branch 'feat/v2-endpoints-3-10'

Author: alkihis

doc/v2.md

@@ -43,9 +43,10 @@ For streaming API, see [Streaming part](./streaming.md).
 	* [Unfollow someone](#Unfollowsomeone)
 	* [Block someone](#Blocksomeone)
 	* [Unblock someone](#Unblocksomeone)
-	* [Get users that are blocked by a user](#Getusersthatareblockedbyauser)
+	* [Get users that are blocked by you](#Getusersthatareblockedbyyou)
 	* [Mute someone](#Mutesomeone)
 	* [Unmute someone](#Unmutesomeone)
+	* [Get users that are muted by you](#Getusersthataremutedbyyou)
 * [Spaces](#Spaces)
 	* [Space by ID](#SpacebyID)
 	* [Spaces by ID](#SpacesbyID)
@@ -614,9 +615,9 @@ await client.v2.block('12', '1903892');
 await client.v2.unblock('12', '1903892');
 ```
 
-### <a name='Getusersthatareblockedbyauser'></a>Get users that are blocked by a user
+### <a name='Getusersthatareblockedbyyou'></a>Get users that are blocked by you
 
-Get users blocked by a specific user.
+Get users blocked by the authenticating user.
 Get to know how [paginators work here](./paginators.md).
 
 **Method**: `.userBlockingUsers()`
@@ -626,17 +627,16 @@ Get to know how [paginators work here](./paginators.md).
 **Right level**: `Read-only`
 
 **Arguments**:
-  - `userId: string`
   - `options?: UserV2TimelineParams`
 
 **Returns**: `UserBlockingUsersV2Paginator`
 
 **Example**
 ```ts
-const blockedPaginator = await client.v2.userBlockingUsers('12');
+const blockedPaginator = await client.v2.userBlockingUsers();
 
 for await (const blockedUser of blockedPaginator) {
-  console.log(`Jack is blocking @${blockedUser.username}.`);
+  console.log(`You are blocking @${blockedUser.username}.`);
 }
 ```
 
@@ -678,6 +678,31 @@ await client.v2.mute('12', '1903892');
 await client.v2.unmute('12', '1903892');
 ```
 
+### <a name='Getusersthataremutedbyyou'></a>Get users that are muted by you
+
+Get users muted by authenticated user.
+Get to know how [paginators work here](./paginators.md).
+
+**Method**: `.userMutingUsers()`
+
+**Endpoint**: `users/:id/muting`
+
+**Right level**: `Read-only`
+
+**Arguments**:
+  - `options?: UserV2TimelineParams`
+
+**Returns**: `UserMutingUsersV2Paginator`
+
+**Example**
+```ts
+const mutedPaginator = await client.v2.userMutingUsers();
+
+for await (const mutedUser of mutedPaginator) {
+  console.log(`You are blocking @${mutedUser.username}.`);
+}
+```
+
 ## <a name='Spaces'></a>Spaces
 
 ### <a name='SpacebyID'></a>Space by ID

src/client.base.ts

@@ -1,4 +1,4 @@
-import { TClientTokens, TwitterApiBasicAuth, TwitterApiOAuth2Init, TwitterApiTokens, TwitterRateLimit, TwitterResponse } from './types';
+import { TClientTokens, TwitterApiBasicAuth, TwitterApiOAuth2Init, TwitterApiTokens, TwitterRateLimit, TwitterResponse, UserV1 } from './types';
 import {
   ClientRequestMaker,
   TCustomizableRequestArgs,
@@ -35,6 +35,7 @@ export type TStreamClientRequestArgs = TCustomizableRequestArgs & {
  */
 export default abstract class TwitterApiBase extends ClientRequestMaker {
   protected _prefix: string | undefined;
+  protected _currentUser: UserV1 | null = null;
 
   /**
    * Create a new TwitterApi object without authentification.
@@ -98,6 +99,8 @@ export default abstract class TwitterApiBase extends ClientRequestMaker {
     }
   }
 
+  /* Prefix/Token handling */
+
   protected setPrefix(prefix: string | undefined) {
     this._prefix = prefix;
   }
@@ -134,6 +137,8 @@ export default abstract class TwitterApiBase extends ClientRequestMaker {
     return { type: 'none' };
   }
 
+  /* Rate limit cache */
+
   /**
    * Tells if you hit the Twitter rate limit for {endpoint}.
    * (local data only, this should not ask anything to Twitter)
@@ -168,6 +173,23 @@ export default abstract class TwitterApiBase extends ClientRequestMaker {
     return this._rateLimits[endpointWithPrefix];
   }
 
+  /* Current user cache */
+
+  /** Get cached current user. */
+  protected async getCurrentUserObject(forceFetch = false) {
+    if (!forceFetch && this._currentUser) {
+      return this._currentUser;
+    }
+
+    const currentUser = await this.get<UserV1>(
+      'account/verify_credentials.json',
+      { tweet_mode: 'extended' },
+      { prefix: 'https://api.twitter.com/1.1/' },
+    );
+    this._currentUser = currentUser;
+
+    return currentUser;
+  }
 
   /* Direct HTTP methods */
 

src/client/readonly.ts

@@ -12,7 +12,6 @@ import {
 } from '../types';
 import TwitterApiv1ReadOnly from '../v1/client.v1.read';
 import TwitterApiv2ReadOnly from '../v2/client.v2.read';
-import { UserV1 } from '../types';
 import { OAuth2Helper } from '../client-mixins/oauth2.helper';
 
 /**
@@ -21,7 +20,6 @@ import { OAuth2Helper } from '../client-mixins/oauth2.helper';
 export default class TwitterApiReadOnly extends TwitterApiBase {
   protected _v1?: TwitterApiv1ReadOnly;
   protected _v2?: TwitterApiv2ReadOnly;
-  protected _currentUser?: UserV1;
 
   /* Direct access to subclients */
 
@@ -45,11 +43,7 @@ export default class TwitterApiReadOnly extends TwitterApiBase {
    * Next calls to this methods will use the cached user, unless `forceFetch: true` is given.
    */
   public async currentUser(forceFetch = false) {
-    if (!forceFetch && this._currentUser) {
-      return this._currentUser;
-    }
-
-    return (this._currentUser = await this.v1.verifyCredentials());
+    return await this.getCurrentUserObject(forceFetch);
   }
 
   /* Shortcuts to endpoints */

src/helpers.ts

@@ -1,3 +1,5 @@
+import { TwitterApiV2Settings } from './settings';
+
 export function arrayWrap<T>(value: T | T[]) : T[] {
   if (Array.isArray(value)) {
     return value;
@@ -26,3 +28,32 @@ export function hasMultipleItems(item: string | string[]) {
   }
   return item.toString().includes(',');
 }
+
+/* Deprecation warnings */
+
+export interface IDeprecationWarning {
+  instance: string;
+  method: string;
+  problem: string;
+  resolution: string;
+}
+
+const deprecationWarningsCache = new Set<string>();
+
+export function safeDeprecationWarning(message: IDeprecationWarning) {
+  if (typeof console === 'undefined' || !console.warn || !TwitterApiV2Settings.deprecationWarnings) {
+    return;
+  }
+
+  const hash = `${message.instance}-${message.method}-${message.problem}`;
+  if (deprecationWarningsCache.has(hash)) {
+    return;
+  }
+
+  const formattedMsg = `[twitter-api-v2] Deprecation warning: In ${message.instance}.${message.method}() call` +
+    `, ${message.problem}.\n${message.resolution}.`;
+
+  console.warn(formattedMsg);
+  console.warn('To disable this message, import TwitterApiV2Settings from twitter-api-v2 and set TwitterApiV2Settings.deprecationWarnings to false.');
+  deprecationWarningsCache.add(hash);
+}

src/paginators/user.paginator.v2.ts

@@ -98,6 +98,10 @@ export class UserBlockingUsersV2Paginator extends UserTimelineV2Paginator<UserV2
   protected _endpoint = 'users/:id/blocking';
 }
 
+export class UserMutingUsersV2Paginator extends UserTimelineV2Paginator<UserV2TimelineResult, UserV2TimelineParams, { id: string }> {
+  protected _endpoint = 'users/:id/muting';
+}
+
 export class UserFollowersV2Paginator extends UserTimelineV2Paginator<UserV2TimelineResult, UserV2TimelineParams, { id: string }> {
   protected _endpoint = 'users/:id/followers';
 }

src/settings.ts

@@ -1,4 +1,5 @@
 
 export const TwitterApiV2Settings = {
   debug: false,
+  deprecationWarnings: true,
 };

src/types/auth.types.ts

@@ -2,7 +2,7 @@ import type TwitterApi from '../client';
 import { TypeOrArrayOf } from './shared.types';
 
 export type TOAuth2Scope = 'tweet.read' | 'users.read' | 'account.follows.read' | 'account.follows.write'
- | 'offline.access' | 'spaces.read';
+ | 'offline.access' | 'space.read';
 
 export interface BuildOAuth2RequestLinkArgs {
   scope?: TypeOrArrayOf<TOAuth2Scope> | TypeOrArrayOf<string>;

src/v2/client.v2.read.ts

@@ -51,7 +51,7 @@ import {
   TweetV2UserLikedTweetsPaginator,
 } from '../paginators';
 import TwitterApiv2LabsReadOnly from '../v2-labs/client.v2.labs.read';
-import { UserBlockingUsersV2Paginator, UserFollowersV2Paginator, UserFollowingV2Paginator } from '../paginators/user.paginator.v2';
+import { UserBlockingUsersV2Paginator, UserFollowersV2Paginator, UserFollowingV2Paginator, UserMutingUsersV2Paginator } from '../paginators/user.paginator.v2';
 import { isTweetStreamV2ErrorPayload } from '../helpers';
 
 /**
@@ -316,7 +316,7 @@ export default class TwitterApiv2ReadOnly extends TwitterApiSubClient {
   }
 
   /**
-   * Returns a list of users who are blocked by the specified user ID. User ID must be the authenticating user.
+   * Returns a list of users who are blocked by the authenticating user.
    * https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/get-users-blocking
    */
   public async userBlockingUsers(userId: string, options: Partial<UserV2TimelineParams> = {}) {
@@ -332,13 +332,31 @@ export default class TwitterApiv2ReadOnly extends TwitterApiSubClient {
     });
   }
 
+  /**
+   * Returns a list of users who are muted by the authenticating user.
+   * https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/get-users-muting
+   */
+  public async userMutingUsers(options: Partial<UserV2TimelineParams> = {}) {
+    const { id_str: userId } = await this.getCurrentUserObject();
+    const params = { id: userId };
+    const initialRq = await this.get<UserV2TimelineResult>('users/:id/muting', options, { fullResponse: true, params });
+
+    return new UserMutingUsersV2Paginator({
+      realData: initialRq.data,
+      rateLimit: initialRq.rateLimit!,
+      instance: this,
+      queryParams: { ...options },
+      sharedParams: params,
+    });
+  }
+
   /* Spaces */
 
   /**
    * Get a single space by ID.
    * https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id
    *
-   * OAuth2 scopes: `tweet.read`, `users.read`, `spaces.read`.
+   * OAuth2 scopes: `tweet.read`, `users.read`, `space.read`.
    */
   public space(spaceId: string, options: Partial<SpaceV2FieldsParams> = {}) {
     return this.get<SpaceV2SingleResult>('spaces/:id', options, { params: { id: spaceId } });
@@ -348,7 +366,7 @@ export default class TwitterApiv2ReadOnly extends TwitterApiSubClient {
    * Get spaces using their IDs.
    * https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces
    *
-   * OAuth2 scopes: `tweet.read`, `users.read`, `spaces.read`.
+   * OAuth2 scopes: `tweet.read`, `users.read`, `space.read`.
    */
   public spaces(spaceIds: string | string[], options: Partial<SpaceV2FieldsParams> = {}) {
     return this.get<SpaceV2LookupResult>('spaces', { ids: spaceIds, ...options });
@@ -358,7 +376,7 @@ export default class TwitterApiv2ReadOnly extends TwitterApiSubClient {
    * Get spaces using their creator user ID(s). (no pagination available)
    * https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-by-creator-ids
    *
-   * OAuth2 scopes: `tweet.read`, `users.read`, `spaces.read`.
+   * OAuth2 scopes: `tweet.read`, `users.read`, `space.read`.
    */
   public spacesByCreators(creatorIds: string | string[], options: Partial<SpaceV2CreatorLookupParams> = {}) {
     return this.get<SpaceV2LookupResult>('spaces/by/creator_ids', { user_ids: creatorIds, ...options });

src/v2/client.v2.write.ts

@@ -84,7 +84,7 @@ export default class TwitterApiv2ReadWrite extends TwitterApiv2ReadOnly {
    * **Note**: You must specify the currently logged user ID ; you can obtain it through v1.1 API.
    */
   public retweet(loggedUserId: string, targetTweetId: string) {
-    return this.post<TweetV2RetweetResult>(`users/:id/retweets`, { tweet_id: targetTweetId }, { params: { id: loggedUserId } });
+    return this.post<TweetV2RetweetResult>('users/:id/retweets', { tweet_id: targetTweetId }, { params: { id: loggedUserId } });
   }
 
   /**