rettiwt-api 6.3.0-alpha.0 → 7.0.0

package/src/requests/Space.ts

@@ -0,0 +1,76 @@
+import { AxiosRequestConfig } from 'axios';
+
+/**
+ * Collection of requests related to spaces.
+ *
+ * @public
+ */
+export class SpaceRequests {
+	/**
+	 * @param id - The id of the space whose details are to be fetched.
+	 * @param withReplays - Whether to include replay information.
+	 * @param withListeners - Whether to include listeners information.
+	 * @param isMetatagsQuery - Whether the request is a metatags query.
+	 */
+	public static details(
+		id: string,
+		withReplays?: boolean,
+		withListeners?: boolean,
+		isMetatagsQuery?: boolean,
+	): AxiosRequestConfig {
+		return {
+			method: 'get',
+			url: 'https://x.com/i/api/graphql/rR7CQrr8kxb6fatlUaB61Q/AudioSpaceById',
+			params: {
+				/* eslint-disable @typescript-eslint/naming-convention */
+				variables: JSON.stringify({
+					id: id,
+					isMetatagsQuery: isMetatagsQuery ?? false,
+					withReplays: withReplays ?? true,
+					withListeners: withListeners ?? false,
+				}),
+				features: JSON.stringify({
+					spaces_2022_h2_spaces_communities: true,
+					spaces_2022_h2_clipping: true,
+					creator_subscriptions_tweet_preview_api_enabled: true,
+					profile_label_improvements_pcf_label_in_post_enabled: true,
+					responsive_web_profile_redirect_enabled: false,
+					rweb_tipjar_consumption_enabled: false,
+					verified_phone_label_enabled: false,
+					premium_content_api_read_enabled: false,
+					communities_web_enable_tweet_community_results_fetch: true,
+					c9s_tweet_anatomy_moderator_badge_enabled: true,
+					responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+					responsive_web_grok_analyze_post_followups_enabled: true,
+					responsive_web_jetfuel_frame: true,
+					responsive_web_grok_share_attachment_enabled: true,
+					responsive_web_grok_annotations_enabled: false,
+					articles_preview_enabled: true,
+					responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+					responsive_web_edit_tweet_api_enabled: true,
+					graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+					view_counts_everywhere_api_enabled: true,
+					longform_notetweets_consumption_enabled: true,
+					responsive_web_twitter_article_tweet_consumption_enabled: true,
+					tweet_awards_web_tipping_enabled: false,
+					responsive_web_grok_show_grok_translated_post: false,
+					responsive_web_grok_analysis_button_from_backend: true,
+					post_ctas_fetch_enabled: true,
+					creator_subscriptions_quote_tweet_preview_enabled: false,
+					freedom_of_speech_not_reach_fetch_enabled: true,
+					standardized_nudges_misinfo: true,
+					tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+					longform_notetweets_rich_text_read_enabled: true,
+					longform_notetweets_inline_media_enabled: true,
+					responsive_web_grok_image_annotation_enabled: true,
+					responsive_web_grok_imagine_annotation_enabled: true,
+					responsive_web_graphql_timeline_navigation_enabled: true,
+					responsive_web_grok_community_note_auto_translation_is_enabled: false,
+					responsive_web_enhance_cards_enabled: false,
+				}),
+				/* eslint-enable @typescript-eslint/naming-convention */
+			},
+			paramsSerializer: { encode: encodeURIComponent },
+		};
+	}
+}

package/src/requests/Tweet.ts

@@ -287,6 +287,65 @@ export class TweetRequests {
 		};
 	}
 
