@glagan/rettiwt-api 7.0.0

package/src/models/auth/AuthCredential.ts

@@ -0,0 +1,83 @@
+import { Cookie } from 'cookiejar';
+
+import { AuthenticationType } from '../../enums/Authentication';
+import { IAuthCredential } from '../../types/auth/AuthCredential';
+
+import { AuthCookie } from './AuthCookie';
+
+/**
+ * The credentials for authenticating against Twitter.
+ *
+ * Depending on which tokens are present, the authentication type is determined as follows:
+ * - authToken, guestToken =\> Guest authentication.
+ * - authToken, csrfToken, cookie =\> User authentication.
+ * - authToken, guestToken, cookie =\> Guest authentication while logging in.
+ *
+ * @internal
+ */
+export class AuthCredential implements IAuthCredential {
+	public authToken?: string;
+	public authenticationType?: AuthenticationType;
+	public cookies?: string;
+	public csrfToken?: string;
+	public guestToken?: string;
+
+	/**
+	 * @param cookies - The list of cookies to be used for authenticating against Twitter.
+	 * @param guestToken - The guest token to be used to authenticate a guest session.
+	 */
+	public constructor(cookies?: Cookie[], guestToken?: string) {
+		this.authToken =
+			'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+		// If guest credentials given
+		if (!cookies && guestToken) {
+			this.guestToken = guestToken;
+			this.authenticationType = AuthenticationType.GUEST;
+		}
+		// If login credentials given
+		else if (cookies && guestToken) {
+			// Parsing the cookies
+			const parsedCookie: AuthCookie = new AuthCookie(cookies);
+
+			this.cookies = parsedCookie.toString();
+			this.guestToken = guestToken;
+			this.authenticationType = AuthenticationType.LOGIN;
+		}
+		// If user credentials given
+		else if (cookies && !guestToken) {
+			// Parsing the cookies
+			const parsedCookie: AuthCookie = new AuthCookie(cookies);
+
+			this.cookies = parsedCookie.toString();
+			this.csrfToken = parsedCookie.ct0;
+			this.authenticationType = AuthenticationType.USER;
+		}
+	}
+
+	/**
+	 * @returns The HTTP header representation of 'this' object.
+	 */
+	public toHeader(): Record<string, string> {
+		const headers = {} as Record<string, string>;
+
+		/**
+		 * Conditionally initializing only those data which are supplied.
+		 *
+		 * This is done to ensure that the data that is not supplied, is not included in output, not even undefined.
+		 */
+		if (this.authToken) {
+			headers['authorization'] = `Bearer ${this.authToken}`;
+		}
+		if (this.guestToken) {
+			headers['x-guest-token'] = this.guestToken;
+		}
+		if (this.csrfToken) {
+			headers['x-csrf-token'] = this.csrfToken;
+		}
+		if (this.cookies) {
+			headers['cookie'] = this.cookies;
+		}
+
+		return headers;
+	}
+}

package/src/models/data/Analytics.ts

