rettiwt-api 2.7.1 → 3.0.0

package/src/models/data/User.ts

@@ -1,5 +1,8 @@
-// PACKAGES
-import { IUser as IRawUser } from 'rettiwt-core';
+import { IUser as IRawUser, IResponse, ITimelineUser, IUser } from 'rettiwt-core';
+
+import { ELogActions } from '../../enums/Logging';
+import { findByFilter } from '../../helper/JsonUtils';
+import { LogService } from '../../services/internal/LogService';
 
 /**
  * The details of a single user.
@@ -7,26 +10,11 @@ import { IUser as IRawUser } from 'rettiwt-core';
  * @public
  */
 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;
+	public description?: string;
 
 	/** The number of followers of the user. */
 	public followersCount: number;
@@ -34,40 +22,119 @@ export class User {
 	/** The number of following of the user. */
 	public followingsCount: number;
 
-	/** The number of tweets made by the user. */
-	public statusesCount: number;
+	/** The full name of the user. */
+	public fullName: string;
+
+	/** The rest id of the user. */
+	public id: string;
+
+	/** Whether the account is verified or not. */
+	public isVerified: boolean;
+
+	/** The number of tweets liked by the user. */
+	public likeCount: number;
 
 	/** The location of user as provided by user. */
-	public location: string;
+	public location?: string;
 
 	/** The rest id of the tweet pinned in the user's profile. */
-	public pinnedTweet: string;
+	public pinnedTweet?: string;
 
 	/** The url of the profile banner image. */
-	public profileBanner: string;
+	public profileBanner?: string;
 
 	/** The url of the profile image. */
 	public profileImage: string;
 
+	/** The number of tweets made by the user. */
+	public statusesCount: number;
+
+	/** The username/screenname of the user. */
+	public userName: string;
+
 	/**
-	 * Initializes a new User from the given raw user data.
-	 *
-	 * @param user - The raw user data.
+	 * @param user - The raw user details.
 	 */
 	public constructor(user: IRawUser) {
 		this.id = user.rest_id;
 		this.userName = user.legacy.screen_name;
 		this.fullName = user.legacy.name;
 		this.createdAt = user.legacy.created_at;
-		this.description = user.legacy.description;
-		this.isVerified = user.legacy.verified;
-		this.favouritesCount = user.legacy.favourites_count;
+		this.description = user.legacy.description.length ? user.legacy.description : undefined;
+		this.isVerified = user.is_blue_verified;
+		this.likeCount = user.legacy.favourites_count;
 		this.followersCount = user.legacy.followers_count;
 		this.followingsCount = user.legacy.friends_count;
 		this.statusesCount = user.legacy.statuses_count;
-		this.location = user.legacy.location;
+		this.location = user.legacy.location.length ? user.legacy.location : undefined;
 		this.pinnedTweet = user.legacy.pinned_tweet_ids_str[0];
 		this.profileBanner = user.legacy.profile_banner_url;
 		this.profileImage = user.legacy.profile_image_url_https;
 	}
+
+	/**
+	 * Extracts and deserializes the list of users from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @returns The deserialized list of users.
+	 *
+	 * @internal
+	 */
+	public static list(response: IResponse<unknown>): User[] {
+		const users: User[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<ITimelineUser>(response, '__typename', 'TimelineUser');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.user_results?.result?.legacy) {
+				// Logging
+				LogService.log(ELogActions.DESERIALIZE, { id: item.user_results.result.rest_id });
+
+				users.push(new User(item.user_results.result));
+			} else {
+				// Logging
+				LogService.log(ELogActions.WARNING, {
+					action: ELogActions.DESERIALIZE,
+					message: `User not found, skipping`,
+				});
+			}
+		}
+
+		return users;
+	}
+
+	/**
+	 * Extracts and deserializes a single target user from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @returns The target deserialized user.
+	 *
+	 * @internal
+	 */
+	public static single(response: IResponse<unknown>): User | undefined {
+		const users: User[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<IUser>(response, '__typename', 'User');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.legacy) {
+				// Logging
+				LogService.log(ELogActions.DESERIALIZE, { id: item.rest_id });
+
+				users.push(new User(item));
+			} else {
+				// Logging
+				LogService.log(ELogActions.WARNING, {
+					action: ELogActions.DESERIALIZE,
+					message: `User not found, skipping`,
+				});
+			}
+		}
+
+		return users.length ? users[0] : undefined;
+	}
 }