+	/**
+	 * @param args - The configuration object for the long-form tweet to be posted (X Premium only).
+	 */
+	public static postNote(args: INewTweet): AxiosRequestConfig {
+		// Parsing the args
+		const parsedArgs = new NewTweet(args);
+
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/graphql/_eeuQKX1-VyRP_ROM-GN7g/CreateNoteTweet',
+			data: {
+				/* eslint-disable @typescript-eslint/naming-convention */
+				variables: {
+					tweet_text: parsedArgs.text,
+					media: parsedArgs.media ? new MediaVariable(parsedArgs.media) : undefined,
+					semantic_annotation_ids: [],
+					disallowed_reply_options: null,
+				},
+				features: {
+					premium_content_api_read_enabled: false,
+					communities_web_enable_tweet_community_results_fetch: true,
+					c9s_tweet_anatomy_moderator_badge_enabled: true,
+					responsive_web_grok_analyze_button_fetch_trends_enabled: false,
+					responsive_web_grok_analyze_post_followups_enabled: true,
+					responsive_web_jetfuel_frame: true,
+					responsive_web_grok_share_attachment_enabled: true,
+					responsive_web_grok_annotations_enabled: true,
+					responsive_web_edit_tweet_api_enabled: true,
+					graphql_is_translatable_rweb_tweet_is_translatable_enabled: true,
+					view_counts_everywhere_api_enabled: true,
+					longform_notetweets_consumption_enabled: true,
+					responsive_web_twitter_article_tweet_consumption_enabled: true,
+					tweet_awards_web_tipping_enabled: false,
+					content_disclosure_indicator_enabled: true,
+					content_disclosure_ai_generated_indicator_enabled: true,
+					responsive_web_grok_show_grok_translated_post: true,
+					responsive_web_grok_analysis_button_from_backend: true,
+					post_ctas_fetch_enabled: true,
+					longform_notetweets_rich_text_read_enabled: true,
+					longform_notetweets_inline_media_enabled: false,
+					profile_label_improvements_pcf_label_in_post_enabled: true,
+					responsive_web_profile_redirect_enabled: false,
+					rweb_tipjar_consumption_enabled: false,
+					verified_phone_label_enabled: false,
+					articles_preview_enabled: true,
+					responsive_web_grok_community_note_auto_translation_is_enabled: false,
+					responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+					freedom_of_speech_not_reach_fetch_enabled: true,
+					standardized_nudges_misinfo: true,
+					tweet_with_visibility_results_prefer_gql_limited_actions_policy_enabled: true,
+					responsive_web_grok_image_annotation_enabled: true,
+					responsive_web_grok_imagine_annotation_enabled: true,
+					responsive_web_graphql_timeline_navigation_enabled: true,
+					responsive_web_enhance_cards_enabled: false,
+				},
+			},
+		};
+	}
+
 	/**
 	 * @param id - The id of the tweet whose replies are to be fetched.
 	 * @param cursor - The cursor to the batch of replies to fetch.

package/src/requests/User.ts

@@ -11,6 +11,20 @@ import { IProfileUpdateOptions } from '../types/args/ProfileArgs';
  * @public
  */
 export class UserRequests {
+	/**
+	 * @param userName - The username of the user whose about profile is to be fetched.
+	 */
+	public static aboutByUsername(userName: string): AxiosRequestConfig {
+		return {
+			method: 'get',
+			url: 'https://x.com/i/api/graphql/zs_jFPFT78rBpXv9Z3U2YQ/AboutAccountQuery',
+			params: {
+				variables: JSON.stringify({ screenName: userName }),
+			},
+			paramsSerializer: { encode: encodeURIComponent },
+		};
+	}
+
 	/**
 	 * @param id - The id of the user whose affiliates are to be fetched.
 	 * @param count - The number of affiliates to fetch. Only works as a lower limit when used with a cursor.
@@ -311,6 +325,39 @@ export class UserRequests {
 		};
 	}
 
+	/**
+	 * @param currentPassword - The current password.
+	 * @param newPassword - The new password.
+	 */
+	public static changePassword(currentPassword: string, newPassword: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/i/account/change_password.json',
+			data: qs.stringify({
+				/* eslint-disable @typescript-eslint/naming-convention */
+				current_password: currentPassword,
+				password: newPassword,
+				password_confirmation: newPassword,
+				/* eslint-enable @typescript-eslint/naming-convention */
+			}),
+		};
+	}
+
+	/**
+	 * @param newUsername - The new username to set.
+	 */
+	public static changeUsername(newUsername: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/1.1/account/settings.json',
+			data: qs.stringify({
+				/* eslint-disable @typescript-eslint/naming-convention */
+				screen_name: newUsername,
+				/* eslint-enable @typescript-eslint/naming-convention */
+			}),
+		};
+	}
+
 	/**
 	 * @param id - The id of the user whose details are to be fetched.
 	 */
@@ -1209,4 +1256,26 @@ export class UserRequests {
 			}),
 		};
 	}
+
+	/**
+	 * @param bannerBase64 - The base64-encoded banner image data.
+	 */
+	public static updateProfileBanner(bannerBase64: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/1.1/account/update_profile_banner.json',
+			data: qs.stringify({ banner: bannerBase64 }),
+		};
+	}
+
+	/**
+	 * @param imageBase64 - The base64-encoded image data.
+	 */
+	public static updateProfileImage(imageBase64: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/1.1/account/update_profile_image.json',
+			data: qs.stringify({ image: imageBase64 }),
+		};
+	}
 }

