rettiwt-api 6.3.0-alpha.0 → 7.0.0

package/src/services/public/TweetService.ts

@@ -17,7 +17,7 @@ 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';
+import { ITweetPostNoteResponse, ITweetPostResponse } from '../../types/raw/tweet/Post';
 import { ITweetRepliesResponse } from '../../types/raw/tweet/Replies';
 import { ITweetRetweetResponse } from '../../types/raw/tweet/Retweet';
 import { ITweetRetweetersResponse } from '../../types/raw/tweet/Retweeters';
@@ -80,7 +80,7 @@ export class TweetService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -146,7 +146,7 @@ export class TweetService extends FetcherService {
 			const response = await this.request<ITweetRepliesResponse>(resource, { id: id });
 
 			// Deserializing response
-			const data = Extractors[resource](response, id);
+			const data = Extractors[resource](response.data, id);
 
 			return data as T extends string ? Tweet | undefined : Tweet[];
 		}
@@ -158,7 +158,7 @@ export class TweetService extends FetcherService {
 			const response = await this.request<ITweetDetailsBulkResponse>(resource, { ids: id });
 
 			// Deserializing response
-			const data = Extractors[resource](response, id);
+			const data = Extractors[resource](response.data, id);
 
 			return data as T extends string ? Tweet | undefined : Tweet[];
 		}
@@ -170,7 +170,7 @@ export class TweetService extends FetcherService {
 			const response = await this.request<ITweetDetailsResponse>(resource, { id: String(id) });
 
 			// Deserializing response
-			const data = Extractors[resource](response, String(id));
+			const data = Extractors[resource](response.data, String(id));
 
 			return data as T extends string ? Tweet | undefined : Tweet[];
 		}
@@ -210,7 +210,7 @@ export class TweetService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -253,7 +253,7 @@ export class TweetService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -342,15 +342,18 @@ export class TweetService extends FetcherService {
 	 * ```
 	 */
 	public async post(options: INewTweet): Promise<string | undefined> {
-		const resource = ResourceType.TWEET_POST;
+		// Use CreateNoteTweet endpoint for long-form tweets (X Premium, >280 chars)
+		if ((options.text?.length ?? 0) > 280) {
+			const response = await this.request<ITweetPostNoteResponse>(ResourceType.TWEET_POST_NOTE, {
+				tweet: options,
+			});
 
-		// Posting the tweet
-		const response = await this.request<ITweetPostResponse>(resource, { tweet: options });
+			return Extractors[ResourceType.TWEET_POST_NOTE](response.data);
+		}
 
-		// Deserializing response
-		const data = Extractors[resource](response);
+		const response = await this.request<ITweetPostResponse>(ResourceType.TWEET_POST, { tweet: options });
 
-		return data;
+		return Extractors[ResourceType.TWEET_POST](response.data);
 	}
 
 	/**
@@ -403,7 +406,7 @@ export class TweetService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -440,7 +443,7 @@ export class TweetService extends FetcherService {
 		const response = await this.request<ITweetRetweetResponse>(resource, { id: id });
 
 		// Deserializing response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -483,7 +486,7 @@ export class TweetService extends FetcherService {
 		});
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -525,7 +528,7 @@ export class TweetService extends FetcherService {
 		const response = await this.request<ITweetScheduleResponse>(resource, { tweet: options });
 
 		// Deserializing response
-		const data = Extractors[resource](response);
+		const data = Extractors[resource](response.data);
 
 		return data;
 	}
@@ -573,7 +576,7 @@ export class TweetService 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());
@@ -682,7 +685,7 @@ export class TweetService extends FetcherService {
 		const response = await this.request<ITweetUnbookmarkResponse>(resource, { id: id });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -719,7 +722,7 @@ export class TweetService extends FetcherService {
 		const response = await this.request<ITweetUnlikeResponse>(resource, { id: id });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -756,7 +759,7 @@ export class TweetService extends FetcherService {
 		const response = await this.request<ITweetUnpostResponse>(resource, { id: id });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -793,7 +796,7 @@ export class TweetService extends FetcherService {
 		const response = await this.request<ITweetUnretweetResponse>(resource, { id: id });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -830,7 +833,7 @@ export class TweetService extends FetcherService {
 		const response = await this.request<ITweetUnscheduleResponse>(resource, { id: id });
 
 		// Deserializing the response
-		const data = Extractors[resource](response) ?? false;
+		const data = Extractors[resource](response.data) ?? false;
 
 		return data;
 	}
@@ -873,7 +876,7 @@ export class TweetService extends FetcherService {
 			await this.request<IMediaInitializeUploadResponse>(ResourceType.MEDIA_UPLOAD_INITIALIZE, {
 				upload: { size: size },
 			})
-		).media_id_string;
+		).data.media_id_string;
 
 		// APPEND
 		await this.request<unknown>(ResourceType.MEDIA_UPLOAD_APPEND, { upload: { id: id, media: media } });

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;