rettiwt-api 2.4.1 → 2.5.0

package/src/services/internal/ErrorService.ts

@@ -0,0 +1,158 @@
+// PACKAGES
+import axios, { AxiosError, AxiosResponse } from 'axios';
+import { findKeyByValue } from '../../helper/JsonUtils';
+
+// TYPES
+import { IErrorHandler } from '../../types/ErrorHandler';
+
+// ENUMS
+import { EApiErrors } from '../../enums/Api';
+import { EHttpStatus } from '../../enums/Http';
+import { EErrorCodes } from 'rettiwt-core';
+
+// ERRORS
+import { ApiError } from '../../models/errors/ApiError';
+import { HttpError } from '../../models/errors/HttpError';
+import { TimeoutError } from '../../models/errors/TimeoutError';
+
+// TODO Refactor and document this module
+
+/**
+ * The base service that handles any errors.
+ *
+ * @public
+ */
+export class ErrorService implements IErrorHandler {
+	/**
+	 * Error message used when the specific error type is not defined in the required enums.
+	 */
+	protected static readonly DEFAULT_ERROR_MESSAGE = 'Unknown error';
+
+	/**
+	 * The method called when an error response is received from Twitter API.
+	 *
+	 * @param error - The error caught while making HTTP request to Twitter API.
+	 */
+	public handle(error: unknown): void {
+		if (!axios.isAxiosError(error)) {
+			throw error;
+		}
+
+		this.handleTimeoutError(error);
+
+		const axiosResponse = this.getAxiosResponse(error);
+		this.handleApiError(axiosResponse);
+		this.handleHttpError(axiosResponse);
+	}
+
+	/**
+	 * Handles exceeded timeout, configured in RettiwtConfig.
+	 *
+	 * @param error - The error object.
+	 * @throws An error if the configured request timeout has been exceeded.
+	 */
+	protected handleTimeoutError(error: AxiosError): void {
+		if (error.code === 'ECONNABORTED') {
+			throw new TimeoutError(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 {
+		if (error.response) {
+			return error.response;
+		}
+
+		throw error;
+	}
+
+	/**
+	 * Handles HTTP error in a response.
+	 *
+	 * @param response - The response object received.
+	 * @throws An error with the corresponding HTTP status text if any HTTP-related error has occurred.
+	 */
+	protected handleHttpError(response: AxiosResponse): void {
+		throw this.createHttpError(response.status);
+	}
+
+	/**
+	 * 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 {
+		const errorCode = this.getErrorCode(response);
+
+		if (errorCode === undefined) {
+			return;
+		}
+
+		throw this.createApiError(errorCode);
+	}
+
+	/**
+	 * 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));
+	}
+
+	/**
+	 * 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;
+	}
+
+	/**
+	 * Retrieves the API error code from the Axios response data.
+	 *
+	 * @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 errorCode - The error code.
+	 * @returns An API error instance.
+	 */
+	protected createApiError(errorCode: number): ApiError {
+		return new ApiError(errorCode, this.getApiErrorMessage(errorCode));
+	}
+
+	/**
+	 * Retrieves the API error message based on the provided error code.
+	 *
+	 * @param errorCode - The error code.
+	 * @returns The API 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;
+	}
+}

package/src/services/internal/FetcherService.ts

@@ -1,7 +1,8 @@
 // PACKAGES
 import {
 	Request,
-	Args,
+	FetchArgs,
+	PostArgs,
 	EResourceType,
 	ICursor as IRawCursor,
 	ITweet as IRawTweet,
@@ -9,29 +10,34 @@ import {
 	ITimelineTweet,
 	ITimelineUser,
 	IResponse,
-	EErrorCodes,
+	EUploadSteps,
+	IMediaUploadInitializeResponse,
 } from 'rettiwt-core';
-import axios, { AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse } from 'axios';
+import axios, { AxiosRequestConfig, AxiosResponse } from 'axios';
 import https, { Agent } from 'https';
 import { AuthCredential, Auth } from 'rettiwt-auth';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 
 // SERVICES
+import { ErrorService } from './ErrorService';
 import { LogService } from './LogService';
 
+// TYPES
+import { IRettiwtConfig } from '../../types/RettiwtConfig';
+import { IErrorHandler } from '../../types/ErrorHandler';
+
 // ENUMS
-import { EHttpStatus } from '../../enums/HTTP';
-import { EApiErrors } from '../../enums/ApiErrors';
+import { EApiErrors } from '../../enums/Api';
 import { ELogActions } from '../../enums/Logging';
 
 // MODELS
-import { RettiwtConfig } from '../../models/internal/RettiwtConfig';
-import { CursoredData } from '../../models/public/CursoredData';
-import { Tweet } from '../../models/public/Tweet';
-import { User } from '../../models/public/User';
+import { CursoredData } from '../../models/data/CursoredData';
+import { Tweet } from '../../models/data/Tweet';
+import { User } from '../../models/data/User';
 
 // HELPERS
-import { findByFilter, findKeyByValue } from '../../helper/JsonUtils';
+import { findByFilter } from '../../helper/JsonUtils';
+import { statSync } from 'fs';
 
 /**
  * The base service that handles all HTTP requests.
@@ -45,16 +51,25 @@ export class FetcherService {
 	/** Whether the instance is authenticated or not. */
 	private readonly isAuthenticated: boolean;
 
+	/** The URL to the proxy server to use for authentication. */
+	protected readonly authProxyUrl?: URL;
+
 	/** The HTTPS Agent to use for requests to Twitter API. */
 	private readonly httpsAgent: Agent;
 
+	/** The max wait time for a response. */
+	private readonly timeout: number;
+
 	/** The log service instance to use to logging. */
 	private readonly logger: LogService;
 
+	/** The service used to handle HTTP and API errors */
+	private readonly errorHandler: IErrorHandler;
+
 	/**
 	 * @param config - The config object for configuring the Rettiwt instance.
 	 */
-	public constructor(config?: RettiwtConfig) {
+	public constructor(config?: IRettiwtConfig) {
 		// If API key is supplied
 		if (config?.apiKey) {
 			this.cred = this.getAuthCredential(config.apiKey);
@@ -68,8 +83,11 @@ export class FetcherService {
 			this.cred = undefined;
 		}
 		this.isAuthenticated = config?.apiKey ? true : false;
+		this.authProxyUrl = config?.authProxyUrl ?? config?.proxyUrl;
 		this.httpsAgent = this.getHttpsAgent(config?.proxyUrl);
+		this.timeout = config?.timeout ?? 0;
 		this.logger = new LogService(config?.logging);
+		this.errorHandler = config?.errorHandler ?? new ErrorService();
 	}
 
 	/**
@@ -92,9 +110,6 @@ export class FetcherService {
 	 * @returns The generated AuthCredential.
 	 */
 	private getGuestCredential(guestKey: string): AuthCredential {
-		// Converting guestKey from base64 to string
-		guestKey = Buffer.from(guestKey).toString('ascii');
-
 		return new AuthCredential(undefined, guestKey);
 	}
 
@@ -133,79 +148,33 @@ export class FetcherService {
 		return new https.Agent();
 	}
 
-	/**
-	 * The middleware for handling any http error.
-	 *
-	 * @param res - The response object received.
-	 * @returns The received response, if no HTTP errors are found.
-	 * @throws An error if any HTTP-related error has occured.
-	 */
-	private handleHttpError(res: AxiosResponse<IResponse<unknown>>): AxiosResponse<IResponse<unknown>> {
-		/**
-		 * If the status code is not 200 =\> the HTTP request was not successful. hence throwing error
-		 */
-		if (res.status != 200 && res.status in EHttpStatus) {
-			throw new Error(EHttpStatus[res.status]);
-		}
-
-		return res;
-	}
-
-	/**
-	 * The middleware for handling any Twitter API-level errors.
-	 *
-	 * @param res - The response object received.
-	 * @returns The received response, if no API errors are found.
-	 * @throws An error if any API-related error has occured.
-	 */
-	private handleApiError(res: AxiosResponse<IResponse<unknown>>): AxiosResponse<IResponse<unknown>> {
-		// If error exists
-		if (res.data.errors && res.data.errors.length) {
-			// Getting the error code
-			const code: number = res.data.errors[0].code;
-
-			// Getting the error message
-			const message: string = EApiErrors[
-				findKeyByValue(EErrorCodes, `${code}`) as keyof typeof EApiErrors
-			] as string;
-
-			// Throw the error
-			throw new Error(message);
-		}
-
-		return res;
-	}
-
 	/**
 	 * Makes an HTTP request according to the given parameters.
 	 *
+	 * @typeParam ResType - The type of the returned response data.
 	 * @param config - The request configuration.
 	 * @returns The response received.
 	 */
-	private async request(config: Request): Promise<AxiosResponse<IResponse<unknown>>> {
+	private async request<ResType>(config: AxiosRequestConfig): Promise<AxiosResponse<ResType>> {
 		// Checking authorization for the requested resource
-		this.checkAuthorization(config.endpoint);
+		this.checkAuthorization(config.url as EResourceType);
 
 		// If not authenticated, use guest authentication
-		this.cred = this.cred ?? (await new Auth().getGuestCredential());
+		this.cred = this.cred ?? (await new Auth({ proxyUrl: this.authProxyUrl }).getGuestCredential());
 
-		/**
-		 * Creating axios request configuration from the input configuration.
-		 */
-		const axiosRequest: AxiosRequestConfig = {
-			url: config.url,
-			method: config.type,
-			data: config.payload,
-			headers: JSON.parse(JSON.stringify(this.cred.toHeader())) as AxiosRequestHeaders,
-			httpsAgent: this.httpsAgent,
-		};
+		// Setting additional request parameters
+		config.headers = { ...config.headers, ...this.cred.toHeader() };
+		config.httpAgent = this.httpsAgent;
+		config.timeout = this.timeout;
 
 		/**
-		 * After making the request, the response is then passed to HTTP error handling middleware for HTTP error handling.
+		 * If Axios request results in an error, catch it and rethrow a more specific error.
 		 */
-		return await axios<IResponse<unknown>>(axiosRequest)
-			.then((res) => this.handleHttpError(res))
-			.then((res) => this.handleApiError(res));
+		return await axios<ResType>(config).catch((error: unknown) => {
+			this.errorHandler.handle(error);
+
+			throw error;
+		});
 	}
 
 	/**
@@ -308,16 +277,16 @@ export class FetcherService {
 	 */
 	protected async fetch<OutType extends Tweet | User>(
 		resourceType: EResourceType,
-		args: Args,
+		args: FetchArgs,
 	): Promise<CursoredData<OutType>> {
 		// Logging
 		this.logger.log(ELogActions.FETCH, { resourceType: resourceType, args: args });
 
 		// Preparing the HTTP request
-		const request: Request = new Request(resourceType, args);
+		const request: AxiosRequestConfig = new Request(resourceType, args).toAxiosRequestConfig();
 
 		// Getting the raw data
-		const res = await this.request(request).then((res) => res.data);
+		const res = await this.request<IResponse<unknown>>(request).then((res) => res.data);
 
 		// Extracting data
 		const extractedData = this.extractData(res, resourceType);
@@ -335,16 +304,61 @@ export class FetcherService {
 	 * @param args - Resource specific arguments.
 	 * @returns Whether posting was successful or not.
 	 */
-	protected async post(resourceType: EResourceType, args: Args): Promise<boolean> {
+	protected async post(resourceType: EResourceType, args: PostArgs): Promise<boolean> {
 		// Logging
 		this.logger.log(ELogActions.POST, { resourceType: resourceType, args: args });
 
 		// Preparing the HTTP request
-		const request: Request = new Request(resourceType, args);
+		const request: AxiosRequestConfig = new Request(resourceType, args).toAxiosRequestConfig();
 
 		// Posting the data
-		await this.request(request);
+		await this.request<unknown>(request);
 
 		return true;
 	}
+
+	/**
+	 * Uploads the given media file to Twitter
+	 *
+	 * @param media - The path to the media file to upload.
+	 * @returns The id of the uploaded media.
+	 */
+	protected async upload(media: string): Promise<string> {
+		// INITIALIZE
+
+		// Logging
+		this.logger.log(ELogActions.UPLOAD, { step: EUploadSteps.INITIALIZE });
+
+		const id: string = (
+			await this.request<IMediaUploadInitializeResponse>(
+				new Request(EResourceType.MEDIA_UPLOAD, {
+					upload: { step: EUploadSteps.INITIALIZE, size: statSync(media).size },
+				}).toAxiosRequestConfig(),
+			)
+		).data.media_id_string;
+
+		// APPEND
+
+		// Logging
+		this.logger.log(ELogActions.UPLOAD, { step: EUploadSteps.APPEND });
+
+		await this.request<unknown>(
+			new Request(EResourceType.MEDIA_UPLOAD, {
+				upload: { step: EUploadSteps.APPEND, id: id, media: media },
+			}).toAxiosRequestConfig(),
+		);
+
+		// FINALIZE
+
+		// Logging
+		this.logger.log(ELogActions.UPLOAD, { step: EUploadSteps.APPEND });
+
+		await this.request<unknown>(
+			new Request(EResourceType.MEDIA_UPLOAD, {
+				upload: { step: EUploadSteps.FINALIZE, id: id },
+			}).toAxiosRequestConfig(),
+		);
+
+		return id;
+	}
 }

package/src/services/public/AuthService.ts

@@ -0,0 +1,97 @@
+// PACKAGES
+import { Auth } from 'rettiwt-auth';
+
+// SERVICES
+import { FetcherService } from '../internal/FetcherService';
+
+// TYPES
+import { IRettiwtConfig } from '../../types/RettiwtConfig';
+
+/**
+ * Handles authentication.
+ *
+ * @public
+ */
+export class AuthService extends FetcherService {
+	/**
+	 * @param config - The config object for configuring the Rettiwt instance.
+	 *
+	 * @internal
+	 */
+	public constructor(config?: IRettiwtConfig) {
+		super(config);
+	}
+
+	/**
+	 * 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.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance
+	 * const rettiwt = new Rettiwt();
+	 *
+	 * // Logging in an getting the API_KEY
+	 * rettiwt.auth.login("email@domain.com", "username", "password")
+	 * .then(apiKey => {
+	 * 	// Use the API_KEY
+	 * 	...
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async login(email: string, userName: string, password: string): Promise<string> {
+		// Logging in and getting the credentials
+		let apiKey: string =
+			((
+				await new Auth({ proxyUrl: this.authProxyUrl }).getUserCredential({
+					email: email,
+					userName: userName,
+					password: password,
+				})
+			).toHeader().cookie as string) ?? '';
+
+		// Converting the credentials to base64 string
+		apiKey = Buffer.from(apiKey).toString('base64');
+
+		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;
+	}
+}

package/src/services/public/TweetService.ts

@@ -1,14 +1,17 @@
 // PACKAGES
-import { EResourceType, TweetFilter } from 'rettiwt-core';
+import { EResourceType, MediaArgs, TweetFilter } from 'rettiwt-core';
 
 // SERVICES
 import { FetcherService } from '../internal/FetcherService';
 
+// TYPES
+import { IRettiwtConfig } from '../../types/RettiwtConfig';
+
 // MODELS
-import { RettiwtConfig } from '../../models/internal/RettiwtConfig';
-import { Tweet } from '../../models/public/Tweet';
-import { User } from '../../models/public/User';
-import { CursoredData } from '../../models/public/CursoredData';
+import { Tweet } from '../../models/data/Tweet';
+import { User } from '../../models/data/User';
+import { CursoredData } from '../../models/data/CursoredData';
+import { ITweetMediaArgs } from '../../types/args/TweetMediaArgs';
 
 /**
  * Handles fetching of data related to tweets.
@@ -21,7 +24,7 @@ export class TweetService extends FetcherService {
 	 *
 	 * @internal
 	 */
-	public constructor(config?: RettiwtConfig) {
+	public constructor(config?: IRettiwtConfig) {
 		super(config);
 	}
 
@@ -220,10 +223,11 @@ export class TweetService extends FetcherService {
 	/**
 	 * Post a tweet.
 	 *
-	 * @param tweetText - The text to be posted, length must be \<= 280 characters.
+	 * @param text - The text to be posted, length must be \<= 280 characters.
+	 * @param media - The list of media to post in the tweet.
 	 * @returns Whether posting was successful or not.
 	 *
-	 * @example
+	 * @example Posting a simple text
 	 * ```
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
@@ -240,11 +244,42 @@ export class TweetService extends FetcherService {
 	 * });
 	 * ```
 	 *
+	 * @example Posting a tweet with an image
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Posting a tweet, containing an image called 'mountains.jpg', to twitter
+	 * rettiwt.tweet.tweet('What a nice view!', [{ path: 'mountains.jpg' }])
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
-	public async tweet(tweetText: string): Promise<boolean> {
+	public async tweet(text: string, media?: ITweetMediaArgs[]): Promise<boolean> {
+		/** Stores the list of media that has been uploaded */
+		const uploadedMedia: MediaArgs[] = [];
+
+		// If tweet includes media, upload the media items
+		if (media) {
+			for (const item of media) {
+				// Uploading the media item and getting it's allocated id
+				const id: string = await this.upload(item.path);
+
+				// Storing the uploaded media item
+				uploadedMedia.push({ id: id, tags: item.tags });
+			}
+		}
+
 		// Posting the tweet
-		const data = await this.post(EResourceType.CREATE_TWEET, { tweetText: tweetText });
+		const data = await this.post(EResourceType.CREATE_TWEET, { tweet: { text: text, media: uploadedMedia } });
 
 		return data;
 	}

package/src/services/public/UserService.ts

@@ -4,13 +4,15 @@ import { EResourceType } from 'rettiwt-core';
 // SERVICES
 import { FetcherService } from '../internal/FetcherService';
 
+// TYPES
+import { IRettiwtConfig } from '../../types/RettiwtConfig';
+
 // MODELS
-import { RettiwtConfig } from '../../models/internal/RettiwtConfig';
-import { User } from '../../models/public/User';
-import { Tweet } from '../../models/public/Tweet';
+import { User } from '../../models/data/User';
+import { Tweet } from '../../models/data/Tweet';
 
 // TYPES
-import { CursoredData } from '../../models/public/CursoredData';
+import { CursoredData } from '../../models/data/CursoredData';
 
 /**
  * Handles fetching of data related to user account
@@ -23,7 +25,7 @@ export class UserService extends FetcherService {
 	 *
 	 * @internal
 	 */
-	public constructor(config?: RettiwtConfig) {
+	public constructor(config?: IRettiwtConfig) {
 		super(config);
 	}
 

package/src/types/ErrorHandler.ts

@@ -0,0 +1,13 @@
+/**
+ * Defines the error handler that processes API/HTTP errors in the responses.
+ *
+ * @public
+ */
+export interface IErrorHandler {
+	/**
+	 * The method called when an error response is received from Twitter API.
+	 *
+	 * @param error - The error caught while making request to Twitter API.
+	 */
+	handle(error: unknown): void;
+}