rettiwt-api 6.3.0-alpha.1 → 7.0.1

package/src/services/public/UserService.ts

@@ -9,13 +9,16 @@ import { List } from '../../models/data/List';
 import { Notification } from '../../models/data/Notification';
 import { Tweet } from '../../models/data/Tweet';
 import { User } from '../../models/data/User';
+import { UserAbout } from '../../models/data/UserAbout';
 import { RettiwtConfig } from '../../models/RettiwtConfig';
 import { IProfileUpdateOptions } from '../../types/args/ProfileArgs';
+import { IUserAboutResponse } from '../../types/raw/user/About';
 import { IUserAffiliatesResponse } from '../../types/raw/user/Affiliates';
 import { IUserAnalyticsResponse } from '../../types/raw/user/Analytics';
 import { IUserBookmarkFoldersResponse } from '../../types/raw/user/BookmarkFolders';
 import { IUserBookmarkFolderTweetsResponse } from '../../types/raw/user/BookmarkFolderTweets';
 import { IUserBookmarksResponse } from '../../types/raw/user/Bookmarks';
+import { IUserChangePasswordResponse } from '../../types/raw/user/ChangePassword';
 import { IUserDetailsResponse } from '../../types/raw/user/Details';
 import { IUserDetailsBulkResponse } from '../../types/raw/user/DetailsBulk';
 import { IUserFollowResponse } from '../../types/raw/user/Follow';
@@ -30,11 +33,14 @@ import { IUserNotificationsResponse } from '../../types/raw/user/Notifications';
 import { IUserProfileUpdateResponse } from '../../types/raw/user/ProfileUpdate';
 import { IUserRecommendedResponse } from '../../types/raw/user/Recommended';
 import { IUserSearchResponse } from '../../types/raw/user/Search';
+import { IUserSettingsResponse } from '../../types/raw/user/Settings';
 import { IUserSubscriptionsResponse } from '../../types/raw/user/Subscriptions';
 import { IUserTweetsResponse } from '../../types/raw/user/Tweets';
 import { IUserTweetsAndRepliesResponse } from '../../types/raw/user/TweetsAndReplies';
 import { IUserUnfollowResponse } from '../../types/raw/user/Unfollow';
 
+import { AuthService } from '../internal/AuthService';
+
 import { FetcherService } from './FetcherService';
 
 /**
@@ -52,6 +58,97 @@ export class UserService extends FetcherService {
 		super(config);
 	}
 
+	/**
+	 * Gets the size in bytes of a base64 string.
+	 *
+	 * @param base64Data - The base64 data show size is required.
+	 *
+	 * @returns The size in bytes of the data.
+	 */
+	private _base64ByteSize(base64Data: string): number {
+		const paddingMatch = base64Data.match(/=+$/);
+		const paddingLength = paddingMatch ? paddingMatch[0].length : 0;
+
+		return (base64Data.length * 3) / 4 - paddingLength;
+	}
+
+	/**
+	 * Normalizes base64 data into just the raw base64 string.
+	 *
+	 * @param payload - The data to normalize.
+	 *
+	 * @returns The raw base64 part of the data.
+	 */
+	private _normalizeBase64(payload: string): string {
+		const trimmedPayload = payload.trim();
+		const lowerCasePayload = trimmedPayload.toLowerCase();
+		const base64Marker = ';base64,';
+
+		if (lowerCasePayload.startsWith('data:')) {
+			const markerIndex = lowerCasePayload.indexOf(base64Marker);
+			if (markerIndex !== -1) {
+				return trimmedPayload.slice(markerIndex + base64Marker.length).trim();
+			}
+		}
+
+		return trimmedPayload;
+	}
+
+	private _validateBase64Payload(payload: string, fieldName: string): string {
+		const normalizedPayload = this._normalizeBase64(payload).replace(/\s+/g, '');
+
+		if (normalizedPayload.length === 0) {
+			throw new Error(`${fieldName} cannot be empty`);
+		}
+
+		if (!/^[A-Za-z0-9+/]*={0,2}$/.test(normalizedPayload)) {
+			throw new Error(`${fieldName} must be valid base64`);
+		}
+
+		return normalizedPayload;
+	}
+
+	/**
+	 * Get the about profile of a user.
+	 *
+	 * @param userName - The username/screenname of the target user.
+	 *
+	 * @returns The about profile of the user.
+	 *
+	 * @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 about profile of the User with username 'user1' or '@user1'
+	 * rettiwt.user.about('user1') // or @user1
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async about(userName: string): Promise<UserAbout | undefined> {
+		const resource = ResourceType.USER_ABOUT_BY_USERNAME;
+
+		if (userName.startsWith('@')) {
+			userName = userName.slice(1);
+		}
+
+		// Fetching raw about profile
+		const response = await this.request<IUserAboutResponse>(resource, { id: userName });
+
+		// Deserializing response
+		const data = Extractors[resource](response.data);
+
+		return data;
+	}
+
 	/**
 	 * Get the list affiliates of a user.
 	 *
@@ -90,7 +187,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -148,7 +245,7 @@ export class UserService extends FetcherService {
 			showVerifiedFollowers,
 		});
 
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -191,7 +288,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -230,7 +327,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -271,11 +368,86 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
+
+		return data;
+	}
+
+	/**
+	 * Changes the password of the authenticated user.
+	 *
+	 * @param currentPassword - The current account password.
+	 * @param newPassword - The new password to set.
+	 * @returns Whether the password was changed successfully.
+	 *
+	 * @remarks
+	 * After a successful password change, this method attempts to rotate the current
+	 * `apiKey` using cookies returned by Twitter. If rotation is not possible, you
+	 * must re-authenticate and obtain a new `apiKey` to continue making authenticated
+	 * requests.
+	 */
+	public async changePassword(currentPassword: string, newPassword: string): Promise<boolean> {
+		const resource = ResourceType.USER_PASSWORD_CHANGE;
+
+		// Changing the password
+		const response = await this.request<IUserChangePasswordResponse>(resource, {
+			changePassword: { currentPassword, newPassword },
+		});
+
+		// Getting if password change was successful or not
+		const data = Extractors[resource](response.data) ?? false;
+
+		// If password change was successful
+		if (data === true) {
+			// Getting the new API key
+			const newApiKey = AuthService.getApiKeyFromReponse(response);
+
+			// If new API key is generated, update current API key
+			if (newApiKey !== undefined) {
+				this.config.apiKey = newApiKey;
+			}
+
+			// Getting the new CSRF token and updating current API key
+			await AuthService.refreshCsrfToken(this.config);
+		}
 
 		return data;
 	}
 
