rettiwt-api 6.0.8 → 6.1.0

package/src/models/data/DirectMessage.ts

@@ -0,0 +1,335 @@
+import { IDirectMessage } from '../../types/data/DirectMessage';
+import { IMessage as IRawMessage } from '../../types/raw/base/Message';
+import { IConversationTimelineResponse } from '../../types/raw/dm/Conversation';
+import { IInboxInitialResponse } from '../../types/raw/dm/InboxInitial';
+import { IInboxTimelineResponse } from '../../types/raw/dm/InboxTimeline';
+
+/**
+ * Type guard to check if the response is an IInboxInitialResponse
+ */
+function isInboxInitialResponse(
+	response: IInboxInitialResponse | IConversationTimelineResponse | IInboxTimelineResponse,
+): response is IInboxInitialResponse {
+	return 'inbox_initial_state' in response;
+}
+
+/**
+ * Type guard to check if the response is an IConversationTimelineResponse
+ */
+function isConversationTimelineResponse(
+	response: IInboxInitialResponse | IConversationTimelineResponse | IInboxTimelineResponse,
+): response is IConversationTimelineResponse {
+	return 'conversation_timeline' in response;
+}
+
+/**
+ * Type guard to check if the response is an IInboxTimelineResponse
+ */
+function isInboxTimelineResponse(
+	response: IInboxInitialResponse | IConversationTimelineResponse | IInboxTimelineResponse,
+): response is IInboxTimelineResponse {
+	return 'inbox_timeline' in response;
+}
+
+/**
+ * The details of a single direct message.
+ *
+ * @public
+ */
+export class DirectMessage implements IDirectMessage {
+	/** The raw message details. */
+	private readonly _raw: IRawMessage;
+
+	public conversationId: string;
+	public createdAt: string;
+	public editCount?: number;
+	public id: string;
+	public mediaUrls?: string[];
+	public read?: boolean;
+	public recipientId?: string;
+	public senderId: string;
+	public text: string;
+
+	/**
+	 * @param message - The raw message details from the API response.
+	 */
+	public constructor(message: unknown) {
+		this._raw = message as IRawMessage;
+
+		const parsedData = this._parseMessageData(message);
+
+		this.id = parsedData.id;
+		this.conversationId = parsedData.conversationId;
+		this.senderId = parsedData.senderId;
+		this.recipientId = parsedData.recipientId;
+		this.text = parsedData.text;
+		this.createdAt = parsedData.createdAt;
+		this.editCount = parsedData.editCount ?? 0;
+		this.mediaUrls = this._extractMediaUrls(message);
+		this.read = true; // Default to true, can be enhanced later
+	}
+
+	/** The raw message details. */
+	public get raw(): IRawMessage {
+		return this._raw;
+	}
+
+	/**
+	 * Extract messages from conversation timeline response
+	 */
+	private static _extractFromConversationTimeline(response: IConversationTimelineResponse): DirectMessage[] {
+		const messages: DirectMessage[] = [];
+		const entries = response.conversation_timeline?.entries ?? [];
+
+		for (const entry of entries) {
+			if ('message' in entry && entry.message) {
+				messages.push(new DirectMessage(entry.message));
+			}
+		}
+
+		return messages;
+	}
+
+	/**
+	 * Extract messages from inbox initial response
+	 */
+	private static _extractFromInboxInitial(response: IInboxInitialResponse): DirectMessage[] {
+		const messages: DirectMessage[] = [];
+		const entries = response.inbox_initial_state?.entries ?? [];
+
+		for (const entry of entries) {
+			if ('message' in entry && entry.message) {
+				messages.push(new DirectMessage(entry.message));
+			}
+		}
+
+		return messages;
+	}
+
+	/**
+	 * Extract messages from inbox timeline response
+	 */
+	private static _extractFromInboxTimeline(response: IInboxTimelineResponse): DirectMessage[] {
+		const messages: DirectMessage[] = [];
+		const entries = response.inbox_timeline?.entries ?? [];
+
+		for (const entry of entries) {
+			if ('message' in entry && entry.message) {
+				messages.push(new DirectMessage(entry.message));
+			}
+		}
+
+		return messages;
+	}
+
+	/**
+	 * Extract media URLs from message attachment data with proper type safety.
+	 */
+	private _extractMediaUrls(message: unknown): string[] | undefined {
+		const urls: string[] = [];
+		const msg = message as Record<string, unknown>;
+		const messageData = msg.message_data as Record<string, unknown> | undefined;
+
+		// Check for card attachments with images
+		const attachment = messageData?.attachment as Record<string, unknown> | undefined;
+		const card = attachment?.card as Record<string, unknown> | undefined;
+		const bindingValues = card?.binding_values as Record<string, unknown> | undefined;
+
+		if (bindingValues) {
+			// Extract URLs from various image binding values
+			const imageBindings = [
+				'thumbnail_image',
+				'photo_image_full_size',
+				'summary_photo_image',
+				'thumbnail_image_original',
+				'summary_photo_image_original',
+				'photo_image_full_size_original',
+			];
+
+			for (const bindingKey of imageBindings) {
+				const imageBinding = bindingValues[bindingKey] as Record<string, unknown> | undefined;
+				const imageValue = imageBinding?.image_value as Record<string, unknown> | undefined;
+
+				if (imageValue?.url && typeof imageValue.url === 'string') {
+					urls.push(imageValue.url);
+				}
+			}
+		}
+
+		// Check for tweet attachments
+		const tweet = attachment?.tweet as Record<string, unknown> | undefined;
+		if (tweet?.expanded_url && typeof tweet.expanded_url === 'string') {
+			urls.push(tweet.expanded_url);
+		}
+
+		return urls.length > 0 ? [...new Set(urls)] : undefined; // Remove duplicates
+	}
+
+	/**
+	 * Safely extract number value
+	 */
+	private _extractNumberValue(value: unknown): number | undefined {
+		if (typeof value === 'number') {
+			return value;
+		}
+		if (typeof value === 'string') {
+			const parsed = Number(value);
+			return isNaN(parsed) ? undefined : parsed;
+		}
+		return undefined;
+	}
+
+	/**
+	 * Safely extract string value with fallback
+	 */
+	private _extractStringValue(...values: unknown[]): string | undefined {
+		for (const value of values) {
+			if (typeof value === 'string' && value.length > 0) {
+				return value;
+			}
+		}
+		return undefined;
+	}
+
+	/**
+	 * Parse message data with proper type safety
+	 */
+	private _parseMessageData(message: unknown): IDirectMessage {
+		const msg = message as Record<string, unknown>;
+		const messageData = msg.message_data as Record<string, unknown> | undefined;
+
+		const id = this._extractStringValue(messageData?.id, msg.id) ?? '';
+		const conversationId = this._extractStringValue(msg.conversation_id, messageData?.conversation_id) ?? '';
+		const senderId = this._extractStringValue(messageData?.sender_id, msg.sender_id) ?? '';
+		const recipientId = this._extractStringValue(messageData?.recipient_id, msg.recipient_id);
+		const text = this._extractStringValue(messageData?.text, msg.text) ?? '';
+		const createdAt = this._parseTimestamp(this._extractStringValue(messageData?.time, msg.time) ?? '');
+		const editCount = this._extractNumberValue(messageData?.edit_count);
+
+		return {
+			id,
+			conversationId,
+			senderId,
+			recipientId,
+			createdAt,
+			text,
+			editCount,
+		};
+	}
+
+	/**
+	 * Parse timestamp with proper validation
+	 */
+	private _parseTimestamp(timestamp: string): string {
+		const numericTimestamp = Number(timestamp);
+		if (!isNaN(numericTimestamp)) {
+			const date = new Date(numericTimestamp);
+			if (!isNaN(date.getTime())) {
+				return date.toISOString();
+			}
+		}
+		return new Date().toISOString();
+	}
+
+	/**
+	 * Filter messages by conversation ID
+	 */
+	public static filterByConversation(messages: DirectMessage[], conversationId: string): DirectMessage[] {
+		return messages.filter((message) => message.conversationId === conversationId);
+	}
+
+	/**
+	 * Filter messages by sender ID
+	 */
+	public static filterBySender(messages: DirectMessage[], senderId: string): DirectMessage[] {
+		return messages.filter((message) => message.isFromSender(senderId));
+	}
+
+	/**
+	 * Extracts and deserializes the list of direct messages from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized list of direct messages.
+	 */
+	public static list(
+		response: IInboxInitialResponse | IConversationTimelineResponse | IInboxTimelineResponse,
+	): DirectMessage[] {
+		const messages: DirectMessage[] = [];
+
+		if (isInboxInitialResponse(response)) {
+			return DirectMessage._extractFromInboxInitial(response);
+		} else if (isConversationTimelineResponse(response)) {
+			return DirectMessage._extractFromConversationTimeline(response);
+		} else if (isInboxTimelineResponse(response)) {
+			return DirectMessage._extractFromInboxTimeline(response);
+		}
+
+		return messages;
+	}
+
+	/**
+	 * Generic method to extract messages from any supported response type
+	 */
+	public static listFromResponse(
+		response: IInboxInitialResponse | IConversationTimelineResponse | IInboxTimelineResponse,
+	): DirectMessage[] {
+		return DirectMessage.list(response);
+	}
+
+	/**
+	 * Sort messages by creation time (oldest to newest)
+	 */
+	public static sortByTime(messages: DirectMessage[], ascending = true): DirectMessage[] {
+		return [...messages].sort((a, b) => {
+			const timeA = new Date(a.createdAt).getTime();
+			const timeB = new Date(b.createdAt).getTime();
+			return ascending ? timeA - timeB : timeB - timeA;
+		});
+	}
+
+	/**
+	 * Get the age of this message in milliseconds
+	 */
+	public getAgeInMs(): number {
+		return Date.now() - new Date(this.createdAt).getTime();
+	}
+
+	/**
+	 * Check if this message has media attachments
+	 */
+	public hasMedia(): boolean {
+		return Boolean(this.mediaUrls && this.mediaUrls.length > 0);
+	}
+
+	/**
+	 * Check if this message is from a specific sender
+	 */
+	public isFromSender(senderId: string): boolean {
+		return this.senderId === senderId;
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): IDirectMessage {
+		return {
+			conversationId: this.conversationId,
+			createdAt: this.createdAt,
+			editCount: this.editCount,
+			id: this.id,
+			mediaUrls: this.mediaUrls,
+			read: this.read,
+			recipientId: this.recipientId,
+			senderId: this.senderId,
+			text: this.text,
+		};
+	}
+
+	/**
+	 * Check if this message was edited
+	 */
+	public wasEdited(): boolean {
+		return Boolean(this.editCount && this.editCount > 0);
+	}
+}

