@youmind-openlab/rettiwt-api 1.0.0

package/src/services/public/FetcherService.ts

@@ -0,0 +1,372 @@
+import axios, { AxiosError, isAxiosError } from 'axios';
+import { Cookie } from 'cookiejar';
+import { JSDOM } from 'jsdom';
+import { ClientTransaction } from 'x-client-transaction-id';
+
+import { AllowGuestAuthenticationGroup, FetchResourcesGroup, PostResourcesGroup } from '../../collections/Groups';
+import { Requests } from '../../collections/Requests';
+import { ApiErrors } from '../../enums/Api';
+import { LogActions } from '../../enums/Logging';
+import { ResourceType } from '../../enums/Resource';
+import { FetchArgs } from '../../models/args/FetchArgs';
+import { PostArgs } from '../../models/args/PostArgs';
+import { AuthCredential } from '../../models/auth/AuthCredential';
+import { TwitterError } from '../../models/errors/TwitterError';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IFetchArgs } from '../../types/args/FetchArgs';
+import { IPostArgs } from '../../types/args/PostArgs';
+import { ITransactionHeader } from '../../types/auth/TransactionHeader';
+import { IErrorHandler } from '../../types/ErrorHandler';
+import { IErrorData } from '../../types/raw/base/Error';
+
+import { AuthService } from '../internal/AuthService';
+import { ErrorService } from '../internal/ErrorService';
+import { LogService } from '../internal/LogService';
+
+/**
+ * The base service that handles all HTTP requests.
+ *
+ * @public
+ */
+export class FetcherService {
+	/** The AuthService instance to use. */
+	protected readonly _auth: AuthService;
+
+	/** The delay/delay function to use (ms). */
+	private readonly _delay?: number | (() => number | Promise<number>);
+
+	/** The service used to handle HTTP and API errors */
+	private readonly _errorHandler: IErrorHandler;
+
+	/** The max wait time for a response. */
+	private readonly _timeout: number;
+
+	/** The config object. */
+	protected readonly config: RettiwtConfig;
+
+	/**
+	 * @param config - The config object for configuring the Rettiwt instance.
+	 */
+	public constructor(config: RettiwtConfig) {
+		LogService.enabled = config.logging ?? false;
+		this.config = config;
+		this._delay = config.delay;
+		this._errorHandler = config.errorHandler ?? new ErrorService();
+		this._timeout = config.timeout ?? 0;
+		this._auth = new AuthService(config);
+	}
+
+	/**
+	 * Checks the authorization status based on the requested resource.
+	 *
+	 * @param resource - The requested resource.
+	 *
+	 * @throws An error if not authorized to access the requested resource.
+	 */
+	private _checkAuthorization(resource: ResourceType): void {
+		// Logging
+		LogService.log(LogActions.AUTHORIZATION, { authenticated: this.config.userId != undefined });
+
+		// Checking authorization status
+		if (!AllowGuestAuthenticationGroup.includes(resource) && this.config.userId == undefined) {
+			throw new Error(ApiErrors.RESOURCE_NOT_ALLOWED);
+		}
+	}
+
+	/**
+	 * Returns the AuthCredentials based on the type of key present.
+	 *
+	 * @returns The generated AuthCredential
+	 */
+	protected async _getCredential(): Promise<AuthCredential> {
+		if (this.config.apiKey) {
+			// Logging
+			LogService.log(LogActions.GET, { target: 'USER_CREDENTIAL' });
+
+			return new AuthCredential(
+				AuthService.decodeCookie(this.config.apiKey)
+					.split(';')
+					.map((item) => new Cookie(item)),
+			);
+		} else {
+			// Logging
+			LogService.log(LogActions.GET, { target: 'NEW_GUEST_CREDENTIAL' });
+
+			return this._auth.guest();
+		}
+	}
+
+	/**
+	 * Generates the header for the transaction ID.
+	 *
+	 * @param method - The target method.
+	 * @param url - The target URL.
+	 *
+	 * @returns The header containing the transaction ID.
+	 */
+	protected async _getTransactionHeader(method: string, url: string): Promise<ITransactionHeader> {
+		// Get the X homepage HTML document (using utility function)
+		const document = await this._handleXMigration();
+
+		// Create and initialize ClientTransaction instance
+		const transaction = await ClientTransaction.create(document);
+
+		// Getting the URL path excluding all params
+		const path = new URL(url).pathname.split('?')[0].trim();
+
+		// Generating the transaction ID
+		const tid = await transaction.generateTransactionId(method.toUpperCase(), path);
+
+		return {
+			/* eslint-disable @typescript-eslint/naming-convention */
+			'x-client-transaction-id': tid,
+			/* eslint-enable @typescript-eslint/naming-convention */
+		};
+	}
+
+	protected async _handleXMigration(): Promise<Document> {
+		// Fetch X.com homepage
+		const homePageResponse = await axios.get<string>('https://x.com', {
+			headers: this.config.headers,
+			httpAgent: this.config.httpsAgent,
+			httpsAgent: this.config.httpsAgent,
+		});
+
+		// Parse HTML using linkedom
+		let dom = new JSDOM(homePageResponse.data);
+		let document = dom.window.document;
+
+		// Check for migration redirection links
+		const migrationRedirectionRegex = new RegExp(
+			'(http(?:s)?://(?:www\\.)?(twitter|x){1}\\.com(/x)?/migrate([/?])?tok=[a-zA-Z0-9%\\-_]+)+',
+			'i',
+		);
+
+		const metaRefresh = document.querySelector("meta[http-equiv='refresh']");
+		const metaContent = metaRefresh ? metaRefresh.getAttribute('content') || '' : '';
+
+		const migrationRedirectionUrl =
+			migrationRedirectionRegex.exec(metaContent) || migrationRedirectionRegex.exec(homePageResponse.data);
+
+		if (migrationRedirectionUrl) {
+			// Follow redirection URL
+			const redirectResponse = await axios.get<string>(migrationRedirectionUrl[0], {
+				httpAgent: this.config.httpsAgent,
+				httpsAgent: this.config.httpsAgent,
+			});
+
+			dom = new JSDOM(redirectResponse.data);
+			document = dom.window.document;
+		}
+
+		// Handle migration form if present
+		const migrationForm =
+			document.querySelector("form[name='f']") ||
+			document.querySelector("form[action='https://x.com/x/migrate']");
+
+		if (migrationForm) {
+			const url = migrationForm.getAttribute('action') || 'https://x.com/x/migrate';
+			const method = migrationForm.getAttribute('method') || 'POST';
+
+			// Collect form input fields
+			const requestPayload = new FormData();
+
+			const inputFields = migrationForm.querySelectorAll('input');
+			for (const element of Array.from(inputFields)) {
+				const name = element.getAttribute('name');
+				const value = element.getAttribute('value');
+				if (name && value) {
+					requestPayload.append(name, value);
+				}
+			}
+
+			// Submit form using POST request
+			const formResponse = await axios.request<string>({
+				method: method,
+				url: url,
+				data: requestPayload,
+				headers: {
+					/* eslint-disable @typescript-eslint/naming-convention */
+
+					'Content-Type': 'multipart/form-data',
+					...this.config.headers,
+
+					/* eslint-enable @typescript-eslint/naming-convention */
+				},
+				httpAgent: this.config.httpsAgent,
+				httpsAgent: this.config.httpsAgent,
+			});
+
+			dom = new JSDOM(formResponse.data);
+			document = dom.window.document;
+		}
+
+		// Return final DOM document
+		return document;
+	}
+
+	/**
+	 * Validates the given args against the given resource.
+	 *
+	 * @param resource - The resource against which validation is to be done.
+	 * @param args - The args to be validated.
+	 *
+	 * @returns The validated args.
+	 */
+	private _validateArgs(resource: ResourceType, args: IFetchArgs | IPostArgs): FetchArgs | PostArgs | undefined {
+		if (FetchResourcesGroup.includes(resource)) {
+			// Logging
+			LogService.log(LogActions.VALIDATE, { target: 'FETCH_ARGS' });
+
+			return new FetchArgs(args);
+		} else if (PostResourcesGroup.includes(resource)) {
+			// Logging
+			LogService.log(LogActions.VALIDATE, { target: 'POST_ARGS' });
+
+			return new PostArgs(args);
+		}
+	}
+
+	/**
+	 * Introduces a delay using the configured delay/delay function.
+	 */
+	private async _wait(): Promise<void> {
+		// If no delay is set, skip
+		if (this._delay == undefined) {
+			return;
+		}
+
+		/** The delay (in ms) to use. */
+		let delay = 0;
+
+		// Getting the delay
+		if (this._delay && typeof this._delay == 'number') {
+			delay = this._delay;
+		} else if (this._delay && typeof this._delay == 'function') {
+			delay = await this._delay();
+		}
+
+		// Awaiting for the delay time
+		await new Promise((resolve) => setTimeout(resolve, delay));
+	}
+
+	/**
+	 * Makes an HTTP request according to the given parameters.
+	 *
+	 * @param resource - The requested resource.
+	 * @param config - The request configuration.
+	 *
+	 * @typeParam T - The type of the returned response data.
+	 *
+	 * @returns The raw data response received.
+	 *
+	 * @example
+	 *
+	 * #### Fetching the raw details of a single user, using their username
+	 * ```ts
+	 * import { FetcherService, ResourceType } from 'rettiwt-api';
+	 *
+	 * // Creating a new FetcherService instance using the given 'API_KEY'
+	 * const fetcher = new FetcherService({ apiKey: API_KEY });
+	 *
+	 * // Fetching the details of the User with username 'user1'
+	 * fetcher.request(ResourceType.USER_DETAILS_BY_USERNAME, { id: 'user1' })
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async request<T = unknown>(resource: ResourceType, args: IFetchArgs | IPostArgs): Promise<T> {
+		/** The current retry number. */
+		let retry = 0;
+
+		/** The error, if any. */
+		let error: unknown = undefined;
+
+		// Logging
+		LogService.log(LogActions.REQUEST, { resource: resource, args: args });
+
+		// Checking authorization for the requested resource
+		this._checkAuthorization(resource);
+
+		// Validating args
+		args = this._validateArgs(resource, args)!;
+
+		// Getting credentials from key
+		const cred: AuthCredential = await this._getCredential();
+
+		// Getting request configuration
+		const config = Requests[resource](args);
+
+		// Setting additional request parameters
+		config.headers = {
+			...config.headers,
+			...cred.toHeader(),
+			...this.config.headers,
+		};
+		config.httpAgent = this.config.httpsAgent;
+		config.httpsAgent = this.config.httpsAgent;
+		config.timeout = this._timeout;
+
+		// Using retries for error 404
+		do {
+			// Sending the request
+			try {
+				// Getting and appending transaction information
+				config.headers = {
+					...(await this._getTransactionHeader(config.method ?? '', config.url ?? '')),
+					...config.headers,
+				};
+
+				// Introducing a delay
+				await this._wait();
+
+				// Getting the response body
+				const responseData = (await axios<T>(config)).data;
+
+				// Check for Twitter API errors in response body
+				// Type guard to check if response contains errors
+				const potentialErrorResponse = responseData as unknown as Partial<IErrorData>;
+				if (
+					potentialErrorResponse.errors &&
+					Array.isArray(potentialErrorResponse.errors) &&
+					(potentialErrorResponse.data === undefined ||
+						JSON.stringify(potentialErrorResponse.data) === JSON.stringify({}))
+				) {
+					// Throw TwitterError using existing error class
+					const axiosError = {
+						response: {
+							data: { errors: potentialErrorResponse.errors },
+							status: 200,
+						},
+						message: potentialErrorResponse.errors[0]?.message ?? 'Twitter API Error',
+						status: 200,
+					} as AxiosError<IErrorData>;
+					throw new TwitterError(axiosError);
+				}
+
+				// Returning the reponse body
+				return responseData;
+			} catch (err) {
+				// If it's an error 404, retry
+				if (isAxiosError(err) && err.status === 404) {
+					error = err;
+					continue;
+				}
+				// Else, delegate error handling
+				else {
+					this._errorHandler.handle(err);
+				}
+			} finally {
+				// Incrementing the number of retries done
+				retry++;
+			}
+		} while (retry < this.config.maxRetries);
+
+		/** If request not successful even after retries, throw the error */
+		throw error;
+	}
+}