package/src/services/internal/AuthService.ts

@@ -1,4 +1,6 @@
-import axios from 'axios';
+import axios, { AxiosResponse } from 'axios';
+
+import { Cookie } from 'cookiejar';
 
 import { ApiErrors } from '../../enums/Api';
 import { AuthCredential } from '../../models/auth/AuthCredential';
@@ -20,6 +22,21 @@ export class AuthService {
 		this._config = config;
 	}
 
+	/**
+	 * Splits the cookie header into a list of key=value pairs.
+	 *
+	 * @param cookieHeader - The value of the cookie header.
+	 *
+	 * @returns The list of key=value pairs in the cookies.
+	 */
+	private static _splitCookieHeader(cookieHeader: string | string[]): string[] {
+		if (Array.isArray(cookieHeader)) {
+			return cookieHeader;
+		}
+
+		return cookieHeader.split(/,(?=\s*[^;,]+=)/g);
+	}
+
 	/**
 	 * Decodes the encoded cookie string.
 	 *
@@ -46,6 +63,91 @@ export class AuthService {
 		return encodedCookies;
 	}
 
+	/**
+	 * Gets a new API key from an HTTP response.
+	 *
+	 * @param response - The HTTP response received.
+	 * @param config - The current Rettiwt config.
+	 *
+	 * @returns The new API key.
+	 */
+	public static getApiKeyFromReponse(response: AxiosResponse, config?: RettiwtConfig): string | undefined {
+		// If new cookies not returned or user not authenticated, terminate
+		if (response.headers['set-cookie'] === undefined || config?.apiKey === undefined) {
+			return;
+		}
+
+		/** The collection of required cookie names. */
+		const requiredCookieNames = new Set(['auth_token', 'ct0', 'kdt', 'twid']);
+
+		/** The current cookie string. */
+		const currentCookieString = AuthService.decodeCookie(config.apiKey);
+
+		/** The cookie key=value pairs from the response. */
+		const cookies = AuthService._splitCookieHeader(response.headers['set-cookie']);
+
+		/** The map from cookie key to value. */
+		const cookiesMap = new Map<string, string>();
+
+		for (const cookieEntry of currentCookieString.split(';')) {
+			const trimmedEntry = cookieEntry.trim();
+			const separatorIndex = trimmedEntry.indexOf('=');
+
+			if (!trimmedEntry || separatorIndex < 1) {
+				continue;
+			}
+
+			const key = trimmedEntry.slice(0, separatorIndex).trim();
+			const value = trimmedEntry.slice(separatorIndex + 1).trim();
+			if (!key || !value || !requiredCookieNames.has(key)) {
+				continue;
+			}
+
+			cookiesMap.set(key, value);
+		}
+
+		let hasUpdate = false;
+		for (const cookie of cookies) {
+			const cookieValuePair = cookie.split(';', 1)[0]?.trim();
+			const separatorIndex = cookieValuePair?.indexOf('=') ?? -1;
+
+			if (!cookieValuePair || separatorIndex < 1) {
+				continue;
+			}
+
+			const key = cookieValuePair.slice(0, separatorIndex).trim();
+			const value = cookieValuePair.slice(separatorIndex + 1).trim();
+			if (!key || !value || !requiredCookieNames.has(key)) {
+				continue;
+			}
+
+			cookiesMap.set(key, value);
+			hasUpdate = true;
+		}
+
+		if (!hasUpdate || !cookiesMap.has('twid')) {
+			return;
+		}
+
+		let mergedCookieString = '';
+		for (const [key, value] of cookiesMap.entries()) {
+			mergedCookieString += `${key}=${value};`;
+		}
+
+		if (!mergedCookieString) {
+			return;
+		}
+
+		try {
+			// Encoding the new cookies into an API key
+			const newApiKey = AuthService.encodeCookie(mergedCookieString);
+
+			return newApiKey;
+		} catch {
+			return;
+		}
+	}
+
 	/**
 	 * Gets the user's id from the given API key.
 	 *
@@ -71,6 +173,50 @@ export class AuthService {
 		}
 	}
 
+	/**
+	 * Fetches a fresh CSRF from Twitter by making a lightweight
+	 * authenticated request, then rotates the apiKey with the updated cookie.
+	 *
+	 * @param config - The current Rettiwt config.
+	 */
+	public static async refreshCsrfToken(config: RettiwtConfig): Promise<void> {
+		// If unauthenticated, skip
+		if (config.apiKey === undefined) {
+			return;
+		}
+
+		try {
+			const cred = new AuthCredential(
+				AuthService.decodeCookie(config.apiKey)
+					.split(';')
+					.map((item) => new Cookie(item)),
+			);
+
+			const refreshResponse = await axios.get('https://x.com/i/api/1.1/account/verify_credentials.json', {
+				headers: {
+					...cred.toHeader(),
+					authorization:
+						'Bearer AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA',
+				},
+				httpAgent: config.httpAgent,
+				httpsAgent: config.httpsAgent,
+				proxy: config.axiosProxyConfig,
+				validateStatus: () => true,
+			});
+
+			// Getting the new API key
+			const newApiKey = AuthService.getApiKeyFromReponse(refreshResponse, config);
+
+			// If new API key is generated, update current API key
+			if (newApiKey !== undefined) {
+				config.apiKey = newApiKey;
+			}
+		} catch {
+			// If ct0 refresh fails, leave apiKey as-is
+			return;
+		}
+	}
+
 	/**
 	 * Login to twitter as guest.
 	 *
@@ -106,7 +252,9 @@ export class AuthService {
 				/* eslint-enable @typescript-eslint/naming-convention */
 			}>('https://api.twitter.com/1.1/guest/activate.json', undefined, {
 				headers: cred.toHeader(),
+				httpAgent: this._config.httpAgent,
 				httpsAgent: this._config.httpsAgent,
+				proxy: this._config.axiosProxyConfig,
 			})
 			.then((res) => {
 				cred.guestToken = res.data.guest_token;

package/src/services/public/DirectMessageService.ts

@@ -64,7 +64,7 @@ export class DirectMessageService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -139,7 +139,7 @@ export class DirectMessageService extends FetcherService {
 			});
 
 			// Deserializing response
-			const data = Extractors[resource](response);
+			const data = Extractors[resource](response.data);
 
 			return data;
 		}