package/src/models/data/Inbox.ts

@@ -0,0 +1,124 @@
+import { IInbox } from '../../types/data/Inbox';
+import { IInboxInitialResponse } from '../../types/raw/dm/InboxInitial';
+import { IInboxTimelineResponse } from '../../types/raw/dm/InboxTimeline';
+
+import { Conversation } from './Conversation';
+
+/**
+ * Type guard to check if the response is an IInboxInitialResponse
+ */
+function isInboxInitialResponse(
+	response: IInboxInitialResponse | IInboxTimelineResponse,
+): response is IInboxInitialResponse {
+	return 'inbox_initial_state' in response;
+}
+
+/**
+ * Type guard to check if the response is an IInboxTimelineResponse
+ */
+function isInboxTimelineResponse(
+	response: IInboxInitialResponse | IInboxTimelineResponse,
+): response is IInboxTimelineResponse {
+	return 'inbox_timeline' in response;
+}
+
+/**
+ * The details of a DM inbox containing conversations and metadata.
+ *
+ * @public
+ */
+export class Inbox implements IInbox {
+	/** The raw inbox details. */
+	private readonly _raw: IInboxInitialResponse | IInboxTimelineResponse;
+
+	public conversations: Conversation[];
+	public cursor: string;
+	public lastSeenEventId: string;
+	public trustedLastSeenEventId: string;
+	public untrustedLastSeenEventId: string;
+
+	/**
+	 * @param response - The raw inbox response from the API.
+	 */
+	public constructor(response: IInboxInitialResponse | IInboxTimelineResponse) {
+		this._raw = response;
+
+		// Handle inbox initial state response
+		if (isInboxInitialResponse(response)) {
+			const inboxState = response.inbox_initial_state;
+
+			this.cursor = inboxState.cursor ?? '';
+			this.lastSeenEventId = inboxState.last_seen_event_id ?? '';
+			this.trustedLastSeenEventId = inboxState.trusted_last_seen_event_id ?? '';
+			this.untrustedLastSeenEventId = inboxState.untrusted_last_seen_event_id ?? '';
+
+			// Parse conversations from inbox initial state
+			this.conversations = Conversation.listFromInboxInitial(response);
+		}
+		// Handle inbox timeline response
+		else if (isInboxTimelineResponse(response)) {
+			const inboxTimeline = response.inbox_timeline;
+
+			this.cursor = inboxTimeline.min_entry_id ?? '';
+			this.lastSeenEventId = '';
+			this.trustedLastSeenEventId = '';
+			this.untrustedLastSeenEventId = '';
+
+			// Parse conversations from inbox timeline
+			this.conversations = Conversation.listFromInboxTimeline(response);
+		} else {
+			// Fallback defaults (this should never happen with proper typing)
+			this.cursor = '';
+			this.lastSeenEventId = '';
+			this.trustedLastSeenEventId = '';
+			this.untrustedLastSeenEventId = '';
+			this.conversations = [];
+		}
+	}
+
+	/** The raw inbox details. */
+	public get raw(): IInboxInitialResponse | IInboxTimelineResponse {
+		return this._raw;
+	}
+
+	/**
+	 * Get the raw inbox initial state if this inbox was created from one
+	 */
+	public getInitialState(): IInboxInitialResponse | undefined {
+		return this.isInitialState() ? (this._raw as IInboxInitialResponse) : undefined;
+	}
+
+	/**
+	 * Get the raw inbox timeline if this inbox was created from one
+	 */
+	public getTimeline(): IInboxTimelineResponse | undefined {
+		return this.isTimeline() ? (this._raw as IInboxTimelineResponse) : undefined;
+	}
+
+	/**
+	 * Check if this inbox was created from an initial state response
+	 */
+	public isInitialState(): boolean {
+		return isInboxInitialResponse(this._raw);
+	}
+
+	/**
+	 * Check if this inbox was created from a timeline response
+	 */
+	public isTimeline(): boolean {
+		return isInboxTimelineResponse(this._raw);
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): IInbox {
+		return {
+			conversations: this.conversations.map((conv) => conv.toJSON()),
+			cursor: this.cursor,
+			lastSeenEventId: this.lastSeenEventId,
+			trustedLastSeenEventId: this.trustedLastSeenEventId,
+			untrustedLastSeenEventId: this.untrustedLastSeenEventId,
+		};
+	}
+}

