rettiwt-api 1.4.0 → 2.0.1

package/src/models/Tweet.ts

@@ -0,0 +1,116 @@
+// TYPES
+import { ITweet, ITweetEntities } from '../types/Tweet';
+import { ITweet as IRawTweet, IEntities as IRawTweetEntities } from 'rettiwt-core';
+
+// PARSERS
+import { normalizeText } from '../helper/JsonUtils';
+
+/**
+ * The different types parsed entities like urls, media, mentions, hashtags, etc.
+ *
+ * @public
+ */
+export class TweetEntities implements ITweetEntities {
+	/** The list of hashtags mentioned in the tweet. */
+	hashtags: string[] = [];
+
+	/** The list of urls mentioned in the tweet. */
+	urls: string[] = [];
+
+	/** The list of IDs of users mentioned in the tweet. */
+	mentionedUsers: string[] = [];
+
+	/** The list of urls to various media mentioned in the tweet. */
+	media: string[] = [];
+
+	constructor(entities: IRawTweetEntities) {
+		// Extracting user mentions
+		if (entities.user_mentions) {
+			for (const user of entities.user_mentions) {
+				this.mentionedUsers.push(user.screen_name);
+			}
+		}
+
+		// Extracting urls
+		if (entities.urls) {
+			for (const url of entities.urls) {
+				this.urls.push(url.expanded_url);
+			}
+		}
+
+		// Extracting hashtags
+		if (entities.hashtags) {
+			for (const hashtag of entities.hashtags) {
+				this.hashtags.push(hashtag.text);
+			}
+		}
+
+		// Extracting media urls (if any)
+		if (entities.media) {
+			for (const media of entities.media) {
+				this.media.push(media.media_url_https);
+			}
+		}
+	}
+}
+
+/**
+ * The details of a single Tweet.
+ *
+ * @public
+ */
+export class Tweet implements ITweet {
+	/** The rest id of the tweet. */
+	id: string;
+
+	/** The rest id of the user who made the tweet. */
+	tweetBy: string;
+
+	/** The date and time of creation of the tweet, in UTC string format. */
+	createdAt: string;
+
+	/** Additional tweet entities like urls, mentions, etc. */
+	entities: TweetEntities;
+
+	/** The rest id of the tweet which is quoted in the tweet. */
+	quoted: string;
+
+	/** The full text content of the tweet. */
+	fullText: string;
+
+	/** The rest id of the user to which the tweet is a reply. */
+	replyTo: string;
+
+	/** The language in which the tweet is written. */
+	lang: string;
+
+	/** The number of quotes of the tweet. */
+	quoteCount: number;
+
+	/** The number of replies to the tweet. */
+	replyCount: number;
+
+	/** The number of retweets of the tweet. */
+	retweetCount: number;
+
+	/** The number of likes of the tweet. */
+	likeCount: number;
+
+	/**
+	 * @param tweet - The raw tweet data.
+	 */
+	constructor(tweet: IRawTweet) {
+		this.id = tweet.rest_id;
+		this.createdAt = tweet.legacy.created_at;
+		this.tweetBy = tweet.legacy.user_id_str;
+		this.entities = new TweetEntities(tweet.legacy.entities);
+		this.quoted = tweet.legacy.quoted_status_id_str;
+		this.fullText = normalizeText(tweet.legacy.full_text);
+		this.replyTo = tweet.legacy.in_reply_to_status_id_str;
+		this.lang = tweet.legacy.lang;
+		this.quoteCount = tweet.legacy.quote_count;
+		this.replyCount = tweet.legacy.reply_count;
+		this.retweetCount = tweet.legacy.retweet_count;
+		this.likeCount = tweet.legacy.favorite_count;
+	}
+}

package/src/models/User.ts