@@ -0,0 +1,97 @@
+import { RawAnalyticsMetric } from '../../enums/raw/Analytics';
+import { IAnalytics as IRawAnalytics } from '../../types/raw/base/Analytic';
+
+import type { IAnalytics } from '../../types/data/Analytics';
+import type { IAnalyticsMetric } from '../../types/raw/base/Analytic';
+
+/**
+ * The details of the analytic result of the connected User.
+ *
+ * @public
+ */
+export class Analytics implements IAnalytics {
+	/** The raw analytic details. */
+	private readonly _raw: IRawAnalytics;
+
+	public bookmarks: number;
+	public createQuote: number;
+	public createReply: number;
+	public createTweets: number;
+	public createdAt: string;
+	public engagements: number;
+	public followers: number;
+	public follows: number;
+	public impressions: number;
+	public likes: number;
+	public organicMetricsTimeSeries: IAnalyticsMetric[];
+	public profileVisits: number;
+	public replies: number;
+	public retweets: number;
+	public shares: number;
+	public unfollows: number;
+	public verifiedFollowers: number;
+
+	public constructor(analytics: IRawAnalytics) {
+		this._raw = { ...analytics };
+		this.organicMetricsTimeSeries = analytics.organic_metrics_time_series;
+		this.createdAt = new Date().toISOString();
+		this.followers = analytics.relationship_counts.followers;
+		this.verifiedFollowers = parseInt(analytics.verified_follower_count, 10);
+		this.impressions = this._reduceMetrics(RawAnalyticsMetric.IMPRESSIONS);
+		this.profileVisits = this._reduceMetrics(RawAnalyticsMetric.PROFILE_VISITS);
+		this.engagements = this._reduceMetrics(RawAnalyticsMetric.ENGAGEMENTS);
+		this.follows = this._reduceMetrics(RawAnalyticsMetric.FOLLOWS);
+		this.replies = this._reduceMetrics(RawAnalyticsMetric.REPLIES);
+		this.likes = this._reduceMetrics(RawAnalyticsMetric.LIKES);
+		this.retweets = this._reduceMetrics(RawAnalyticsMetric.RETWEETS);
+		this.bookmarks = this._reduceMetrics(RawAnalyticsMetric.BOOKMARK);
+		this.shares = this._reduceMetrics(RawAnalyticsMetric.SHARE);
+		this.createTweets = this._reduceMetrics(RawAnalyticsMetric.CREATE_TWEET);
+		this.createQuote = this._reduceMetrics(RawAnalyticsMetric.CREATE_QUOTE);
+		this.createReply = this._reduceMetrics(RawAnalyticsMetric.CREATE_REPLY);
+		this.unfollows = this._reduceMetrics(RawAnalyticsMetric.UNFOLLOWS);
+	}
+
+	/** The raw analytic details. */
+	public get raw(): IRawAnalytics {
+		return { ...this._raw };
+	}
+
+	/**
+	 * Reduces the organic metrics time series to a total value for a specific metric type.
+	 *
+	 * @param metricType - metricType The type of metric to reduce.
+	 * @returns the total value of the specified metric type across all time series.
+	 */
+	private _reduceMetrics(metricType: RawAnalyticsMetric): number {
+		return this.organicMetricsTimeSeries.reduce((acc, metric) => {
+			const metricValue = metric.metric_values.find((m) => m.metric_type === (metricType as string));
+			return acc + (metricValue ? metricValue.metric_value : 0);
+		}, 0);
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): IAnalytics {
+		return {
+			createdAt: this.createdAt,
+			followers: this.followers,
+			verifiedFollowers: this.verifiedFollowers,
+			impressions: this.impressions,
+			profileVisits: this.profileVisits,
+			engagements: this.engagements,
+			follows: this.follows,
+			replies: this.replies,
+			likes: this.likes,
+			retweets: this.retweets,
+			bookmarks: this.bookmarks,
+			shares: this.shares,
+			createTweets: this.createTweets,
+			createQuote: this.createQuote,
+			unfollows: this.unfollows,
+			createReply: this.createReply,
+			organicMetricsTimeSeries: this.organicMetricsTimeSeries,
+		};
+	}
+}

package/src/models/data/BookmarkFolder.ts

@@ -0,0 +1,73 @@
+import { LogActions } from '../../enums/Logging';
+import { LogService } from '../../services/internal/LogService';
+import { IBookmarkFolder } from '../../types/data/BookmarkFolder';
+import { IBookmarkFolder as IRawBookmarkFolder } from '../../types/raw/base/BookmarkFolder';
+import { IUserBookmarkFoldersResponse } from '../../types/raw/user/BookmarkFolders';
+
+/**
+ * The details of a single Bookmark Folder.
+ *
+ * @public
+ */
+export class BookmarkFolder implements IBookmarkFolder {
+	/** The raw bookmark folder details. */
+	private readonly _raw: IRawBookmarkFolder;
+
+	public id: string;
+	public name: string;
+
+	/**
+	 * @param folder - The raw bookmark folder details.
+	 */
+	public constructor(folder: IRawBookmarkFolder) {
+		this._raw = { ...folder };
+		this.id = folder.id;
+		this.name = folder.name;
+	}
+
+	/** The raw bookmark folder details. */
+	public get raw(): IRawBookmarkFolder {
+		return { ...this._raw };
+	}
+
+	/**
+	 * Extracts and deserializes bookmark folders from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized list of bookmark folders.
+	 */
+	public static list(response: NonNullable<unknown>): BookmarkFolder[] {
+		const folders: BookmarkFolder[] = [];
+
+		// Extract items from the response structure
+		const items = (response as IUserBookmarkFoldersResponse)?.data?.viewer?.user_results?.result
+			?.bookmark_collections_slice?.items;
+
+		if (!items || !Array.isArray(items)) {
+			return folders;
+		}
+
+		// Deserialize valid folders
+		for (const item of items) {
+			if (item && item.id) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.id });
+
+				folders.push(new BookmarkFolder(item));
+			}
+		}
+
+		return folders;
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): IBookmarkFolder {
+		return {
+			id: this.id,
+			name: this.name,
+		};
+	}
+}

