rettiwt-api 2.0.3 → 2.2.0

package/src/models/List.ts

@@ -0,0 +1,48 @@
+// PACKAGES
+import { IList as IRawList } from 'rettiwt-core';
+
+// TYPES
+import { IList } from '../types/List';
+
+/**
+ * The details of a single Twitter List.
+ *
+ * @public
+ */
+export class List implements IList {
+	/** The rest id of the list. */
+	id: string;
+
+	/** The name of the list. */
+	name: string;
+
+	/** The date and time of creation of the list, int UTC string format. */
+	createdAt: string;
+
+	/** The list description. */
+	description: string;
+
+	/** The number of memeber of the list. */
+	memberCount: number;
+
+	/** The number of subscribers of the list. */
+	subscriberCount: number;
+
+	/** The rest id of the user who created the list. */
+	createdBy: string;
+
+	/**
+	 * Initializes a new Tweet List from the given raw list data.
+	 *
+	 * @param list - list The raw tweet list data.
+	 */
+	constructor(list: IRawList) {
+		this.id = list.id_str;
+		this.name = list.name;
+		this.createdAt = new Date(list.created_at).toISOString();
+		this.description = list.description;
+		this.memberCount = list.member_count;
+		this.subscriberCount = list.subscriber_count;
+		this.createdBy = list.user_results.result.id;
+	}
+}

package/src/models/Tweet.ts

@@ -1,59 +1,20 @@
+// PACKAGES
+import {
+	ITweet as IRawTweet,
+	IEntities as IRawTweetEntities,
+	IExtendedMedia as IRawExtendedMedia,
+	EMediaType,
+} from 'rettiwt-core';
+
 // TYPES
 import { ITweet, ITweetEntities } from '../types/Tweet';
-import { ITweet as IRawTweet, IEntities as IRawTweetEntities } from 'rettiwt-core';
+
+// MODELS
+import { User } from './User';
 
 // 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.
  *
@@ -63,8 +24,8 @@ 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 details of the user who made the tweet. */
+	tweetBy: User;
 
 	/** The date and time of creation of the tweet, in UTC string format. */
 	createdAt: string;
@@ -72,6 +33,9 @@ export class Tweet implements ITweet {
 	/** Additional tweet entities like urls, mentions, etc. */
 	entities: TweetEntities;
 
+	/** The urls of the media contents of the tweet (if any). */
+	media: TweetMedia[];
+
 	/** The rest id of the tweet which is quoted in the tweet. */
 	quoted: string;
 
@@ -96,14 +60,23 @@ export class Tweet implements ITweet {
 	/** The number of likes of the tweet. */
 	likeCount: number;
 
+	/** The number of views of a tweet. */
+	viewCount: number;
+
+	/** The number of bookmarks of a tweet. */
+	bookmarkCount: number;
+
 	/**
+	 * Initializes a new Tweet from the given raw tweet data.
+	 *
 	 * @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.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 = tweet.legacy.quoted_status_id_str;
 		this.fullText = normalizeText(tweet.legacy.full_text);
 		this.replyTo = tweet.legacy.in_reply_to_status_id_str;
@@ -112,5 +85,97 @@ export class Tweet implements ITweet {
 		this.replyCount = tweet.legacy.reply_count;
 		this.retweetCount = tweet.legacy.retweet_count;
 		this.likeCount = tweet.legacy.favorite_count;
+		this.viewCount = parseInt(tweet.views.count);
+		this.bookmarkCount = tweet.legacy.bookmark_count;
+	}
+}
+
+/**
+ * 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[] = [];
+
+	/**
+	 * Initializes the TweetEntities from the raw tweet entities.
+	 *
+	 * @param entities - The raw tweet entities.
+	 */
+	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);
+			}
+		}
+	}
+}
+
+/**
+ * A single media content.
+ *
+ * @public
+ */
+export class TweetMedia {
+	/** The type of media. */
+	type: EMediaType;
+
+	/** The direct URL to the media. */
+	url: string = '';
+
+	/**
+	 * Initializes the TweetMedia from the raw tweet media.
+	 *
+	 * @param media - The raw tweet media.
+	 */
+	constructor(media: IRawExtendedMedia) {
+		this.type = media.type;
+
+		// If the media is a photo
+		if (media.type == EMediaType.PHOTO) {
+			this.url = media.media_url_https;
+		}
+		// If the media is a gif
+		else if (media.type == EMediaType.GIF) {
+			this.url = media.video_info?.variants[0].url as string;
+		}
+		// If the media is a video
+		else {
+			/** The highest bitrate of all variants. */
+			let highestRate: number = 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;
+				}
+			});
+		}
 	}
 }

