rettiwt-api 2.7.1 → 3.0.0

package/src/commands/User.ts

@@ -1,9 +1,7 @@
-// PACKAGES
 import { Command, createCommand } from 'commander';
-import { Rettiwt } from '../Rettiwt';
 
-// UTILITY
 import { output } from '../helper/CliUtils';
+import { Rettiwt } from '../Rettiwt';
 
 /**
  * Creates a new 'user' command which uses the given Rettiwt instance.
@@ -20,8 +18,40 @@ function createUserCommand(rettiwt: Rettiwt): Command {
 		.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) => {
-			const details = await rettiwt.user.details(id);
-			output(details);
+			try {
+				const details = await rettiwt.user.details(id);
+				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);
+			}
+		});
+
+	// 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
@@ -31,19 +61,27 @@ function createUserCommand(rettiwt: Rettiwt): Command {
 		.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) => {
-			const users = await rettiwt.user.following(id, count ? parseInt(count) : undefined, cursor);
-			output(users);
+			try {
+				const users = await rettiwt.user.following(id, count ? parseInt(count) : undefined, cursor);
+				output(users);
+			} catch (error) {
+				output(error);
+			}
 		});
 
-	// Followers
-	user.command('followers')
-		.description('Fetch the list of users who follow the given user')
+	// 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 followers to fetch')
-		.argument('[cursor]', 'The cursor to the batch of followers to fetch')
+		.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) => {
-			const users = await rettiwt.user.followers(id, count ? parseInt(count) : undefined, cursor);
-			output(users);
+			try {
+				const tweets = await rettiwt.user.highlights(id, count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
 		});
 
 	// Likes
@@ -53,19 +91,27 @@ function createUserCommand(rettiwt: Rettiwt): Command {
 		.argument('[count]', 'The number of liked tweets to fetch')
 		.argument('[cursor]', 'The cursor to the batch of liked tweets to fetch')
 		.action(async (id: string, count?: string, cursor?: string) => {
-			const users = await rettiwt.user.likes(id, count ? parseInt(count) : undefined, cursor);
-			output(users);
+			try {
+				const tweets = await rettiwt.user.likes(id, count ? parseInt(count) : undefined, cursor);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
 		});
 
-	// Timeline
-	user.command('timeline')
-		.description('Fetch the tweets timeline the given user')
+	// Media
+	user.command('media')
+		.description('Fetch the media 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')
+		.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) => {
-			const users = await rettiwt.user.timeline(id, count ? parseInt(count) : undefined, cursor);
-			output(users);
+			try {
+				const media = await rettiwt.user.media(id, count ? parseInt(count) : undefined, cursor);
+				output(media);
+			} catch (error) {
+				output(error);
+			}
 		});
 
 	// Replies
@@ -75,8 +121,55 @@ function createUserCommand(rettiwt: Rettiwt): Command {
 		.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) => {
-			const users = await rettiwt.user.replies(id, count ? parseInt(count) : undefined, cursor);
-			output(users);
+			try {
+				const replies = await rettiwt.user.replies(id, count ? parseInt(count) : undefined, cursor);
+				output(replies);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	// Subscriptions
+	user.command('subscriptions')
+		.description('Fetch the list of users who are subscribed by the given user')
+		.argument('<id>', 'The id of the user')
+		.argument('[count]', 'The number of subscriptions to fetch')
+		.argument('[cursor]', 'The cursor to the batch of subscriptions to fetch')
+		.action(async (id: string, count?: string, cursor?: string) => {
+			try {
+				const users = await rettiwt.user.subscriptions(id, count ? parseInt(count) : undefined, cursor);
+				output(users);
+			} 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);
+			}
 		});
 
 	return user;

package/src/enums/Api.ts

@@ -28,3 +28,34 @@ export enum EApiErrors {
 	TWEET_VIOLATED_RULES = 'Requestd tweet has been removed for rules violation',
 	DISABLED_TWEET_ACTIONS = 'Reqeusted action disabled on the tweet',
 }
+
+/**
+ * The different error codes.
+ *
+ * @public
+ */
+export enum EErrorCodes {
+	COULD_NOT_AUTHENTICATE = 32,
+	RESOURCE_NOT_FOUND = 34,
+	MISSING_PARAMETER = 38,
+	USER_NOT_FOUND = 50,
+	USER_SUSPENDED = 63,
+	ACCOUNT_SUSPENDED = 64,
+	RATE_LIMIT_EXCEEDED = 88,
+	INTERNAL_ERROR = 131,
+	TIME_ERROR = 135,
+	ALREADY_FAVORITED = 139,
+	STATUS_NOT_FOUND = 144,
+	NOT_AUTHORIZED = 179,
+	DAILY_STATUS_LIMIT_EXCEEDED = 185,
+	TWEET_LENGTH_EXCEEDED = 186,
+	DUPLICATE_STATUS = 187,
+	BAD_AUTHENTICATION = 215,
+	RESOURCE_NOT_ALLOWED = 220,
+	AUTOMATED_REQUEST_ERROR = 226,
+	ACCOUNT_LOCKED = 326,
+	ALREADY_RETWEETED = 327,
+	TWEET_NOT_FOUND = 421,
+	TWEET_VIOLATED_RULES = 422,
+	DISABLED_TWEET_ACTIONS = 425,
+}

