@youmind-openlab/rettiwt-api 1.0.3 → 1.0.4

package/src/services/public/UserService.ts

@@ -1,7 +1,12 @@
+import axios from 'axios';
+
+import { Cookie } from 'cookiejar';
+
 import { Extractors } from '../../collections/Extractors';
 import { RawAnalyticsGranularity, RawAnalyticsMetric } from '../../enums/raw/Analytics';
 import { ResourceType } from '../../enums/Resource';
 import { ProfileUpdateOptions } from '../../models/args/ProfileArgs';
+import { AuthCredential } from '../../models/auth/AuthCredential';
 import { Analytics } from '../../models/data/Analytics';
 import { BookmarkFolder } from '../../models/data/BookmarkFolder';
 import { CursoredData } from '../../models/data/CursoredData';
@@ -18,6 +23,7 @@ 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';
@@ -32,11 +38,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';
 
 /**
@@ -54,6 +63,149 @@ export class UserService extends FetcherService {
 		super(config);
 	}
 
+	private _base64ByteSize(base64Data: string): number {
+		const paddingMatch = base64Data.match(/=+$/);
+		const paddingLength = paddingMatch ? paddingMatch[0].length : 0;
+
+		return (base64Data.length * 3) / 4 - paddingLength;
+	}
+
+	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 _refreshApiKeyFromResponseCookies(setCookieHeader: string | string[] | undefined): void {
+		if (!this.config.apiKey || !setCookieHeader) {
+			return;
+		}
+
+		const requiredCookieNames = new Set(['auth_token', 'ct0', 'kdt', 'twid']);
+		const currentCookieString = AuthService.decodeCookie(this.config.apiKey);
+		const cookiePairs = this._splitSetCookieHeader(setCookieHeader);
+		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 cookiePair of cookiePairs) {
+			const cookieValuePair = cookiePair.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 {
+			this.config.apiKey = AuthService.encodeCookie(mergedCookieString);
+		} catch {
+			// Ignore cookie rotation errors and leave existing apiKey unchanged.
+		}
+	}
+
+	/**
+	 * Fetches a fresh ct0 (CSRF token) from Twitter by making a lightweight
+	 * authenticated request, then rotates the apiKey with the updated cookie.
+	 */
+	private async _refreshCsrfToken(): Promise<void> {
+		if (!this.config.apiKey) {
+			return;
+		}
+
+		try {
+			const cred = new AuthCredential(
+				AuthService.decodeCookie(this.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: this.config.httpsAgent,
+				httpsAgent: this.config.httpsAgent,
+				validateStatus: () => true,
+			});
+
+			this._refreshApiKeyFromResponseCookies(refreshResponse.headers['set-cookie']);
+		} catch {
+			// Best-effort: if ct0 refresh fails, leave apiKey as-is
+		}
+	}
+
+	private _splitSetCookieHeader(setCookieHeader: string | string[]): string[] {
+		if (Array.isArray(setCookieHeader)) {
+			return setCookieHeader;
+		}
+
+		return setCookieHeader.split(/,(?=\s*[^;,]+=)/g);
+	}
+
+	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.
 	 *
@@ -319,6 +471,67 @@ export class UserService extends FetcherService {
 		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;
+
+		const response = await this.requestWithResponse<IUserChangePasswordResponse>(resource, {
+			changePassword: { currentPassword, newPassword },
+		});
+
+		const data = Extractors[resource](response.data) ?? false;
+		if (data) {
+			this._refreshApiKeyFromResponseCookies(response.headers['set-cookie']);
+			await this._refreshCsrfToken();
+		}
+
+		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');
+		}
+
+		const response = await this.request<IUserSettingsResponse>(resource, {
+			username,
+		});
+
+		const updatedUsername = Extractors[resource](response);
+
+		return updatedUsername?.toLowerCase() === username.toLowerCase();
+	}
+
 	/**
 	 * Get the details of the logged in user.
 	 *
@@ -1194,4 +1407,56 @@ export class UserService extends FetcherService {
 
 		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) ?? 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) ?? false;
+
+		return data;
+	}
 }

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;
 }
@@ -143,3 +179,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;
+}

package/src/types/raw/tweet/Post.ts

@@ -10,7 +10,8 @@ export interface ITweetPostResponse {
 }
 
 interface Data {
-	create_tweet: CreateTweet;
+	create_tweet?: CreateTweet;
+	create_note_tweet?: CreateTweet;
 }
 
 interface CreateTweet {
@@ -148,3 +149,20 @@ interface UserMention {
 }
 
 interface UnmentionInfo {}
+
+/**
+ * The raw data received after creating a note tweet (long-form tweet for X Premium accounts).
+ *
+ * @public
+ */
+export interface ITweetPostNoteResponse {
+	data: NoteTweetData;
+}
+
+interface NoteTweetData {
+	notetweet_create: NoteTweetCreate;
+}
+
+interface NoteTweetCreate {
+	tweet_results: TweetResults;
+}

package/src/types/raw/user/ChangePassword.ts

@@ -0,0 +1,8 @@
+/**
+ * The raw data received when changing the account password.
+ *
+ * @public
+ */
+export interface IUserChangePasswordResponse {
+	status: string;
+}

package/src/types/raw/user/ProfileUpdate.ts

@@ -39,6 +39,7 @@ export interface IUserProfileUpdateResponse {
 	profile_image_url: string;
 	profile_image_url_https: string;
 	profile_banner_url: string;
+	profile_banner_url_https?: string;
 	profile_link_color: string;
 	profile_sidebar_border_color: string;
 	profile_sidebar_fill_color: string;

package/src/types/raw/user/Settings.ts

@@ -0,0 +1,23 @@
+/* eslint-disable @typescript-eslint/naming-convention, @typescript-eslint/no-explicit-any */
+
+/**
+ * The raw data received from the account settings endpoint.
+ *
+ * @public
+ */
+export interface IUserSettingsResponse {
+	screen_name: string;
+	protected: boolean;
+	language: string;
+	geo_enabled: boolean;
+	discoverable_by_email: boolean;
+	discoverable_by_mobile_phone: boolean;
+	use_cookie_personalization: boolean;
+	sleep_time: {
+		enabled: boolean;
+		end_time: any;
+		start_time: any;
+	};
+	display_sensitive_media: boolean;
+	allow_media_tagging: string;
+}

package/.claude/settings.local.json

@@ -1,9 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(npm run build:*)",
-      "Bash(npm run build:browser:*)",
-      "Bash(npm run build:all:*)"
-    ]
-  }
-}