@youmind-openlab/rettiwt-api 1.0.0

package/src/models/data/Tweet.ts

@@ -0,0 +1,388 @@
+import { LogActions } from '../../enums/Logging';
+import { MediaType } from '../../enums/Media';
+import { RawMediaType } from '../../enums/raw/Media';
+import { findByFilter } from '../../helper/JsonUtils';
+
+import { LogService } from '../../services/internal/LogService';
+
+import { ITweet, ITweetEntities, ITweetMedia } from '../../types/data/Tweet';
+import { ILimitedVisibilityTweet } from '../../types/raw/base/LimitedVisibilityTweet';
+import { IExtendedMedia as IRawExtendedMedia } from '../../types/raw/base/Media';
+import { ITweet as IRawTweet, IEntities as IRawTweetEntities } from '../../types/raw/base/Tweet';
+import { ITimelineTweet } from '../../types/raw/composite/TimelineTweet';
+
+import { User } from './User';
+
+/**
+ * The details of a single tweet.
+ *
+ * @public
+ */
+export class Tweet implements ITweet {
+	/** The raw tweet details. */
+	private readonly _raw: IRawTweet;
+
+	public bookmarkCount?: number;
+	public conversationId: string;
+	public createdAt: string;
+	public entities: TweetEntities;
+	public fullText: string;
+	public id: string;
+	public lang: string;
+	public likeCount?: number;
+	public media?: TweetMedia[];
+	public quoteCount?: number;
+	public quoted?: Tweet;
+	public replyCount?: number;
+	public replyTo?: string;
+	public retweetCount?: number;
+	public retweetedTweet?: Tweet;
+	public tweetBy: User;
+	public url: string;
+	public viewCount?: number;
+
+	/**
+	 * @param tweet - The raw tweet details.
+	 */
+	public constructor(tweet: IRawTweet) {
+		this._raw = { ...tweet };
+		this.id = tweet.rest_id;
+		this.conversationId = tweet.legacy.conversation_id_str;
+		this.createdAt = new Date(tweet.legacy.created_at).toISOString();
+		this.tweetBy = new User(tweet.core.user_results.result);
+		this.entities = new TweetEntities(tweet.legacy.entities);
+		this.media = tweet.legacy.extended_entities?.media?.map((media) => new TweetMedia(media));
+		this.quoted = this._getQuotedTweet(tweet);
+		this.fullText = tweet.note_tweet?.note_tweet_results?.result?.text
+			? tweet.note_tweet.note_tweet_results.result.text
+			: 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;
+		this.viewCount = tweet.views?.count ? parseInt(tweet.views.count) : undefined;
+		this.bookmarkCount = tweet.legacy.bookmark_count;
+		this.retweetedTweet = this._getRetweetedTweet(tweet);
+		this.url = `https://x.com/${this.tweetBy.userName}/status/${this.id}`;
+	}
+
+	/** The raw tweet details. */
+	public get raw(): IRawTweet {
+		return { ...this._raw };
+	}
+
+	/**
+	 * Extract and deserialize the original quoted tweet from the given raw tweet.
+	 *
+	 * @param tweet - The raw tweet.
+	 *
+	 * @returns - The deserialized original quoted tweet.
+	 */
+	private _getQuotedTweet(tweet: IRawTweet): Tweet | undefined {
+		// If tweet with limited visibility
+		if (
+			tweet.quoted_status_result &&
+			tweet.quoted_status_result?.result?.__typename == 'TweetWithVisibilityResults' &&
+			(tweet.quoted_status_result.result as ILimitedVisibilityTweet)?.tweet?.legacy
+		) {
+			return new Tweet((tweet.quoted_status_result.result as ILimitedVisibilityTweet).tweet);
+		}
+		// If normal tweet
+		else if ((tweet.quoted_status_result?.result as IRawTweet)?.rest_id) {
+			return new Tweet(tweet.quoted_status_result.result as IRawTweet);
+		}
+		// Else, skip
+		else {
+			return undefined;
+		}
+	}
+
+	/**
+	 * Extract and deserialize the original retweeted tweet from the given raw tweet.
+	 *
+	 * @param tweet - The raw tweet.
+	 *
+	 * @returns - The deserialized original retweeted tweet.
+	 */
+	private _getRetweetedTweet(tweet: IRawTweet): Tweet | undefined {
+		// If retweet with limited visibility
+		if (
+			tweet.legacy?.retweeted_status_result &&
+			tweet.legacy?.retweeted_status_result?.result?.__typename == 'TweetWithVisibilityResults' &&
+			(tweet.legacy?.retweeted_status_result?.result as ILimitedVisibilityTweet)?.tweet?.legacy
+		) {
+			return new Tweet((tweet.legacy.retweeted_status_result.result as ILimitedVisibilityTweet).tweet);
+		}
+		// If normal tweet
+		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 {
+			return undefined;
+		}
+	}
+
+	/**
+	 * Extracts and deserializes multiple target tweets from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @param ids - The ids of the target tweets.
+	 *
+	 * @returns The target deserialized tweets.
+	 */
+	public static multiple(response: NonNullable<unknown>, ids: string[]): Tweet[] {
+		let tweets: Tweet[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<IRawTweet>(response, '__typename', 'Tweet');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.legacy) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.rest_id });
+
+				tweets.push(new Tweet(item));
+			} else {
+				// Logging
+				LogService.log(LogActions.WARNING, {
+					action: LogActions.DESERIALIZE,
+					message: `Tweet not found, skipping`,
+				});
+			}
+		}
+
+		// Filtering only required tweets, if required
+		if (ids && ids.length) {
+			tweets = tweets.filter((tweet) => ids.includes(tweet.id));
+		}
+
+		return tweets;
+	}
+
+	/**
+	 * Extracts and deserializes a single target tweet from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @param id - The id of the target tweet.
+	 *
+	 * @returns The target deserialized tweet.
+	 */
+	public static single(response: NonNullable<unknown>, id: string): Tweet | undefined {
+		const tweets: Tweet[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<IRawTweet>(response, 'rest_id', id);
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.legacy) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.rest_id });
+
+				tweets.push(new Tweet(item));
+			} else {
+				// Logging
+				LogService.log(LogActions.WARNING, {
+					action: LogActions.DESERIALIZE,
+					message: `Tweet not found, skipping`,
+				});
+			}
+		}
+
+		return tweets.length ? tweets[0] : undefined;
+	}
+
+	/**
+	 * Extracts and deserializes the timeline of tweets from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @param ids - The IDs of specific tweets that need to be extracted.
+	 *
+	 * @returns The deserialized timeline of tweets.
+	 */
+	public static timeline(response: NonNullable<unknown>): Tweet[] {
+		const tweets: Tweet[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<ITimelineTweet>(response, '__typename', 'TimelineTweet');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			// If tweet with limited visibility
+			if (
+				item.tweet_results?.result &&
+				item.tweet_results?.result?.__typename == 'TweetWithVisibilityResults' &&
+				(item.tweet_results?.result as ILimitedVisibilityTweet)?.tweet?.legacy
+			) {
+				tweets.push(new Tweet((item.tweet_results.result as ILimitedVisibilityTweet).tweet));
+			}
+			// If normal tweet
+			else if ((item.tweet_results?.result as IRawTweet)?.legacy) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: (item.tweet_results.result as IRawTweet).rest_id });
+
+				tweets.push(new Tweet(item.tweet_results.result as IRawTweet));
+			}
+			// If invalid/unrecognized tweet
+			else {
+				// Logging
+				LogService.log(LogActions.WARNING, {
+					action: LogActions.DESERIALIZE,
+					message: `Tweet not found, skipping`,
+				});
+			}
+		}
+
+		return tweets;
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): ITweet {
+		return {
+			bookmarkCount: this.bookmarkCount,
+			conversationId: this.conversationId,
+			createdAt: this.createdAt,
+			entities: this.entities.toJSON(),
+			fullText: this.fullText,
+			id: this.id,
+			lang: this.lang,
+			likeCount: this.likeCount,
+			media: this.media?.map((item) => item.toJSON()),
+			quoteCount: this.quoteCount,
+			quoted: this.quoted?.toJSON(),
+			replyCount: this.replyCount,
+			replyTo: this.replyTo,
+			retweetCount: this.retweetCount,
+			retweetedTweet: this.retweetedTweet?.toJSON(),
+			tweetBy: this.tweetBy.toJSON(),
+			url: this.url,
+			viewCount: this.viewCount,
+		};
+	}
+}
+
+/**
+ * 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. */
+	public hashtags: string[] = [];
+
+	/** The list of IDs of users mentioned in the tweet. */
+	public mentionedUsers: string[] = [];
+
+	/** The list of urls mentioned in the tweet. */
+	public urls: string[] = [];
+
+	/**
+	 * @param entities - The raw tweet entities.
+	 */
+	public 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);
+			}
+		}
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): ITweetEntities {
+		return {
+			hashtags: this.hashtags,
+			mentionedUsers: this.mentionedUsers,
+			urls: this.urls,
+		};
+	}
+}
+
+/**
+ * The details of a single media content included in a tweet.
+ *
+ * @public
+ */
+export class TweetMedia implements ITweetMedia {
+	/** The ID of the media. */
+	public id: string;
+
+	/** The thumbnail URL for the video content of the tweet. */
+	public thumbnailUrl?: string;
+
+	/** The type of media. */
+	public type: MediaType;
+
+	/** The direct URL to the media. */
+	public url = '';
+
+	/**
+	 * @param media - The raw media details.
+	 */
+	public constructor(media: IRawExtendedMedia) {
+		this.id = media.id_str;
+
+		// If the media is a photo
+		if (media.type == RawMediaType.PHOTO) {
+			this.type = MediaType.PHOTO;
+			this.url = media.media_url_https;
+		}
+		// If the media is a gif
+		else if (media.type == RawMediaType.GIF) {
+			this.type = MediaType.GIF;
+			this.url = media.video_info?.variants[0].url as string;
+		}
+		// If the media is a video
+		else {
+			this.type = MediaType.VIDEO;
+			this.thumbnailUrl = media.media_url_https;
+
+			/** The highest bitrate of all variants. */
+			let highestRate = 0;
+
+			/**
+			 * Selecting the URL of the video variant with the highest bitrate.
+			 */
+			media.video_info?.variants.forEach((variant) => {
+				if (variant.bitrate > highestRate) {
+					highestRate = variant.bitrate;
+					this.url = variant.url;
+				}
+			});
+		}
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): ITweetMedia {
+		return {
+			id: this.id,
+			thumbnailUrl: this.thumbnailUrl,
+			type: this.type,
+			url: this.url,
+		};
+	}
+}

