rettiwt-api 6.0.8 → 6.1.0

package/src/requests/DirectMessage.ts

@@ -0,0 +1,233 @@
+import qs from 'querystring';
+
+import { AxiosRequestConfig } from 'axios';
+
+/**
+ * Common parameter sets for DM requests
+ */
+const BaseDMParams = {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	nsfw_filtering_enabled: false,
+	filter_low_quality: true,
+	include_quality: 'all',
+	dm_secret_conversations_enabled: false,
+	krs_registration_enabled: false,
+	cards_platform: 'Web-12',
+	include_cards: 1,
+	include_ext_alt_text: true,
+	include_ext_limited_action_results: true,
+	include_quote_count: true,
+	include_reply_count: 1,
+	tweet_mode: 'extended',
+	include_ext_views: true,
+	include_groups: true,
+	include_inbox_timelines: true,
+	include_ext_media_color: true,
+	supports_reactions: true,
+	supports_edit: true,
+	include_ext_edit_control: true,
+	include_ext_business_affiliations_label: true,
+	ext: 'mediaColor%2CaltText%2CbusinessAffiliationsLabel%2CmediaStats%2ChighlightedLabel%2CparodyCommentaryFanLabel%2CvoiceInfo%2CbirdwatchPivot%2CsuperFollowMetadata%2CunmentionInfo%2CeditControl%2Carticle',
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+};
+
+const DMUserIncludeParams = {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	include_profile_interstitial_type: 1,
+	include_blocking: 1,
+	include_blocked_by: 1,
+	include_followed_by: 1,
+	include_want_retweets: 1,
+	include_mute_edge: 1,
+	include_can_dm: 1,
+	include_can_media_tag: 1,
+	include_ext_is_blue_verified: 1,
+	include_ext_verified_type: 1,
+	include_ext_profile_image_shape: 1,
+	skip_status: 1,
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+};
+
+/**
+ * Collection of requests related to direct messages.
+ *
+ * @public
+ */
+export class DMRequests {
+	/**
+	 * Get a specific DM conversation
+	 * @param conversationId - The conversation ID (e.g., "394028042-1712730991884689408")
+	 * @param maxId - Maximum ID for pagination (optional)
+	 */
+	public static conversation(conversationId: string, maxId?: string): AxiosRequestConfig {
+		const context = maxId ? 'FETCH_DM_CONVERSATION_HISTORY' : 'FETCH_DM_CONVERSATION';
+
+		return {
+			method: 'get',
+			url: `https://x.com/i/api/1.1/dm/conversation/${conversationId}.json`,
+			params: {
+				...BaseDMParams,
+				...DMUserIncludeParams,
+				/* eslint-disable @typescript-eslint/naming-convention */
+				max_id: maxId,
+				context: context,
+				dm_users: false,
+				include_conversation_info: true,
+				/* eslint-enable @typescript-eslint/naming-convention */
+			},
+			paramsSerializer: { encode: encodeURIComponent },
+		};
+	}
+
+	/**
+	 * Delete a DM conversation
+	 * @param conversationId - The ID of the conversation to delete
+	 */
+	public static deleteConversation(conversationId: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: `https://x.com/i/api/1.1/dm/${conversationId}/delete.json`,
+			data: qs.stringify({
+				/* eslint-disable @typescript-eslint/naming-convention */
+				dm_secret_conversations_enabled: false,
+				krs_registration_enabled: false,
+				cards_platform: 'Web-12',
+				include_cards: 1,
+				include_ext_alt_text: true,
+				include_ext_limited_action_results: true,
+				include_quote_count: true,
+				include_reply_count: 1,
+				tweet_mode: 'extended',
+				include_ext_views: true,
+				dm_users: false,
+				include_groups: true,
+				include_inbox_timelines: true,
+				include_ext_media_color: true,
+				supports_reactions: true,
+				supports_edit: true,
+				include_conversation_info: true,
+			}),
+		};
+	}
+
+	/**
+	 * Get the initial state of the DM inbox
+	 */
+	public static inboxInitial(): AxiosRequestConfig {
+		return {
+			method: 'get',
+			url: 'https://x.com/i/api/1.1/dm/inbox_initial_state.json',
+			params: {
+				...BaseDMParams,
+				...DMUserIncludeParams,
+				/* eslint-disable @typescript-eslint/naming-convention */
+				dm_users: true,
+				include_ext_parody_commentary_fan_label: true,
+				ext: 'mediaColor%2CaltText%2CmediaStats%2ChighlightedLabel%2CparodyCommentaryFanLabel%2CvoiceInfo%2CbirdwatchPivot%2CsuperFollowMetadata%2CunmentionInfo%2CeditControl%2Carticle',
+			},
+			paramsSerializer: { encode: encodeURIComponent },
+		};
+	}
+
+	/**
+	 * Get inbox timeline (pagination of conversations)
+	 * @param maxId - Maximum ID for pagination
+	 */
+	public static inboxTimeline(maxId?: string): AxiosRequestConfig {
+		return {
+			method: 'get',
+			url: 'https://x.com/i/api/1.1/dm/inbox_timeline/trusted.json',
+			params: {
+				...BaseDMParams,
+				...DMUserIncludeParams,
+				/* eslint-disable @typescript-eslint/naming-convention */
+				max_id: maxId,
+				dm_users: false,
+			},
+			paramsSerializer: { encode: encodeURIComponent },
+		};
+	}
+
+	/**
+	 * Create a new DM or get DM creation interface
+	 */
+	// public static new(): AxiosRequestConfig {
+	// 	return {
+	// 		method: 'get',
+	// 		url: 'https://x.com/i/api/1.1/dm/new2.json',
+	// 		params: {
+	// 			/* eslint-disable @typescript-eslint/naming-convention */
+	// 			ext: 'mediaColor%2CaltText%2CmediaStats%2ChighlightedLabel%2CparodyCommentaryFanLabel%2CvoiceInfo%2CbirdwatchPivot%2CsuperFollowMetadata%2CunmentionInfo%2CeditControl%2Carticle',
+	// 			include_ext_alt_text: true,
+	// 			include_ext_limited_action_results: true,
+	// 			include_reply_count: 1,
+	// 			tweet_mode: 'extended',
+	// 			include_ext_views: true,
+	// 			include_groups: true,
+	// 			include_inbox_timelines: true,
+	// 			include_ext_media_color: true,
+	// 			supports_reactions: true,
+	// 			supports_edit: true,
+	// 		},
+	// 		paramsSerializer: { encode: encodeURIComponent },
+	// 	};
+	// }
+
+	/**
+	 * Check DM permissions for specific recipients
+	 * @param recipientIds - Array of recipient user IDs
+	 */
+	// public static permissions(recipientIds: string[]): AxiosRequestConfig {
+	// 	return {
+	// 		method: 'get',
+	// 		url: 'https://x.com/i/api/1.1/dm/permissions.json',
+	// 		params: {
+	// 			/* eslint-disable @typescript-eslint/naming-convention */
+	// 			recipient_ids: recipientIds.join(','),
+	// 			dm_users: true,
+	// 		},
+	// 		paramsSerializer: { encode: encodeURIComponent },
+	// 	};
+	// }
+
+	/**
+	 * Update the last seen event ID for a conversation
+	 * @param lastSeenEventId - The ID of the last seen event
+	 * @param trustedLastSeenEventId - The trusted last seen event ID (usually same as lastSeenEventId)
+	 */
+	// public static updateLastSeenEventId(lastSeenEventId: string, trustedLastSeenEventId?: string): AxiosRequestConfig {
+	// 	return {
+	// 		method: 'post',
+	// 		url: 'https://x.com/i/api/1.1/dm/update_last_seen_event_id.json',
+	// 		data: qs.stringify({
+	// 			/* eslint-disable @typescript-eslint/naming-convention */
+	// 			last_seen_event_id: lastSeenEventId,
+	// 			trusted_last_seen_event_id: trustedLastSeenEventId ?? lastSeenEventId,
+	// 		}),
+	// 	};
+	// }
+
+	/**
+	 * Get user updates for DMs (polling for new messages)
+	 * @param cursor - Cursor for pagination
+	 * @param activeConversationId - ID of the currently active conversation
+	 */
+	// public static userUpdates(cursor?: string, activeConversationId?: string): AxiosRequestConfig {
+	// 	return {
+	// 		method: 'get',
+	// 		url: 'https://x.com/i/api/1.1/dm/user_updates.json',
+	// 		params: {
+	// 			...DM_BASE_PARAMS,
+	// 			/* eslint-disable @typescript-eslint/naming-convention */
+	// 			cursor: cursor,
+	// 			active_conversation_id: activeConversationId,
+	// 			dm_users: false,
+	// 		},
+	// 		paramsSerializer: { encode: encodeURIComponent },
+	// 	};
+	// }
+}

