rettiwt-api 2.4.1 → 2.5.0

package/src/commands/Auth.ts

@@ -1,11 +1,11 @@
 // PACKAGES
 import { Command, createCommand } from 'commander';
-import { Auth } from 'rettiwt-auth';
+import { Rettiwt } from '../Rettiwt';
 
 // UTILITY
 import { output } from '../helper/CliUtils';
 
-function createAuthCommand(): Command {
+function createAuthCommand(rettiwt: Rettiwt): Command {
 	// Creating the 'auth' command
 	const auth = createCommand('auth').description('Manage authentication');
 
@@ -16,26 +16,15 @@ function createAuthCommand(): 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) => {
-			// Logging in and getting the credentials
-			let apiKey: string =
-				(
-					await new Auth().getUserCredential({ email: email, userName: username, password: password })
-				).toHeader().cookie ?? '';
-
-			// Converting the credentials to base64 string
-			apiKey = Buffer.from(apiKey).toString('base64');
+			const apiKey: string = await rettiwt.auth.login(email, username, password);
 			output(apiKey);
 		});
 
 	// Guest
 	auth.command('guest')
-		.description('Generate a new guest API key')
+		.description('Generate a new guest key')
 		.action(async () => {
-			// Getting a new guest API key
-			let guestKey: string = (await new Auth().getGuestCredential()).guestToken ?? '';
-
-			// Converting the credentials to base64 string
-			guestKey = Buffer.from(guestKey).toString('base64');
+			const guestKey: string = await rettiwt.auth.guest();
 			output(guestKey);
 		});
 

package/src/commands/Tweet.ts