@@ -151,7 +151,7 @@ export class DirectMessageService extends FetcherService {
 			const response = await this.request<IInboxInitialResponse>(resource, {});
 
 			// Deserializing response
-			const data = Extractors[resource](response);
+			const data = Extractors[resource](response.data);
 
 			return data;
 		}

package/src/services/public/FetcherService.ts

@@ -1,6 +1,6 @@
-import axios, { AxiosError, isAxiosError } from 'axios';
+import axios, { AxiosError, AxiosResponse, isAxiosError } from 'axios';
 import { Cookie } from 'cookiejar';
-import { JSDOM } from 'jsdom';
+import { parseHTML } from 'linkedom';
 import { ClientTransaction } from 'x-client-transaction-id';
 
 import { AllowGuestAuthenticationGroup, FetchResourcesGroup, PostResourcesGroup } from '../../collections/Groups';
@@ -128,13 +128,13 @@ export class FetcherService {
 		// Fetch X.com homepage
 		const homePageResponse = await axios.get<string>('https://x.com', {
 			headers: this.config.headers,
-			httpAgent: this.config.httpsAgent,
+			httpAgent: this.config.httpAgent,
 			httpsAgent: this.config.httpsAgent,
+			proxy: this.config.axiosProxyConfig,
 		});
 
 		// Parse HTML using linkedom
-		let dom = new JSDOM(homePageResponse.data);
-		let document = dom.window.document;
+		let document = parseHTML(homePageResponse.data).document;
 
 		// Check for migration redirection links
 		const migrationRedirectionRegex = new RegExp(
@@ -151,12 +151,12 @@ export class FetcherService {
 		if (migrationRedirectionUrl) {
 			// Follow redirection URL
 			const redirectResponse = await axios.get<string>(migrationRedirectionUrl[0], {
-				httpAgent: this.config.httpsAgent,
+				httpAgent: this.config.httpAgent,
 				httpsAgent: this.config.httpsAgent,
+				proxy: this.config.axiosProxyConfig,
 			});
 
-			dom = new JSDOM(redirectResponse.data);
-			document = dom.window.document;
+			document = parseHTML(redirectResponse.data).document;
 		}
 
 		// Handle migration form if present
@@ -193,12 +193,12 @@ export class FetcherService {
 
 					/* eslint-enable @typescript-eslint/naming-convention */
 				},
-				httpAgent: this.config.httpsAgent,
+				httpAgent: this.config.httpAgent,
 				httpsAgent: this.config.httpsAgent,
+				proxy: this.config.axiosProxyConfig,
 			});
 
-			dom = new JSDOM(formResponse.data);
-			document = dom.window.document;
+			document = parseHTML(formResponse.data).document;
 		}
 
 		// Return final DOM document
