@youmind-openlab/rettiwt-api 1.0.0

package/src/commands/User.ts

@@ -0,0 +1,367 @@
+import { Command, createCommand } from 'commander';
+
+import { RawAnalyticsGranularity, RawAnalyticsMetric } from '../enums/raw/Analytics';
+import { output } from '../helper/CliUtils';
+import { Rettiwt } from '../Rettiwt';
+
+/**
+ * Creates a new 'user' command which uses the given Rettiwt instance.
+ *
+ * @param rettiwt - The Rettiwt instance to use.
+ * @returns The created 'user' command.
+ */
+function createUserCommand(rettiwt: Rettiwt): Command {
+	// Creating the 'user' command
+	const user = createCommand('user').description('Access resources related to users');
+
+	// Affiliates
+	user.command('affiliates')
+		.description('Fetch the list of users who affiliated to the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of affiliates to fetch')
+		.argument('[cursor]', 'The cursor to the batch of affiliates to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const users = await rettiwt.user.affiliates(id, count ? parseInt(count) : undefined, cursor);
+				output(users);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Analytics
+	user.command('analytics')
+		.description('Fetch the analytics of the logged-in user (premium accounts only)')
+		.option('-f, --from-time <string>', 'The start time for fetching analytics')
+		.option('-t, --to-time <string>', 'The end time for fetching analytics')
+		.option(
+			'-g, --granularity <string>',
+			'The granularity of the analytics data. Defaults to daily. Check https://rishikant181.github.io/Rettiwt-API/enums/RawAnalyticsGranularity.html for granularity options',
+		)
+		.option(
+			'-m, --metrics <string>',
+			'Comma-separated list of metrics required. Check https://rishikant181.github.io/Rettiwt-API/enums/RawAnalyticsMetric.html for available metrics',
+		)
+		.option(
+			'-v, --verified-followers',
+			'Whether to include verified follower count and relationship counts in the response. Defaults to true',
+		)
+		.action(async (options?: UserAnalyticsOptions) => {
+			try {
+				const analytics = await rettiwt.user.analytics(
+					options?.fromTime ? new Date(options.fromTime) : undefined,
+					options?.toTime ? new Date(options.toTime) : undefined,
+					options?.granularity
+						? RawAnalyticsGranularity[options.granularity as keyof typeof RawAnalyticsGranularity]
+						: undefined,
+					options?.metrics
+						? options.metrics
+								.split(',')
+								.map((item) => RawAnalyticsMetric[item as keyof typeof RawAnalyticsMetric])
+						: undefined,
+					options?.verifiedFollowers,
+				);
+				output(analytics);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	user.command('bookmarks')
+		.description('Fetch your list of bookmarks')
+		.argument('[count]', 'The number of bookmarks to fetch')
+		.argument('[cursor]', 'The cursor to the batch of bookmarks to fetch')
+		.action(async (count?: string, cursor?: string) => {
+			try {
+				const bookmarks = await rettiwt.user.bookmarks(count ? parseInt(count) : undefined, cursor);
+				output(bookmarks);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	user.command('bookmark-folders')
+		.description('Fetch your list of bookmark folders')
+		.argument('[cursor]', 'The cursor to the batch of bookmark folders to fetch')
+		.action(async (cursor?: string) => {
+			try {
+				const folders = await rettiwt.user.bookmarkFolders(cursor);
+				output(folders);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	user.command('bookmark-folder-tweets')
+		.description('Fetch tweets from a specific bookmark folder')
+		.argument('<folderId>', 'The ID of the bookmark folder')
+		.argument('[count]', 'The number of tweets to fetch')
+		.argument('[cursor]', 'The cursor to the batch of tweets to fetch')
+		.action(async (folderId: string, count?: string, cursor?: string) => {
+			try {
+				const tweets = await rettiwt.user.bookmarkFolderTweets(
+					folderId,
+					count ? parseInt(count) : undefined,
+					cursor,
+				);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Details
+	user.command('details')
+		.description('Fetch the details of the user with the given id/username')
+		.argument('<id>', 'The username/id of the user whose details are to be fetched')
+		.action(async (id: string) => {
+			try {
+				// Getting the different IDs
+				const ids: string[] = id.split(',');
+
+				// If single ID given
+				if (ids.length <= 1) {
+					const details = await rettiwt.user.details(ids[0]);
+					output(details);
+				}
+				// If multiple IDs given
+				else {
+					const details = await rettiwt.user.details(ids);
+					output(details);
+				}
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Follow
+	user.command('follow')
+		.description('Follow a user')
+		.argument('<id>', 'The user to follow')
+		.action(async (id: string) => {
+			try {
+				const result = await rettiwt.user.follow(id);
+				output(result);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Followed
+	user.command('followed')
+		.description('Fetch your followed feed')
+		.argument('[cursor]', 'The cursor to the batch of feed items to fetch')
+		.action(async (cursor?: string) => {
+			try {
+				const tweets = await rettiwt.user.followed(cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Followers
+	user.command('followers')
+		.description('Fetch the list of users who follow the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of followers to fetch')
+		.argument('[cursor]', 'The cursor to the batch of followers to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const users = await rettiwt.user.followers(id, count ? parseInt(count) : undefined, cursor);
+				output(users);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Following
+	user.command('following')
+		.description('Fetch the list of users who are followed by the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of following to fetch')
+		.argument('[cursor]', 'The cursor to the batch of following to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const users = await rettiwt.user.following(id, count ? parseInt(count) : undefined, cursor);
+				output(users);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Highlights
+	user.command('highlights')
+		.description('Fetch the list of highlighted tweets of the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of highlighted tweets to fetch')
+		.argument('[cursor]', 'The cursor to the batch of highlights to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const tweets = await rettiwt.user.highlights(id, count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Likes
+	user.command('likes')
+		.description('Fetch your list of liked tweet')
+		.argument('[count]', 'The number of liked tweets to fetch')
+		.argument('[cursor]', 'The cursor to the batch of liked tweets to fetch')
+		.action(async (count?: string, cursor?: string) => {
+			try {
+				const tweets = await rettiwt.user.likes(count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Lists
+	user.command('lists')
+		.description('Fetch your lists')
+		.argument('[count]', 'The number of lists to fetch')
+		.argument('[cursor]', 'The cursor to the batch of lists to fetch')
+		.action(async (count?: string, cursor?: string) => {
+			try {
+				const lists = await rettiwt.user.lists(count ? parseInt(count) : undefined, cursor);
+				output(lists);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Media
+	user.command('media')
+		.description('Fetch the media timeline the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of media to fetch')
+		.argument('[cursor]', 'The cursor to the batch of media to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const media = await rettiwt.user.media(id, count ? parseInt(count) : undefined, cursor);
+				output(media);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Recommended
+	user.command('recommended')
+		.description('Fetch your recommended feed')
+		.argument('[cursor]', 'The cursor to the batch of feed items to fetch')
+		.action(async (cursor?: string) => {
+			try {
+				const tweets = await rettiwt.user.recommended(cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Replies
+	user.command('replies')
+		.description('Fetch the replies timeline the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of replies to fetch')
+		.argument('[cursor]', 'The cursor to the batch of replies to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const replies = await rettiwt.user.replies(id, count ? parseInt(count) : undefined, cursor);
+				output(replies);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Replies
+	user.command('search')
+		.description('Search for a username')
+		.argument('<username>', 'The username to search for')
+		.argument('[count]', 'The number of results to fetch')
+		.argument('[cursor]', 'The cursor to the batch of results to fetch')
+		.action(async (userName: string, count?: string, cursor?: string) => {
+			try {
+				const replies = await rettiwt.user.search(userName, count ? parseInt(count) : undefined, cursor);
+				output(replies);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Timeline
+	user.command('timeline')
+		.description('Fetch the tweets timeline the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of tweets to fetch')
+		.argument('[cursor]', 'The cursor to the batch of tweets to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const tweets = await rettiwt.user.timeline(id, count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Unfollow
+	user.command('unfollow')
+		.description('Unfollow a user')
+		.argument('<id>', 'The user to unfollow')
+		.action(async (id: string) => {
+			try {
+				const result = await rettiwt.user.unfollow(id);
+				output(result);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Update Profile
+	user.command('update-profile')
+		.description('Update your profile information')
+		.option('-n, --name <string>', 'Display name (max 50 characters)')
+		.option('-u, --url <string>', 'Profile URL')
+		.option('-l, --location <string>', 'Location (max 30 characters)')
+		.option('-d, --description <string>', 'Description/bio (max 160 characters)')
+		.action(async (options?: UserProfileUpdateOptions) => {
+			try {
+				const result = await rettiwt.user.updateProfile({
+					name: options?.name,
+					url: options?.url,
+					location: options?.location,
+					description: options?.description,
+				});
+				output(result);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	return user;
+}
+
+/**
+ * The options for fetching user analytics.
+ */
+type UserAnalyticsOptions = {
+	fromTime?: string;
+	toTime?: string;
+	granularity?: string;
+	metrics?: string;
+	verifiedFollowers?: boolean;
+};
+
+/**
+ * The options for updating user profile.
+ */
+type UserProfileUpdateOptions = {
+	name?: string;
+	url?: string;
+	location?: string;
+	description?: string;
+};
+
+export default createUserCommand;

package/src/enums/Api.ts

@@ -0,0 +1,10 @@
+/**
+ * The different types of api error messages.
+ *
+ * @public
+ */
+export enum ApiErrors {
+	COULD_NOT_AUTHENTICATE = 'Failed to authenticate',
+	BAD_AUTHENTICATION = 'Invalid authentication data',
+	RESOURCE_NOT_ALLOWED = 'Not authorized to access requested resource',
+}

package/src/enums/Authentication.ts

@@ -0,0 +1,10 @@
+/**
+ * The different types of authentication for authenticating against Twitter.
+ *
+ * @public
+ */
+export enum AuthenticationType {
+	GUEST = 'GUEST',
+	USER = 'USER',
+	LOGIN = 'LOGIN',
+}

package/src/enums/Data.ts

@@ -0,0 +1,13 @@
+/**
+ * The different base types of data contained in response.
+ *
+ * @internal
+ */
+export enum BaseType {
+	DIRECT_MESSAGE = 'DIRECT_MESSAGE',
+	NOTIFICATION = 'NOTIFICATION',
+	TWEET = 'TWEET',
+	USER = 'USER',
+	LIST = 'LIST',
+	BOOKMARK_FOLDER = 'BOOKMARK_FOLDER',
+}

package/src/enums/Logging.ts

@@ -0,0 +1,14 @@
+/**
+ * The different types of actions that are logged.
+ *
+ * @internal
+ */
+export enum LogActions {
+	AUTHORIZATION = 'AUTHORIZATION',
+	DESERIALIZE = 'DESERIALIZE',
+	EXTRACT = 'EXTRACT',
+	GET = 'GET',
+	REQUEST = 'REQUEST',
+	VALIDATE = 'VALIDATE',
+	WARNING = 'WARNING',
+}

package/src/enums/Media.ts

@@ -0,0 +1,10 @@
+/**
+ * The different types of media items.
+ *
+ * @public
+ */
+export enum MediaType {
+	PHOTO = 'PHOTO',
+	VIDEO = 'VIDEO',
+	GIF = 'GIF',
+}

package/src/enums/Notification.ts

@@ -0,0 +1,12 @@
+/**
+ * The different types of notifications.
+ *
+ * @public
+ */
+export enum NotificationType {
+	RECOMMENDATION = 'RECOMMENDATION',
+	INFORMATION = 'INFORMATION',
+	LIVE = 'LIVE',
+	ALERT = 'ALERT',
+	UNDEFINED = 'UNDEFINED',
+}

package/src/enums/Resource.ts

@@ -0,0 +1,69 @@
+/**
+ * The different types of resources that can be interacted with.
+ *
+ * @public
+ */
+export enum ResourceType {
+	// LIST
+	LIST_DETAILS = 'LIST_DETAILS',
+	LIST_MEMBER_ADD = 'LIST_MEMBER_ADD',
+	LIST_MEMBER_REMOVE = 'LIST_MEMBER_REMOVE',
+	LIST_MEMBERS = 'LIST_MEMBERS',
+	LIST_TWEETS = 'LIST_TWEETS',
+
+	// MEDIA
+	MEDIA_UPLOAD_APPEND = 'MEDIA_UPLOAD_APPEND',
+	MEDIA_UPLOAD_FINALIZE = 'MEDIA_UPLOAD_FINALIZE',
+	MEDIA_UPLOAD_INITIALIZE = 'MEDIA_UPLOAD_INITIALIZE',
+
+	// DM
+	DM_CONVERSATION = 'DM_CONVERSATION',
+	DM_INBOX_INITIAL_STATE = 'DM_INBOX_INITIAL_STATE',
+	DM_INBOX_TIMELINE = 'DM_INBOX_TIMELINE',
+	DM_DELETE_CONVERSATION = 'DM_DELETE_CONVERSATION',
+
+	// TWEET
+	TWEET_BOOKMARK = 'TWEET_BOOKMARK',
+	TWEET_DETAILS = 'TWEET_DETAILS',
+	TWEET_DETAILS_ALT = 'TWEET_DETAILS_ALT',
+	TWEET_DETAILS_BULK = 'TWEET_DETAILS_BULK',
+	TWEET_LIKE = 'TWEET_LIKE',
+	TWEET_LIKERS = 'TWEET_LIKERS',
+	TWEET_POST = 'TWEET_POST',
+	TWEET_REPLIES = 'TWEET_REPLIES',
+	TWEET_RETWEET = 'TWEET_RETWEET',
+	TWEET_RETWEETERS = 'TWEET_RETWEETERS',
+	TWEET_SCHEDULE = 'TWEET_SCHEDULE',
+	TWEET_SEARCH = 'TWEET_SEARCH',
+	TWEET_UNBOOKMARK = 'TWEET_UNBOOKMARK',
+	TWEET_UNLIKE = 'TWEET_UNLIKE',
+	TWEET_UNPOST = 'TWEET_UNPOST',
+	TWEET_UNRETWEET = 'TWEET_UNRETWEET',
+	TWEET_UNSCHEDULE = 'TWEET_UNSCHEDULE',
+
+	// USER
+	USER_AFFILIATES = 'USER_AFFILIATES',
+	USER_ANALYTICS = 'USER_ANALYTICS',
+	USER_BOOKMARKS = 'USER_BOOKMARKS',
+	USER_BOOKMARK_FOLDERS = 'USER_BOOKMARK_FOLDERS',
+	USER_BOOKMARK_FOLDER_TWEETS = 'USER_BOOKMARK_FOLDER_TWEETS',
+	USER_DETAILS_BY_USERNAME = 'USER_DETAILS_BY_USERNAME',
+	USER_DETAILS_BY_ID = 'USER_DETAILS_BY_ID',
+	USER_DETAILS_BY_IDS_BULK = 'USER_DETAILS_BY_IDS_BULK',
+	USER_FEED_FOLLOWED = 'USER_FEED_FOLLOWED',
+	USER_FEED_RECOMMENDED = 'USER_FEED_RECOMMENDED',
+	USER_FOLLOW = 'USER_FOLLOW',
+	USER_FOLLOWING = 'USER_FOLLOWING',
+	USER_FOLLOWERS = 'USER_FOLLOWERS',
+	USER_HIGHLIGHTS = 'USER_HIGHLIGHTS',
+	USER_LIKES = 'USER_LIKES',
+	USER_LISTS = 'USER_LISTS',
+	USER_MEDIA = 'USER_MEDIA',
+	USER_NOTIFICATIONS = 'USER_NOTIFICATIONS',
+	USER_SEARCH = 'USER_SEARCH',
+	USER_SUBSCRIPTIONS = 'USER_SUBSCRIPTIONS',
+	USER_TIMELINE = 'USER_TIMELINE',
+	USER_TIMELINE_AND_REPLIES = 'USER_TIMELINE_AND_REPLIES',
+	USER_UNFOLLOW = 'USER_UNFOLLOW',
+	USER_PROFILE_UPDATE = 'USER_PROFILE_UPDATE',
+}

package/src/enums/Tweet.ts

@@ -0,0 +1,8 @@
+/**
+ * The different types of sorting options when fetching replies to tweets.
+ */
+export enum TweetRepliesSortType {
+	LIKES = 'LIKES',
+	LATEST = 'LATEST',
+	RELEVANCE = 'RELEVANCE',
+}

package/src/enums/raw/Analytics.ts

@@ -0,0 +1,32 @@
+/**
+ * Granularity types for analytics.
+ *
+ * @public
+ */
+export enum RawAnalyticsGranularity {
+	DAILY = 'Daily',
+	WEEKLY = 'Weekly',
+	MONTHLY = 'Monthly',
+}
+
+/**
+ * The different types of metric someone can request.
+ *
+ * @public
+ */
+export enum RawAnalyticsMetric {
+	ENGAGEMENTS = 'Engagements',
+	IMPRESSIONS = 'Impressions',
+	PROFILE_VISITS = 'ProfileVisits',
+	FOLLOWS = 'Follows',
+	REPLIES = 'Replies',
+	LIKES = 'Likes',
+	RETWEETS = 'Retweets',
+	BOOKMARK = 'Bookmark',
+	SHARE = 'Share',
+	URL_CLICKS = 'UrlClicks',
+	CREATE_TWEET = 'CreateTweet',
+	CREATE_QUOTE = 'CreateQuote',
+	CREATE_REPLY = 'CreateReply',
+	UNFOLLOWS = 'Unfollows',
+}

package/src/enums/raw/Media.ts

@@ -0,0 +1,10 @@
+/**
+ * The different types of media items.
+ *
+ * @public
+ */
+export enum RawMediaType {
+	PHOTO = 'photo',
+	VIDEO = 'video',
+	GIF = 'animated_gif',
+}

package/src/enums/raw/Notification.ts

@@ -0,0 +1,11 @@
+/**
+ * The different types of notifications.
+ *
+ * @public
+ */
+export enum RawNotificationType {
+	RECOMMENDATION = 'recommendation_icon',
+	INFORMATION = 'bird_icon',
+	LIVE = 'live_icon',
+	ALERT = 'bell_icon',
+}

package/src/enums/raw/Tweet.ts

@@ -0,0 +1,20 @@
+/**
+ * The different types of search results when searching for tweets.
+ *
+ * @public
+ */
+export enum RawTweetSearchResultType {
+	LATEST = 'Latest',
+	TOP = 'Top',
+}
+
+/**
+ * The different types of sorting options when fetching replies to tweets.
+ *
+ * @public
+ */
+export enum RawTweetRepliesSortType {
+	RELEVACE = 'Relevance',
+	LATEST = 'Recency',
+	LIKES = 'Likes',
+}

package/src/helper/CliUtils.ts

@@ -0,0 +1,17 @@
+/**
+ * Outputs the given JSON data.
+ *
+ * @param data - The data to be output.
+ *
+ * @internal
+ */
+export function output(data: unknown): void {
+	// If data is string, output as is
+	if (typeof data == 'string') {
+		console.log(data);
+	}
+	// Else, format the output
+	else {
+		console.log(JSON.stringify(data, null, 4));
+	}
+}

package/src/helper/JsonUtils.ts

@@ -0,0 +1,70 @@
+/**
+ * Search for all the sub-objects (even deep-nested ones) that have the given key-value pair(filter).
+ *
+ * @param data - The data on which search is to be performed.
+ * @param key - The key of the key-value pair to search.
+ * @param value - The value of the key-value pait to search.
+ * @returns The list of sub-objects from the given object, having the given key-value pair.
+ *
+ * @internal
+ */
+export function findByFilter<T>(data: NonNullable<unknown>, key: string, value: string): T[] {
+	/**
+	 * The list containing all the objects matching given filter.
+	 */
+	let res: T[] = [];
+
+	/**
+	 * If the data is an array, recursively run the function of each element of the array and merge the results.
+	 */
+	if (Array.isArray(data)) {
+		/**
+		 * findByFilter returns an array.
+		 * map() also returns an array.
+		 * Therefore, map(item =\> findByFilter(.......)) returns an array of arrays.
+		 * Therefore, using ... operator to spread the 2-D array in 1-D array.
+		 */
+		res = res.concat(...data.map((item: NonNullable<unknown>) => findByFilter<T>(item, key, value)));
+	}
+	// If the data is an object
+	else if (data != null && typeof data == 'object') {
+		/**
+		 * If the object includes the key and the value specified by the key matches the filter, add it to the result.
+		 */
+		if (Object.keys(data).includes(key) && data[key as keyof typeof data] == value) {
+			res.push(data as T);
+		}
+
+		/**
+		 * Recursively run the function on each value specified by each key in the object, for subsequent matches.
+		 */
+		for (const [, v] of Object.entries(data)) {
+			res = res.concat(findByFilter<T>(v as NonNullable<unknown>, key, value));
+		}
+	}
+
+	return res;
+}
+
+/**
+ * Searches for the key which has the given value in the given object.
+ *
+ * @param data - The data on which search is to be performed.
+ * @param value - The value to search.
+ * @returns The key with the given value.
+ *
+ * @internal
+ */
+export function findKeyByValue(data: NonNullable<unknown>, value: string): string | undefined {
+	// Finding the key-value pairs that have the given value
+	const kvPair = Object.entries(data).filter(([, v]) => v == value)[0];
+
+	// If a match is found
+	if (kvPair) {
+		return kvPair[0];
+	}
+	// If no match is found
+	else {
+		return undefined;
+	}
+}