@@ -35,7 +35,26 @@ function createTweetCommand(rettiwt: Rettiwt): Command {
 		.option('-f, --from <string>', "Matches the tweets made by list of given users, separated by ';'")
 		.option('-t, --to <string>', "Matches the tweets made to the list of given users, separated by ';'")
 		.option('-w, --words <string>', "Matches the tweets containing the given list of words, separated by ';'")
+		.option('-p, --phrase <string>', 'Matches the tweets containing the exact phrase')
+		.option(
+			'--optional-words <string>',
+			"Matches the tweets containing any of the given list of words, separated by ';'",
+		)
+		.option(
+			'--exclude-words <string>',
+			"Matches the tweets that do not contain any of the give list of words, separated by ';'",
+		)
 		.option('-h, --hashtags <string>', "Matches the tweets containing the given list of hashtags, separated by ';'")
+		.option(
+			'-m, --mentions <string>',
+			"Matches the tweets that mention the give list of usernames, separated by ';'",
+		)
+		.option('-r, --min-replies <number>', 'Matches the tweets that have a minimum of given number of replies')
+		.option('-l, --min-likes <number>', 'Matches the tweets that have a minimum of given number of likes')
+		.option('-x, --min-retweets <number>', 'Matches the tweets that have a minimum of given number of retweets')
+		.option('-q, --quoted <string>', 'Matches the tweets that quote the tweet with the given id')
+		.option('--exclude-links', 'Matches tweets that do not contain links')
+		.option('--exclude-replies', 'Matches the tweets that are not replies')
 		.option('-s, --start <string>', 'Matches the tweets made since the given date (valid date string)')
 		.option('-e, --end <string>', 'Matches the tweets made upto the given date (valid date string)')
 		.action(async (count?: string, cursor?: string, options?: TweetSearchOptions) => {
@@ -88,8 +107,12 @@ function createTweetCommand(rettiwt: Rettiwt): Command {
 		.command('post')
 		.description('Post a tweet (text only)')
 		.argument('<text>', 'The text to post as a tweet')
-		.action(async (text: string) => {
-			const result = await rettiwt.tweet.tweet(text);
+		.option('-m, --media [string]', "The path to the media item(s) to be posted, separated by ';'")
+		.action(async (text: string, options?: { media?: string }) => {
+			const result = await rettiwt.tweet.tweet(
+				text,
+				options?.media ? options?.media.split(';').map((item) => ({ path: item })) : undefined,
+			);
 			output(result);
 		});
 
@@ -125,7 +148,17 @@ class TweetSearchOptions {
 	public from?: string;
 	public to?: string;
 	public words?: string;
+	public phrase?: string;
+	public optionalWords?: string;
+	public excludeWords?: string;
 	public hashtags?: string;
+	public mentions?: string;
+	public minReplies?: number;
+	public minLikes?: number;
+	public minRetweets?: number;
+	public quoted?: string;
+	public excludeLinks?: boolean = false;
+	public excludeReplies?: boolean = false;
 	public start?: string;
 	public end?: string;
 
@@ -138,7 +171,17 @@ class TweetSearchOptions {
 		this.from = options?.from;
 		this.to = options?.to;
 		this.words = options?.words;
+		this.phrase = options?.phrase;
+		this.optionalWords = options?.optionalWords;
+		this.excludeWords = options?.excludeWords;
 		this.hashtags = options?.hashtags;
+		this.mentions = options?.mentions;
+		this.minReplies = options?.minReplies;
+		this.minLikes = options?.minLikes;
+		this.minRetweets = options?.minRetweets;
+		this.quoted = options?.quoted;
+		this.excludeLinks = options?.excludeLinks;
+		this.excludeReplies = options?.excludeReplies;
 		this.start = options?.start;
 		this.end = options?.end;
 	}
@@ -152,8 +195,18 @@ class TweetSearchOptions {
 		return new TweetFilter({
 			fromUsers: this.from ? this.from.split(';') : undefined,
 			toUsers: this.to ? this.to.split(';') : undefined,
-			words: this.words ? this.words.split(';') : undefined,
+			includeWords: this.words ? this.words.split(';') : undefined,
+			includePhrase: this.phrase,
+			optionalWords: this.optionalWords ? this.optionalWords.split(';') : undefined,
+			excludeWords: this.excludeWords ? this.excludeWords.split(';') : undefined,
 			hashtags: this.hashtags ? this.hashtags.split(';') : undefined,
+			mentions: this.mentions ? this.mentions.split(';') : undefined,
+			minReplies: this.minReplies,
+			minLikes: this.minLikes,
+			minRetweets: this.minRetweets,
+			quoted: this.quoted,
+			links: !this.excludeLinks,
+			replies: !this.excludeReplies,
 			startDate: this.start ? new Date(this.start) : undefined,
 			endDate: this.end ? new Date(this.end) : undefined,
 		});

package/src/enums/Http.ts

@@ -0,0 +1,68 @@
+/**
+ * The different types of http status codes
+ *
+ * @internal
+ */
+export enum EHttpStatus {
+	CONTINUE = 100,
+	SWITCHING_PROTOCOLS = 101,
+	PROCESSING = 102,
+	OK = 200,
+	CREATED = 201,
+	ACCEPTED = 202,
+	NON_AUTHORITATIVE_INFORMATION = 203,
+	NO_CONTENT = 204,
+	RESET_CONTENT = 205,
+	PARTIAL_CONTENT = 206,
+	MULTI_STATUS = 207,
+	ALREADY_REPORTED = 208,
+	IM_USED = 226,
+	MULTIPLE_CHOICES = 300,
+	MOVED_PERMANENTLY = 301,
+	FOUND = 302,
+	SEE_OTHER = 303,
+	NOT_MODIFIED = 304,
+	USE_PROXY = 305,
+	SWITCH_PROXY = 306,
+	TEMPORARY_REDIRECT = 307,
+	PERMANENT_REDIRECT = 308,
+	BAD_REQUEST = 400,
+	UNAUTHORIZED = 401,
+	PAYMENT_REQUIRED = 402,
+	FORBIDDEN = 403,
+	NOT_FOUND = 404,
+	METHOD_NOT_ALLOWED = 405,
+	NOT_ACCEPTABLE = 406,
+	PROXY_AUTHENTICATION_REQUIRED = 407,
+	REQUEST_TIMEOUT = 408,
+	CONFLICT = 409,
+	GONE = 410,
+	LENGTH_REQUIRED = 411,
+	PRECONDITION_FAILED = 412,
+	PAYLOAD_TOO_LARGE = 413,
+	URI_TOO_LONG = 414,
+	UNSUPPORTED_MEDIA_TYPE = 415,
+	RANGE_NOT_SATISFIABLE = 416,
+	EXPECTATION_FAILED = 417,
+	I_AM_A_TEAPOT = 418,
+	MISDIRECTED_REQUEST = 421,
+	UNPROCESSABLE_ENTITY = 422,
+	LOCKED = 423,
+	FAILED_DEPENDENCY = 424,
+	UPGRADE_REQUIRED = 426,
+	PRECONDITION_REQUIRED = 428,
+	TOO_MANY_REQUESTS = 429,
+	REQUEST_HEADER_FIELDS_TOO_LARGE = 431,
+	UNAVAILABLE_FOR_LEGAL_REASONS = 451,
+	INTERNAL_SERVER_ERROR = 500,
+	NOT_IMPLEMENTED = 501,
+	BAD_GATEWAY = 502,
+	SERVICE_UNAVAILABLE = 503,
+	GATEWAY_TIMEOUT = 504,
+	HTTP_VERSION_NOT_SUPPORTED = 505,
+	VARIANT_ALSO_NEGOTIATES = 506,
+	INSUFFICIENT_STORAGE = 507,
+	LOOP_DETECTED = 508,
+	NOT_EXTENDED = 510,
+	NETWORK_AUTHENTICATION_REQUIRED = 511,
+}

package/src/enums/Logging.ts

@@ -6,6 +6,7 @@
 export enum ELogActions {
 	FETCH = 'FETCH',
 	POST = 'POST',
+	UPLOAD = 'UPLOAD',
 	EXTRACT = 'EXTRACT',
 	DESERIALIZE = 'DESERIALIZE',
 	AUTHORIZATION = 'AUTHORIZATION',

package/src/index.ts

@@ -1,29 +1,34 @@
 // MAIN
 export * from './Rettiwt';
 
-// Exporting enums
-export * from './enums/ApiErrors';
-export * from './enums/HTTP';
+// EXTERNAL
+export { TweetFilter } from 'rettiwt-core';
+
+// ENUMS
+export * from './enums/Api';
+export * from './enums/Http';
 export * from './enums/Logging';
 
-// Exporting models
-export * from './models/internal/RettiwtConfig';
-export * from './models/public/CursoredData';
-export * from './models/public/List';
-export * from './models/public/Tweet';
-export * from './models/public/User';
-export { TweetFilter } from 'rettiwt-core';
+// ERROR MODELS
+export * from './models/errors/ApiError';
+export * from './models/errors/HttpError';
+export * from './models/errors/RettiwtError';
+
+// DATA MODELS
+export * from './models/data/CursoredData';
+export * from './models/data/List';
+export * from './models/data/Tweet';
+export * from './models/data/User';
 
-// Exporting services
+// 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/TweetService';
 export * from './services/public/UserService';
 
-// Exporting types
-export * from './types/internal/RettiwtConfig';
-export * from './types/public/CursoredData';
-export * from './types/public/List';
-export * from './types/public/Tweet';
-export * from './types/public/User';
-export { ITweetFilter } from 'rettiwt-core';
+// TYPES
+export * from './types/args/TweetMediaArgs';
+export * from './types/RettiwtConfig';
+export * from './types/ErrorHandler';

package/src/models/{public → data}/CursoredData.ts

@@ -2,9 +2,6 @@
 import { Tweet } from './Tweet';
 import { User } from './User';
 
-// TYPES
-import { ICursor, ICursoredData } from '../../types/public/CursoredData';
-
 /**
  * The data that us fetched batch-wise along with a cursor.
  *
@@ -12,8 +9,11 @@ import { ICursor, ICursoredData } from '../../types/public/CursoredData';
  *
  * @public
  */
-export class CursoredData<T extends Tweet | User> implements ICursoredData<T> {
+export class CursoredData<T extends Tweet | User> {
+	/** The list of data of the given type. */
 	public list: T[] = [];
+
+	/** The cursor to the next batch of data. */
 	public next: Cursor;
 
 	/**
@@ -31,7 +31,8 @@ export class CursoredData<T extends Tweet | User> implements ICursoredData<T> {
  *
  * @public
  */
-export class Cursor implements ICursor {
+export class Cursor {
+	/** The cursor string. */
 	public value: string;
 
 	/**

package/src/models/{public → data}/List.ts

@@ -1,21 +1,31 @@
 // PACKAGES
 import { IList as IRawList } from 'rettiwt-core';
 
-// TYPES
-import { IList } from '../../types/public/List';
-
 /**
  * The details of a single Twitter List.
  *
  * @public
  */
-export class List implements IList {
+export class List {
+	/** The rest id of the list. */
 	public id: string;
+
+	/** The name of the list. */
 	public name: string;
+
+	/** The date and time of creation of the list, int UTC string format. */
 	public createdAt: string;
+
+	/** The list description. */
 	public description: string;
+
+	/** The number of memeber of the list. */
 	public memberCount: number;
+
+	/** The number of subscribers of the list. */
 	public subscriberCount: number;
+
+	/** The rest id of the user who created the list. */
 	public createdBy: string;
 
 	/**

package/src/models/data/Media.ts

@@ -0,0 +1,19 @@
+// PACKAGES
+import { IMediaUploadInitializeResponse } from 'rettiwt-core';
+
+/**
+ * The details of a single media file.
+ *
+ * @public
+ */
+export class Media {
+	/** The id of the media. */
+	public id: string;
+
+	/**
+	 * @param media - The raw media data.
+	 */
+	public constructor(media: IMediaUploadInitializeResponse) {
+		this.id = media.media_id_string;
+	}
+}

package/src/models/{public → data}/Tweet.ts

@@ -6,9 +6,6 @@ import {
 	EMediaType,
 } from 'rettiwt-core';
 
-// TYPES
-import { ITweet, ITweetEntities } from '../../types/public/Tweet';
-
 // MODELS
 import { User } from './User';
 
@@ -20,21 +17,50 @@ import { normalizeText } from '../../helper/JsonUtils';
  *
  * @public
  */
-export class Tweet implements ITweet {
+export class Tweet {
+	/** The rest id of the tweet. */
 	public id: string;
+
+	/** The details of the user who made the tweet. */
 	public tweetBy: User;
+
+	/** The date and time of creation of the tweet, in UTC string format. */
 	public createdAt: string;
+
+	/** Additional tweet entities like urls, mentions, etc. */
 	public entities: TweetEntities;
+
+	/** The urls of the media contents of the tweet (if any). */
 	public media: TweetMedia[];
+
+	/** The rest id of the tweet which is quoted in the tweet. */
 	public quoted: string;
+
+	/** The full text content of the tweet. */
 	public fullText: string;
+
+	/** The rest id of the user to which the tweet is a reply. */
 	public replyTo: string;
+
+	/** The language in which the tweet is written. */
 	public lang: string;
+
+	/** The number of quotes of the tweet. */
 	public quoteCount: number;
+
+	/** The number of replies to the tweet. */
 	public replyCount: number;
+
+	/** The number of retweets of the tweet. */
 	public retweetCount: number;
+
+	/** The number of likes of the tweet. */
 	public likeCount: number;
+
+	/** The number of views of a tweet. */
 	public viewCount: number;
+
+	/** The number of bookmarks of a tweet. */
 	public bookmarkCount: number;
 
 	/**
@@ -66,9 +92,14 @@ export class Tweet implements ITweet {
  *
  * @public
  */
-export class TweetEntities implements ITweetEntities {
+export class TweetEntities {
+	/** The list of hashtags mentioned in the tweet. */
 	public hashtags: string[] = [];
+
+	/** The list of urls mentioned in the tweet. */
 	public urls: string[] = [];
+
+	/** The list of IDs of users mentioned in the tweet. */
 	public mentionedUsers: string[] = [];
 
 	/**
@@ -106,7 +137,10 @@ export class TweetEntities implements ITweetEntities {
  * @public
  */
 export class TweetMedia {
+	/** The type of media. */
 	public type: EMediaType;
+
+	/** The direct URL to the media. */
 	public url: string = '';
 
 	/**

package/src/models/{public → data}/User.ts

@@ -1,28 +1,52 @@
 // PACKAGES
 import { IUser as IRawUser } from 'rettiwt-core';
 
-// TYPES
-import { IUser } from '../../types/public/User';
-
 /**
  * The details of a single user.
  *
  * @public
  */
-export class User implements IUser {
+export class User {
+	/** The rest id of the user. */
 	public id: string;
+
+	/** The username/screenname of the user. */
 	public userName: string;
+
+	/** The full name of the user. */
 	public fullName: string;
+
+	/** The creation date of user's account. */
 	public createdAt: string;
+
+	/** The user's description. */
 	public description: string;
+
+	/** Whether the account is verified or not. */
 	public isVerified: boolean;
+
+	/** The number of tweets liked by the user. */
 	public favouritesCount: number;
+
+	/** The number of followers of the user. */
 	public followersCount: number;
+
+	/** The number of following of the user. */
 	public followingsCount: number;
+
+	/** The number of tweets made by the user. */
 	public statusesCount: number;
+
+	/** The location of user as provided by user. */
 	public location: string;
+
+	/** The rest id of the tweet pinned in the user's profile. */
 	public pinnedTweet: string;
+
+	/** The url of the profile banner image. */
 	public profileBanner: string;
+
+	/** The url of the profile image. */
 	public profileImage: string;
 
 	/**

package/src/models/errors/ApiError.ts

@@ -0,0 +1,24 @@
+// ERRORS
+import { RettiwtError } from './RettiwtError';
+
+/**
+ * Represents an error that is thrown by Twitter API.
+ *
+ * @internal
+ */
+export class ApiError extends RettiwtError {
+	/** The error code thrown by Twitter API. */
+	public code: number;
+
+	/**
+	 * Initializes a new ApiError based on the given error details.
+	 *
+	 * @param errorCode - The error code thrown by Twitter API.
+	 * @param message - Any additional error message.
+	 */
+	public constructor(errorCode: number, message?: string) {
+		super(message);
+
+		this.code = errorCode;
+	}
+}

package/src/models/errors/HttpError.ts

@@ -0,0 +1,24 @@
+// ERRORS
+import { RettiwtError } from './RettiwtError';
+
+/**
+ * Represents an HTTP error that occues while making a request to Twitter API.
+ *
+ * @internal
+ */
+export class HttpError extends RettiwtError {
+	/** The HTTP status code. */
+	public status: number;
+
+	/**
+	 * Initializes a new HttpError based on the given error details.
+	 *
+	 * @param httpStatus - The HTTP status code received upon making the request
+	 * @param message - Any additional error message.
+	 */
+	public constructor(httpStatus: number, message?: string) {
+		super(message);
+
+		this.status = httpStatus;
+	}
+}

package/src/models/errors/RettiwtError.ts

@@ -0,0 +1,12 @@
+/**
+ * Represents an error that arises inside the package.
+ *
+ * @internal
+ */
+export class RettiwtError extends Error {
+	public constructor(message?: string) {
+		super(message);
+
+		Object.setPrototypeOf(this, RettiwtError.prototype);
+	}
+}

package/src/models/errors/TimeoutError.ts

@@ -0,0 +1,18 @@
+// ERRORS
+import { RettiwtError } from './RettiwtError';
+
+/**
+ * Represents an HTTP error that occues while making a request to Twitter API.
+ *
+ * @internal
+ */
+export class TimeoutError extends RettiwtError {
+	/**
+	 * Initializes a new TimeoutError based on the given error details.
+	 *
+	 * @param message - Error message with the configured timeout.
+	 */
+	public constructor(message?: string) {
+		super(message);
+	}
+}