package/src/models/errors/ApiError.ts

@@ -1,18 +1,15 @@
-// ERRORS
 import { RettiwtError } from './RettiwtError';
 
 /**
  * Represents an error that is thrown by Twitter API.
  *
- * @internal
+ * @public
  */
 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.
 	 */

package/src/models/errors/DataValidationError.ts

@@ -0,0 +1,44 @@
+import { ValidationError } from 'class-validator';
+
+/**
+ * Represents and error when any fields of a validation-enabled class fails to validate.
+ *
+ * @public
+ */
+export class DataValidationError {
+	/** The detaied error message(s). */
+	public details: ValidationErrorDetails[];
+
+	/** The user-friendly error message. */
+	public message: string;
+
+	/** The name of the error. */
+	public name: string;
+
+	/**
+	 * @param data - The error details, as a list of type {@link ValidationError}
+	 */
+	public constructor(errorDetails: ValidationError[]) {
+		this.name = 'VALIDATION_ERROR';
+		this.message = 'One or more validation error(s) occured, check details field.';
+		this.details = errorDetails.map((error) => new ValidationErrorDetails(error));
+	}
+}
+
+/**
+ * Represents the validation error details of a single field.
+ *
+ * @public
+ */
+export class ValidationErrorDetails {
+	/** The constraints which failed to be validated for the given field. */
+	public constraints: string[];
+
+	/** The name of the field which failed validation. */
+	public field: string;
+
+	public constructor(details: ValidationError) {
+		this.field = details.property;
+		this.constraints = Object.values(details.constraints!);
+	}
+}

package/src/models/errors/HttpError.ts

@@ -1,18 +1,15 @@
-// ERRORS
 import { RettiwtError } from './RettiwtError';
 
 /**
  * Represents an HTTP error that occues while making a request to Twitter API.
  *
- * @internal
+ * @public
  */
 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.
 	 */

package/src/models/errors/TimeoutError.ts