package/src/models/data/Conversation.ts

@@ -0,0 +1,344 @@
+import { IConversation } from '../../types/data/Conversation';
+import { IConversationTimelineResponse } from '../../types/raw/dm/Conversation';
+import {
+	IInboxInitialResponse,
+	Conversation as RawConversation,
+	Conversations as RawConversations,
+} from '../../types/raw/dm/InboxInitial';
+import { IInboxTimelineResponse } from '../../types/raw/dm/InboxTimeline';
+
+import { DirectMessage } from './DirectMessage';
+
+/**
+ * Type guard to check if the response is an IConversationTimelineResponse
+ */
+function isConversationTimelineResponse(
+	response: IConversationTimelineResponse | IInboxInitialResponse | IInboxTimelineResponse,
+): response is IConversationTimelineResponse {
+	return 'conversation_timeline' in response;
+}
+
+/**
+ * Type guard to check if the response is an IInboxInitialResponse
+ */
+function isInboxInitialResponse(
+	response: IConversationTimelineResponse | IInboxInitialResponse | IInboxTimelineResponse,
+): response is IInboxInitialResponse {
+	return 'inbox_initial_state' in response;
+}
+
+/**
+ * Type guard to check if the response is an IInboxTimelineResponse
+ */
+function isInboxTimelineResponse(
+	response: IConversationTimelineResponse | IInboxInitialResponse | IInboxTimelineResponse,
+): response is IInboxTimelineResponse {
+	return 'inbox_timeline' in response;
+}
+
+/**
+ * Extract typed conversation data from raw conversations object
+ */
+function extractConversationData(rawConversations: RawConversations): Array<[string, RawConversation]> {
+	return Object.entries(rawConversations);
+}
+
+/**
+ * The details of a single conversation.
+ *
+ * @public
+ */
+export class Conversation implements IConversation {
+	/** The raw conversation details. */
+	private readonly _raw: RawConversation;
+
+	public avatarUrl?: string;
+	public hasMore: boolean;
+	public id: string;
+	public lastActivityAt: string;
+	public lastMessageId?: string;
+	public messages: DirectMessage[];
+	public muted: boolean;
+	public name?: string;
+	public notificationsDisabled: boolean;
+	public participants: string[];
+	public trusted: boolean;
+	public type: 'ONE_TO_ONE' | 'GROUP_DM';
+
+	/**
+	 * @param conversation - The raw conversation details from the API response.
+	 * @param messages - Array of messages in this conversation.
+	 */
+	public constructor(conversation: unknown, messages: DirectMessage[] = []) {
+		this._raw = conversation as RawConversation;
+
+		const conv = conversation as Record<string, unknown>;
+
+		this.id = conv.conversation_id && typeof conv.conversation_id === 'string' ? conv.conversation_id : '';
+		this.type = this._parseConversationType(conv.type);
+		this.participants = this._parseParticipants(conv.participants);
+		this.name = conv.name && typeof conv.name === 'string' ? conv.name : undefined;
+		this.avatarUrl = this._parseAvatarUrl(conv);
+		this.trusted = Boolean(conv.trusted);
+		this.muted = Boolean(conv.muted);
+		this.notificationsDisabled = Boolean(conv.notifications_disabled);
+		this.lastActivityAt = this._parseTimestamp(conv.sort_timestamp);
+		this.lastMessageId =
+			conv.sort_event_id && typeof conv.sort_event_id === 'string' ? conv.sort_event_id : undefined;
+		this.hasMore = conv.status === 'HAS_MORE';
+		this.messages = messages;
+	}
+
+	/** The raw conversation details. */
+	public get raw(): RawConversation {
+		return this._raw;
+	}
+
+	/**
+	 * Parse avatar URL from conversation data
+	 */
+	private _parseAvatarUrl(conv: Record<string, unknown>): string | undefined {
+		// Try avatar_image_https first
+		if (conv.avatar_image_https && typeof conv.avatar_image_https === 'string') {
+			return conv.avatar_image_https;
+		}
+
+		// Try nested avatar.image.original_info.url
+		const avatar = conv.avatar as Record<string, unknown> | undefined;
+		const image = avatar?.image as Record<string, unknown> | undefined;
+		const originalInfo = image?.original_info as Record<string, unknown> | undefined;
+
+		if (originalInfo?.url && typeof originalInfo.url === 'string') {
+			return originalInfo.url;
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * Parse conversation type with proper fallback
+	 */
+	private _parseConversationType(type: unknown): 'ONE_TO_ONE' | 'GROUP_DM' {
+		if (type === 'ONE_TO_ONE' || type === 'GROUP_DM') {
+			return type;
+		}
+		return 'ONE_TO_ONE';
+	}
+
+	/**
+	 * Parse participants array with type safety
+	 */
+	private _parseParticipants(participants: unknown): string[] {
+		if (!Array.isArray(participants)) {
+			return [];
+		}
+
+		return participants
+			.map((p) => {
+				if (p && typeof p === 'object' && 'user_id' in p) {
+					// eslint-disable-next-line @typescript-eslint/naming-convention
+					const participantObj = p as { user_id: unknown };
+					if (typeof participantObj.user_id === 'string') {
+						return participantObj.user_id;
+					}
+				}
+				return '';
+			})
+			.filter(Boolean);
+	}
+
+	/**
+	 * Parse timestamp with proper fallback
+	 */
+	private _parseTimestamp(timestamp: unknown): string {
+		if (timestamp && (typeof timestamp === 'string' || typeof timestamp === 'number')) {
+			const date = new Date(Number(timestamp));
+			if (!isNaN(date.getTime())) {
+				return date.toISOString();
+			}
+		}
+		return new Date().toISOString();
+	}
+
+	/**
+	 * Extracts a single conversation from conversation timeline response.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized conversation with full message history.
+	 */
+	public static fromConversationTimeline(response: IConversationTimelineResponse): Conversation | undefined {
+		if (!response.conversation_timeline?.conversations) {
+			return undefined;
+		}
+
+		const rawConversations = response.conversation_timeline.conversations;
+		const entries = response.conversation_timeline.entries ?? [];
+
+		// Extract messages from entries
+		const messages: DirectMessage[] = [];
+		for (const entry of entries) {
+			if ('message' in entry && entry.message) {
+				messages.push(new DirectMessage(entry.message));
+			}
+		}
+
+		// Get the first (and typically only) conversation
+		const conversationEntries = extractConversationData(rawConversations);
+		const firstEntry = conversationEntries[0];
+
+		if (firstEntry) {
+			const [, conversationData] = firstEntry;
+			return new Conversation(conversationData, messages);
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * Extracts conversations from inbox initial state response.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized list of conversations with their preview messages.
+	 */
+	public static listFromInboxInitial(response: IInboxInitialResponse): Conversation[] {
+		const conversations: Conversation[] = [];
+
+		if (!response.inbox_initial_state?.conversations) {
+			return conversations;
+		}
+
+		const rawConversations = response.inbox_initial_state.conversations;
+		const entries = response.inbox_initial_state.entries ?? [];
+
+		// Group messages by conversation ID
+		const messagesByConversation = new Map<string, DirectMessage[]>();
+		for (const entry of entries) {
+			if ('message' in entry && entry.message) {
+				const message = new DirectMessage(entry.message);
+				const convId = message.conversationId;
+				if (convId) {
+					if (!messagesByConversation.has(convId)) {
+						messagesByConversation.set(convId, []);
+					}
+					messagesByConversation.get(convId)!.push(message);
+				}
+			}
+		}
+
+		// Create conversations with their messages
+		const conversationEntries = extractConversationData(rawConversations);
+		for (const [, conversation] of conversationEntries) {
+			const convId = (conversation as unknown as Record<string, unknown>).conversation_id as string;
+			const messages = messagesByConversation.get(convId) ?? [];
+			conversations.push(new Conversation(conversation, messages));
+		}
+
+		return conversations;
+	}
+
+	/**
+	 * Extracts conversations from inbox timeline response.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized list of conversations with their messages.
+	 */
+	public static listFromInboxTimeline(response: IInboxTimelineResponse): Conversation[] {
+		const conversations: Conversation[] = [];
+
+		if (!response.inbox_timeline?.conversations) {
+			return conversations;
+		}
+
+		const rawConversations = response.inbox_timeline.conversations;
+		const entries = response.inbox_timeline.entries ?? [];
+
+		// Group messages by conversation ID
+		const messagesByConversation = new Map<string, DirectMessage[]>();
+		for (const entry of entries) {
+			if ('message' in entry && entry.message) {
+				const message = new DirectMessage(entry.message);
+				const convId = message.conversationId;
+				if (convId) {
+					if (!messagesByConversation.has(convId)) {
+						messagesByConversation.set(convId, []);
+					}
+					messagesByConversation.get(convId)!.push(message);
+				}
+			}
+		}
+
+		// Create conversations with their messages
+		const conversationEntries = extractConversationData(rawConversations);
+		for (const [, conversation] of conversationEntries) {
+			const convId = (conversation as unknown as Record<string, unknown>).conversation_id as string;
+			const messages = messagesByConversation.get(convId) ?? [];
+			conversations.push(new Conversation(conversation, messages));
+		}
+
+		return conversations;
+	}
+
+	/**
+	 * Generic method to extract conversations from any supported response type
+	 */
+	public static listFromResponse(
+		response: IConversationTimelineResponse | IInboxInitialResponse | IInboxTimelineResponse,
+	): Conversation[] {
+		if (isConversationTimelineResponse(response)) {
+			const conversation = Conversation.fromConversationTimeline(response);
+			return conversation ? [conversation] : [];
+		} else if (isInboxInitialResponse(response)) {
+			return Conversation.listFromInboxInitial(response);
+		} else if (isInboxTimelineResponse(response)) {
+			return Conversation.listFromInboxTimeline(response);
+		}
+		return [];
+	}
+
+	/**
+	 * Get the other participant's ID (only for one-to-one conversations)
+	 */
+	public getOtherParticipant(currentUserId: string): string | undefined {
+		if (!this.isOneToOne() || this.participants.length !== 2) {
+			return undefined;
+		}
+		return this.participants.find((id) => id !== currentUserId);
+	}
+
+	/**
+	 * Check if this conversation is a group DM
+	 */
+	public isGroupDM(): boolean {
+		return this.type === 'GROUP_DM';
+	}
+
+	/**
+	 * Check if this conversation is one-to-one
+	 */
+	public isOneToOne(): boolean {
+		return this.type === 'ONE_TO_ONE';
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): IConversation {
+		return {
+			avatarUrl: this.avatarUrl,
+			hasMore: this.hasMore,
+			id: this.id,
+			lastActivityAt: this.lastActivityAt,
+			lastMessageId: this.lastMessageId,
+			messages: this.messages.map((msg) => msg.toJSON()),
+			muted: this.muted,
+			name: this.name,
+			notificationsDisabled: this.notificationsDisabled,
+			participants: this.participants,
+			trusted: this.trusted,
+			type: this.type,
+		};
+	}
+}

package/src/models/data/CursoredData.ts

@@ -0,0 +1,64 @@
+import { BaseType } from '../../enums/Data';
+
+import { findByFilter } from '../../helper/JsonUtils';
+
+import { ICursoredData } from '../../types/data/CursoredData';
+import { ICursor as IRawCursor } from '../../types/raw/base/Cursor';
+import { IUserBookmarkFoldersResponse } from '../../types/raw/user/BookmarkFolders';
+
+import { BookmarkFolder } from './BookmarkFolder';
+import { List } from './List';
+import { Notification } from './Notification';
+import { Tweet } from './Tweet';
+import { User } from './User';
+
+/**
+ * The data that is fetched batch-wise using a cursor.
+ *
+ * @typeParam T - Type of data to be stored.
+ *
+ * @public
+ */
+export class CursoredData<T extends Notification | Tweet | User | List | BookmarkFolder> implements ICursoredData<T> {
+	public list: T[];
+	public next: string;
+
+	/**
+	 * @param response - The raw response.
+	 * @param type - The base type of the data included in the batch.
+	 */
+	public constructor(response: NonNullable<unknown>, type: BaseType) {
+		// Initializing defaults
+		this.list = [];
+		this.next = '';
+
+		if (type == BaseType.TWEET) {
+			this.list = Tweet.timeline(response) as T[];
+			this.next = findByFilter<IRawCursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '';
+		} else if (type == BaseType.USER) {
+			this.list = User.timeline(response) as T[];
+			this.next = findByFilter<IRawCursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '';
+		} else if (type == BaseType.LIST) {
+			this.list = List.timeline(response) as T[];
+			this.next = findByFilter<IRawCursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '';
+		} else if (type == BaseType.NOTIFICATION) {
+			this.list = Notification.list(response) as T[];
+			this.next = findByFilter<IRawCursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '';
+		} else if (type == BaseType.BOOKMARK_FOLDER) {
+			this.list = BookmarkFolder.list(response) as T[];
+			const sliceInfo = (response as IUserBookmarkFoldersResponse)?.data?.viewer?.user_results?.result
+				?.bookmark_collections_slice?.slice_info;
+			this.next = sliceInfo?.next_cursor ?? '';
+		}
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): ICursoredData<T> {
+		return {
+			list: this.list.map((item) => item.toJSON() as T),
+			next: this.next,
+		};
+	}
+}