package/src/models/data/List.ts

@@ -1,5 +1,10 @@
+import { LogActions } from '../../enums/Logging';
+import { findByFilter } from '../../helper/JsonUtils';
+import { LogService } from '../../services/internal/LogService';
 import { IList } from '../../types/data/List';
 import { IList as IRawList } from '../../types/raw/base/List';
+import { ITimelineList } from '../../types/raw/composite/TimelineList';
+import { IListDetailsResponse } from '../../types/raw/list/Details';
 
 /**
  * The details of a single Twitter List.
@@ -14,6 +19,8 @@ export class List implements IList {
 	public createdBy: string;
 	public description?: string;
 	public id: string;
+	public isFollowing: boolean;
+	public isMember: boolean;
 	public memberCount: number;
 	public name: string;
 	public subscriberCount: number;
@@ -27,9 +34,11 @@ export class List implements IList {
 		this.name = list.name;
 		this.createdAt = new Date(list.created_at).toISOString();
 		this.description = list.description.length ? list.description : undefined;
+		this.isFollowing = list.following;
+		this.isMember = list.is_member;
 		this.memberCount = list.member_count;
 		this.subscriberCount = list.subscriber_count;
-		this.createdBy = list.user_results.result.id;
+		this.createdBy = list.user_results.result.rest_id;
 	}
 
 	/** The raw list details. */