@@ -254,11 +254,11 @@ export class FetcherService {
 	 * Makes an HTTP request according to the given parameters.
 	 *
 	 * @param resource - The requested resource.
-	 * @param config - The request configuration.
+	 * @param args - The args to be used for the request.
 	 *
 	 * @typeParam T - The type of the returned response data.
 	 *
-	 * @returns The raw data response received.
+	 * @returns The raw Axios response.
 	 *
 	 * @example
 	 *
@@ -279,7 +279,7 @@ export class FetcherService {
 	 * });
 	 * ```
 	 */
-	public async request<T = unknown>(resource: ResourceType, args: IFetchArgs | IPostArgs): Promise<T> {
+	public async request<T = unknown>(resource: ResourceType, args: IFetchArgs | IPostArgs): Promise<AxiosResponse<T>> {
 		/** The current retry number. */
 		let retry = 0;
 
@@ -307,8 +307,9 @@ export class FetcherService {
 			...cred.toHeader(),
 			...this.config.headers,
 		};
-		config.httpAgent = this.config.httpsAgent;
+		config.httpAgent = this.config.httpAgent;
 		config.httpsAgent = this.config.httpsAgent;
+		config.proxy = this.config.axiosProxyConfig;
 		config.timeout = this._timeout;
 
 		// Using retries for error 404
@@ -325,7 +326,8 @@ export class FetcherService {
 				await this._wait();
 
 				// Getting the response body
-				const responseData = (await axios<T>(config)).data;
+				const response = await axios<T>(config);
+				const responseData = response.data;
 
 				// Check for Twitter API errors in response body
 				// Type guard to check if response contains errors
@@ -348,8 +350,13 @@ export class FetcherService {
 					throw new TwitterError(axiosError);
 				}
 
-				// Returning the reponse body
-				return responseData;
+				// Calling the request middleware, if configured
+				if (this.config.responseMiddleware !== undefined) {
+					await this.config.responseMiddleware(response);
+				}
+
+				// Returning the response
+				return response;
 			} catch (err) {
 				// If it's an error 404, retry
 				if (isAxiosError(err) && err.status === 404) {

package/src/services/public/ListService.ts

@@ -59,7 +59,7 @@ export class ListService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -100,7 +100,7 @@ export class ListService extends FetcherService {
 		const response = await this.request<IListDetailsResponse>(resource, { id: id });
 
 		// Deserializing response
-		const data = Extractors[resource](response, id);
+		const data = Extractors[resource](response.data, id);
 
 		return data;
 	}
@@ -145,7 +145,7 @@ export class ListService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -186,7 +186,7 @@ export class ListService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -231,7 +231,7 @@ export class ListService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		// Sorting the tweets by date, from recent to oldest
 		data.list.sort((a, b) => new Date(b.createdAt).valueOf() - new Date(a.createdAt).valueOf());

package/src/services/public/SpaceService.ts

@@ -0,0 +1,65 @@
+import { Extractors } from '../../collections/Extractors';
+import { ResourceType } from '../../enums/Resource';
+import { Space } from '../../models/data/Space';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { ISpaceDetailsOptions } from '../../types/args/FetchArgs';
+import { IAudioSpaceByIdResponse } from '../../types/raw/space/AudioSpaceById';
+
+import { FetcherService } from './FetcherService';
+
+/**
+ * Handles interacting with resources related to spaces.
+ *
+ * @public
+ */
+export class SpaceService extends FetcherService {
+	/**
+	 * @param config - The config object for configuring the Rettiwt instance.
+	 *
+	 * @internal
+	 */
+	public constructor(config: RettiwtConfig) {
+		super(config);
+	}
+
+	/**
+	 * Get the details of a space.
+	 *
+	 * @param id - The ID of the target space.
+	 * @param options - Additional options for the fetch.
+	 *
+	 * @returns The details of the space with the given ID.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * rettiwt.space.details('1YqJDNEzvoVKV', { withListeners: true })
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async details(id: string, options?: ISpaceDetailsOptions): Promise<Space | undefined> {
+		const resource = ResourceType.SPACE_DETAILS;
+
+		// Fetching raw space details
+		const response = await this.request<IAudioSpaceByIdResponse>(resource, {
+			id: id,
+			withReplays: options?.withReplays,
+			withListeners: options?.withListeners,
+			isMetatagsQuery: options?.isMetatagsQuery,
+		});
+
+		// Deserializing response
+		const data = Extractors[resource](response.data);
+
+		return data;
+	}
+}