package/src/models/data/User.ts

@@ -0,0 +1,187 @@
+import { LogActions } from '../../enums/Logging';
+import { findByFilter } from '../../helper/JsonUtils';
+import { LogService } from '../../services/internal/LogService';
+import { IUser } from '../../types/data/User';
+import { IUser as IRawUser } from '../../types/raw/base/User';
+import { ITimelineUser as IRawTimelineUser } from '../../types/raw/composite/TimelineUser';
+
+/**
+ * The details of a single user.
+ *
+ * @public
+ */
+export class User implements IUser {
+	/** The raw user details. */
+	private readonly _raw: IRawUser;
+
+	public createdAt: string;
+	public description?: string;
+	public followersCount: number;
+	public followingsCount: number;
+	public fullName: string;
+	public id: string;
+	public isFollowed?: boolean;
+	public isFollowing?: boolean;
+	public isVerified: boolean;
+	public likeCount: number;
+	public location?: string;
+	public pinnedTweet?: string;
+	public profileBanner?: string;
+	public profileImage: string;
+	public statusesCount: number;
+	public userName: string;
+
+	/**
+	 * @param user - The raw user details.
+	 */
+	public constructor(user: IRawUser) {
+		this._raw = { ...user };
+		this.id = user.rest_id;
+		this.userName = user.core?.screen_name ?? user.legacy.screen_name ?? '';
+		this.fullName = user.core?.name ?? user.legacy.name ?? '';
+		this.createdAt = new Date(user.core?.created_at ?? user.legacy.created_at ?? 0).toISOString();
+		this.description = user.legacy.description.length ? user.legacy.description : undefined;
+		this.isFollowed = user.legacy.following;
+		this.isFollowing = user.legacy.followed_by;
+		this.isVerified = user.is_blue_verified;
+		this.likeCount = 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.location?.location ?? user.legacy.location ?? undefined;
+		this.pinnedTweet = user.legacy.pinned_tweet_ids_str[0];
+		this.profileBanner = user.legacy.profile_banner_url;
+		this.profileImage = user.avatar?.image_url ?? user.legacy.profile_image_url_https ?? '';
+	}
+
+	/** The raw user details. */
+	public get raw(): IRawUser {
+		return { ...this._raw };
+	}
+
+	/**
+	 * Extracts and deserializes multiple target users from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @param ids - The ids of the target users.
+	 *
+	 * @returns The target deserialized users.
+	 */
+	public static multiple(response: NonNullable<unknown>, ids: string[]): User[] {
+		let users: User[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<IRawUser>(response, '__typename', 'User');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.legacy && (item.core?.created_at || item.legacy.created_at)) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.rest_id });
+
+				users.push(new User(item));
+			} else {
+				// Logging
+				LogService.log(LogActions.WARNING, {
+					action: LogActions.DESERIALIZE,
+					message: `User not found, skipping`,
+				});
+			}
+		}
+
+		// Filtering only required user, if required
+		if (ids && ids.length) {
+			users = users.filter((user) => ids.includes(user.id));
+		}
+
+		return users;
+	}
+
+	/**
+	 * Extracts and deserializes a single target user from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The target deserialized user.
+	 */
+	public static single(response: NonNullable<unknown>): User | undefined {
+		const users: User[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<IRawUser>(response, '__typename', 'User');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.legacy && (item.core?.created_at || item.legacy.created_at)) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.rest_id });
+
+				users.push(new User(item));
+			} else {
+				// Logging
+				LogService.log(LogActions.WARNING, {
+					action: LogActions.DESERIALIZE,
+					message: `User not found, skipping`,
+				});
+			}
+		}
+
+		return users.length ? users[0] : undefined;
+	}
+
+	/**
+	 * Extracts and deserializes the timeline of users from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized timeline of users.
+	 */
+	public static timeline(response: NonNullable<unknown>): User[] {
+		const users: User[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<IRawTimelineUser>(response, '__typename', 'TimelineUser');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.user_results?.result?.legacy) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.user_results.result.rest_id });
+
+				users.push(new User(item.user_results.result));
+			} else {
+				// Logging
+				LogService.log(LogActions.WARNING, {
+					action: LogActions.DESERIALIZE,
+					message: `User not found, skipping`,
+				});
+			}
+		}
+
+		return users;
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): IUser {
+		return {
+			createdAt: this.createdAt,
+			description: this.description,
+			followersCount: this.followersCount,
+			followingsCount: this.followingsCount,
+			fullName: this.fullName,
+			id: this.id,
+			isFollowed: this.isFollowed,
+			isFollowing: this.isFollowing,
+			isVerified: this.isVerified,
+			likeCount: this.likeCount,
+			location: this.location,
+			pinnedTweet: this.pinnedTweet,
+			profileBanner: this.profileBanner,
+			profileImage: this.profileImage,
+			statusesCount: this.statusesCount,
+			userName: this.userName,
+		};
+	}
+}