@@ -37,6 +46,54 @@ export class List implements IList {
 		return { ...this._raw };
 	}
 
+	/**
+	 * Extracts and deserializes a single target list from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @param id - The id of the target list.
+	 *
+	 * @returns The target deserialized list.
+	 */
+	public static single(response: IListDetailsResponse, id: string): List | undefined {
+		// If list found
+		if (response.data.list.id_str === id) {
+			return new List(response.data.list as unknown as IRawList);
+		}
+		// If not found
+		else {
+			return undefined;
+		}
+	}
+
+	/**
+	 * Extracts and deserializes the timeline of lists followed from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized timeline of lists.
+	 */
+	public static timeline(response: NonNullable<unknown>): List[] {
+		const lists: List[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<ITimelineList>(response, '__typename', 'TimelineTwitterList').map(
+			(item) => item.list,
+		);
+
+		// Deserializing valid data
+		for (const item of extract) {
+			// If valid list
+			if (item !== undefined && item.id !== undefined && item.following === true) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.id });
+
+				lists.push(new List(item));
+			}
+		}
+
+		return lists;
+	}
+
 	/**
 	 * @returns A serializable JSON representation of `this` object.
 	 */
@@ -46,6 +103,8 @@ export class List implements IList {
 			createdBy: this.createdBy,
 			description: this.description,
 			id: this.id,
+			isFollowing: this.isFollowing,
+			isMember: this.isMember,
 			memberCount: this.memberCount,
 			name: this.name,
 			subscriberCount: this.subscriberCount,

package/src/models/data/Tweet.ts

@@ -22,24 +22,24 @@ export class Tweet implements ITweet {
 	/** The raw tweet details. */
 	private readonly _raw: IRawTweet;
 
-	public bookmarkCount: number;
+	public bookmarkCount?: number;
 	public conversationId: string;
 	public createdAt: string;
 	public entities: TweetEntities;
 	public fullText: string;
 	public id: string;
 	public lang: string;
-	public likeCount: number;
+	public likeCount?: number;
 	public media?: TweetMedia[];
-	public quoteCount: number;
+	public quoteCount?: number;
 	public quoted?: Tweet;
-	public replyCount: number;
+	public replyCount?: number;
 	public replyTo?: string;
-	public retweetCount: number;
+	public retweetCount?: number;
 	public retweetedTweet?: Tweet;
 	public tweetBy: User;
 	public url: string;
-	public viewCount: number;
+	public viewCount?: number;
 
 	/**
 	 * @param tweet - The raw tweet details.
@@ -53,14 +53,16 @@ export class Tweet implements ITweet {
 		this.entities = new TweetEntities(tweet.legacy.entities);
 		this.media = tweet.legacy.extended_entities?.media?.map((media) => new TweetMedia(media));
 		this.quoted = this._getQuotedTweet(tweet);
-		this.fullText = tweet.note_tweet ? tweet.note_tweet.note_tweet_results.result.text : tweet.legacy.full_text;
+		this.fullText = tweet.note_tweet?.note_tweet_results?.result?.text
+			? tweet.note_tweet.note_tweet_results.result.text
+			: tweet.legacy.full_text;
 		this.replyTo = tweet.legacy.in_reply_to_status_id_str;
 		this.lang = tweet.legacy.lang;
 		this.quoteCount = tweet.legacy.quote_count;
 		this.replyCount = tweet.legacy.reply_count;
 		this.retweetCount = tweet.legacy.retweet_count;
 		this.likeCount = tweet.legacy.favorite_count;
-		this.viewCount = tweet.views.count ? parseInt(tweet.views.count) : 0;
+		this.viewCount = tweet.views?.count ? parseInt(tweet.views.count) : undefined;
 		this.bookmarkCount = tweet.legacy.bookmark_count;
 		this.retweetedTweet = this._getRetweetedTweet(tweet);
 		this.url = `https://x.com/${this.tweetBy.userName}/status/${this.id}`;

package/src/models/data/User.ts

@@ -20,6 +20,8 @@ export class User implements IUser {
 	public followingsCount: number;
 	public fullName: string;
 	public id: string;
+	public isFollowed?: boolean;
+	public isFollowing?: boolean;
 	public isVerified: boolean;
 	public likeCount: number;
 	public location?: string;
@@ -39,6 +41,8 @@ export class User implements IUser {
 		this.fullName = user.legacy.name;
 		this.createdAt = new Date(user.legacy.created_at).toISOString();
 		this.description = user.legacy.description.length ? user.legacy.description : undefined;
+		this.isFollowed = user.legacy.following;
+		this.isFollowing = user.legacy.followed_by;
 		this.isVerified = user.is_blue_verified;
 		this.likeCount = user.legacy.favourites_count;
 		this.followersCount = user.legacy.followers_count;
@@ -168,6 +172,8 @@ export class User implements IUser {
 			followingsCount: this.followingsCount,
 			fullName: this.fullName,
 			id: this.id,
+			isFollowed: this.isFollowed,
+			isFollowing: this.isFollowing,
 			isVerified: this.isVerified,
 			likeCount: this.likeCount,
 			location: this.location,