rettiwt-api 5.0.0-alpha.0 → 5.0.0-alpha.2

package/src/services/public/TweetService.ts

@@ -1,31 +1,30 @@
 import { statSync } from 'fs';
 
-import {
-	ESearchResultType,
-	IInitializeMediaUploadResponse,
-	IListTweetsResponse,
-	ITweetDetailsResponse,
-	ITweetLikeResponse,
-	ITweetPostResponse,
-	ITweetRepliesResponse,
-	ITweetRetweetersResponse,
-	ITweetRetweetResponse,
-	ITweetScheduleResponse,
-	ITweetSearchResponse,
-	ITweetUnlikeResponse,
-	ITweetUnpostResponse,
-	ITweetUnretweetResponse,
-	ITweetUnscheduleResponse,
-	TweetFilter,
-} from 'rettiwt-core';
-
 import { extractors } from '../../collections/Extractors';
 import { EResourceType } from '../../enums/Resource';
-import { TweetArgs } from '../../models/args/PostArgs';
 import { CursoredData } from '../../models/data/CursoredData';
 import { Tweet } from '../../models/data/Tweet';
 import { User } from '../../models/data/User';
-import { IRettiwtConfig } from '../../types/RettiwtConfig';
+
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { ITweetFilter } from '../../types/args/FetchArgs';
+import { INewTweet } from '../../types/args/PostArgs';
+import { IListTweetsResponse } from '../../types/raw/list/Tweets';
+import { IMediaInitializeUploadResponse } from '../../types/raw/media/InitalizeUpload';
+import { ITweetDetailsResponse } from '../../types/raw/tweet/Details';
+
+import { ITweetLikeResponse } from '../../types/raw/tweet/Like';
+import { ITweetLikersResponse } from '../../types/raw/tweet/Likers';
+import { ITweetPostResponse } from '../../types/raw/tweet/Post';
+import { ITweetRepliesResponse } from '../../types/raw/tweet/Replies';
+import { ITweetRetweetResponse } from '../../types/raw/tweet/Retweet';
+import { ITweetRetweetersResponse } from '../../types/raw/tweet/Retweeters';
+import { ITweetScheduleResponse } from '../../types/raw/tweet/Schedule';
+import { ITweetSearchResponse } from '../../types/raw/tweet/Search';
+import { ITweetUnlikeResponse } from '../../types/raw/tweet/Unlike';
+import { ITweetUnpostResponse } from '../../types/raw/tweet/Unpost';
+import { ITweetUnretweetResponse } from '../../types/raw/tweet/Unretweet';
+import { ITweetUnscheduleResponse } from '../../types/raw/tweet/Unschedule';
 
 import { FetcherService } from './FetcherService';
 