package/src/enums/Data.ts

@@ -0,0 +1,9 @@
+/**
+ * The different base types of data contained in response.
+ *
+ * @internal
+ */
+export enum EBaseType {
+	TWEET = 'Tweet',
+	USER = 'User',
+}

package/src/enums/Http.ts

@@ -1,7 +1,7 @@
 /**
  * The different types of http status codes
  *
- * @internal
+ * @public
  */
 export enum EHttpStatus {
 	CONTINUE = 100,

package/src/enums/Logging.ts

@@ -4,10 +4,11 @@
  * @internal
  */
 export enum ELogActions {
-	FETCH = 'FETCH',
-	POST = 'POST',
-	UPLOAD = 'UPLOAD',
-	EXTRACT = 'EXTRACT',
-	DESERIALIZE = 'DESERIALIZE',
 	AUTHORIZATION = 'AUTHORIZATION',
+	DESERIALIZE = 'DESERIALIZE',
+	EXTRACT = 'EXTRACT',
+	GET = 'GET',
+	REQUEST = 'REQUEST',
+	VALIDATE = 'VALIDATE',
+	WARNING = 'WARNING',
 }

package/src/enums/Resource.ts

@@ -0,0 +1,40 @@
+/**
+ * The different types of resources that can be interacted with.
+ *
+ * @public
+ */
+export enum EResourceType {
+	// LIST
+	LIST_TWEETS = 'LIST_TWEETS',
+
+	// MEDIA
+	MEDIA_UPLOAD_APPEND = 'MEDIA_UPLOAD_APPEND',
+	MEDIA_UPLOAD_FINALIZE = 'MEDIA_UPLOAD_FINALIZE',
+	MEDIA_UPLOAD_INITIALIZE = 'MEDIA_UPLOAD_INITIALIZE',
+
+	// TWEET
+	TWEET_DETAILS = 'TWEET_DETAILS',
+	TWEET_LIKE = 'TWEET_LIKE',
+	TWEET_LIKERS = 'TWEET_LIKERS',
+	TWEET_POST = 'TWEET_POST',
+	TWEET_RETWEET = 'TWEET_RETWEET',
+	TWEET_RETWEETERS = 'TWEET_RETWEETERS',
+	TWEET_SEARCH = 'TWEET_SEARCH',
+	TWEET_UNLIKE = 'TWEET_UNLIKE',
+	TWEET_UNPOST = 'TWEET_UNPOST',
+	TWEET_UNRETWEET = 'TWEET_UNRETWEET',
+
+	// USER
+	USER_DETAILS_BY_USERNAME = 'USER_DETAILS_BY_USERNAME',
+	USER_DETAILS_BY_ID = 'USER_DETAILS_BY_ID',
+	USER_FOLLOW = 'USER_FOLLOW',
+	USER_FOLLOWING = 'USER_FOLLOWING',
+	USER_FOLLOWERS = 'USER_FOLLOWERS',
+	USER_HIGHLIGHTS = 'USER_HIGHLIGHTS',
+	USER_LIKES = 'USER_LIKES',
+	USER_MEDIA = 'USER_MEDIA',
+	USER_SUBSCRIPTIONS = 'USER_SUBSCRIPTIONS',
+	USER_TIMELINE = 'USER_TIMELINE',
+	USER_TIMELINE_AND_REPLIES = 'USER_TIMELINE_AND_REPLIES',
+	USER_UNFOLLOW = 'USER_UNFOLLOW',
+}

package/src/helper/CliUtils.ts

@@ -3,7 +3,7 @@
  *
  * @param data - The data to be output.
  */
-export function output(data: NonNullable<unknown>): void {
+export function output(data: unknown): void {
 	// If data is string, output as is
 	if (typeof data == 'string') {
 		console.log(data);

package/src/index.ts

@@ -1,21 +1,14 @@
 // MAIN
 export * from './Rettiwt';
 
-// EXTERNAL
-export { TweetFilter } from 'rettiwt-core';
-
 // ENUMS
 export * from './enums/Api';
 export * from './enums/Http';
-export * from './enums/Logging';
-
-// ARGS MODELS
-export * from './models/args/TweetArgs';
+export * from './enums/Resource';
 
-// ERROR MODELS
-export * from './models/errors/ApiError';
-export * from './models/errors/HttpError';
-export * from './models/errors/RettiwtError';
+// ARG MODELS
+export * from './models/args/FetchArgs';
+export * from './models/args/PostArgs';
 
 // DATA MODELS
 export * from './models/data/CursoredData';
@@ -23,14 +16,48 @@ export * from './models/data/List';
 export * from './models/data/Tweet';
 export * from './models/data/User';
 
+// ERROR MODELS
+export * from './models/errors/ApiError';
+export * from './models/errors/DataValidationError';
+export * from './models/errors/HttpError';
+export * from './models/errors/RettiwtError';
+export * from './models/errors/TimeoutError';
+
 // SERVICES
-export * from './services/internal/ErrorService';
-export * from './services/internal/FetcherService';
-export * from './services/internal/LogService';
 export * from './services/public/AuthService';
+export * from './services/public/FetcherService';
 export * from './services/public/TweetService';
 export * from './services/public/UserService';
 
 // TYPES
 export * from './types/RettiwtConfig';
 export * from './types/ErrorHandler';
+
+// RAW TYPES
+export {
+	IInitializeMediaUploadResponse,
+	IListTweetsResponse,
+	ITweetDetailsResponse,
+	ITweetLikeResponse,
+	ITweetLikersResponse,
+	ITweetPostResponse,
+	ITweetRetweetersResponse,
+	ITweetRetweetResponse,
+	ITweetSearchResponse,
+	ITweetUnlikeResponse,
+	ITweetUnpostResponse,
+	ITweetUnretweetResponse,
+} from 'rettiwt-core';
+export {
+	IUserDetailsResponse,
+	IUserFollowersResponse,
+	IUserFollowingResponse,
+	IUserFollowResponse,
+	IUserHighlightsResponse,
+	IUserLikesResponse,
+	IUserMediaResponse,
+	IUserSubscriptionsResponse,
+	IUserTweetsAndRepliesResponse,
+	IUserTweetsResponse,
+	IUserUnfollowResponse,
+} from 'rettiwt-core';

package/src/models/args/FetchArgs.ts

@@ -0,0 +1,296 @@
+import {
+	IsArray,
+	IsBoolean,
+	IsDate,
+	IsNotEmpty,
+	IsNumber,
+	IsNumberString,
+	IsObject,
+	IsOptional,
+	IsString,
+	Max,
+	validateSync,
+} from 'class-validator';
+
+import { TweetFilter as TweetFilterCore } from 'rettiwt-core';
+
+import { EResourceType } from '../../enums/Resource';
+import { DataValidationError } from '../errors/DataValidationError';
+
+/**
+ * Options specifying the data that is to be fetched.
+ *
+ * @public
+ */
+export class FetchArgs {
+	/**
+	 * The number of data items to fetch.
+	 *
+	 * @remarks
+	 * - Works only for cursored resources.
+	 * - Must be \<= 20 for:
+	 * 	- {@link EResourceType.USER_TIMELINE}
+	 * 	- {@link EResourceType.USER_TIMELINE}
+	 * 	- {@link EResourceType.USER_TIMELINE_AND_REPLIES}.
+	 * - Must be \<= 100 for all other cursored resources.
+	 * - Due a bug on Twitter's end, count does not work for {@link EResourceType.USER_FOLLOWERS} and {@link EResourceType.USER_FOLLOWING}.
+	 *
+	 * @defaultValue 20
+	 */
+	@IsOptional()
+	@Max(100, {
+		groups: [
+			EResourceType.LIST_TWEETS,
+			EResourceType.TWEET_LIKERS,
+			EResourceType.TWEET_RETWEETERS,
+			EResourceType.USER_FOLLOWERS,
+			EResourceType.USER_FOLLOWING,
+			EResourceType.USER_HIGHLIGHTS,
+			EResourceType.USER_LIKES,
+			EResourceType.USER_MEDIA,
+			EResourceType.USER_SUBSCRIPTIONS,
+		],
+	})
+	@Max(20, {
+		groups: [EResourceType.TWEET_SEARCH, EResourceType.USER_TIMELINE, EResourceType.USER_TIMELINE_AND_REPLIES],
+	})
+	public count?: number;
+
+	/**
+	 * The cursor to the batch of data to fetch.
+	 *
+	 * @remarks
+	 * - May be used for cursored resources.
+	 * - Has no effect for other resources.
+	 */
+	@IsOptional()
+	@IsString()
+	public cursor?: string;
+
+	/**
+	 * The filter for searching tweets.
+	 *
+	 * @remarks
+	 * Required when searching for tweets using {@link EResourceType.TWEET_SEARCH}.
+	 */
+	@IsOptional()
+	@IsNotEmpty({ groups: [EResourceType.TWEET_SEARCH] })
+	@IsObject({ groups: [EResourceType.TWEET_SEARCH] })
+	public filter?: TweetFilter;
+
+	/**
+	 * The id of the target resource.
+	 *
+	 * @remarks
+	 * - Required for all resources except {@link EResourceType.TWEET_SEARCH}.
+	 * - For {@link EResourceType.USER_DETAILS_BY_USERNAME}, can be alphanumeric, while for others, is strictly numeric.
+	 */
+	@IsOptional()
+	@IsNotEmpty({
+		groups: [
+			EResourceType.LIST_TWEETS,
+			EResourceType.TWEET_DETAILS,
+			EResourceType.TWEET_LIKERS,
+			EResourceType.TWEET_RETWEETERS,
+			EResourceType.USER_DETAILS_BY_USERNAME,
+			EResourceType.USER_DETAILS_BY_ID,
+			EResourceType.USER_FOLLOWERS,
+			EResourceType.USER_FOLLOWING,
+			EResourceType.USER_HIGHLIGHTS,
+			EResourceType.USER_LIKES,
+			EResourceType.USER_MEDIA,
+			EResourceType.USER_SUBSCRIPTIONS,
+			EResourceType.USER_TIMELINE,
+			EResourceType.USER_TIMELINE_AND_REPLIES,
+		],
+	})
+	@IsNumberString(undefined, {
+		groups: [
+			EResourceType.LIST_TWEETS,
+			EResourceType.TWEET_DETAILS,
+			EResourceType.TWEET_LIKERS,
+			EResourceType.TWEET_RETWEETERS,
+			EResourceType.USER_DETAILS_BY_ID,
+			EResourceType.USER_FOLLOWERS,
+			EResourceType.USER_FOLLOWING,
+			EResourceType.USER_HIGHLIGHTS,
+			EResourceType.USER_LIKES,
+			EResourceType.USER_MEDIA,
+			EResourceType.USER_SUBSCRIPTIONS,
+			EResourceType.USER_TIMELINE,
+			EResourceType.USER_TIMELINE_AND_REPLIES,
+		],
+	})
+	public id?: string;
+
+	/**
+	 * @param resource - The resource to be fetched.
+	 * @param args - Additional user-defined arguments for fetching the resource.
+	 */
+	public constructor(resource: EResourceType, args: FetchArgs) {
+		this.id = args.id;
+		this.count = args.count ?? 20;
+		this.cursor = args.cursor;
+		this.filter = args.filter ? new TweetFilter(args.filter) : undefined;
+
+		// Validating this object
+		const validationResult = validateSync(this, { groups: [resource] });
+
+		// If valiation error occured
+		if (validationResult.length) {
+			throw new DataValidationError(validationResult);
+		}
+	}
+}
+
+/**
+ * The filter to be used for searching tweets.
+ *
+ * @public
+ */
+export class TweetFilter extends TweetFilterCore {
+	/** The date upto which tweets are to be searched. */
+	@IsOptional()
+	@IsDate()
+	public endDate?: Date;
+
+	/** The list of words to exclude from search. */
+	@IsOptional()
+	@IsArray()
+	@IsString({ each: true })
+	public excludeWords?: string[];
+
+	/**
+	 * The list of usernames whose tweets are to be searched.
+	 *
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	@IsOptional()
+	@IsArray()
+	@IsString({ each: true })
+	public fromUsers?: string[];
+
+	/**
+	 * The list of hashtags to search.
+	 *
+	 * @remarks
+	 * '#' must be excluded from the hashtag!
+	 */
+	@IsOptional()
+	@IsArray()
+	@IsString({ each: true })
+	public hashtags?: string[];
+
+	/** The exact phrase to search. */
+	@IsOptional()
+	@IsString()
+	public includePhrase?: string;
+
+	/** The list of words to search. */
+	@IsOptional()
+	@IsArray()
+	@IsString({ each: true })
+	public includeWords?: string[];
+
+	/** The language of the tweets to search. */
+	@IsOptional()
+	@IsString()
+	public language?: string;
+
+	/**
+	 * Whether to fetch tweets that are links or not.
+	 *
+	 * @defaultValue true
+	 */
+	@IsOptional()
+	@IsBoolean()
+	public links?: boolean = true;
+
+	/** The id of the tweet, before which the tweets are to be searched. */
+	@IsOptional()
+	@IsNumberString()
+	public maxId?: string;
+
+	/**
+	 * The list of username mentioned in the tweets to search.
+	 *
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	@IsOptional()
+	@IsArray()
+	@IsString({ each: true })
+	public mentions?: string[];
+
+	/** The minimun number of likes to search by. */
+	@IsOptional()
+	@IsNumber()
+	public minLikes?: number;
+
+	/** The minimum number of replies to search by. */
+	@IsOptional()
+	@IsNumber()
+	public minReplies?: number;
+
+	/** The minimum number of retweets to search by. */
+	@IsOptional()
+	@IsNumber()
+	public minRetweets?: number;
+
+	/** The optional words to search. */
+	@IsOptional()
+	@IsArray()
+	@IsString({ each: true })
+	public optionalWords?: string[];
+
+	/** The id of the tweet which is quoted in the tweets to search. */
+	@IsOptional()
+	@IsNumberString()
+	public quoted?: string;
+
+	/**
+	 * Whether to fetch tweets that are replies or not.
+	 *
+	 * @defaultValue true
+	 */
+	@IsOptional()
+	@IsBoolean()
+	public replies?: boolean = true;
+
+	/** The id of the tweet, after which the tweets are to be searched. */
+	@IsOptional()
+	@IsNumberString()
+	public sinceId?: string;
+
+	/** The date starting from which tweets are to be searched. */
+	@IsOptional()
+	@IsDate()
+	public startDate?: Date;
+
+	/**
+	 * The list of username to whom the tweets to be searched, are adressed.
+	 *
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	@IsOptional()
+	@IsArray()
+	@IsString({ each: true })
+	public toUsers?: string[];
+
+	/**
+	 * @param filter - The filter to use for searching tweets.
+	 */
+	public constructor(filter: TweetFilter) {
+		super(filter);
+
+		// Validating this object
+		const validationResult = validateSync(this);
+
+		// If valiation error occured
+		if (validationResult.length) {
+			throw new DataValidationError(validationResult);
+		}
+	}
+}