package/src/models/errors/TwitterError.ts

@@ -0,0 +1,65 @@
+import { AxiosError } from 'axios';
+
+import { ITwitterError, ITwitterErrorDetails } from '../../types/errors/TwitterError';
+import { IErrorData as IRawErrorData, IErrorDetails as IRawErrorDetails } from '../../types/raw/base/Error';
+
+/**
+ * The error thrown by Twitter API.
+ *
+ * @public
+ */
+export class TwitterError extends Error implements ITwitterError {
+	public details: ITwitterErrorDetails[];
+	public message: string;
+	public name: string;
+	public status: number;
+
+	/**
+	 * @param error - The error response received from Twitter.
+	 */
+	public constructor(error: AxiosError<IRawErrorData | IRawErrorDetails>) {
+		super(error.message);
+		this.details = (
+			(error.response?.data as IRawErrorData).errors
+				? (error.response?.data as IRawErrorData).errors.map((item) => new TwitterErrorDetails(item))
+				: [new TwitterErrorDetails(error.response?.data as IRawErrorDetails)]
+		).map((item) => item.toJSON());
+		this.message = error.message;
+		this.name = 'TWITTER_ERROR';
+		this.status = error.status ?? 500;
+	}
+}
+
+/**
+ * The error details.
+ *
+ * @public
+ */
+export class TwitterErrorDetails implements ITwitterErrorDetails {
+	public code: number;
+	public message: string;
+	public name?: string;
+	public type?: string;
+
+	/**
+	 * @param details - The details of the error.
+	 */
+	public constructor(details: IRawErrorDetails) {
+		this.code = details.code;
+		this.message = details.message;
+		this.name = details.name;
+		this.type = details.kind;
+	}
+
+	/**
+	 * @returns The JSON representation of `this` object.
+	 */
+	public toJSON(): ITwitterErrorDetails {
+		return {
+			code: this.code,
+			message: this.message,
+			name: this.message,
+			type: this.type,
+		};
+	}
+}