@@ -0,0 +1,72 @@
+// TYPES
+import { IUser } from '../types/User';
+import { IUser as IRawUser } from 'rettiwt-core';
+
+/**
+ * The details of a single user.
+ *
+ * @public
+ */
+export class User implements IUser {
+	/** The rest id of the user. */
+	id: string;
+
+	/** The username/screenname of the user. */
+	userName: string;
+
+	/** The full name of the user. */
+	fullName: string;
+
+	/** The creation date of user's account. */
+	createdAt: string;
+
+	/** The user's description. */
+	description: string;
+
+	/** Whether the account is verified or not. */
+	isVerified: boolean;
+
+	/** The number of tweets liked by the user. */
+	favouritesCount: number;
+
+	/** The number of followers of the user. */
+	followersCount: number;
+
+	/** The number of following of the user. */
+	followingsCount: number;
+
+	/** The number of tweets made by the user. */
+	statusesCount: number;
+
+	/** The location of user as provided by user. */
+	location: string;
+
+	/** The rest id of the tweet pinned in the user's profile. */
+	pinnedTweet: string;
+
+	/** The url of the profile banner image. */
+	profileBanner: string;
+
+	/** The url of the profile image. */
+	profileImage: string;
+
+	/**
+	 * @param user - The raw user data.
+	 */
+	constructor(user: IRawUser) {
+		this.id = user.rest_id;
+		this.userName = user.legacy.screen_name;
+		this.fullName = user.legacy.name;
+		this.createdAt = user.legacy.created_at;
+		this.description = user.legacy.description;
+		this.isVerified = user.legacy.verified;
+		this.favouritesCount = user.legacy.favourites_count;
+		this.followersCount = user.legacy.followers_count;
+		this.followingsCount = user.legacy.friends_count;
+		this.statusesCount = user.legacy.statuses_count;
+		this.location = user.legacy.location;
+		this.pinnedTweet = user.legacy.pinned_tweet_ids_str[0];
+		this.profileBanner = user.legacy.profile_banner_url;
+		this.profileImage = user.legacy.profile_image_url_https;
+	}
+}

package/src/services/FetcherService.ts