package/src/requests/List.ts

@@ -6,6 +6,35 @@ import { AxiosRequestConfig } from 'axios';
  * @public
  */
 export class ListRequests {
+	/**
+	 * @param listId - The ID of the target list.
+	 * @param userId - The ID of the user to be added as a member.
+	 */
+	public static addMember(listId: string, userId: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/graphql/uFQumgzNDR27zs0yK5J3Fw/ListAddMember',
+			data: {
+				/* eslint-disable @typescript-eslint/naming-convention */
+
+				variables: {
+					listId: listId,
+					userId: userId,
+				},
+				features: {
+					payments_enabled: false,
+					profile_label_improvements_pcf_label_in_post_enabled: false,
+					rweb_tipjar_consumption_enabled: false,
+					verified_phone_label_enabled: false,
+					responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+					responsive_web_graphql_timeline_navigation_enabled: false,
+				},
+
+				/* eslint-enable @typescript-eslint/naming-convention */
+			},
+		};
+	}
+
 	/**
 	 * @param id - The id of the list whose details are to be fetched.
 	 */
@@ -83,6 +112,35 @@ export class ListRequests {
 		};
 	}
 
+	/**
+	 * @param listId - The ID of the target list.
+	 * @param userId - The ID of the user to remove as a member.
+	 */
+	public static removeMember(listId: string, userId: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/graphql/IzgPnK3wZpNgpcN31ry3Xg/ListRemoveMember',
+			data: {
+				/* eslint-disable @typescript-eslint/naming-convention */
+
+				variables: {
+					listId: listId,
+					userId: userId,
+				},
+				features: {
+					payments_enabled: false,
+					profile_label_improvements_pcf_label_in_post_enabled: false,
+					rweb_tipjar_consumption_enabled: false,
+					verified_phone_label_enabled: false,
+					responsive_web_graphql_skip_user_profile_image_extensions_enabled: false,
+					responsive_web_graphql_timeline_navigation_enabled: false,
+				},
+
+				/* eslint-enable @typescript-eslint/naming-convention */
+			},
+		};
+	}
+
 	/**
 	 * @param id - The id of the list whose tweets are to be fetched.
 	 * @param count - The number of tweets to fetch. Must be \<= 100.

package/src/requests/Tweet.ts

@@ -13,6 +13,21 @@ import { INewTweet } from '../types/args/PostArgs';
  * @public
  */
 export class TweetRequests {
+	/**
+	 * @param id - The ID of the tweet to bookmark
+	 */
+	public static bookmark(id: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/graphql/aoDbu3RHznuiSkQ9aNM67Q/CreateBookmark',
+			data: {
+				/* eslint-disable @typescript-eslint/naming-convention */
+				variables: JSON.stringify({ tweet_id: id }),
+				/* eslint-enable @typescript-eslint/naming-convention */
+			},
+		};
+	}
+
 	/**
 	 * @param ids - The IDs of the tweets whose details are to be fetched.
 	 */
