rettiwt-api 5.0.0-alpha.4 → 5.0.1

package/src/services/public/UserService.ts

@@ -43,14 +43,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the list affiliates of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no id is provided, the logged-in user's id is used.
 	 * @param count - The number of affiliates to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of affiliates to fetch.
 	 *
 	 * @returns The list of users affiliated to the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -71,7 +72,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of affiliates
 		const response = await this.request<IUserAffiliatesResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -91,7 +92,8 @@ export class UserService extends FetcherService {
 	 * @returns The list of tweets bookmarked by the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -125,15 +127,19 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the details of a user.
 	 *
-	 * @param id - The username/id(s) of the target user/users. If no ID is provided, uses ID of authenticated user.
+	 * @param id - The username/ID/IDs of the target user/users. If no ID is provided, the logged-in user's ID is used.
 	 *
 	 * @returns
 	 * The details of the given user.
+	 *
+	 * If more than one ID is provided, returns a list.
+	 *
 	 * If no user matches the given id, returns `undefined`.
 	 *
 	 * @example
-	 * Fetching the details using username
-	 * ```
+	 *
+	 * #### Fetching the details of a single user using username
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -150,8 +156,9 @@ export class UserService extends FetcherService {
 	 * ```
 	 *
 	 * @example
-	 * Fetching the details using id
-	 * ```
+	 *
+	 * #### Fetching the details of a single user using ID
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -160,7 +167,25 @@ export class UserService extends FetcherService {
 	 * // Fetching the details of the User with id '1234567890'
 	 * rettiwt.user.details('1234567890')
 	 * .then(res => {
-	 * 	console.log(res);
+	 * 	console.log(res);	# 'res' is a single tweet
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 * * @example
+	 *
+	 * #### Fetching the details of multiple users
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the details of the users with IDs '123', '456', '789'
+	 * rettiwt.user.details(['123', '456', '789'])
+	 * .then(res => {
+	 * 	console.log(res);	# 'res' is an array of users
 	 * })
 	 * .catch(err => {
 	 * 	console.log(err);
@@ -213,14 +238,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Follow a user.
 	 *
-	 * @param id - The id the user to be followed.
+	 * @param id - The ID the user to be followed.
 	 *
 	 * @returns Whether following was successful or not.
 	 *
 	 * @throws Code 108 if given user id is invalid.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -256,7 +282,8 @@ export class UserService extends FetcherService {
 	 * @returns - The followed feed of the logged-in user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -291,14 +318,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the list followers of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @param count - The number of followers to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of followers to fetch.
 	 *
 	 * @returns The list of users following the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -314,12 +342,12 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async followers(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+	public async followers(id?: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
 		const resource = EResourceType.USER_FOLLOWERS;
 
 		// Fetching raw list of followers
 		const response = await this.request<IUserFollowersResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -333,14 +361,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the list of users who are followed by a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @param count - The number of following to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of following to fetch.
 	 *
 	 * @returns The list of users followed by the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -356,12 +385,12 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async following(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+	public async following(id?: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
 		const resource = EResourceType.USER_FOLLOWING;
 
 		// Fetching raw list of following
 		const response = await this.request<IUserFollowingResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -375,14 +404,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the highlighted tweets of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @param count - The number of followers to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of followers to fetch.
 	 *
 	 * @returns The list of highlighted tweets of the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -403,7 +433,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of highlights
 		const response = await this.request<IUserHighlightsResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -423,7 +453,8 @@ export class UserService extends FetcherService {
 	 * @returns The list of tweets liked by the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -458,14 +489,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the media timeline of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @param count - The number of media to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of media to fetch
 	 *
 	 * @returns The media timeline of the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -481,12 +513,12 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async media(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+	public async media(id?: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
 		const resource = EResourceType.USER_MEDIA;
 
 		// Fetching raw list of media
 		const response = await this.request<IUserMediaResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -505,7 +537,8 @@ export class UserService extends FetcherService {
 	 * @returns An async generator that yields new notifications as they are received.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -515,7 +548,7 @@ export class UserService extends FetcherService {
 	 * async function streamNotifications() {
 	 * 	try {
 	 * 		// Awaiting for the notifications returned by the AsyncGenerator returned by the method
-	 * 		for await (const notification of rettiwt.user.notifications(1000)) {
+	 * 		for await (const notification of rettiwt.user.notifications(5000)) {
 	 * 			console.log(notification.message);
 	 * 		}
 	 * 	}
@@ -577,7 +610,8 @@ export class UserService extends FetcherService {
 	 * @returns - The recommended feed of the logged-in user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -612,14 +646,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the reply timeline of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @param count - The number of replies to fetch, must be \<= 20.
 	 * @param cursor - The cursor to the batch of replies to fetch.
 	 *
 	 * @returns The reply timeline of the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -635,14 +670,16 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 *
-	 * @remarks If the target user has a pinned tweet, the returned reply timeline has one item extra and this is always the pinned tweet.
+	 * @remarks
+	 *
+	 * If the target user has a pinned tweet, the returned reply timeline has one item extra and this is always the pinned tweet.
 	 */
-	public async replies(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+	public async replies(id?: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
 		const resource = EResourceType.USER_TIMELINE_AND_REPLIES;
 
 		// Fetching raw list of replies
 		const response = await this.request<IUserTweetsAndRepliesResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -656,14 +693,17 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the list of subscriptions of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @deprecated Currently not working.
+	 *
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @param count - The number of subscriptions to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of subscriptions to fetch.
 	 *
 	 * @returns The list of subscriptions by the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -684,7 +724,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of subscriptions
 		const response = await this.request<IUserSubscriptionsResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -698,14 +738,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the tweet timeline of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @param count - The number of timeline items to fetch, must be \<= 20.
 	 * @param cursor - The cursor to the batch of timeline items to fetch.
 	 *
 	 * @returns The timeline of the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -722,6 +763,7 @@ export class UserService extends FetcherService {
 	 * ```
 	 *
 	 * @remarks
+	 *
 	 * - If the target user has a pinned tweet, the returned timeline has one item extra and this is always the pinned tweet.
 	 * - If timeline is fetched without authenticating, then the most popular tweets of the target user are returned instead.
 	 */
@@ -730,7 +772,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of tweets
 		const response = await this.request<IUserTweetsResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -744,14 +786,13 @@ export class UserService extends FetcherService {
 	/**
 	 * Unfollow a user.
 	 *
-	 * @param id - The id the user to be unfollowed.
+	 * @param id - The ID the user to be unfollowed.
 	 *
 	 * @returns Whether unfollowing was successful or not.
 	 *
-	 * @throws Code 34 if given user id is invalid.
-	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'

package/src/types/args/FetchArgs.ts

@@ -1,3 +1,5 @@
+import { ETweetRepliesSortType } from '../../enums/Tweet';
+
 /**
  * Options specifying the data that is to be fetched.
  *
@@ -55,6 +57,14 @@ export interface IFetchArgs {
 	 * - Required only for {@link EResourceType.TWEET_DETAILS_BULK} and {@link EResourceType.USER_DETAILS_BY_IDS_BULK}.
 	 */
 	ids?: string[];
+
+	/**
+	 * The sorting to use for tweet results.
+	 *
+	 * @remarks
+	 * - Only works for {@link EResourceType.TWEET_REPLIES}.
+	 */
+	sortBy?: ETweetRepliesSortType;
 }
 
 /**