@@ -1,15 +1,12 @@
-// ERRORS
 import { RettiwtError } from './RettiwtError';
 
 /**
- * Represents an HTTP error that occues while making a request to Twitter API.
+ * Represents a timeout error that occues while making a request to Twitter API.
  *
- * @internal
+ * @public
  */
 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) {

package/src/services/internal/ErrorService.ts

@@ -1,21 +1,12 @@
-// PACKAGES
-import axios, { AxiosError, AxiosResponse } from 'axios';
-import { findKeyByValue } from '../../helper/JsonUtils';
-
-// TYPES
-import { IErrorHandler } from '../../types/ErrorHandler';
+import { AxiosError, AxiosResponse, isAxiosError } from 'axios';
 
-// ENUMS
-import { EApiErrors } from '../../enums/Api';
+import { EApiErrors, EErrorCodes } from '../../enums/Api';
 import { EHttpStatus } from '../../enums/Http';
-import { EErrorCodes } from 'rettiwt-core';
-
-// ERRORS
+import { findKeyByValue } from '../../helper/JsonUtils';
 import { ApiError } from '../../models/errors/ApiError';
 import { HttpError } from '../../models/errors/HttpError';
 import { TimeoutError } from '../../models/errors/TimeoutError';
-
-// TODO Refactor and document this module
+import { IErrorHandler } from '../../types/ErrorHandler';
 
 /**
  * The base service that handles any errors.
@@ -29,39 +20,49 @@ export class ErrorService implements IErrorHandler {
 	protected static readonly DEFAULT_ERROR_MESSAGE = 'Unknown error';
 
 	/**
-	 * The method called when an error response is received from Twitter API.
+	 * Creates an API error instance based on the provided error code.
 	 *
-	 * @param error - The error caught while making HTTP request to Twitter API.
+	 * @param errorCode - The error code.
+	 *
+	 * @returns An API error instance.
 	 */
-	public handle(error: unknown): void {
-		if (!axios.isAxiosError(error)) {
-			throw error;
-		}
-
-		this.handleTimeoutError(error);
+	protected createApiError(errorCode: number): ApiError {
+		return new ApiError(errorCode, this.getApiErrorMessage(errorCode));
+	}
 
-		const axiosResponse = this.getAxiosResponse(error);
-		this.handleApiError(axiosResponse);
-		this.handleHttpError(axiosResponse);
+	/**
+	 * Creates an HTTP error instance based on the provided HTTP status.
+	 *
+	 * @param httpStatus - The HTTP status code.
+	 *
+	 * @returns An HTTP error instance.
+	 */
+	protected createHttpError(httpStatus: number): HttpError {
+		return new HttpError(httpStatus, this.getHttpErrorMessage(httpStatus));
 	}
 
 	/**
-	 * Handles exceeded timeout, configured in RettiwtConfig.
+	 * Retrieves the API error message based on the provided error code.
 	 *
-	 * @param error - The error object.
-	 * @throws An error if the configured request timeout has been exceeded.
+	 * @param errorCode - The error code.
+	 *
+	 * @returns The API error message.
 	 */
-	protected handleTimeoutError(error: AxiosError): void {
-		if (error.code === 'ECONNABORTED') {
-			throw new TimeoutError(error.message);
-		}
+	protected getApiErrorMessage(errorCode: number): string {
+		const errorCodeKey = findKeyByValue(EErrorCodes, errorCode.toString());
+
+		return !!errorCodeKey && errorCodeKey in EApiErrors
+			? EApiErrors[errorCodeKey as keyof typeof EApiErrors]
+			: ErrorService.DEFAULT_ERROR_MESSAGE;
 	}
 
 	/**
 	 * Retrieves the response data from the given error.
 	 *
 	 * @param error - The error object.
+	 *
 	 * @returns The response data.
+	 *
 	 * @throws The original error if it is not an HTTP error with a response.
 	 */
 	protected getAxiosResponse(error: AxiosError): AxiosResponse {
@@ -73,19 +74,36 @@ export class ErrorService implements IErrorHandler {
 	}
 
 	/**
-	 * Handles HTTP error in a response.
+	 * Retrieves the API error code from the Axios response data.
 	 *
 	 * @param response - The response object received.
-	 * @throws An error with the corresponding HTTP status text if any HTTP-related error has occurred.
+	 *
+	 * @returns The error code, or undefined if not found.
 	 */
-	protected handleHttpError(response: AxiosResponse): void {
-		throw this.createHttpError(response.status);
+	protected getErrorCode(response: AxiosResponse): number | undefined {
+		const errors = (response.data as { errors: { code: number }[] }).errors;
+
+		return !!errors && errors.length ? errors[0].code : undefined;
+	}
+
+	/**
+	 * Retrieves the HTTP error message based on the provided HTTP status.
+	 *
+	 * @param httpStatus - The HTTP status code.
+	 *
+	 * @returns The HTTP error message.
+	 */
+	protected getHttpErrorMessage(httpStatus: number): string {
+		return Object.values(EHttpStatus).includes(httpStatus)
+			? EHttpStatus[httpStatus]
+			: ErrorService.DEFAULT_ERROR_MESSAGE;
 	}
 
 	/**
 	 * Handles API error in a response.
 	 *
 	 * @param response - The response object received.
+	 *
 	 * @throws An error with the corresponding API error message if any API-related error has occurred.
 	 */
 	protected handleApiError(response: AxiosResponse): void {
@@ -99,60 +117,43 @@ export class ErrorService implements IErrorHandler {
 	}
 
 	/**
-	 * Creates an HTTP error instance based on the provided HTTP status.
+	 * Handles HTTP error in a response.
 	 *
-	 * @param httpStatus - The HTTP status code.
-	 * @returns An HTTP error instance.
-	 */
-	protected createHttpError(httpStatus: number): HttpError {
-		return new HttpError(httpStatus, this.getHttpErrorMessage(httpStatus));
-	}
-
-	/**
-	 * Retrieves the HTTP error message based on the provided HTTP status.
+	 * @param response - The response object received.
 	 *
-	 * @param httpStatus - The HTTP status code.
-	 * @returns The HTTP error message.
+	 * @throws An error with the corresponding HTTP status text if any HTTP-related error has occurred.
 	 */
-	protected getHttpErrorMessage(httpStatus: number): string {
-		return Object.values(EHttpStatus).includes(httpStatus)
-			? EHttpStatus[httpStatus]
-			: ErrorService.DEFAULT_ERROR_MESSAGE;
+	protected handleHttpError(response: AxiosResponse): void {
+		throw this.createHttpError(response.status);
 	}
 
 	/**
-	 * Retrieves the API error code from the Axios response data.
+	 * Handles exceeded timeout, configured in RettiwtConfig.
 	 *
-	 * @param response - The response object received.
-	 * @returns The error code, or undefined if not found.
-	 */
-	protected getErrorCode(response: AxiosResponse): number | undefined {
-		const errors = (response.data as { errors: { code: number }[] }).errors;
-
-		return !!errors && errors.length ? errors[0].code : undefined;
-	}
-
-	/**
-	 * Creates an API error instance based on the provided error code.
+	 * @param error - The error object.
 	 *
-	 * @param errorCode - The error code.
-	 * @returns An API error instance.
+	 * @throws An error if the configured request timeout has been exceeded.
 	 */
-	protected createApiError(errorCode: number): ApiError {
-		return new ApiError(errorCode, this.getApiErrorMessage(errorCode));
+	protected handleTimeoutError(error: AxiosError): void {
+		if (error.code === 'ECONNABORTED') {
+			throw new TimeoutError(error.message);
+		}
 	}
 
 	/**
-	 * Retrieves the API error message based on the provided error code.
+	 * The method called when an error response is received from Twitter API.
 	 *
-	 * @param errorCode - The error code.
-	 * @returns The API error message.
+	 * @param error - The error caught while making HTTP request to Twitter API.
 	 */
-	protected getApiErrorMessage(errorCode: number): string {
-		const errorCodeKey = findKeyByValue(EErrorCodes, errorCode.toString());
+	public handle(error: unknown): void {
+		if (!isAxiosError(error)) {
+			throw error;
+		}
 
-		return !!errorCodeKey && errorCodeKey in EApiErrors
-			? EApiErrors[errorCodeKey as keyof typeof EApiErrors]
-			: ErrorService.DEFAULT_ERROR_MESSAGE;
+		this.handleTimeoutError(error);
+
+		const axiosResponse = this.getAxiosResponse(error);
+		this.handleApiError(axiosResponse);
+		this.handleHttpError(axiosResponse);
 	}
 }

package/src/services/internal/LogService.ts

@@ -1,4 +1,5 @@
-// ENUMS
+import chalk from 'chalk';
+
 import { ELogActions } from '../../enums/Logging';
 
 /**
@@ -8,29 +9,38 @@ import { ELogActions } from '../../enums/Logging';
  */
 export class LogService {
 	/** Whether logging is enabled or not. */
-	private readonly enabled: boolean;
+	public static enabled: boolean = false;
 
 	/**
-	 * Initializes a new LogService instance.
+	 * @param action - The action to be logged.
 	 *
-	 * @param enable - Whether to enable logging or not.
+	 * @returns - The colored text representing the action.
 	 */
-	public constructor(enable?: boolean) {
-		this.enabled = enable ?? false;
+	private static getColoredAction(action: ELogActions): string {
+		if (action == ELogActions.WARNING) {
+			return chalk.yellow(action);
+		} else {
+			return chalk.green(action);
+		}
 	}
 
 	/**
 	 * Logs the given data.
 	 *
+	 * @param action - The action to be logged.
+	 *
 	 * @param data - The data to be logged.
 	 */
-	public log(action: ELogActions, data: NonNullable<unknown>): void {
+	public static log(action: ELogActions, data: NonNullable<unknown>): void {
 		// Proceed to log only if logging is enabled
 		if (this.enabled) {
 			// Preparing the log message
-			const logMessage: string = `[Rettiwt-API] [${action}] [${new Date().toISOString()}] ${JSON.stringify(
-				data,
-			)}`;
+			const logPrefix: string = chalk.blue('Rettiwt-API');
+			const logTime: string = new Date().toISOString();
+			const logAction: string = LogService.getColoredAction(action);
+			const logData: string = JSON.stringify(data);
+
+			const logMessage: string = `[${logPrefix}] [${logTime}] [${logAction}] ${logData}`;
 
 			// Logging
 			console.log(logMessage);

package/src/services/public/AuthService.ts

@@ -1,20 +1,17 @@
-// PACKAGES
 import { Auth } from 'rettiwt-auth';
 
-// SERVICES
-import { FetcherService } from '../internal/FetcherService';
-
-// TYPES
 import { IRettiwtConfig } from '../../types/RettiwtConfig';
 
+import { FetcherService } from './FetcherService';
+
 /**
- * Handles authentication.
+ * The services that handles authentication.
  *
  * @public
  */
 export class AuthService extends FetcherService {
 	/**
-	 * @param config - The config object for configuring the Rettiwt instance.
+	 * @param config - The config object for configuring the `Rettiwt` instance.
 	 *
 	 * @internal
 	 */
@@ -22,13 +19,44 @@ export class AuthService extends FetcherService {
 		super(config);
 	}
 
+	/**
+	 * Login to twitter as guest.
+	 *
+	 * @returns A new guest key.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance
+	 * const rettiwt = new Rettiwt();
+	 *
+	 * // Logging in an getting a new guest key
+	 * rettiwt.auth.guest()
+	 * .then(guestKey => {
+	 * 	// Use the guest key
+	 * 	...
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async guest(): Promise<string> {
+		// Getting a new guest key
+		const guestKey: string = (await new Auth().getGuestCredential()).guestToken ?? '';
+
+		return guestKey;
+	}
+
 	/**
 	 * Login to twitter using account credentials.
 	 *
 	 * @param email - The email id associated with the Twitter account.
 	 * @param userName - The username associated with the Twitter account.
 	 * @param password - The password to the Twitter account.
-	 * @returns The API_KEY for the Twitter account.
+	 *
+	 * @returns The `API_KEY` for the Twitter account.
 	 *
 	 * @example
 	 * ```
@@ -47,6 +75,9 @@ export class AuthService extends FetcherService {
 	 * 	console.log(err);
 	 * });
 	 * ```
+	 *
+	 * @remarks
+	 * Interchanging `email` and `userName` works too.
 	 */
 	public async login(email: string, userName: string, password: string): Promise<string> {
 		// Logging in and getting the credentials
@@ -64,34 +95,4 @@ export class AuthService extends FetcherService {
 
 		return apiKey;
 	}
-
-	/**
-	 * Login to twitter as guest.
-	 *
-	 * @returns A new guest key.
-	 *
-	 * @example
-	 * ```
-	 * import { Rettiwt } from 'rettiwt-api';
-	 *
-	 * // Creating a new Rettiwt instance
-	 * const rettiwt = new Rettiwt();
-	 *
-	 * // Logging in an getting a new guest key
-	 * rettiwt.auth.guest()
-	 * .then(guestKey => {
-	 * 	// Use the guest key
-	 * 	...
-	 * })
-	 * .catch(err => {
-	 * 	console.log(err);
-	 * });
-	 * ```
-	 */
-	public async guest(): Promise<string> {
-		// Getting a new guest key
-		const guestKey: string = (await new Auth().getGuestCredential()).guestToken ?? '';
-
-		return guestKey;
-	}
 }