@@ -0,0 +1,186 @@
+// PACKAGES
+import {
+	Request,
+	Args,
+	EResourceType,
+	ICursor as IRawCursor,
+	ITweet as IRawTweet,
+	IUser as IRawUser,
+	ITimelineTweet,
+	ITimelineUser,
+	IResponse,
+	EErrorCodes,
+} from 'rettiwt-core';
+import axios, { AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse } from 'axios';
+import { AuthCredential } from 'rettiwt-auth';
+
+// ENUMS
+import { EHttpStatus } from '../enums/HTTP';
+import { EApiErrors } from '../enums/ApiErrors';
+
+// MODELS
+import { CursoredData } from '../models/CursoredData';
+import { Tweet } from '../models/Tweet';
+import { User } from '../models/User';
+
+// HELPERS
+import { findByFilter, findKeyByValue } from '../helper/JsonUtils';
+
+/**
+ * The base service that handles all HTTP requests.
+ *
+ * @internal
+ */
+export class FetcherService {
+	/** The credential to use for authenticating against Twitter API. */
+	private cred: AuthCredential;
+
+	/**
+	 * @param cred - The credentials to use for authenticating against Twitter API.
+	 */
+	constructor(cred: AuthCredential) {
+		this.cred = cred;
+	}
+
+	/**
+	 * The middleware for handling any http error.
+	 *
+	 * @param res - The response object received.
+	 * @returns The received response, if no HTTP errors are found.
+	 */
+	private handleHttpError(res: AxiosResponse<IResponse<unknown>>): AxiosResponse<IResponse<unknown>> {
+		/**
+		 * If the status code is not 200 =\> the HTTP request was not successful. hence throwing error
+		 */
+		if (res.status != 200 && res.status in EHttpStatus) {
+			throw new Error(EHttpStatus[res.status]);
+		}
+
+		return res;
+	}
+
+	/**
+	 * The middleware for handling any Twitter API-level errors.
+	 *
+	 * @param res - The response object received.
+	 * @returns The received response, if no API errors are found.
+	 */
+	private handleApiError(res: AxiosResponse<IResponse<unknown>>): AxiosResponse<IResponse<unknown>> {
+		// If error exists
+		if (res.data.errors && res.data.errors.length) {
+			// Getting the error code
+			const code: number = res.data.errors[0].code;
+
+			// Getting the error message
+			const message: string = EApiErrors[
+				findKeyByValue(EErrorCodes, `${code}`) as keyof typeof EApiErrors
+			] as string;
+
+			// Throw the error
+			throw new Error(message);
+		}
+
+		return res;
+	}
+
+	/**
+	 * Makes an HTTP request according to the given parameters.
+	 *
+	 * @param config - The request configuration.
+	 * @returns The response received.
+	 */
+	private async request(config: Request): Promise<AxiosResponse<IResponse<unknown>>> {
+		/**
+		 * Creating axios request configuration from the input configuration.
+		 */
+		const axiosRequest: AxiosRequestConfig = {
+			url: config.url,
+			method: config.type,
+			data: config.payload,
+			headers: JSON.parse(JSON.stringify(this.cred.toHeader())) as AxiosRequestHeaders,
+		};
+
+		/**
+		 * After making the request, the response is then passed to HTTP error handling middlware for HTTP error handling.
+		 */
+		return await axios<IResponse<unknown>>(axiosRequest)
+			.then((res) => this.handleHttpError(res))
+			.then((res) => this.handleApiError(res));
+	}
+
+	/**
+	 * Extracts the required data based on the type of resource passed as argument.
+	 *
+	 * @param data - The data from which extraction is to be done.
+	 * @param type - The type of data to extract.
+	 * @typeParam BaseType - The base type of the raw data present in the input.
+	 * @typeParam DeserializedType - The type of data produced after deserialization of BaseType.
+	 * @returns The extracted data.
+	 */
+	private extractData<DeserializedType extends Tweet | User>(
+		data: NonNullable<unknown>,
+		type: EResourceType,
+	): CursoredData<DeserializedType> {
+		/**
+		 * The required extracted data.
+		 */
+		let required = [];
+
+		if (type == EResourceType.TWEET_DETAILS) {
+			required = findByFilter<IRawTweet>(data, '__typename', 'Tweet');
+		} else if (type == EResourceType.USER_DETAILS || type == EResourceType.USER_DETAILS_BY_ID) {
+			required = findByFilter<IRawUser>(data, '__typename', 'User');
+		} else if (type == EResourceType.TWEET_SEARCH || type == EResourceType.USER_LIKES) {
+			required = findByFilter<ITimelineTweet>(data, '__typename', 'TimelineTweet').map(
+				(item) => item.tweet_results.result,
+			);
+		} else {
+			required = findByFilter<ITimelineUser>(data, '__typename', 'TimelineUser').map(
+				(item) => item.user_results.result,
+			);
+		}
+
+		return new CursoredData(required, findByFilter<IRawCursor>(data, 'cursorType', 'Bottom')[0]?.value);
+	}
+
+	/**
+	 * Fetches the requested resource from Twitter and returns it after processing.
+	 *
+	 * @param resourceType - The type of resource to fetch.
+	 * @param args - Resource specific arguments.
+	 * @typeParam OutType - The type of deserialized data returned.
+	 * @returns The processed data requested from Twitter.
+	 */
+	protected async fetch<OutType extends Tweet | User>(
+		resourceType: EResourceType,
+		args: Args,
+	): Promise<CursoredData<OutType>> {
+		// Preparing the HTTP request
+		const request: Request = new Request(resourceType, args);
+
+		// Getting the raw data
+		const res = await this.request(request).then((res) => res.data);
+
+		// Extracting data
+		const data = this.extractData<OutType>(res, resourceType);
+
+		return data;
+	}
+
+	/**
+	 * Posts the requested resource to Twitter and returns the response.
+	 *
+	 * @param resourceType - The type of resource to post.
+	 * @param args - Resource specific arguments.
+	 * @returns Whether posting was successful or not.
+	 */
+	protected async post(resourceType: EResourceType, args: Args): Promise<boolean> {
+		// Preparing the HTTP request
+		const request: Request = new Request(resourceType, args);
+
+		// Posting the data
+		await this.request(request);
+
+		return true;
+	}
+}