package/src/models/params/Variables.ts

@@ -0,0 +1,62 @@
+import { IMediaEntityVariable, IMediaVariable, IReplyVariable } from '../../types/params/Variables';
+import { NewTweetMedia } from '../args/PostArgs';
+
+/**
+ * Media to be sent as payload.
+ *
+ * @internal
+ */
+export class MediaVariable implements IMediaVariable {
+	/* eslint-disable @typescript-eslint/naming-convention */
+	public media_entities: MediaEntityVariable[];
+	public possibly_sensitive: boolean;
+	/* eslint-enable @typescript-eslint/naming-convention */
+
+	/**
+	 * @param media - The list of NewTweetMedia objects specifying the media items to be sent in the Tweet.
+	 */
+	public constructor(media: NewTweetMedia[]) {
+		this.media_entities = media.map((item) => new MediaEntityVariable(item));
+		this.possibly_sensitive = false;
+	}
+}
+
+/**
+ * Each media item in the media payload.
+ *
+ * @internal
+ */
+export class MediaEntityVariable implements IMediaEntityVariable {
+	/* eslint-disable @typescript-eslint/naming-convention */
+	public media_id: string;
+	public tagged_users: string[];
+	/* eslint-enable @typescript-eslint/naming-convention */
+
+	/**
+	 * @param media - The NewTweetMedia object specifying the details of the media item to be included in the payload.
+	 */
+	public constructor(media: NewTweetMedia) {
+		this.media_id = media.id;
+		this.tagged_users = media.tags ?? [];
+	}
+}
+
+/**
+ * Reply specific details to be sent in payload.
+ *
+ * @internal
+ */
+export class ReplyVariable implements IReplyVariable {
+	/* eslint-disable @typescript-eslint/naming-convention */
+	public exclude_reply_user_ids: string[];
+	public in_reply_to_tweet_id: string;
+	/* eslint-enable @typescript-eslint/naming-convention */
+
+	/**
+	 * @param replyTo - The id of the Tweet to which this Tweet is a reply.
+	 */
+	public constructor(replyTo: string) {
+		this.in_reply_to_tweet_id = replyTo;
+		this.exclude_reply_user_ids = [];
+	}
+}