package/src/models/User.ts

@@ -1,6 +1,8 @@
+// PACKAGES
+import { IUser as IRawUser } from 'rettiwt-core';
+
 // TYPES
 import { IUser } from '../types/User';
-import { IUser as IRawUser } from 'rettiwt-core';
 
 /**
  * The details of a single user.
@@ -51,6 +53,8 @@ export class User implements IUser {
 	profileImage: string;
 
 	/**
+	 * Initializes a new User from the given raw user data.
+	 *
 	 * @param user - The raw user data.
 	 */
 	constructor(user: IRawUser) {

package/src/services/FetcherService.ts

@@ -12,7 +12,9 @@ import {
 	EErrorCodes,
 } from 'rettiwt-core';
 import axios, { AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse } from 'axios';
+import https, { Agent } from 'https';
 import { AuthCredential } from 'rettiwt-auth';
+import { HttpsProxyAgent } from 'https-proxy-agent';
 
 // ENUMS
 import { EHttpStatus } from '../enums/HTTP';
@@ -35,11 +37,40 @@ export class FetcherService {
 	/** The credential to use for authenticating against Twitter API. */
 	private cred: AuthCredential;
 
+	/** The HTTPS Agent to use for requests to Twitter API. */
+	private readonly httpsAgent: Agent;
+
 	/**
-	 * @param cred - The credentials to use for authenticating against Twitter API.
+	 * @param apiKey - The apiKey (cookie) to use for authenticating Rettiwt against Twitter API.
+	 * @param proxyUrl - Optional URL with proxy configuration to use for requests to Twitter API.
 	 */
-	constructor(cred: AuthCredential) {
-		this.cred = cred;
+	constructor(apiKey: string, proxyUrl?: URL) {
+		this.cred = this.getAuthCredential(apiKey);
+		this.httpsAgent = this.getHttpsAgent(proxyUrl);
+	}
+
+	/**
+	 * Returns an AuthCredential generated using the given API key.
+	 *
+	 * @param apiKey - The API key to use for authenticating.
+	 * @returns The generated AuthCredential.
+	 */
+	private getAuthCredential(apiKey: string): AuthCredential {
+		return new AuthCredential(apiKey.split(';'));
+	}
+
+	/**
+	 * Gets the HttpsAgent based on whether a proxy is used or not.
+	 *
+	 * @param proxyUrl - Optional URL with proxy configuration to use for requests to Twitter API.
+	 * @returns The HttpsAgent to use.
+	 */
+	private getHttpsAgent(proxyUrl?: URL): Agent {
+		if (proxyUrl) {
+			return new HttpsProxyAgent(proxyUrl);
+		}
+
+		return new https.Agent();
 	}
 
 	/**
@@ -98,10 +129,11 @@ export class FetcherService {
 			method: config.type,
 			data: config.payload,
 			headers: JSON.parse(JSON.stringify(this.cred.toHeader())) as AxiosRequestHeaders,
+			httpsAgent: this.httpsAgent,
 		};
 
 		/**
-		 * After making the request, the response is then passed to HTTP error handling middlware for HTTP error handling.
+		 * After making the request, the response is then passed to HTTP error handling middleware for HTTP error handling.
 		 */
 		return await axios<IResponse<unknown>>(axiosRequest)
 			.then((res) => this.handleHttpError(res))
@@ -124,17 +156,27 @@ export class FetcherService {
 		/**
 		 * The required extracted data.
 		 */
-		let required = [];
+		let required: IRawTweet[] | IRawUser[] = [];
 
 		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) {
+		} else if (
+			type == EResourceType.TWEET_SEARCH ||
+			type == EResourceType.USER_LIKES ||
+			type == EResourceType.LIST_TWEETS ||
+			type == EResourceType.USER_TWEETS
+		) {
 			required = findByFilter<ITimelineTweet>(data, '__typename', 'TimelineTweet').map(
 				(item) => item.tweet_results.result,
 			);
-		} else {
+		} else if (
+			type == EResourceType.TWEET_FAVORITERS ||
+			type == EResourceType.TWEET_RETWEETERS ||
+			type == EResourceType.USER_FOLLOWERS ||
+			type == EResourceType.USER_FOLLOWING
+		) {
 			required = findByFilter<ITimelineUser>(data, '__typename', 'TimelineUser').map(
 				(item) => item.user_results.result,
 			);

package/src/services/TweetService.ts

@@ -1,6 +1,5 @@
 // PACKAGES
 import { EResourceType, TweetFilter } from 'rettiwt-core';
-import { AuthCredential } from 'rettiwt-auth';
 
 // SERVICES
 import { FetcherService } from './FetcherService';
@@ -17,12 +16,28 @@ import { CursoredData } from '../models/CursoredData';
  */
 export class TweetService extends FetcherService {
 	/**
-	 * @param cred - The credentials to use for authenticating against Twitter API.
+	 * @param apiKey - The apiKey (cookie) to use for authenticating Rettiwt against Twitter API.
+	 * @param proxyUrl - Optional URL with proxy configuration to use for requests to Twitter API.
 	 *
 	 * @internal
 	 */
-	constructor(cred: AuthCredential) {
-		super(cred);
+	constructor(apiKey: string, proxyUrl?: URL) {
+		super(apiKey, proxyUrl);
+	}
+
+	/**
+	 * 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];
 	}
 
 	/**
@@ -50,18 +65,27 @@ export class TweetService extends FetcherService {
 	}
 
 	/**
-	 * Get the details of a tweet.
+	 * Get the tweets from the tweet list with the given id.
 	 *
-	 * @param id - The id of the target tweet.
-	 * @returns The details of a single tweet with the given tweet id.
+	 * @param listId - The id of list from where the tweets are to be fetched.
+	 * @param count - The number of tweets to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of tweets to fetch.
+	 * @returns The list tweets present in the given list.
 	 *
-	 * @public
+	 * @remarks Due a bug in Twitter API, the count is ignored when no cursor is provided and defaults to 100.
 	 */
-	async details(id: string): Promise<Tweet> {
+	async list(listId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
 		// Fetching the requested data
-		const data = await this.fetch<Tweet>(EResourceType.TWEET_DETAILS, { id: id });
+		const data = await this.fetch<Tweet>(EResourceType.LIST_TWEETS, {
+			id: listId,
+			count: count,
+			cursor: cursor,
+		});
 
-		return data.list[0];
+		// 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;
 	}
 
 	/**

package/src/services/UserService.ts

@@ -1,6 +1,5 @@
 // PACKAGES
 import { EResourceType } from 'rettiwt-core';
-import { AuthCredential } from 'rettiwt-auth';
 
 // SERVICES
 import { FetcherService } from './FetcherService';
@@ -19,12 +18,13 @@ import { CursoredData } from '../models/CursoredData';
  */
 export class UserService extends FetcherService {
 	/**
-	 * @param cred - The credentials to use for authenticating against Twitter API.
+	 * @param apiKey - The apiKey (cookie) to use for authenticating Rettiwt against Twitter API.
+	 * @param proxyUrl - Optional URL with proxy configuration to use for requests to Twitter API.
 	 *
 	 * @internal
 	 */
-	constructor(cred: AuthCredential) {
-		super(cred);
+	constructor(apiKey: string, proxyUrl?: URL) {
+		super(apiKey, proxyUrl);
 	}
 
 	/**
@@ -114,4 +114,27 @@ export class UserService extends FetcherService {
 
 		return data;
 	}
+
+	/**
+	 * Get the timeline of the given user.
+	 *
+	 * @param userId - The rest id of the target user.
+	 * @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.
+	 *
+	 * @remarks If the target user has a pinned tweet, the returned timeline has one item extra and this is always the pinned tweet.
+	 *
+	 * @public
+	 */
+	async timeline(userId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		// Fetching the requested data
+		const data = await this.fetch<Tweet>(EResourceType.USER_TWEETS, {
+			id: userId,
+			count: count,
+			cursor: cursor,
+		});
+
+		return data;
+	}
 }

package/src/types/CursoredData.ts

@@ -1,13 +1,3 @@
-/**
- * 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.
  *
@@ -22,3 +12,13 @@ export interface ICursoredData<T> {
 	/** The cursor to the next batch of data. */
 	next: ICursor;
 }
+
+/**
+ * The cursor to the batch of data to be fetched.
+ *
+ * @public
+ */
+export interface ICursor {
+	/** The cursor string. */
+	value: string;
+}

package/src/types/List.ts

@@ -0,0 +1,27 @@
+/**
+ * The details of a single Twitter List.
+ *
+ * @public
+ */
+export interface IList {
+	/** The rest id of the list. */
+	id: string;
+
+	/** The name of the list. */
+	name: string;
+
+	/** The date and time of creation of the list, int UTC string format. */
+	createdAt: string;
+
+	/** The list description. */
+	description: string;
+
+	/** The number of memeber of the list. */
+	memberCount: number;
+
+	/** The number of subscribers of the list. */
+	subscriberCount: number;
+
+	/** The rest id of the user who created the list. */
+	createdBy: string;
+}

package/src/types/Tweet.ts

@@ -1,21 +1,8 @@
-/**
- * The different types parsed entities like urls, media, mentions, hashtags, etc.
- *
- * @public
- */
-export interface ITweetEntities {
-	/** The list of hashtags mentioned in the tweet. */
-	hashtags: string[];
+// PACKAGES
+import { EMediaType } from 'rettiwt-core';
 
-	/** 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[];
-}
+// TYPES
+import { IUser } from './User';
 
 /**
  * The details of a single Tweet.
@@ -26,8 +13,8 @@ export interface ITweet {
 	/** The rest id of the tweet. */
 	id: string;
 
-	/** The rest id of the user who made the tweet. */
-	tweetBy: string;
+	/** The details of the user who made the tweet. */
+	tweetBy: IUser;
 
 	/** The date and time of creation of the tweet, in UTC string format. */
 	createdAt: string;
@@ -35,6 +22,9 @@ export interface ITweet {
 	/** Additional tweet entities like urls, mentions, etc. */
 	entities: ITweetEntities;
 
+	/** The urls of the media contents of the tweet (if any). */
+	media: ITweetMedia[];
+
 	/** The rest id of the tweet which is quoted in the tweet. */
 	quoted: string;
 
@@ -58,4 +48,39 @@ export interface ITweet {
 
 	/** The number of likes of the tweet. */
 	likeCount: number;
+
+	/** The number of views of a tweet. */
+	viewCount: number;
+
+	/** The number of bookmarks of a tweet. */
+	bookmarkCount: number;
+}
+
+/**
+ * The different types parsed entities like urls, media, mentions, hashtags, etc.
+ *
+ * @public
+ */
+export interface 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[];
+}
+
+/**
+ * A single media content.
+ *
+ * @public
+ */
+export interface ITweetMedia {
+	/** The type of media. */
+	type: EMediaType;
+
+	/** The direct URL to the media. */
+	url: string;
 }

package/.dockerignore

@@ -1,2 +0,0 @@
-node_modules
-dist