rettiwt-api 5.0.0-alpha.2 → 5.0.0-alpha.4

package/src/services/internal/AuthService.ts

@@ -1,9 +1,8 @@
-import { Agent } from 'https';
-
 import axios from 'axios';
 
 import { EApiErrors } from '../../enums/Api';
 import { AuthCredential } from '../../models/auth/AuthCredential';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
 
 /**
  * The services that handles authentication.
@@ -11,14 +10,14 @@ import { AuthCredential } from '../../models/auth/AuthCredential';
  * @public
  */
 export class AuthService {
-	/** The HTTPS Agent to use for requests to Twitter API. */
-	private readonly _httpsAgent: Agent;
+	/** The config object. */
+	private readonly _config: RettiwtConfig;
 
 	/**
-	 * @param httpsAgent - The HTTPS agent to use. If none is provided, default is used.
+	 * @param config - The config for Rettiwt.
 	 */
-	public constructor(httpsAgent?: Agent) {
-		this._httpsAgent = httpsAgent ?? new Agent();
+	public constructor(config: RettiwtConfig) {
+		this._config = config;
 	}
 
 	/**
@@ -107,7 +106,7 @@ export class AuthService {
 				/* eslint-enable @typescript-eslint/naming-convention */
 			}>('https://api.twitter.com/1.1/guest/activate.json', undefined, {
 				headers: cred.toHeader(),
-				httpsAgent: this._httpsAgent,
+				httpsAgent: this._config.httpsAgent,
 			})
 			.then((res) => {
 				cred.guestToken = res.data.guest_token;

package/src/services/internal/ErrorService.ts

@@ -1,12 +1,8 @@
-import { AxiosError, AxiosResponse, isAxiosError } from 'axios';
+import { AxiosError, isAxiosError } from 'axios';
 
-import { EApiErrors, EErrorCodes } from '../../enums/Api';
-import { EHttpStatus } from '../../enums/Http';
-import { findKeyByValue } from '../../helper/JsonUtils';
-import { ApiError } from '../../models/errors/ApiError';
-import { HttpError } from '../../models/errors/HttpError';
-import { TimeoutError } from '../../models/errors/TimeoutError';
+import { TwitterError } from '../../models/errors/TwitterError';
 import { IErrorHandler } from '../../types/ErrorHandler';
+import { IErrorData as IRawErrorData, IErrorDetails as IRawErrorDetails } from '../../types/raw/base/Error';
 
 /**
  * The base service that handles any errors.
@@ -15,129 +11,19 @@ import { IErrorHandler } from '../../types/ErrorHandler';
  */
 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';
-
-	/**
-	 * 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));
-	}
-
-	/**
-	 * 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 API error message based on the provided error code.
+	 * Handles errors thrown by Twitter.
 	 *
-	 * @param errorCode - The error code.
-	 *
-	 * @returns The API error message.
+	 * @param error - The error response received from Twitter.
 	 */
-	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;
+	private handleAxiosError(error: AxiosError<IRawErrorData | IRawErrorDetails>): void {
+		throw new TwitterError(error);
 	}
 
 	/**
-	 * 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.
+	 * Handle unknown error.
 	 */
-	protected getAxiosResponse(error: AxiosError): AxiosResponse {
-		if (error.response) {
-			return error.response;
-		}
-
-		throw error;
-	}
-
-	/**
-	 * 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;
-	}
-
-	/**
-	 * 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 {
-		const errorCode = this.getErrorCode(response);
-
-		if (errorCode === undefined) {
-			return;
-		}
-
-		throw this.createApiError(errorCode);
-	}
-
-	/**
-	 * 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 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);
-		}
+	private handleUnknownError(): void {
+		throw new Error('Unknown error');
 	}
 
 	/**
@@ -146,14 +32,10 @@ export class ErrorService implements IErrorHandler {
 	 * @param error - The error caught while making HTTP request to Twitter API.
 	 */
 	public handle(error: unknown): void {
-		if (!isAxiosError(error)) {
-			throw error;
+		if (isAxiosError(error)) {
+			this.handleAxiosError(error as AxiosError<IRawErrorData | IRawErrorDetails>);
+		} else {
+			this.handleUnknownError();
 		}
-
-		this.handleTimeoutError(error);
-
-		const axiosResponse = this.getAxiosResponse(error);
-		this.handleApiError(axiosResponse);
-		this.handleHttpError(axiosResponse);
 	}
 }

package/src/services/internal/TidService.ts

@@ -1,5 +1,3 @@
-import { Agent } from 'http';
-
 import axios from 'axios';
 import * as htmlParser from 'node-html-parser';
 
@@ -7,6 +5,7 @@ import { ELogActions } from '../../enums/Logging';
 
 import { calculateClientTransactionIdHeader } from '../../helper/TidUtils';
 
+import { RettiwtConfig } from '../../models/RettiwtConfig';
 import { ITidDynamicArgs } from '../../types/auth/TidDynamicArgs';
 import { ITidProvider } from '../../types/auth/TidProvider';
 
@@ -19,16 +18,16 @@ import { LogService } from './LogService';
  */
 export class TidService implements ITidProvider {
 	private readonly _cdnUrl: string;
-	private readonly _httpsAgent: Agent;
+	private readonly _config: RettiwtConfig;
 	private readonly _requestHeaders: NonNullable<unknown>;
 	private _dynamicArgs?: ITidDynamicArgs;
 
 	/**
-	 * @param httpsAgent - The HTTPS agent to use. If none is provided, default is used.
+	 * @param config - The config for Rettiwt.
 	 */
-	public constructor(httpsAgent?: Agent) {
+	public constructor(config: RettiwtConfig) {
 		this._cdnUrl = 'https://abs.twimg.com/responsive-web/client-web';
-		this._httpsAgent = httpsAgent ?? new Agent();
+		this._config = config;
 		this._requestHeaders = {
 			/* eslint-disable @typescript-eslint/naming-convention */
 
@@ -71,8 +70,8 @@ export class TidService implements ITidProvider {
 	private async getHomepageHtml(): Promise<string> {
 		const response = await axios.get<string>('https://x.com', {
 			headers: this._requestHeaders,
-			httpAgent: this._httpsAgent,
-			httpsAgent: this._httpsAgent,
+			httpAgent: this._config.httpsAgent,
+			httpsAgent: this._config.httpsAgent,
 		});
 
 		return response.data;
@@ -88,8 +87,8 @@ export class TidService implements ITidProvider {
 
 		const onDemandFileHash = ondemandFileMatch ? ondemandFileMatch[1] : '';
 		const response = await axios.get<string>(`${this._cdnUrl}/ondemand.s.${onDemandFileHash}a.js`, {
-			httpAgent: this._httpsAgent,
-			httpsAgent: this._httpsAgent,
+			httpAgent: this._config.httpsAgent,
+			httpsAgent: this._config.httpsAgent,
 		});
 		const match = response.data.matchAll(/(\(\w\[(\d{1,2})],\s*16\))+?/gm);
 

package/src/services/public/FetcherService.ts

@@ -53,9 +53,9 @@ export class FetcherService {
 		this.config = config;
 		this._delay = config.delay;
 		this._errorHandler = config.errorHandler ?? new ErrorService();
-		this._tidProvider = config.tidProvider ?? new TidService(config.httpsAgent);
+		this._tidProvider = config.tidProvider ?? new TidService(config);
 		this._timeout = config.timeout ?? 0;
-		this._auth = new AuthService(config.httpsAgent);
+		this._auth = new AuthService(config);
 	}
 
 	/**

package/src/services/public/TweetService.ts

@@ -11,8 +11,9 @@ import { ITweetFilter } from '../../types/args/FetchArgs';
 import { INewTweet } from '../../types/args/PostArgs';
 import { IListTweetsResponse } from '../../types/raw/list/Tweets';
 import { IMediaInitializeUploadResponse } from '../../types/raw/media/InitalizeUpload';
-import { ITweetDetailsResponse } from '../../types/raw/tweet/Details';
 
+import { ITweetDetailsResponse } from '../../types/raw/tweet/Details';
+import { ITweetDetailsBulkResponse } from '../../types/raw/tweet/DetailsBulk';
 import { ITweetLikeResponse } from '../../types/raw/tweet/Like';
 import { ITweetLikersResponse } from '../../types/raw/tweet/Likers';
 import { ITweetPostResponse } from '../../types/raw/tweet/Post';
@@ -89,7 +90,7 @@ export class TweetService extends FetcherService {
 			resource = EResourceType.TWEET_DETAILS_BULK;
 
 			// Fetching raw tweet details
-			const response = await this.request<ITweetRepliesResponse>(resource, { ids: id });
+			const response = await this.request<ITweetDetailsBulkResponse>(resource, { ids: id });
 
 			// Deserializing response
 			const data = extractors[resource](response, id);

package/src/services/public/UserService.ts

@@ -5,8 +5,10 @@ import { Notification } from '../../models/data/Notification';
 import { Tweet } from '../../models/data/Tweet';
 import { User } from '../../models/data/User';
 import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IUserAffiliatesResponse } from '../../types/raw/user/Affiliates';
 import { IUserBookmarksResponse } from '../../types/raw/user/Bookmarks';
 import { IUserDetailsResponse } from '../../types/raw/user/Details';
+import { IUserDetailsBulkResponse } from '../../types/raw/user/DetailsBulk';
 import { IUserFollowResponse } from '../../types/raw/user/Follow';
 import { IUserFollowedResponse } from '../../types/raw/user/Followed';
 import { IUserFollowersResponse } from '../../types/raw/user/Followers';
@@ -38,6 +40,48 @@ export class UserService extends FetcherService {
 		super(config);
 	}
 
+	/**
+	 * Get the list affiliates of a user.
+	 *
+	 * @param id - The id of the target user.
+	 * @param count - The number of affiliates to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of affiliates to fetch.
+	 *
+	 * @returns The list of users affiliated to the target user.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 100 affiliates of the User with id '1234567890'
+	 * rettiwt.user.affiliates('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async affiliates(id?: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		const resource = EResourceType.USER_AFFILIATES;
+
+		// Fetching raw list of affiliates
+		const response = await this.request<IUserAffiliatesResponse>(resource, {
+			id: id,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = extractors[resource](response);
+
+		return data;
+	}
+
 	/**
 	 * Get the list of bookmarks of the logged in user.
 	 *
@@ -81,7 +125,7 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the details of a user.
 	 *
-	 * @param id - The username/id(s) of the target user/users.
+	 * @param id - The username/id(s) of the target user/users. If no ID is provided, uses ID of authenticated user.
 	 *
 	 * @returns
 	 * The details of the given user.
@@ -123,7 +167,9 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async details<T extends string | string[]>(id: T): Promise<T extends string ? User | undefined : User[]> {
+	public async details<T extends string | string[] | undefined>(
+		id: T,
+	): Promise<T extends string | undefined ? User | undefined : User[]> {
 		let resource: EResourceType;
 
 		// If details of multiple users required
@@ -131,31 +177,36 @@ export class UserService extends FetcherService {
 			resource = EResourceType.USER_DETAILS_BY_IDS_BULK;
 
 			// Fetching raw details
-			const response = await this.request<IUserDetailsResponse>(resource, { ids: id });
+			const response = await this.request<IUserDetailsBulkResponse>(resource, { ids: id });
 
 			// Deserializing response
 			const data = extractors[resource](response, id);
 
-			return data as T extends string ? User | undefined : User[];
+			return data as T extends string | undefined ? User | undefined : User[];
 		}
 		// If details of single user required
 		else {
 			// If username is given
-			if (isNaN(Number(id))) {
+			if (id && isNaN(Number(id))) {
 				resource = EResourceType.USER_DETAILS_BY_USERNAME;
 			}
-			// If id is given
+			// If id is given (or not, for self details)
 			else {
 				resource = EResourceType.USER_DETAILS_BY_ID;
 			}
 
+			// If no ID is given, and not authenticated, skip
+			if (!id && !this.config.userId) {
+				return undefined as T extends string | undefined ? User | undefined : User[];
+			}
+
 			// Fetching raw details
-			const response = await this.request<IUserDetailsResponse>(resource, { id: id });
+			const response = await this.request<IUserDetailsResponse>(resource, { id: id ?? this.config.userId });
 
 			// Deserializing response
 			const data = extractors[resource](response);
 
-			return data as T extends string ? User | undefined : User[];
+			return data as T extends string | undefined ? User | undefined : User[];
 		}
 	}
 

package/src/types/errors/TwitterError.ts

@@ -0,0 +1,37 @@
+/**
+ * The error thrown by Twitter API.
+ *
+ * @public
+ */
+export interface ITwitterError extends Error {
+	/** The details of each error. */
+	details: ITwitterErrorDetails[];
+
+	/** The error message in the response. */
+	message: string;
+
+	/** The name of the error response. */
+	name: string;
+
+	/** The response status code. */
+	status: number;
+}
+
+/**
+ * The error details.
+ *
+ * @public
+ */
+export interface ITwitterErrorDetails {
+	/** The internal error code. */
+	code: number;
+
+	/** The message associated with the error. */
+	message: string;
+
+	/** The name of the error. */
+	name?: string;
+
+	/** The type of error. */
+	type?: string;
+}

package/src/types/raw/base/Error.ts

@@ -0,0 +1,37 @@
+/* eslint-disable */
+
+/**
+ * Error details for multiple errors.
+ *
+ * @public
+ */
+export interface IErrorData {
+	errors: IErrorDetails[];
+}
+
+/**
+ * Error details of a single error.
+ *
+ * @public
+ */
+export interface IErrorDetails {
+	message: string;
+	extensions?: IErrorExtensions;
+	code: number;
+	kind?: string;
+	name?: string;
+	source?: string;
+	tracing?: IErrorTracing;
+}
+
+export interface IErrorExtensions {
+	name: string;
+	source: string;
+	code: number;
+	kind: string;
+	tracing: IErrorTracing;
+}
+
+export interface IErrorTracing {
+	trace_id: string;
+}

package/src/types/raw/generic/Response.ts

@@ -1,5 +1,3 @@
-import { IError } from './Error';
-
 /**
  * The generic raw data received.
  *
@@ -9,5 +7,4 @@ import { IError } from './Error';
  */
 export interface IResponse<DataType> {
 	data: DataType;
-	errors?: IError[];
 }