+	/**
+	 * Changes the username (screen_name) of the authenticated user.
+	 *
+	 * @param newUsername - The new username (with or without `@`).
+	 * @returns Whether the username was changed successfully.
+	 */
+	public async changeUsername(newUsername: string): Promise<boolean> {
+		const resource = ResourceType.USER_USERNAME_CHANGE;
+
+		// Strip @ prefix if present
+		const username = newUsername.startsWith('@') ? newUsername.slice(1) : newUsername;
+
+		// Username validation
+		if (username.length < 4) {
+			throw new Error('Username must be at least 4 characters long');
+		}
+		if (username.length > 15) {
+			throw new Error('Username cannot exceed 15 characters');
+		}
+		if (!/^[A-Za-z0-9_]+$/.test(username)) {
+			throw new Error('Username can only contain letters, numbers, and underscores');
+		}
+
+		// Changing the username
+		const response = await this.request<IUserSettingsResponse>(resource, {
+			username,
+		});
+
+		// Getting the updated username
+		const updatedUsername = Extractors[resource](response.data);
+
+		return updatedUsername?.toLowerCase() === username.toLowerCase();
+	}
+
 	/**
 	 * Get the details of the logged in user.
 	 *
@@ -386,7 +558,7 @@ export class UserService extends FetcherService {
 			const response = await this.request<IUserDetailsBulkResponse>(resource, { ids: id });
 
 			// Deserializing response
-			const data = Extractors[resource](response, id);
+			const data = Extractors[resource](response.data, id);
 
 			return data;
 		}
@@ -413,7 +585,7 @@ export class UserService extends FetcherService {
 			const response = await this.request<IUserDetailsResponse>(resource, { id: id ?? this.config.userId });
 
 			// Deserializing response
-			const data = Extractors[resource](response);
+			const data = Extractors[resource](response.data);
 
 			return data;
 		}
@@ -453,7 +625,7 @@ export class UserService extends FetcherService {
 		const response = await this.request<IUserFollowResponse>(ResourceType.USER_FOLLOW, { id: id });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -494,7 +666,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -537,7 +709,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -580,7 +752,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -623,7 +795,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -665,7 +837,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -707,7 +879,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -750,7 +922,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -807,7 +979,7 @@ export class UserService extends FetcherService {
 			});
 
 			// Deserializing response
-			const notifications = Extractors[resource](response);
+			const notifications = Extractors[resource](response.data);
 
 			// Sorting the notifications by time, from oldest to recent
 			notifications.list.sort((a, b) => new Date(a.receivedAt).valueOf() - new Date(b.receivedAt).valueOf());
@@ -864,7 +1036,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -911,7 +1083,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -954,7 +1126,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -997,7 +1169,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -1045,7 +1217,7 @@ export class UserService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -1082,7 +1254,7 @@ export class UserService extends FetcherService {
 		const response = await this.request<IUserUnfollowResponse>(ResourceType.USER_UNFOLLOW, { id: id });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -1147,7 +1319,59 @@ export class UserService extends FetcherService {
 		const response = await this.request<IUserProfileUpdateResponse>(resource, { profileOptions: validatedOptions });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
+
+		return data;
+	}
+
+	/**
+	 * Updates the profile banner of the authenticated user.
+	 *
+	 * @param bannerBase64 - The base64-encoded banner image data.
+	 * @returns Whether the profile banner was updated successfully.
+	 */
+	public async updateProfileBanner(bannerBase64: string): Promise<boolean> {
+		const resource = ResourceType.USER_PROFILE_BANNER_UPDATE;
+
+		const validatedBanner = this._validateBase64Payload(bannerBase64, 'Profile banner');
+
+		// Banner size validation (max 5 MB)
+		const bannerSizeBytes = this._base64ByteSize(validatedBanner);
+		if (bannerSizeBytes > 5 * 1024 * 1024) {
+			throw new Error('Profile banner cannot exceed 5 MB');
+		}
+
+		const response = await this.request<IUserProfileUpdateResponse>(resource, {
+			profileBanner: validatedBanner,
+		});
+
+		const data = Extractors[resource](response.data) ?? false;
+
+		return data;
+	}
+
+	/**
+	 * Updates the profile image of the authenticated user.
+	 *
+	 * @param imageBase64 - The base64-encoded image data.
+	 * @returns Whether the profile image was updated successfully.
+	 */
+	public async updateProfileImage(imageBase64: string): Promise<boolean> {
+		const resource = ResourceType.USER_PROFILE_IMAGE_UPDATE;
+
+		const validatedImage = this._validateBase64Payload(imageBase64, 'Profile image');
+
+		// Image size validation (max 2 MB)
+		const imageSizeBytes = this._base64ByteSize(validatedImage);
+		if (imageSizeBytes > 2 * 1024 * 1024) {
+			throw new Error('Profile image cannot exceed 2 MB');
+		}
+
+		const response = await this.request<IUserProfileUpdateResponse>(resource, {
+			profileImage: validatedImage,
+		});
+
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}