@@ -40,14 +39,14 @@ export class TweetService extends FetcherService {
 	 *
 	 * @internal
 	 */
-	public constructor(config?: IRettiwtConfig) {
+	public constructor(config: RettiwtConfig) {
 		super(config);
 	}
 
 	/**
 	 * Get the details of a tweet.
 	 *
-	 * @param id - The id of the target tweet.
+	 * @param id - The id(s) of the target tweet/tweets.
 	 *
 	 * @returns
 	 * The details of the tweet with the given id.
@@ -70,11 +69,11 @@ export class TweetService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async details(id: string): Promise<Tweet | undefined> {
+	public async details<T extends string | string[]>(id: T): Promise<T extends string ? Tweet | undefined : Tweet[]> {
 		let resource: EResourceType;
 
-		// If user is authenticated
-		if (this.userId != undefined) {
+		// If user is authenticated and details of single tweet required
+		if (this.config.userId != undefined && typeof id == 'string') {
 			resource = EResourceType.TWEET_DETAILS_ALT;
 
 			// Fetching raw tweet details
@@ -83,19 +82,31 @@ export class TweetService extends FetcherService {
 			// Deserializing response
 			const data = extractors[resource](response, id);
 
-			return data;
+			return data as T extends string ? Tweet | undefined : Tweet[];
+		}
+		// If user is authenticated and details of multiple tweets required
+		else if (this.config.userId != undefined && Array.isArray(id)) {
+			resource = EResourceType.TWEET_DETAILS_BULK;
+
+			// Fetching raw tweet details
+			const response = await this.request<ITweetRepliesResponse>(resource, { ids: id });
+
+			// Deserializing response
+			const data = extractors[resource](response, id);
+
+			return data as T extends string ? Tweet | undefined : Tweet[];
 		}
 		// If user is not authenticated
 		else {
 			resource = EResourceType.TWEET_DETAILS;
 
 			// Fetching raw tweet details
-			const response = await this.request<ITweetDetailsResponse>(resource, { id: id });
+			const response = await this.request<ITweetDetailsResponse>(resource, { id: String(id) });
 
 			// Deserializing response
-			const data = extractors[resource](response, id);
+			const data = extractors[resource](response, String(id));
 
-			return data;
+			return data as T extends string ? Tweet | undefined : Tweet[];
 		}
 	}
 
@@ -137,6 +148,48 @@ export class TweetService extends FetcherService {
 		return data;
 	}
 
+	/**
+	 * Get the list of users who liked a tweet. Only works for your own tweets.
+	 *
+	 * @param id - The id of the target tweet.
+	 * @param count - The number of likers to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of likers to fetch.
+	 *
+	 * @returns The list of users who liked the given tweet.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the most recent 100 likers of the Tweet with id '1234567890'
+	 * rettiwt.tweet.likers('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async likers(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		const resource = EResourceType.TWEET_LIKERS;
+
+		// Fetching raw likers
+		const response = await this.request<ITweetLikersResponse>(resource, {
+			id: id,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = extractors[resource](response);
+
+		return data;
+	}
+
 	/**
 	 * Get the list of tweets from a tweet list.
 	 *
@@ -263,7 +316,7 @@ export class TweetService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async post(options: TweetArgs): Promise<string | undefined> {
+	public async post(options: INewTweet): Promise<string | undefined> {
 		const resource = EResourceType.TWEET_POST;
 
 		// Posting the tweet
@@ -275,6 +328,46 @@ export class TweetService extends FetcherService {
 		return data;
 	}
 
+	/**
+	 * Get the list of replies to a tweet.
+	 *
+	 * @param id - The id of the target tweet.
+	 * @param cursor - The cursor to the batch of replies to fetch.
+	 *
+	 * @returns The list of replies to the given tweet.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 100 replies to the Tweet with id '1234567890'
+	 * rettiwt.tweet.replies('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async replies(id: string, cursor?: string): Promise<CursoredData<Tweet>> {
+		const resource = EResourceType.TWEET_REPLIES;
+
+		// Fetching raw list of replies
+		const response = await this.request<ITweetDetailsResponse>(resource, {
+			id: id,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = extractors[resource](response);
+
+		return data;
+	}
+
 	/**
 	 * Retweet a tweet.
 	 *
@@ -381,7 +474,7 @@ export class TweetService extends FetcherService {
 	 * @remarks
 	 * Scheduling a tweet is similar to {@link post}ing, except that an extra parameter called `scheduleFor` is used.
 	 */
-	public async schedule(options: TweetArgs): Promise<string | undefined> {
+	public async schedule(options: INewTweet): Promise<string | undefined> {
 		const resource = EResourceType.TWEET_SCHEDULE;
 
 		// Scheduling the tweet
@@ -422,12 +515,7 @@ export class TweetService extends FetcherService {
 	 *
 	 * @remarks For details about available filters, refer to {@link TweetFilter}
 	 */
-	public async search(
-		filter: TweetFilter,
-		count?: number,
-		cursor?: string,
-		results?: ESearchResultType,
-	): Promise<CursoredData<Tweet>> {
+	public async search(filter: ITweetFilter, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
 		const resource = EResourceType.TWEET_SEARCH;
 
 		// Fetching raw list of filtered tweets
@@ -435,7 +523,6 @@ export class TweetService extends FetcherService {
 			filter: filter,
 			count: count,
 			cursor: cursor,
-			results: results,
 		});
 
 		// Deserializing response
@@ -479,7 +566,7 @@ export class TweetService extends FetcherService {
 	 * streamTweets();
 	 * ```
 	 */
-	public async *stream(filter: TweetFilter, pollingInterval: number = 60000): AsyncGenerator<Tweet> {
+	public async *stream(filter: ITweetFilter, pollingInterval = 60000): AsyncGenerator<Tweet> {
 		const startDate = new Date();
 
 		let cursor: string | undefined = undefined;
@@ -505,7 +592,7 @@ export class TweetService extends FetcherService {
 
 			// If there are more tweets to fetch, adjust the cursor value
 			if (tweets.list.length > 0 && tweets.next) {
-				cursor = tweets.next.value;
+				cursor = tweets.next;
 			}
 			// Else, start the next iteration from this batch's most recent tweet
 			else {
@@ -692,7 +779,7 @@ export class TweetService extends FetcherService {
 		// INITIALIZE
 		const size = typeof media == 'string' ? statSync(media).size : media.byteLength;
 		const id: string = (
-			await this.request<IInitializeMediaUploadResponse>(EResourceType.MEDIA_UPLOAD_INITIALIZE, {
+			await this.request<IMediaInitializeUploadResponse>(EResourceType.MEDIA_UPLOAD_INITIALIZE, {
 				upload: { size: size },
 			})
 		).media_id_string;

package/src/services/public/UserService.ts

@@ -1,28 +1,25 @@
-import {
-	IUserBookmarksResponse,
-	IUserDetailsResponse,
-	IUserFollowedResponse,
-	IUserFollowersResponse,
-	IUserFollowingResponse,
-	IUserFollowResponse,
-	IUserHighlightsResponse,
-	IUserLikesResponse,
-	IUserMediaResponse,
-	IUserNotificationsResponse,
-	IUserRecommendedResponse,
-	IUserSubscriptionsResponse,
-	IUserTweetsAndRepliesResponse,
-	IUserTweetsResponse,
-	IUserUnfollowResponse,
-} from 'rettiwt-core';
-
 import { extractors } from '../../collections/Extractors';
 import { EResourceType } from '../../enums/Resource';
 import { CursoredData } from '../../models/data/CursoredData';
 import { Notification } from '../../models/data/Notification';
 import { Tweet } from '../../models/data/Tweet';
 import { User } from '../../models/data/User';
-import { IRettiwtConfig } from '../../types/RettiwtConfig';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IUserBookmarksResponse } from '../../types/raw/user/Bookmarks';
+import { IUserDetailsResponse } from '../../types/raw/user/Details';
+import { IUserFollowResponse } from '../../types/raw/user/Follow';
+import { IUserFollowedResponse } from '../../types/raw/user/Followed';
+import { IUserFollowersResponse } from '../../types/raw/user/Followers';
+import { IUserFollowingResponse } from '../../types/raw/user/Following';
+import { IUserHighlightsResponse } from '../../types/raw/user/Highlights';
+import { IUserLikesResponse } from '../../types/raw/user/Likes';
+import { IUserMediaResponse } from '../../types/raw/user/Media';
+import { IUserNotificationsResponse } from '../../types/raw/user/Notifications';
+import { IUserRecommendedResponse } from '../../types/raw/user/Recommended';
+import { IUserSubscriptionsResponse } from '../../types/raw/user/Subscriptions';
+import { IUserTweetsResponse } from '../../types/raw/user/Tweets';
+import { IUserTweetsAndRepliesResponse } from '../../types/raw/user/TweetsAndReplies';
+import { IUserUnfollowResponse } from '../../types/raw/user/Unfollow';
 
 import { FetcherService } from './FetcherService';
 
@@ -37,7 +34,7 @@ export class UserService extends FetcherService {
 	 *
 	 * @internal
 	 */
-	public constructor(config?: IRettiwtConfig) {
+	public constructor(config: RettiwtConfig) {
 		super(config);
 	}
 
@@ -84,7 +81,7 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the details of a user.
 	 *
-	 * @param id - The username/id of the target user.
+	 * @param id - The username/id(s) of the target user/users.
 	 *
 	 * @returns
 	 * The details of the given user.
@@ -126,25 +123,40 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async details(id: string): Promise<User | undefined> {
+	public async details<T extends string | string[]>(id: T): Promise<T extends string ? User | undefined : User[]> {
 		let resource: EResourceType;
 
-		// If username is given
-		if (isNaN(Number(id))) {
-			resource = EResourceType.USER_DETAILS_BY_USERNAME;
+		// If details of multiple users required
+		if (Array.isArray(id)) {
+			resource = EResourceType.USER_DETAILS_BY_IDS_BULK;
+
+			// Fetching raw details
+			const response = await this.request<IUserDetailsResponse>(resource, { ids: id });
+
+			// Deserializing response
+			const data = extractors[resource](response, id);
+
+			return data as T extends string ? User | undefined : User[];
 		}
-		// If id is given
+		// If details of single user required
 		else {
-			resource = EResourceType.USER_DETAILS_BY_ID;
-		}
+			// If username is given
+			if (isNaN(Number(id))) {
+				resource = EResourceType.USER_DETAILS_BY_USERNAME;
+			}
+			// If id is given
+			else {
+				resource = EResourceType.USER_DETAILS_BY_ID;
+			}
 
-		// Fetching raw details
-		const response = await this.request<IUserDetailsResponse>(resource, { id: id });
+			// Fetching raw details
+			const response = await this.request<IUserDetailsResponse>(resource, { id: id });
 
-		// Deserializing response
-		const data = extractors[resource](response);
+			// Deserializing response
+			const data = extractors[resource](response);
 
-		return data;
+			return data as T extends string ? User | undefined : User[];
+		}
 	}
 
 	/**
@@ -381,7 +393,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of likes
 		const response = await this.request<IUserLikesResponse>(resource, {
-			id: this.userId,
+			id: this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -465,11 +477,11 @@ export class UserService extends FetcherService {
 	 * streamNotifications();
 	 * ```
 	 */
-	public async *notifications(pollingInterval: number = 60000): AsyncGenerator<Notification> {
+	public async *notifications(pollingInterval = 60000): AsyncGenerator<Notification> {
 		const resource = EResourceType.USER_NOTIFICATIONS;
 
 		/** Whether it's the first batch of notifications or not. */
-		let first: boolean = true;
+		let first = true;
 
 		/** The cursor to the last notification received. */
 		let cursor: string | undefined = undefined;
@@ -502,7 +514,7 @@ export class UserService extends FetcherService {
 				first = false;
 			}
 
-			cursor = notifications.next.value;
+			cursor = notifications.next;
 		}
 	}
 

package/src/types/RettiwtConfig.ts

@@ -1,3 +1,4 @@
+import { ITidProvider } from './auth/TidProvider';
 import { IErrorHandler } from './ErrorHandler';
 
 /**
@@ -9,9 +10,6 @@ export interface IRettiwtConfig {
 	/** The apiKey (cookie) to use for authenticating Rettiwt against Twitter API. */
 	apiKey?: string;
 
-	/** The guestKey (guest token) to use for guest access to Twitter API. */
-	guestKey?: string;
-
 	/**
 	 * Optional URL to proxy server to use for requests to Twitter API.
 	 *
@@ -19,15 +17,6 @@ export interface IRettiwtConfig {
 	 */
 	proxyUrl?: URL;
 
-	/**
-	 * Optional URL to proxy server to use for authentication against Twitter API.
-	 *
-	 * @remarks Required when deploying to cloud platforms to bypass Error 429.
-	 *
-	 * @defaultValue Same as {@link IRettiwtConfig.proxyUrl}
-	 */
-	authProxyUrl?: URL;
-
 	/** The max wait time (in milli-seconds) for a response; if not set, Twitter server timeout is used. */
 	timeout?: number;
 
@@ -36,4 +25,21 @@ export interface IRettiwtConfig {
 
 	/** Optional custom error handler to define error conditions and process API/HTTP errors in responses. */
 	errorHandler?: IErrorHandler;
+
+	/** Optional custom `x-client-transaction-id` header provider. */
+	tidProvider?: ITidProvider;
+
+	/**
+	 * Optional custom HTTP headers to add to all requests to Twitter API.
+	 *
+	 * @remarks Custom headers can be useful for proxies, avoiding rate limits, etc.
+	 */
+	headers?: { [key: string]: string };
+
+	/**
+	 * The delay (in ms) to use between concurrent request.
+	 *
+	 * Can either be a number or a function that returns a number synchronously or asynchronously.
+	 */
+	delay?: number | (() => number | Promise<number>);
 }

package/src/types/args/FetchArgs.ts

@@ -0,0 +1,148 @@
+/**
+ * Options specifying the data that is to be fetched.
+ *
+ * @public
+ */
+export interface IFetchArgs {
+	/**
+	 * The number of data items to fetch.
+	 *
+	 * @remarks
+	 * - Works only for cursored resources.
+	 * - Does not work for {@link EResourceType.TWEET_REPLIES}.
+	 * - Must be \<= 20 for:
+	 * 	- {@link EResourceType.USER_TIMELINE}
+	 * 	- {@link EResourceType.USER_TIMELINE}
+	 * 	- {@link EResourceType.USER_TIMELINE_AND_REPLIES}
+	 * - Must be \<= 100 for all other cursored resources.
+	 * - Due a bug on Twitter's end, count does not work for {@link EResourceType.USER_FOLLOWERS} and {@link EResourceType.USER_FOLLOWING}.
+	 * - Has not effect for:
+	 * 	- {@link EResourceType.USER_FEED_FOLLOWED}
+	 * 	- {@link EResourceType.USER_FEED_RECOMMENDED}
+	 */
+	count?: number;
+
+	/**
+	 * The cursor to the batch of data to fetch.
+	 *
+	 * @remarks
+	 * - May be used for cursored resources.
+	 * - Has no effect for other resources.
+	 */
+	cursor?: string;
+
+	/**
+	 * The filter for searching tweets.
+	 *
+	 * @remarks
+	 * Required when searching for tweets using {@link EResourceType.TWEET_SEARCH}.
+	 */
+	filter?: ITweetFilter;
+
+	/**
+	 * The id of the target resource.
+	 *
+	 * @remarks
+	 * - Required for all resources except {@link EResourceType.TWEET_SEARCH} and {@link EResourceType.USER_TIMELINE_RECOMMENDED}.
+	 * - For {@link EResourceType.USER_DETAILS_BY_USERNAME}, can be alphanumeric, while for others, is strictly numeric.
+	 */
+	id?: string;
+
+	/**
+	 * The IDs of the target resources.
+	 *
+	 * @remarks
+	 * - Required only for {@link EResourceType.TWEET_DETAILS_BULK} and {@link EResourceType.USER_DETAILS_BY_IDS_BULK}.
+	 */
+	ids?: string[];
+}
+
+/**
+ * The filter to be used for searching tweets.
+ *
+ * @public
+ */
+export interface ITweetFilter {
+	/** The date upto which tweets are to be searched. */
+	endDate?: Date;
+
+	/** The list of words to exclude from search. */
+	excludeWords?: string[];
+
+	/**
+	 * The list of usernames whose tweets are to be searched.
+	 *
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	fromUsers?: string[];
+
+	/**
+	 * The list of hashtags to search.
+	 *
+	 * @remarks
+	 * '#' must be excluded from the hashtag!
+	 */
+	hashtags?: string[];
+
+	/** The exact phrase to search. */
+	includePhrase?: string;
+
+	/** The list of words to search. */
+	includeWords?: string[];
+
+	/** The language of the tweets to search. */
+	language?: string;
+
+	/** Whether to fetch tweets that are links or not. */
+	links?: boolean;
+
+	/** The list from which tweets are to be searched. */
+	list?: string;
+
+	/** The id of the tweet, before which the tweets are to be searched. */
+	maxId?: string;
+
+	/**
+	 * The list of username mentioned in the tweets to search.
+	 *
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	mentions?: string[];
+
+	/** The minimun number of likes to search by. */
+	minLikes?: number;
+
+	/** The minimum number of replies to search by. */
+	minReplies?: number;
+
+	/** The minimum number of retweets to search by. */
+	minRetweets?: number;
+
+	/** The optional words to search. */
+	optionalWords?: string[];
+
+	/** The id of the tweet which is quoted in the tweets to search. */
+	quoted?: string;
+
+	/** Whether to fetch tweets that are replies or not. */
+	replies?: boolean;
+
+	/** The id of the tweet, after which the tweets are to be searched. */
+	sinceId?: string;
+
+	/** The date starting from which tweets are to be searched. */
+	startDate?: Date;
+
+	/**
+	 * The list of username to whom the tweets to be searched, are adressed.
+	 *
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	toUsers?: string[];
+
+	/** Whether to fetch top tweets or not. */
+	top?: boolean;
+}