@@ -501,6 +516,23 @@ export class TweetRequests {
 		};
 	}
 
+	/**
+	 * @param id - The id of the tweet to be unbookmarked.
+	 */
+	public static unbookmark(id: string): AxiosRequestConfig {
+		return {
+			method: 'post',
+			url: 'https://x.com/i/api/graphql/Wlmlj2-xzyS1GN3a6cj-mQ/DeleteBookmark',
+			data: {
+				/* eslint-disable @typescript-eslint/naming-convention */
+				variables: {
+					tweet_id: id,
+				},
+				/* eslint-enable @typescript-eslint/naming-convention */
+			},
+		};
+	}
+
 	/**
 	 * @param id - The id of the tweet to be unliked.
 	 */

package/src/requests/User.ts

@@ -73,23 +73,31 @@ export class UserRequests {
 	 * @param toTime - The end time of the analytic data to be fetched.
 	 * @param granularity - The granularity of the analytic data to be fetched.
 	 * @param requestedMetrics - The metrics to be fetched.
+	 * @param showVerifiedFollowers - Whether to show verified followers in the analytics.
 	 */
 	public static analytics(
 		fromTime: Date,
 		toTime: Date,
 		granularity: RawAnalyticsGranularity,
 		requestedMetrics: RawAnalyticsMetric[],
+		showVerifiedFollowers: boolean,
 	): AxiosRequestConfig {
+		console.log(
+			`Fetching analytics from ${fromTime?.toString()} to ${toTime?.toString()} with granularity ${granularity} and metrics ${requestedMetrics.join(', ')}`,
+		);
 		return {
 			method: 'get',
-			url: 'https://x.com/i/api/graphql/NlJ6RM-hgHxt-iu9cPQz7A/overviewDataUserQuery',
+			url: 'https://x.com/i/api/graphql/LwtiA7urqM6eDeBheAFi5w/AccountOverviewQuery',
 			params: {
-				/* eslint-disable @typescript-eslint/naming-convention */
-				from_time: fromTime,
-				to_time: toTime,
-				granularity: granularity,
-				requested_metrics: requestedMetrics,
-				/* eslint-enable @typescript-eslint/naming-convention */
+				variables: JSON.stringify({
+					/* eslint-disable @typescript-eslint/naming-convention */
+					from_time: fromTime,
+					to_time: toTime,
+					granularity: granularity,
+					requested_metrics: requestedMetrics,
+					show_verified_followers: showVerifiedFollowers,
+					/* eslint-enable @typescript-eslint/naming-convention */
+				}),
 			},
 			paramsSerializer: { encode: encodeURIComponent },
 		};
@@ -539,6 +547,61 @@ export class UserRequests {
 		};
 	}
 
+	/**
+	 * @param id - The id of the user whose lists are to be fetched.
+	 * @param count - The number of lists to fetch. Only works as a lower limit when used with a cursor.
+	 * @param cursor - The cursor to the batch of lists to fetch.
+	 */
+	public static lists(id: string, count?: number, cursor?: string): AxiosRequestConfig {
+		return {
+			method: 'get',
+			url: 'https://x.com/i/api/graphql/tZg2CHWw-NAL0nKO2Q-P4Q/ListsManagementPageTimeline',
+			params: {
+				/* eslint-disable @typescript-eslint/naming-convention */
+				variables: JSON.stringify({ count: 100, cursor: cursor }),
+				features: JSON.stringify({
+					rweb_video_screen_enabled: false,
+					payments_enabled: false,
+					rweb_xchat_enabled: false,
+					profile_label_improvements_pcf_label_in_post_enabled: true,
+					rweb_tipjar_consumption_enabled: true,
+					verified_phone_label_enabled: true,
+					creator_subscriptions_tweet_preview_api_enabled: true,
+					responsive_web_graphql_timeline_navigation_enabled: true,
+					responsive_web_graphql_skip_user_profile_image_extensions_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,
+					articles_preview_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,
+					responsive_web_grok_show_grok_translated_post: false,
+					responsive_web_grok_analysis_button_from_backend: 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_community_note_auto_translation_is_enabled: false,
+					responsive_web_enhance_cards_enabled: false,
+				}),
+				fieldToggles: { withArticlePlainText: false },
+				/* eslint-enable @typescript-eslint/naming-convention */
+			},
+			paramsSerializer: { encode: encodeURIComponent },
+		};
+	}
+
 	/**
 	 * @param id - The id of the user whose media is to be fetched.
 	 * @param count - The number of media to fetch. Only works as a lower limit when used with a cursor.

package/src/services/public/DirectMessageService.ts

@@ -0,0 +1,159 @@
+import { Extractors } from '../../collections/Extractors';
+import { ResourceType } from '../../enums/Resource';
+import { Conversation } from '../../models/data/Conversation';
+import { Inbox } from '../../models/data/Inbox';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IConversationTimelineResponse } from '../../types/raw/dm/Conversation';
+import { IInboxInitialResponse } from '../../types/raw/dm/InboxInitial';
+import { IInboxTimelineResponse } from '../../types/raw/dm/InboxTimeline';
+
+import { FetcherService } from './FetcherService';
+
+/**
+ * Handles interacting with resources related to direct messages
+ *
+ * @public
+ */
+export class DirectMessageService extends FetcherService {
+	/**
+	 * @param config - The config object for configuring the Rettiwt instance.
+	 *
+	 * @internal
+	 */
+	public constructor(config: RettiwtConfig) {
+		super(config);
+	}
+
+	/**
+	 * Get the full conversation history for a specific conversation, ordered recent to oldest.
+	 * Use this to load complete message history for a conversation identified from the inbox.
+	 *
+	 * @param conversationId - The ID of the conversation (e.g., "394028042-1712730991884689408").
+	 * @param cursor - The cursor for pagination. Is equal to the ID of the last message from previous batch.
+	 *
+	 * @returns The conversation with full message history, or undefined if not found.
+	 *
+	 * @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 a specific conversation
+	 * rettiwt.dm.conversation('394028042-1712730991884689408')
+	 * .then(conversation => {
+	 * 	if (conversation) {
+	 * 		console.log(`Conversation with ${conversation.participants.length} participants`);
+	 * 		console.log(`${conversation.messages.length} messages loaded`);
+	 * 	}
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async conversation(conversationId: string, cursor?: string): Promise<Conversation | undefined> {
+		const resource = ResourceType.DM_CONVERSATION;
+
+		// Fetching raw conversation timeline
+		const response = await this.request<IConversationTimelineResponse>(resource, {
+			conversationId,
+			maxId: cursor,
+		});
+
+		// Deserializing response
+		const data = Extractors[resource](response);
+
+		return data;
+	}
+
+	/**
+	 * Delete a conversation.
+	 * You will leave the conversation and it will be removed from your inbox.
+	 *
+	 * @param conversationId - The ID of the conversation to delete.
+	 *
+	 * @returns A promise that resolves when the conversation is deleted.
+	 *
+	 * @example
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 * // Deleting a conversation
+	 * rettiwt.dm.deleteConversation('394028042-1712730991884689408')
+	 * .then(() => {
+	 * 	console.log('Conversation deleted successfully');
+	 * })
+	 * .catch(err => {
+	 *  console.log('Failed to delete conversation:', err);
+	 * 	});
+	 * ```
+	 **/
+	public async deleteConversation(conversationId: string): Promise<void> {
+		const resource = ResourceType.DM_DELETE_CONVERSATION;
+
+		// Sending delete request
+		await this.request<void>(resource, {
+			conversationId,
+		});
+	}
+
+	/**
+	 * Get your inbox, ordered recent to oldest.
+	 *
+	 * @param cursor - The cursor to the inbox items to fetch. Is equal to the ID of the last inbox conversation.
+	 *
+	 * @returns The required inbox. Returns initial inbox if no cursor is provided.
+	 *
+	 * @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 initial DM inbox state
+	 * rettiwt.dm.inbox()
+	 * .then(inbox => {
+	 * 	console.log(`Found ${inbox.conversations.length} conversations`);
+	 * 	console.log('First conversation:', inbox.conversations[0]);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async inbox(cursor?: string): Promise<Inbox> {
+		// If cursor is provided, fetch initial inbox
+		if (cursor !== undefined) {
+			const resource = ResourceType.DM_INBOX_TIMELINE;
+
+			// Fetching raw inbox timeline
+			const response = await this.request<IInboxTimelineResponse>(resource, {
+				maxId: cursor,
+			});
+
+			// Deserializing response
+			const data = Extractors[resource](response);
+
+			return data;
+		}
+		// Else, fetch next inbox data
+		else {
+			const resource = ResourceType.DM_INBOX_INITIAL_STATE;
+
+			// Fetching raw inbox initial state
+			const response = await this.request<IInboxInitialResponse>(resource, {});
+
+			// Deserializing response
+			const data = Extractors[resource](response);
+
+			return data;
+		}
+	}
+}

package/src/services/public/FetcherService.ts

@@ -262,13 +262,13 @@ export class FetcherService {
 	 *
 	 * #### Fetching the raw details of a single user, using their username
 	 * ```ts
-	 * import { FetcherService, EResourceType } from 'rettiwt-api';
+	 * 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(EResourceType.USER_DETAILS_BY_USERNAME, { id: 'user1' })
+	 * fetcher.request(ResourceType.USER_DETAILS_BY_USERNAME, { id: 'user1' })
 	 * .then(res => {
 	 * 	console.log(res);
 	 * })