package/src/types/RettiwtConfig.ts

@@ -1,3 +1,5 @@
+import { AxiosProxyConfig, AxiosResponse } from 'axios';
+
 import { IErrorHandler } from './ErrorHandler';
 
 /**
@@ -10,11 +12,34 @@ export interface IRettiwtConfig {
 	apiKey?: string;
 
 	/**
-	 * Optional URL to proxy server to use for requests to Twitter API.
+	 * The proxy to use.
+	 *
+	 * @remarks
+	 * <br>
+	 * - If set to anything besides `undefined`, disables Axios' built-in environment variable-set proxy.
+	 *
+	 * @example
+	 * ```
+	 * // Use custom proxy config via config object
+	 * {
+	 *   proxy: {
+	 *     host: '127.0.0.1',
+	 *     port: 8080
+	 *   }
+	 * }
+	 *
+	 * // Use custom proxy config via URL
+	 * {
+	 *   proxy: 'https://127.0.0.1:8080'
+	 * }
 	 *
-	 * @remarks When deploying to cloud platforms, if setting {@link IRettiwtConfig.authProxyUrl} does not resolve Error 429, then this might be required.
+	 * // Use Axios environment variable for proxy
+	 * {
+	 *   proxy: undefined
+	 * }
+	 * ```
 	 */
-	proxyUrl?: URL;
+	proxy?: AxiosProxyConfig | string | null;
 
 	/** The max wait time (in milli-seconds) for a response; if not set, Twitter server timeout is used. */
 	timeout?: number;
