rettiwt-api 4.2.0 → 5.0.0-alpha.1

package/src/models/data/Tweet.ts

@@ -5,7 +5,6 @@ import {
 	ITweet as IRawTweet,
 	IEntities as IRawTweetEntities,
 	ITimelineTweet,
-	ITweet,
 } from 'rettiwt-core';
 
 import { ELogActions } from '../../enums/Logging';
@@ -13,6 +12,8 @@ import { findByFilter } from '../../helper/JsonUtils';
 
 import { LogService } from '../../services/internal/LogService';
 
+import { ITweet } from '../../types/data/Tweet';
+
 import { User } from './User';
 
 /**
@@ -20,53 +21,24 @@ import { User } from './User';
  *
  * @public
  */
-export class Tweet {
-	/** The number of bookmarks of a tweet. */
+export class Tweet implements ITweet {
 	public bookmarkCount: number;
-
-	/** The date and time of creation of the tweet, in UTC string format. */
+	public conversationId: string;
 	public createdAt: string;
-
-	/** Additional tweet entities like urls, mentions, etc. */
 	public entities: TweetEntities;
-
-	/** The full text content of the tweet. */
 	public fullText: string;
-
-	/** The rest id of the tweet. */
 	public id: string;
-
-	/** The language in which the tweet is written. */
 	public lang: string;
-
-	/** The number of likes of the tweet. */
 	public likeCount: number;
-
-	/** The urls of the media contents of the tweet (if any). */
 	public media?: TweetMedia[];
-
-	/** The number of quotes of the tweet. */
 	public quoteCount: number;
-
-	/** The tweet which is quoted in the tweet. */
 	public quoted?: Tweet;
-
-	/** The number of replies to the tweet. */
 	public replyCount: number;
-
-	/** The rest id of the tweet to which the tweet is a reply. */
 	public replyTo?: string;
-
-	/** The number of retweets of the tweet. */
 	public retweetCount: number;
-
-	/** The tweet which is retweeted in this tweet (if any). */
 	public retweetedTweet?: Tweet;
-
-	/** The details of the user who made the tweet. */
 	public tweetBy: User;
-
-	/** The number of views of a tweet. */
+	public url: string;
 	public viewCount: number;
 
 	/**
@@ -74,6 +46,7 @@ export class Tweet {
 	 */
 	public constructor(tweet: IRawTweet) {
 		this.id = tweet.rest_id;
+		this.conversationId = tweet.legacy.conversation_id_str;
 		this.createdAt = tweet.legacy.created_at;
 		this.tweetBy = new User(tweet.core.user_results.result);
 		this.entities = new TweetEntities(tweet.legacy.entities);
@@ -89,6 +62,7 @@ export class Tweet {
 		this.viewCount = tweet.views.count ? parseInt(tweet.views.count) : 0;
 		this.bookmarkCount = tweet.legacy.bookmark_count;
 		this.retweetedTweet = this.getRetweetedTweet(tweet);
+		this.url = `https://x.com/${this.tweetBy.userName}/status/${this.id}`;
 	}
 
 	/**
@@ -108,8 +82,8 @@ export class Tweet {
 			return new Tweet((tweet.quoted_status_result.result as ILimitedVisibilityTweet).tweet);
 		}
 		// If normal tweet
-		else if ((tweet.quoted_status_result?.result as ITweet)?.rest_id) {
-			return new Tweet(tweet.quoted_status_result.result as ITweet);
+		else if ((tweet.quoted_status_result?.result as IRawTweet)?.rest_id) {
+			return new Tweet(tweet.quoted_status_result.result as IRawTweet);
 		}
 		// Else, skip
 		else {
@@ -134,8 +108,8 @@ export class Tweet {
 			return new Tweet((tweet.legacy.retweeted_status_result.result as ILimitedVisibilityTweet).tweet);
 		}
 		// If normal tweet
-		else if ((tweet.legacy?.retweeted_status_result?.result as ITweet)?.rest_id) {
-			return new Tweet(tweet.legacy.retweeted_status_result.result as ITweet);
+		else if ((tweet.legacy?.retweeted_status_result?.result as IRawTweet)?.rest_id) {
+			return new Tweet(tweet.legacy.retweeted_status_result.result as IRawTweet);
 		}
 		// Else, skip
 		else {
@@ -169,11 +143,11 @@ export class Tweet {
 				tweets.push(new Tweet((item.tweet_results.result as ILimitedVisibilityTweet).tweet));
 			}
 			// If normal tweet
-			else if ((item.tweet_results?.result as ITweet)?.legacy) {
+			else if ((item.tweet_results?.result as IRawTweet)?.legacy) {
 				// Logging
-				LogService.log(ELogActions.DESERIALIZE, { id: (item.tweet_results.result as ITweet).rest_id });
+				LogService.log(ELogActions.DESERIALIZE, { id: (item.tweet_results.result as IRawTweet).rest_id });
 
-				tweets.push(new Tweet(item.tweet_results.result as ITweet));
+				tweets.push(new Tweet(item.tweet_results.result as IRawTweet));
 			}
 			// If invalid/unrecognized tweet
 			else {
@@ -202,7 +176,7 @@ export class Tweet {
 		const tweets: Tweet[] = [];
 
 		// Extracting the matching data
-		const extract = findByFilter<ITweet>(response, 'rest_id', id);
+		const extract = findByFilter<IRawTweet>(response, 'rest_id', id);
 
 		// Deserializing valid data
 		for (const item of extract) {
@@ -279,7 +253,7 @@ export class TweetMedia {
 	public type: EMediaType;
 
 	/** The direct URL to the media. */
-	public url: string = '';
+	public url = '';
 
 	/**
 	 * @param media - The raw media details.
@@ -300,7 +274,7 @@ export class TweetMedia {
 			this.thumbnailUrl = media.media_url_https;
 
 			/** The highest bitrate of all variants. */
-			let highestRate: number = 0;
+			let highestRate = 0;
 
 			/**
 			 * Selecting the URL of the video variant with the highest bitrate.

package/src/models/data/User.ts

@@ -1,55 +1,29 @@
-import { IUser as IRawUser, ITimelineUser, IUser } from 'rettiwt-core';
+import { ITimelineUser as IRawTimelineUser, IUser as IRawUser } from 'rettiwt-core';
 
 import { ELogActions } from '../../enums/Logging';
 import { findByFilter } from '../../helper/JsonUtils';
 import { LogService } from '../../services/internal/LogService';
+import { IUser } from '../../types/data/User';
 
 /**
  * The details of a single user.
  *
  * @public
  */
-export class User {
-	/** The creation date of user's account. */
+export class User implements IUser {
 	public createdAt: string;
-
-	/** The user's description. */
 	public description?: string;
-
-	/** The number of followers of the user. */
 	public followersCount: number;
-
-	/** The number of following of the user. */
 	public followingsCount: number;
-
-	/** The full name of the user. */
 	public fullName: string;
-
-	/** The rest id of the user. */
 	public id: string;
-
-	/** Whether the account is verified or not. */
 	public isVerified: boolean;
-
-	/** The number of tweets liked by the user. */
 	public likeCount: number;
-
-	/** The location of user as provided by user. */
 	public location?: string;
-
-	/** The rest id of the tweet pinned in the user's profile. */
 	public pinnedTweet?: string;
-
-	/** The url of the profile banner image. */
 	public profileBanner?: string;
-
-	/** The url of the profile image. */
 	public profileImage: string;
-
-	/** The number of tweets made by the user. */
 	public statusesCount: number;
-
-	/** The username/screenname of the user. */
 	public userName: string;
 
 	/**
@@ -85,7 +59,7 @@ export class User {
 		const users: User[] = [];
 
 		// Extracting the matching data
-		const extract = findByFilter<ITimelineUser>(response, '__typename', 'TimelineUser');
+		const extract = findByFilter<IRawTimelineUser>(response, '__typename', 'TimelineUser');
 
 		// Deserializing valid data
 		for (const item of extract) {
@@ -119,7 +93,7 @@ export class User {
 		const users: User[] = [];
 
 		// Extracting the matching data
-		const extract = findByFilter<IUser>(response, '__typename', 'User');
+		const extract = findByFilter<IRawUser>(response, '__typename', 'User');
 
 		// Deserializing valid data
 		for (const item of extract) {

package/src/services/{public → internal}/AuthService.ts

@@ -1,23 +1,29 @@
-import { Auth } from 'rettiwt-auth';
+import https, { Agent } from 'https';
+
+import axios from 'axios';
+
+import { HttpsProxyAgent } from 'https-proxy-agent';
 
 import { EApiErrors } from '../../enums/Api';
+import { AuthCredential } from '../../models/auth/AuthCredential';
 import { IRettiwtConfig } from '../../types/RettiwtConfig';
 
-import { FetcherService } from './FetcherService';
-
 /**
  * The services that handles authentication.
  *
  * @public
  */
-export class AuthService extends FetcherService {
+export class AuthService {
+	/** The HTTPS Agent to use for requests to Twitter API. */
+	private readonly _httpsAgent: Agent;
+
 	/**
 	 * @param config - The config object for configuring the `Rettiwt` instance.
 	 *
 	 * @internal
 	 */
 	public constructor(config?: IRettiwtConfig) {
-		super(config);
+		this._httpsAgent = config?.proxyUrl ? new HttpsProxyAgent(config.proxyUrl) : new https.Agent();
 	}
 
 	/**
@@ -94,57 +100,24 @@ export class AuthService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async guest(): Promise<string> {
-		// Getting a new guest key
-		const guestKey: string = (await new Auth().getGuestCredential()).guestToken ?? '';
-
-		return guestKey;
-	}
-
-	/**
-	 * Login to twitter using account credentials.
-	 *
-	 * @param email - The email id associated with the Twitter account.
-	 * @param userName - The username associated with the Twitter account.
-	 * @param password - The password to the Twitter account.
-	 *
-	 * @returns The `API_KEY` for the Twitter account.
-	 *
-	 * @example
-	 * ```
-	 * import { Rettiwt } from 'rettiwt-api';
-	 *
-	 * // Creating a new Rettiwt instance
-	 * const rettiwt = new Rettiwt();
-	 *
-	 * // Logging in an getting the API_KEY
-	 * rettiwt.auth.login("email@domain.com", "username", "password")
-	 * .then(apiKey => {
-	 * 	// Use the API_KEY
-	 * 	...
-	 * })
-	 * .catch(err => {
-	 * 	console.log(err);
-	 * });
-	 * ```
-	 *
-	 * @remarks
-	 * Interchanging `email` and `userName` works too.
-	 */
-	public async login(email: string, userName: string, password: string): Promise<string> {
-		// Logging in and getting the credentials
-		let apiKey: string =
-			((
-				await new Auth({ proxyUrl: this.authProxyUrl }).getUserCredential({
-					email: email,
-					userName: userName,
-					password: password,
-				})
-			).toHeader().cookie as string) ?? '';
+	public async guest(): Promise<AuthCredential> {
+		// Creating a new blank credential
+		const cred: AuthCredential = new AuthCredential();
 
-		// Converting the credentials to base64 string
-		apiKey = AuthService.encodeCookie(apiKey);
+		// Getting the guest token
+		await axios
+			.get<{
+				/* eslint-disable @typescript-eslint/naming-convention */
+				guest_token: string;
+				/* eslint-enable @typescript-eslint/naming-convention */
+			}>('https://api.twitter.com/1.1/guest/activate.json', {
+				headers: cred.toHeader(),
+				httpsAgent: this._httpsAgent,
+			})
+			.then((res) => {
+				cred.guestToken = res.data.guest_token;
+			});
 
-		return apiKey;
+		return cred;
 	}
 }

package/src/services/internal/LogService.ts

@@ -1,5 +1,3 @@
-import chalk from 'chalk';
-
 import { ELogActions } from '../../enums/Logging';
 
 /**
@@ -9,20 +7,7 @@ import { ELogActions } from '../../enums/Logging';
  */
 export class LogService {
 	/** Whether logging is enabled or not. */
-	public static enabled: boolean = false;
-
-	/**
-	 * @param action - The action to be logged.
-	 *
-	 * @returns - The colored text representing the action.
-	 */
-	private static getColoredAction(action: ELogActions): string {
-		if (action == ELogActions.WARNING) {
-			return chalk.yellow(action);
-		} else {
-			return chalk.green(action);
-		}
-	}
+	public static enabled = false;
 
 	/**
 	 * Logs the given data.
@@ -35,12 +20,12 @@ export class LogService {
 		// Proceed to log only if logging is enabled
 		if (this.enabled) {
 			// Preparing the log message
-			const logPrefix: string = chalk.blue('Rettiwt-API');
+			const logPrefix = 'Rettiwt-API';
 			const logTime: string = new Date().toISOString();
-			const logAction: string = LogService.getColoredAction(action);
+			const logAction: string = action;
 			const logData: string = JSON.stringify(data);
 
-			const logMessage: string = `[${logPrefix}] [${logTime}] [${logAction}] ${logData}`;
+			const logMessage = `[${logPrefix}] [${logTime}] [${logAction}] ${logData}`;
 
 			// Logging
 			console.log(logMessage);

package/src/services/public/FetcherService.ts

@@ -1,8 +1,8 @@
 import https, { Agent } from 'https';
 
 import axios from 'axios';
+import { Cookie } from 'cookiejar';
 import { HttpsProxyAgent } from 'https-proxy-agent';
-import { Auth, AuthCredential } from 'rettiwt-auth';
 
 import { allowGuestAuthentication, fetchResources, postResources } from '../../collections/Groups';
 import { requests } from '../../collections/Requests';
@@ -11,14 +11,16 @@ import { ELogActions } from '../../enums/Logging';
 import { EResourceType } from '../../enums/Resource';
 import { FetchArgs } from '../../models/args/FetchArgs';
 import { PostArgs } from '../../models/args/PostArgs';
+import { AuthCredential } from '../../models/auth/AuthCredential';
+import { IFetchArgs } from '../../types/args/FetchArgs';
+import { IPostArgs } from '../../types/args/PostArgs';
 import { IErrorHandler } from '../../types/ErrorHandler';
 import { IRettiwtConfig } from '../../types/RettiwtConfig';
 
+import { AuthService } from '../internal/AuthService';
 import { ErrorService } from '../internal/ErrorService';
 import { LogService } from '../internal/LogService';
 
-import { AuthService } from './AuthService';
-
 /**
  * The base service that handles all HTTP requests.
  *
@@ -28,6 +30,9 @@ export class FetcherService {
 	/** The api key to use for authenticating against Twitter API as user. */
 	private readonly _apiKey?: string;
 
+	/** Custom headers to use for all requests */
+	private readonly _customHeaders?: { [key: string]: string };
+
 	/** The service used to handle HTTP and API errors */
 	private readonly _errorHandler: IErrorHandler;
 
@@ -58,6 +63,7 @@ export class FetcherService {
 		this._proxyUrl = config?.proxyUrl;
 		this._timeout = config?.timeout ?? 0;
 		this._errorHandler = config?.errorHandler ?? new ErrorService();
+		this._customHeaders = config?.headers;
 	}
 
 	/**
@@ -87,7 +93,11 @@ export class FetcherService {
 			// Logging
 			LogService.log(ELogActions.GET, { target: 'USER_CREDENTIAL' });
 
-			return new AuthCredential(AuthService.decodeCookie(this._apiKey).split(';'));
+			return new AuthCredential(
+				AuthService.decodeCookie(this._apiKey)
+					.split(';')
+					.map((item) => new Cookie(item)),
+			);
 		} else if (this._guestKey) {
 			// Logging
 			LogService.log(ELogActions.GET, { target: 'GUEST_CREDENTIAL' });
@@ -97,7 +107,7 @@ export class FetcherService {
 			// Logging
 			LogService.log(ELogActions.GET, { target: 'NEW_GUEST_CREDENTIAL' });
 
-			return await new Auth({ proxyUrl: this.authProxyUrl }).getGuestCredential();
+			return await new AuthService({ proxyUrl: this.authProxyUrl }).guest();
 		}
 	}
 
@@ -130,7 +140,7 @@ export class FetcherService {
 	 *
 	 * @returns The validated args.
 	 */
-	private validateArgs(resource: EResourceType, args: FetchArgs | PostArgs): FetchArgs | PostArgs | undefined {
+	private validateArgs(resource: EResourceType, args: IFetchArgs | IPostArgs): FetchArgs | PostArgs | undefined {
 		if (fetchResources.includes(resource)) {
 			// Logging
 			LogService.log(ELogActions.VALIDATE, { target: 'FETCH_ARGS' });
@@ -172,7 +182,7 @@ export class FetcherService {
 	 * })
 	 * ```
 	 */
-	public async request<T>(resource: EResourceType, args: FetchArgs | PostArgs): Promise<T> {
+	public async request<T>(resource: EResourceType, args: IFetchArgs | IPostArgs): Promise<T> {
 		// Logging
 		LogService.log(ELogActions.REQUEST, { resource: resource, args: args });
 
@@ -192,7 +202,7 @@ export class FetcherService {
 		const config = requests[resource](args);
 
 		// Setting additional request parameters
-		config.headers = { ...config.headers, ...cred.toHeader() };
+		config.headers = { ...config.headers, ...cred.toHeader(), ...(this._customHeaders || {}) };
 		config.httpAgent = httpsAgent;
 		config.httpsAgent = httpsAgent;
 		config.timeout = this._timeout;

package/src/services/public/TweetService.ts

@@ -4,6 +4,7 @@ import {
 	ESearchResultType,
 	IInitializeMediaUploadResponse,
 	IListTweetsResponse,
+	INewTweet,
 	ITweetDetailsResponse,
 	ITweetLikeResponse,
 	ITweetPostResponse,
@@ -21,7 +22,6 @@ import {
 
 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';
@@ -263,7 +263,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 +275,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 +421,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
@@ -479,7 +519,7 @@ export class TweetService extends FetcherService {
 	 * streamTweets();
 	 * ```
 	 */
-	public async *stream(filter: TweetFilter, pollingInterval: number = 60000): AsyncGenerator<Tweet> {
+	public async *stream(filter: TweetFilter, pollingInterval = 60000): AsyncGenerator<Tweet> {
 		const startDate = new Date();
 
 		let cursor: string | undefined = undefined;

package/src/services/public/UserService.ts

@@ -465,11 +465,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;

package/src/types/RettiwtConfig.ts

@@ -36,4 +36,11 @@ export interface IRettiwtConfig {
 
 	/** Optional custom error handler to define error conditions and process API/HTTP errors in responses. */
 	errorHandler?: IErrorHandler;
+
+	/**
+	 * 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 };
 }

package/src/types/args/FetchArgs.ts

@@ -0,0 +1,64 @@
+import { ESearchResultType, ITweetFilter } from 'rettiwt-core';
+
+/**
+ * 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 type of search results to fetch. Can be one of:
+	 * - {@link EResourceType.LATEST}, for latest search results.
+	 * - {@link EResourceType.TOP}, for top search results.
+	 *
+	 * @defaultValue {@link ESearchResultType.LATEST}.
+	 *
+	 * @remarks
+	 * - Applicable only for {@link EResourceType.TWEET_SEARCH}.
+	 */
+	results?: ESearchResultType;
+}