rettiwt-api 2.4.2 → 2.5.1

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);
+	}
+}

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;
+	}
 }