@@ -22,6 +47,13 @@ export interface IRettiwtConfig {
 	/** Whether to write logs to console or not. */
 	logging?: boolean;
 
+	/**
+	 * Optional response middleware to be executed on obtaining a successful response.
+	 *
+	 * @param response -  The raw `AxiosReponse` object.
+	 */
+	responseMiddleware?: (response: AxiosResponse) => void | Promise<void>;
+
 	/** Optional custom error handler to define error conditions and process API/HTTP errors in responses. */
 	errorHandler?: IErrorHandler;
 

package/src/types/args/FetchArgs.ts

@@ -71,7 +71,7 @@ export interface IFetchArgs {
 	 *
 	 * @remarks
 	 * - Required for all resources except {@link ResourceType.TWEET_SEARCH} and {@link ResourceType.USER_TIMELINE_RECOMMENDED}.
-	 * - For {@link ResourceType.USER_DETAILS_BY_USERNAME} and {@link ResourceType.USER_SEARCH}, can be alphanumeric, while for others, is strictly numeric.
+	 * - For {@link ResourceType.USER_DETAILS_BY_USERNAME}, {@link ResourceType.USER_ABOUT_BY_USERNAME}, and {@link ResourceType.USER_SEARCH}, can be alphanumeric, while for others, is strictly numeric.
 	 */
 	id?: string;
 
@@ -83,6 +83,30 @@ export interface IFetchArgs {
 	 */
 	ids?: string[];
 
+	/**
+	 * Whether to include replay information when fetching space details.
+	 *
+	 * @remarks
+	 * - Only works for {@link ResourceType.SPACE_DETAILS}.
+	 */
+	withReplays?: boolean;
+
+	/**
+	 * Whether to include listeners information when fetching space details.
+	 *
+	 * @remarks
+	 * - Only works for {@link ResourceType.SPACE_DETAILS}.
+	 */
+	withListeners?: boolean;
+
+	/**
+	 * Whether to request metatags for space details.
+	 *
+	 * @remarks
+	 * - Only works for {@link ResourceType.SPACE_DETAILS}.
+	 */
+	isMetatagsQuery?: boolean;
+
 	/**
 	 * The sorting to use for tweet results.
 	 *
@@ -132,6 +156,22 @@ export interface IFetchArgs {
 	showVerifiedFollowers?: boolean;
 }
 
+/**
+ * Options specifying the data that is to be fetched for space details.
+ *
+ * @public
+ */
+export interface ISpaceDetailsOptions {
+	/** Whether to include replay information. */
+	withReplays?: boolean;
+
+	/** Whether to include listeners information. */
+	withListeners?: boolean;
+
+	/** Whether the request is a metatags query. */
+	isMetatagsQuery?: boolean;
+}
+
 /**
  * The filter to be used for searching tweets.
  *

package/src/types/args/PostArgs.ts

@@ -20,9 +20,20 @@ export interface IPostArgs {
 	 * - {@link ResourceType.TWEET_UNRETWEET}
 	 * - {@link ResourceType.USER_FOLLOW}
 	 * - {@link ResourceType.USER_UNFOLLOW}
+	 *
+	 * For {@link ResourceType.USER_USERNAME_CHANGE}, use {@link IPostArgs.username}.
+	 * `id` is still accepted for backward compatibility.
 	 */
 	id?: string;
 
+	/**
+	 * The new username to set.
+	 *
+	 * @remarks
+	 * Required only when changing username using {@link ResourceType.USER_USERNAME_CHANGE}.
+	 */
+	username?: string;
+
 	/**
 	 * The tweet that is to be posted.
 	 *
@@ -67,6 +78,30 @@ export interface IPostArgs {
 	 * Required only when updating user profile using {@link ResourceType.USER_PROFILE_UPDATE}
 	 */
 	profileOptions?: IProfileUpdateOptions;
+
+	/**
+	 * Base64-encoded profile image data.
+	 *
+	 * @remarks
+	 * Required only when updating profile image using {@link ResourceType.USER_PROFILE_IMAGE_UPDATE}.
+	 */
+	profileImage?: string;
+
+	/**
+	 * Base64-encoded profile banner data.
+	 *
+	 * @remarks
+	 * Required only when updating profile banner using {@link ResourceType.USER_PROFILE_BANNER_UPDATE}.
+	 */
+	profileBanner?: string;
+
+	/**
+	 * Password change arguments.
+	 *
+	 * @remarks
+	 * Required only when changing password using {@link ResourceType.USER_PASSWORD_CHANGE}.
+	 */
+	changePassword?: IChangePasswordArgs;
 }
 
 /**
@@ -98,7 +133,8 @@ export interface INewTweet {
 	 * The text for the tweet to be created.
 	 *
 	 * @remarks
-	 * Length of the tweet must be \<= 280 characters.
+	 * Length of the tweet must be \<= 280 characters for non-premium accounts.
+	 * X Premium (Blue) accounts can post longer tweets (up to 25,000 characters).
 	 */
 	text?: string;
 }
@@ -140,3 +176,16 @@ export interface IUploadArgs {
 	 */
 	size?: number;
 }
+
+/**
+ * Arguments for changing the account password.
+ *
+ * @public
+ */
+export interface IChangePasswordArgs {
+	/** The current account password. */
+	currentPassword: string;
+
+	/** The new password to set. */
+	newPassword: string;
+}