package/src/services/TweetService.ts

@@ -0,0 +1,153 @@
+// PACKAGES
+import { EResourceType, TweetFilter } from 'rettiwt-core';
+import { AuthCredential } from 'rettiwt-auth';
+
+// SERVICES
+import { FetcherService } from './FetcherService';
+
+// MODELS
+import { Tweet } from '../models/Tweet';
+import { User } from '../models/User';
+import { CursoredData } from '../models/CursoredData';
+
+/**
+ * Handles fetching of data related to tweets.
+ *
+ * @public
+ */
+export class TweetService extends FetcherService {
+	/**
+	 * @param cred - The credentials to use for authenticating against Twitter API.
+	 *
+	 * @internal
+	 */
+	constructor(cred: AuthCredential) {
+		super(cred);
+	}
+
+	/**
+	 * Search for tweets using a query.
+	 *
+	 * @param query - The query be used for searching the tweets.
+	 * @param count - The number of tweets to fetch, must be \<= 20.
+	 * @param cursor - The cursor to the batch of tweets to fetch.
+	 * @returns The list of tweets that match the given filter.
+	 *
+	 * @public
+	 */
+	async search(query: TweetFilter, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		// Fetching the requested data
+		const data = await this.fetch<Tweet>(EResourceType.TWEET_SEARCH, {
+			filter: query,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Sorting the tweets by date, from recent to oldest
+		data.list.sort((a, b) => new Date(b.createdAt).valueOf() - new Date(a.createdAt).valueOf());
+
+		return data;
+	}
+
+	/**
+	 * Get the details of a tweet.
+	 *
+	 * @param id - The id of the target tweet.
+	 * @returns The details of a single tweet with the given tweet id.
+	 *
+	 * @public
+	 */
+	async details(id: string): Promise<Tweet> {
+		// Fetching the requested data
+		const data = await this.fetch<Tweet>(EResourceType.TWEET_DETAILS, { id: id });
+
+		return data.list[0];
+	}
+
+	/**
+	 * Get the list of users who liked a tweet.
+	 *
+	 * @param tweetId - The rest id of the target tweet.
+	 * @param count - The number of favoriters to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of favoriters to fetch.
+	 * @returns The list of users who liked the given tweet.
+	 *
+	 * @public
+	 */
+	async favoriters(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		// Fetching the requested data
+		const data = await this.fetch<User>(EResourceType.TWEET_FAVORITERS, {
+			id: tweetId,
+			count: count,
+			cursor: cursor,
+		});
+
+		return data;
+	}
+
+	/**
+	 * Get the list of users who retweeted a tweet.
+	 *
+	 * @param tweetId - The rest id of the target tweet.
+	 * @param count - The number of retweeters to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of retweeters to fetch.
+	 * @returns The list of users who retweeted the given tweet.
+	 *
+	 * @public
+	 */
+	async retweeters(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		// Fetching the requested data
+		const data = await this.fetch<User>(EResourceType.TWEET_RETWEETERS, {
+			id: tweetId,
+			count: count,
+			cursor: cursor,
+		});
+
+		return data;
+	}
+
+	/**
+	 * Post a tweet.
+	 *
+	 * @param tweetText - The text to be posted, length must be \<= 280 characters.
+	 * @returns Whether posting was successful or not.
+	 *
+	 * @public
+	 */
+	async tweet(tweetText: string): Promise<boolean> {
+		// Posting the tweet
+		const data = await this.post(EResourceType.CREATE_TWEET, { tweetText: tweetText });
+
+		return data;
+	}
+
+	/**
+	 * Favorite the tweet with the given id.
+	 *
+	 * @param tweetId - The id of the tweet to be favorited.
+	 * @returns Whether favoriting was successful or not.
+	 *
+	 * @public
+	 */
+	async favorite(tweetId: string): Promise<boolean> {
+		// Favoriting the tweet
+		const data = await this.post(EResourceType.FAVORITE_TWEET, { id: tweetId });
+
+		return data;
+	}
+
+	/**
+	 * Retweet the tweet with the given id.
+	 *
+	 * @param tweetId - The id of the tweet with the given id.
+	 * @returns Whether retweeting was successful or not.
+	 *
+	 * @public
+	 */
+	async retweet(tweetId: string): Promise<boolean> {
+		// Retweeting the tweet
+		const data = await this.post(EResourceType.CREATE_RETWEET, { id: tweetId });
+
+		return data;
+	}
+}

package/src/services/UserService.ts

@@ -0,0 +1,117 @@
+// PACKAGES
+import { EResourceType } from 'rettiwt-core';
+import { AuthCredential } from 'rettiwt-auth';
+
+// SERVICES
+import { FetcherService } from './FetcherService';
+
+// MODELS
+import { User } from '../models/User';
+import { Tweet } from '../models/Tweet';
+
+// TYPES
+import { CursoredData } from '../models/CursoredData';
+
+/**
+ * Handles fetching of data related to user account
+ *
+ * @public
+ */
+export class UserService extends FetcherService {
+	/**
+	 * @param cred - The credentials to use for authenticating against Twitter API.
+	 *
+	 * @internal
+	 */
+	constructor(cred: AuthCredential) {
+		super(cred);
+	}
+
+	/**
+	 * Get the details of a user.
+	 *
+	 * @param id - The username/id of the target user.
+	 * @returns The details of the given user.
+	 *
+	 * @public
+	 */
+	async details(id: string): Promise<User> {
+		let data: CursoredData<User>;
+
+		// If username is given
+		if (isNaN(parseFloat(id))) {
+			// Fetching the requested data
+			data = await this.fetch<User>(EResourceType.USER_DETAILS, { id: id });
+		}
+		// If id is given
+		else {
+			// Fetching the requested data
+			data = await this.fetch<User>(EResourceType.USER_DETAILS_BY_ID, { id: id });
+		}
+
+		return data.list[0];
+	}
+
+	/**
+	 * Get the list of users who are followed by the given user.
+	 *
+	 * @param userId - The rest id of the target user.
+	 * @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.
+	 *
+	 * @public
+	 */
+	async following(userId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		// Fetching the requested data
+		const data = await this.fetch<User>(EResourceType.USER_FOLLOWING, {
+			id: userId,
+			count: count,
+			cursor: cursor,
+		});
+
+		return data;
+	}
+
+	/**
+	 * Get the list followers of a given user.
+	 *
+	 * @param userId - The rest id of the target user.
+	 * @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.
+	 *
+	 * @public
+	 */
+	async followers(userId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		// Fetching the requested data
+		const data = await this.fetch<User>(EResourceType.USER_FOLLOWERS, {
+			id: userId,
+			count: count,
+			cursor: cursor,
+		});
+
+		return data;
+	}
+
+	/**
+	 * Get the list of tweets liked by the given user.
+	 *
+	 * @param userId - The rest id of the target user.
+	 * @param count - The number of likes to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of likes to fetch.
+	 * @returns The list of tweets liked by the target user.
+	 *
+	 * @public
+	 */
+	async likes(userId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		// Fetching the requested data
+		const data = await this.fetch<Tweet>(EResourceType.USER_LIKES, {
+			id: userId,
+			count: count,
+			cursor: cursor,
+		});
+
+		return data;
+	}
+}

package/src/types/CursoredData.ts

@@ -0,0 +1,24 @@
+/**
+ * The cursor to the batch of data to be fetched.
+ *
+ * @public
+ */
+export interface ICursor {
+	/** The cursor string. */
+	value: string;
+}
+
+/**
+ * The data that us fetched batch-wise along with a cursor.
+ *
+ * @typeParam T - Type of data present in the list.
+ *
+ * @public
+ */
+export interface ICursoredData<T> {
+	/** The list of data of the given type. */
+	list: T[];
+
+	/** The cursor to the next batch of data. */
+	next: ICursor;
+}