package/src/services/public/ListService.ts

@@ -0,0 +1,241 @@
+import { Extractors } from '../../collections/Extractors';
+import { ResourceType } from '../../enums/Resource';
+import { CursoredData } from '../../models/data/CursoredData';
+import { List } from '../../models/data/List';
+import { Tweet } from '../../models/data/Tweet';
+import { User } from '../../models/data/User';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IListMemberAddResponse } from '../../types/raw/list/AddMember';
+import { IListDetailsResponse } from '../../types/raw/list/Details';
+import { IListMembersResponse } from '../../types/raw/list/Members';
+import { IListMemberRemoveResponse } from '../../types/raw/list/RemoveMember';
+import { IListTweetsResponse } from '../../types/raw/list/Tweets';
+
+import { FetcherService } from './FetcherService';
+
+export class ListService extends FetcherService {
+	/**
+	 * @param config - The config object for configuring the Rettiwt instance.
+	 *
+	 * @internal
+	 */
+	public constructor(config: RettiwtConfig) {
+		super(config);
+	}
+
+	/**
+	 * Add a user as a member of a list.
+	 *
+	 * @param listId - The ID of the target list.
+	 * @param userId - The ID of the target user to be added as a member.
+	 *
+	 * @returns The new member count of the list. If adding was unsuccessful, return `undefined`.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Adding a user with ID '123456789' as a member to the list with ID '987654321'
+	 * rettiwt.list.addMember('987654321', '123456789')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async addMember(listId: string, userId: string): Promise<number | undefined> {
+		const resource: ResourceType = ResourceType.LIST_MEMBER_ADD;
+
+		// Adding the user as a member
+		const response = await this.request<IListMemberAddResponse>(resource, {
+			id: listId,
+			userId: userId,
+		});
+
+		// Deserializing response
+		const data = Extractors[resource](response);
+
+		return data;
+	}
+
+	/**
+	 * Get the details of a list.
+	 *
+	 * @param id - The ID of the target list.
+	 *
+	 * @returns
+	 * The details of the target list.
+	 *
+	 * If list not found, returns undefined.
+	 *
+	 * @example
+	 *
+	 * #### Fetching the details of a list
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the details of the list with the id '1234567890'
+	 * rettiwt.list.details('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async details(id: string): Promise<List | undefined> {
+		const resource: ResourceType = ResourceType.LIST_DETAILS;
+
+		// Getting the details of the list
+		const response = await this.request<IListDetailsResponse>(resource, { id: id });
+
+		// Deserializing response
+		const data = Extractors[resource](response, id);
+
+		return data;
+	}
+
+	/**
+	 * Get the list of members of a tweet list.
+	 *
+	 * @param id - The ID of target list.
+	 * @param count - The number of members to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of members to fetch.
+	 *
+	 * @returns The list tweets in the given list.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * 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 members of the Twitter list with id '1234567890'
+	 * rettiwt.list.members('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
+	 * @remarks Due a bug in Twitter API, the count is ignored when no cursor is provided and defaults to 100.
+	 */
+	public async members(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		const resource: ResourceType = ResourceType.LIST_MEMBERS;
+
+		// Fetching the raw list of members
+		const response = await this.request<IListMembersResponse>(resource, {
+			id: id,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = Extractors[resource](response);
+
+		return data;
+	}
+
+	/**
+	 * Remove a member from a list.
+	 *
+	 * @param listId - The ID of the target list.
+	 * @param userId - The ID of the target user to removed from the members.
+	 *
+	 * @returns The new member count of the list. If removal was unsuccessful, return `undefined`.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Removing a user with ID '123456789' from the member of the list with ID '987654321'
+	 * rettiwt.list.removeMember('987654321', '123456789')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async removeMember(listId: string, userId: string): Promise<number | undefined> {
+		const resource: ResourceType = ResourceType.LIST_MEMBER_REMOVE;
+
+		// Removing the member
+		const response = await this.request<IListMemberRemoveResponse>(resource, {
+			id: listId,
+			userId: userId,
+		});
+
+		// Deserializing response
+		const data = Extractors[resource](response);
+
+		return data;
+	}
+
+	/**
+	 * Get the list of tweets from a tweet list.
+	 *
+	 * @param id - The ID of target list.
+	 * @param count - The number of tweets to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of tweets to fetch.
+	 *
+	 * @returns The list tweets in the given list.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the most recent 100 tweets of the Twitter list with id '1234567890'
+	 * rettiwt.list.tweets('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
+	 * @remarks Due a bug in Twitter API, the count is ignored when no cursor is provided and defaults to 100.
+	 */
+	public async tweets(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		const resource = ResourceType.LIST_TWEETS;
+
+		// Fetching raw list tweets
+		const response = await this.request<IListTweetsResponse>(resource, {
+			id: id,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = Extractors[resource](response);
+
+		// Sorting the tweets by date, from recent to oldest
+		data.list.sort((a, b) => new Date(b.createdAt).valueOf() - new Date(a.createdAt).valueOf());
+
+		return data;
+	}
+}