rettiwt-api 2.7.1 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rettiwt-api",
-	"version": "2.7.1",
+	"version": "3.0.0",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"description": "An API for fetching data from TwitterAPI, without any rate limits!",
@@ -30,17 +30,19 @@
 	"homepage": "https://rishikant181.github.io/Rettiwt-API/",
 	"dependencies": {
 		"axios": "1.6.3",
+		"chalk": "4.1.2",
 		"class-validator": "0.14.1",
 		"commander": "11.1.0",
 		"https-proxy-agent": "7.0.2",
 		"rettiwt-auth": "2.1.0",
-		"rettiwt-core": "3.4.0"
+		"rettiwt-core": "4.0.0"
 	},
 	"devDependencies": {
 		"@types/node": "20.4.1",
 		"@typescript-eslint/eslint-plugin": "6.0.0",
 		"@typescript-eslint/parser": "6.0.0",
 		"eslint": "8.44.0",
+		"eslint-plugin-import": "2.29.1",
 		"eslint-plugin-tsdoc": "0.2.17",
 		"nodemon": "2.0.20",
 		"prettier": "3.0.0",

package/src/Rettiwt.ts

@@ -1,9 +1,6 @@
-// SERVICES
 import { AuthService } from './services/public/AuthService';
 import { TweetService } from './services/public/TweetService';
 import { UserService } from './services/public/UserService';
-
-// TYPES
 import { IRettiwtConfig } from './types/RettiwtConfig';
 
 /**

package/src/cli.ts

@@ -1,13 +1,11 @@
 #! /usr/bin/env node
 
-// PACKAGES
 import { createCommand } from 'commander';
-import { Rettiwt } from './Rettiwt';
 
-// SUB-COMMANDS
+import auth from './commands/Auth';
 import tweet from './commands/Tweet';
 import user from './commands/User';
-import auth from './commands/Auth';
+import { Rettiwt } from './Rettiwt';
 
 // Creating a new commandline program
 const program = createCommand('rettiwt')

package/src/collections/Extractors.ts

@@ -0,0 +1,63 @@
+import {
+	IInitializeMediaUploadResponse,
+	IListDetailsResponse,
+	IResponse,
+	ITweetLikeResponse,
+	ITweetPostResponse,
+	ITweetRetweetResponse,
+	ITweetUnlikeResponse,
+	ITweetUnpostResponse,
+	ITweetUnretweetResponse,
+	IUserFollowResponse,
+	IUserUnfollowResponse,
+} from 'rettiwt-core';
+
+import { EBaseType } from '../enums/Data';
+import { EResourceType } from '../enums/Resource';
+import { CursoredData } from '../models/data/CursoredData';
+import { Tweet } from '../models/data/Tweet';
+import { User } from '../models/data/User';
+import { AllReturnTypes } from '../types/ReturnTypes';
+
+/**
+ * Collection of data extractors for each resource.
+ *
+ * @internal
+ */
+export const extractors: {
+	[key in keyof typeof EResourceType]: (response: NonNullable<unknown>) => AllReturnTypes | undefined;
+} = {
+	/* eslint-disable @typescript-eslint/naming-convention */
+	LIST_TWEETS: (response) => new CursoredData<Tweet>(response as IListDetailsResponse, EBaseType.TWEET),
+
+	MEDIA_UPLOAD_APPEND: () => undefined,
+	MEDIA_UPLOAD_FINALIZE: () => undefined,
+	MEDIA_UPLOAD_INITIALIZE: (response) => (response as IInitializeMediaUploadResponse).media_id_string ?? undefined,
+
+	TWEET_DETAILS: (response) => Tweet.single(response as IResponse<unknown>),
+	TWEET_LIKE: (response) => ((response as ITweetLikeResponse)?.data?.favorite_tweet ? true : false),
+	TWEET_LIKERS: (response) => new CursoredData<User>(response as IResponse<unknown>, EBaseType.USER),
+	TWEET_POST: (response) =>
+		(response as ITweetPostResponse)?.data?.create_tweet?.tweet_results?.result?.rest_id ?? undefined,
+	TWEET_RETWEET: (response) => ((response as ITweetRetweetResponse)?.data?.create_retweet ? true : false),
+	TWEET_RETWEETERS: (response) => new CursoredData<User>(response as IResponse<unknown>, EBaseType.USER),
+	TWEET_SEARCH: (response) => new CursoredData<Tweet>(response as IResponse<unknown>, EBaseType.TWEET),
+	TWEET_UNLIKE: (response) => ((response as ITweetUnlikeResponse)?.data?.unfavorite_tweet ? true : false),
+	TWEET_UNPOST: (response) => ((response as ITweetUnpostResponse)?.data?.delete_tweet ? true : false),
+	TWEET_UNRETWEET: (response) =>
+		(response as ITweetUnretweetResponse)?.data?.unretweet?.source_tweet_results?.result ? true : false,
+
+	USER_DETAILS_BY_USERNAME: (response) => User.single(response as IResponse<unknown>),
+	USER_DETAILS_BY_ID: (response) => User.single(response as IResponse<unknown>),
+	USER_FOLLOW: (response) => ((response as IUserFollowResponse)?.id ? true : false),
+	USER_FOLLOWING: (response) => new CursoredData<User>(response as IResponse<unknown>, EBaseType.USER),
+	USER_FOLLOWERS: (response) => new CursoredData<User>(response as IResponse<unknown>, EBaseType.USER),
+	USER_HIGHLIGHTS: (response) => new CursoredData<Tweet>(response as IResponse<unknown>, EBaseType.TWEET),
+	USER_LIKES: (response) => new CursoredData<Tweet>(response as IResponse<unknown>, EBaseType.TWEET),
+	USER_MEDIA: (response) => new CursoredData<Tweet>(response as IResponse<unknown>, EBaseType.TWEET),
+	USER_SUBSCRIPTIONS: (response) => new CursoredData<User>(response as IResponse<unknown>, EBaseType.USER),
+	USER_TIMELINE: (response) => new CursoredData<Tweet>(response as IResponse<unknown>, EBaseType.TWEET),
+	USER_TIMELINE_AND_REPLIES: (response) => new CursoredData<Tweet>(response as IResponse<unknown>, EBaseType.TWEET),
+	USER_UNFOLLOW: (response) => ((response as IUserUnfollowResponse)?.id ? true : false),
+	/* eslint-enable @typescript-eslint/naming-convention */
+};

package/src/collections/Groups.ts

@@ -0,0 +1,54 @@
+import { EResourceType } from '../enums/Resource';
+
+/**
+ * Collection of resources that allow guest authentication.
+ *
+ * @internal
+ */
+export const allowGuestAuthentication = [
+	EResourceType.TWEET_DETAILS,
+	EResourceType.USER_DETAILS_BY_USERNAME,
+	EResourceType.USER_TIMELINE,
+];
+
+/**
+ * Collection of resources that can be fetched.
+ *
+ * @internal
+ */
+export const fetchResources = [
+	EResourceType.LIST_TWEETS,
+	EResourceType.TWEET_DETAILS,
+	EResourceType.TWEET_LIKERS,
+	EResourceType.TWEET_RETWEETERS,
+	EResourceType.TWEET_SEARCH,
+	EResourceType.USER_DETAILS_BY_USERNAME,
+	EResourceType.USER_DETAILS_BY_ID,
+	EResourceType.USER_FOLLOWING,
+	EResourceType.USER_FOLLOWERS,
+	EResourceType.USER_HIGHLIGHTS,
+	EResourceType.USER_LIKES,
+	EResourceType.USER_MEDIA,
+	EResourceType.USER_SUBSCRIPTIONS,
+	EResourceType.USER_TIMELINE,
+	EResourceType.USER_TIMELINE_AND_REPLIES,
+];
+
+/**
+ * Collection of resources that can be posted.
+ *
+ * @internal
+ */
+export const postResources = [
+	EResourceType.MEDIA_UPLOAD_APPEND,
+	EResourceType.MEDIA_UPLOAD_FINALIZE,
+	EResourceType.MEDIA_UPLOAD_INITIALIZE,
+	EResourceType.TWEET_LIKE,
+	EResourceType.TWEET_POST,
+	EResourceType.TWEET_RETWEET,
+	EResourceType.TWEET_UNLIKE,
+	EResourceType.TWEET_UNPOST,
+	EResourceType.TWEET_UNRETWEET,
+	EResourceType.USER_FOLLOW,
+	EResourceType.USER_UNFOLLOW,
+];

package/src/collections/Requests.ts

@@ -0,0 +1,52 @@
+import { AxiosRequestConfig } from 'axios';
+import { Request } from 'rettiwt-core';
+
+import { EResourceType } from '../enums/Resource';
+import { FetchArgs } from '../models/args/FetchArgs';
+import { PostArgs } from '../models/args/PostArgs';
+
+/**
+ * The request generator from rettiwt-core.
+ *
+ * @internal
+ */
+const request = new Request();
+
+/**
+ * The collection of requests to various resources.
+ *
+ * @internal
+ */
+export const requests: { [key in keyof typeof EResourceType]: (args: FetchArgs | PostArgs) => AxiosRequestConfig } = {
+	/* eslint-disable @typescript-eslint/naming-convention */
+	LIST_TWEETS: (args: FetchArgs) => request.list.tweets(args.id!, args.count, args.cursor),
+
+	MEDIA_UPLOAD_APPEND: (args: PostArgs) => request.media.appendUpload(args.upload!.id!, args.upload!.media!),
+	MEDIA_UPLOAD_FINALIZE: (args: PostArgs) => request.media.finalizeUpload(args.upload!.id!),
+	MEDIA_UPLOAD_INITIALIZE: (args: PostArgs) => request.media.initializeUpload(args.upload!.size!),
+
+	TWEET_DETAILS: (args: FetchArgs) => request.tweet.details(args.id!),
+	TWEET_LIKE: (args: PostArgs) => request.tweet.like(args.id!),
+	TWEET_LIKERS: (args: FetchArgs) => request.tweet.likers(args.id!, args.count, args.cursor),
+	TWEET_POST: (args: PostArgs) => request.tweet.post(args.tweet!),
+	TWEET_RETWEET: (args: PostArgs) => request.tweet.retweet(args.id!),
+	TWEET_RETWEETERS: (args: FetchArgs) => request.tweet.retweeters(args.id!, args.count, args.cursor),
+	TWEET_SEARCH: (args: FetchArgs) => request.tweet.search(args.filter!, args.count, args.cursor),
+	TWEET_UNLIKE: (args: PostArgs) => request.tweet.unlike(args.id!),
+	TWEET_UNPOST: (args: PostArgs) => request.tweet.unpost(args.id!),
+	TWEET_UNRETWEET: (args: PostArgs) => request.tweet.unretweet(args.id!),
+
+	USER_DETAILS_BY_USERNAME: (args: FetchArgs) => request.user.detailsByUsername(args.id!),
+	USER_DETAILS_BY_ID: (args: FetchArgs) => request.user.detailsById(args.id!),
+	USER_FOLLOW: (args: PostArgs) => request.user.follow(args.id!),
+	USER_FOLLOWING: (args: FetchArgs) => request.user.following(args.id!, args.count, args.cursor),
+	USER_FOLLOWERS: (args: FetchArgs) => request.user.followers(args.id!, args.count, args.cursor),
+	USER_HIGHLIGHTS: (args: FetchArgs) => request.user.highlights(args.id!, args.count, args.cursor),
+	USER_LIKES: (args: FetchArgs) => request.user.likes(args.id!, args.count, args.cursor),
+	USER_MEDIA: (args: FetchArgs) => request.user.media(args.id!, args.count, args.cursor),
+	USER_SUBSCRIPTIONS: (args: FetchArgs) => request.user.subscriptions(args.id!, args.count, args.cursor),
+	USER_TIMELINE: (args: FetchArgs) => request.user.tweets(args.id!, args.count, args.cursor),
+	USER_TIMELINE_AND_REPLIES: (args: FetchArgs) => request.user.tweetsAndReplies(args.id!, args.count, args.cursor),
+	USER_UNFOLLOW: (args: PostArgs) => request.user.unfollow(args.id!),
+	/* eslint-enable @typescript-eslint/naming-convention */
+};

package/src/commands/Auth.ts

@@ -1,10 +1,14 @@
-// PACKAGES
 import { Command, createCommand } from 'commander';
-import { Rettiwt } from '../Rettiwt';
 
-// UTILITY
 import { output } from '../helper/CliUtils';
+import { Rettiwt } from '../Rettiwt';
 
+/**
+ * Creates a new 'auth' command which uses the given Rettiwt instance.
+ *
+ * @param rettiwt - The Rettiwt instance to use.
+ * @returns The created 'auth' command.
+ */
 function createAuthCommand(rettiwt: Rettiwt): Command {
 	// Creating the 'auth' command
 	const auth = createCommand('auth').description('Manage authentication');
@@ -16,16 +20,24 @@ function createAuthCommand(rettiwt: Rettiwt): Command {
 		.argument('<username>', 'The username associated with the Twitter account')
 		.argument('<password>', 'The password to the Twitter account')
 		.action(async (email: string, username: string, password: string) => {
-			const apiKey: string = await rettiwt.auth.login(email, username, password);
-			output(apiKey);
+			try {
+				const apiKey: string = await rettiwt.auth.login(email, username, password);
+				output(apiKey);
+			} catch (error) {
+				output(error);
+			}
 		});
 
 	// Guest
 	auth.command('guest')
 		.description('Generate a new guest key')
 		.action(async () => {
-			const guestKey: string = await rettiwt.auth.guest();
-			output(guestKey);
+			try {
+				const guestKey: string = await rettiwt.auth.guest();
+				output(guestKey);
+			} catch (error) {
+				output(error);
+			}
 		});
 
 	return auth;

package/src/commands/Tweet.ts

@@ -1,10 +1,8 @@
-// PACKAGES
 import { Command, createCommand } from 'commander';
-import { Rettiwt } from '../Rettiwt';
 import { TweetFilter } from 'rettiwt-core';
 
-// UTILITY
 import { output } from '../helper/CliUtils';
+import { Rettiwt } from '../Rettiwt';
 
 /**
  * Creates a new 'tweet' command which uses the given Rettiwt instance.
@@ -22,8 +20,113 @@ function createTweetCommand(rettiwt: Rettiwt): Command {
 		.description('Fetch the details of tweet with the given id')
 		.argument('<id>', 'The id of the tweet whose details are to be fetched')
 		.action(async (id: string) => {
-			const details = await rettiwt.tweet.details(id);
-			output(details);
+			try {
+				const details = await rettiwt.tweet.details(id);
+				output(details);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Like
+	tweet
+		.command('like')
+		.description('Like a tweet')
+		.argument('<id>', 'The tweet to like')
+		.action(async (id: string) => {
+			try {
+				const result = await rettiwt.tweet.like(id);
+				output(result);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Likers
+	tweet
+		.command('likers')
+		.description('Fetch the list of users who liked the given tweets')
+		.argument('<id>', 'The id of the tweet')
+		.argument('[count]', 'The number of likers to fetch')
+		.argument('[cursor]', 'The cursor to the batch of likers to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const tweets = await rettiwt.tweet.likers(id, count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// List
+	tweet
+		.command('list')
+		.description('Fetch the list of tweets in the tweet list with the given id')
+		.argument('<id>', 'The id of the tweet list')
+		.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.tweet.list(id, count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Post
+	tweet
+		.command('post')
+		.description('Post a tweet (text only)')
+		.argument('<text>', 'The text to post as a tweet')
+		.option('-m, --media [string]', 'Comma-separated list of ids of the media item(s) to be posted')
+		.option('-q, --quote [string]', 'The id of the tweet to quote in the tweet to be posted')
+		.option(
+			'-r, --reply [string]',
+			'The id of the tweet to which the reply is to be made, if the tweet is to be a reply',
+		)
+		.action(async (text: string, options?: { media?: string; quote?: string; reply?: string }) => {
+			try {
+				const result = await rettiwt.tweet.post({
+					text: text,
+					media: options?.media ? options?.media.split(',').map((item) => ({ id: item })) : undefined,
+					quote: options?.quote,
+					replyTo: options?.reply,
+				});
+				output(result);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Retweet
+	tweet
+		.command('retweet')
+		.description('Retweet a tweet')
+		.argument('<id>', 'The tweet to retweet')
+		.action(async (id: string) => {
+			try {
+				const result = await rettiwt.tweet.retweet(id);
+				output(result);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Retweeters
+	tweet
+		.command('retweeters')
+		.description('Fetch the list of users who retweeted the given tweets')
+		.argument('<id>', 'The id of the tweet')
+		.argument('[count]', 'The number of retweeters to fetch')
+		.argument('[cursor]', 'The cursor to the batch of retweeters to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const tweets = await rettiwt.tweet.retweeters(id, count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
 		});
 
 	// Search
@@ -60,99 +163,84 @@ function createTweetCommand(rettiwt: Rettiwt): Command {
 		.option('--stream', 'Stream the filtered tweets in pseudo-realtime')
 		.option('-i, --interval <number>', 'The polling interval (in ms) to use for streaming. Default is 60000')
 		.action(async (count?: string, cursor?: string, options?: TweetSearchOptions) => {
-			// If search results are to be streamed
-			if (options?.stream) {
-				for await (const tweet of rettiwt.tweet.stream(
-					new TweetSearchOptions(options).toTweetFilter(),
-					options?.interval,
-				)) {
-					output(tweet);
+			try {
+				// If search results are to be streamed
+				if (options?.stream) {
+					for await (const tweet of rettiwt.tweet.stream(
+						new TweetSearchOptions(options).toTweetFilter(),
+						options?.interval,
+					)) {
+						output(tweet);
+					}
 				}
-			}
-			// If a normal search is to be done
-			else {
-				const tweets = await rettiwt.tweet.search(
-					new TweetSearchOptions(options).toTweetFilter(),
-					count ? parseInt(count) : undefined,
-					cursor,
-				);
-				output(tweets);
+				// If a normal search is to be done
+				else {
+					const tweets = await rettiwt.tweet.search(
+						new TweetSearchOptions(options).toTweetFilter(),
+						count ? parseInt(count) : undefined,
+						cursor,
+					);
+					output(tweets);
+				}
+			} catch (error) {
+				output(error);
 			}
 		});
 
-	// List
+	// Unlike
 	tweet
-		.command('list')
-		.description('Fetch the list of tweets in the tweet list with the given id')
-		.argument('<id>', 'The id of the tweet list')
-		.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) => {
-			const tweets = await rettiwt.tweet.list(id, count ? parseInt(count) : undefined, cursor);
-			output(tweets);
-		});
-
-	// Likes
-	tweet
-		.command('likes')
-		.description('Fetch the list of users who liked the given tweets')
+		.command('unlike')
+		.description('Unlike a tweet')
 		.argument('<id>', 'The id of the tweet')
-		.argument('[count]', 'The number of likers to fetch')
-		.argument('[cursor]', 'The cursor to the batch of likers to fetch')
-		.action(async (id: string, count?: string, cursor?: string) => {
-			const tweets = await rettiwt.tweet.favoriters(id, count ? parseInt(count) : undefined, cursor);
-			output(tweets);
+		.action(async (id: string) => {
+			try {
+				const result = await rettiwt.tweet.unlike(id);
+				output(result);
+			} catch (error) {
+				output(error);
+			}
 		});
 
-	// Retweets
+	// Unpost
 	tweet
-		.command('retweets')
-		.description('Fetch the list of users who retweeted the given tweets')
+		.command('unpost')
+		.description('Unpost a tweet')
 		.argument('<id>', 'The id of the tweet')
-		.argument('[count]', 'The number of retweeters to fetch')
-		.argument('[cursor]', 'The cursor to the batch of retweeters to fetch')
-		.action(async (id: string, count?: string, cursor?: string) => {
-			const tweets = await rettiwt.tweet.retweeters(id, count ? parseInt(count) : undefined, cursor);
-			output(tweets);
-		});
-
-	// Post
-	tweet
-		.command('post')
-		.description('Post a tweet (text only)')
-		.argument('<text>', 'The text to post as a tweet')
-		.option('-m, --media [string]', 'Comma-separated list of path(s) to the media item(s) to be posted')
-		.option(
-			'-r, --reply [string]',
-			'The id of the tweet to which the reply is to be made, if the tweet is to be a reply',
-		)
-		.action(async (text: string, options?: { media?: string; reply?: string }) => {
-			const result = await rettiwt.tweet.tweet(
-				text,
-				options?.media ? options?.media.split(',').map((item) => ({ path: item })) : undefined,
-				options?.reply,
-			);
-			output(result);
+		.action(async (id: string) => {
+			try {
+				const result = await rettiwt.tweet.unpost(id);
+				output(result);
+			} catch (error) {
+				output(error);
+			}
 		});
 
-	// Like
+	// Unretweet
 	tweet
-		.command('like')
-		.description('Like a tweet')
-		.argument('<id>', 'The tweet to like')
+		.command('unretweet')
+		.description('Unretweet a tweet')
+		.argument('<id>', 'The id of the tweet')
 		.action(async (id: string) => {
-			const result = await rettiwt.tweet.favorite(id);
-			output(result);
+			try {
+				const result = await rettiwt.tweet.unretweet(id);
+				output(result);
+			} catch (error) {
+				output(error);
+			}
 		});
 
-	// Retweet
+	// Upload
 	tweet
-		.command('retweet')
-		.description('Retweet a tweet')
-		.argument('<id>', 'The tweet to retweet')
-		.action(async (id: string) => {
-			const result = await rettiwt.tweet.retweet(id);
-			output(result);
+		.command('upload')
+		.description('Upload a media file and returns the alloted id (valid for 24 hrs)')
+		.argument('<path>', 'The path to the media to upload')
+		.action(async (path: string) => {
+			try {
+				const id = await rettiwt.tweet.upload(path);
+				output(id);
+			} catch (error) {
+				output(error);
+			}
 		});
 
 	return tweet;
@@ -164,24 +252,24 @@ function createTweetCommand(rettiwt: Rettiwt): Command {
  * @remarks The search options are implementations of the ones offered by {@link TweetFilter}
  */
 class TweetSearchOptions {
-	public from?: string;
-	public to?: string;
-	public words?: string;
-	public phrase?: string;
-	public optionalWords?: string;
+	public end?: string;
+	public excludeLinks?: boolean = false;
+	public excludeReplies?: boolean = false;
 	public excludeWords?: string;
+	public from?: string;
 	public hashtags?: string;
+	public interval?: number;
 	public mentions?: string;
-	public minReplies?: number;
 	public minLikes?: number;
+	public minReplies?: number;
 	public minRetweets?: number;
+	public optionalWords?: string;
+	public phrase?: string;
 	public quoted?: string;
-	public excludeLinks?: boolean = false;
-	public excludeReplies?: boolean = false;
 	public start?: string;
-	public end?: string;
 	public stream?: boolean;
-	public interval?: number;
+	public to?: string;
+	public words?: string;
 
 	/**
 	 * Initializes a new object from the given options.