rettiwt-api 5.0.0-alpha.1 → 5.0.0-alpha.2

package/src/services/public/UserService.ts

@@ -1,28 +1,25 @@
-import {
-	IUserBookmarksResponse,
-	IUserDetailsResponse,
-	IUserFollowedResponse,
-	IUserFollowersResponse,
-	IUserFollowingResponse,
-	IUserFollowResponse,
-	IUserHighlightsResponse,
-	IUserLikesResponse,
-	IUserMediaResponse,
-	IUserNotificationsResponse,
-	IUserRecommendedResponse,
-	IUserSubscriptionsResponse,
-	IUserTweetsAndRepliesResponse,
-	IUserTweetsResponse,
-	IUserUnfollowResponse,
-} from 'rettiwt-core';
-
 import { extractors } from '../../collections/Extractors';
 import { EResourceType } from '../../enums/Resource';
 import { CursoredData } from '../../models/data/CursoredData';
 import { Notification } from '../../models/data/Notification';
 import { Tweet } from '../../models/data/Tweet';
 import { User } from '../../models/data/User';
-import { IRettiwtConfig } from '../../types/RettiwtConfig';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IUserBookmarksResponse } from '../../types/raw/user/Bookmarks';
+import { IUserDetailsResponse } from '../../types/raw/user/Details';
+import { IUserFollowResponse } from '../../types/raw/user/Follow';
+import { IUserFollowedResponse } from '../../types/raw/user/Followed';
+import { IUserFollowersResponse } from '../../types/raw/user/Followers';
+import { IUserFollowingResponse } from '../../types/raw/user/Following';
+import { IUserHighlightsResponse } from '../../types/raw/user/Highlights';
+import { IUserLikesResponse } from '../../types/raw/user/Likes';
+import { IUserMediaResponse } from '../../types/raw/user/Media';
+import { IUserNotificationsResponse } from '../../types/raw/user/Notifications';
+import { IUserRecommendedResponse } from '../../types/raw/user/Recommended';
+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 { FetcherService } from './FetcherService';
 
@@ -37,7 +34,7 @@ export class UserService extends FetcherService {
 	 *
 	 * @internal
 	 */
-	public constructor(config?: IRettiwtConfig) {
+	public constructor(config: RettiwtConfig) {
 		super(config);
 	}
 
@@ -84,7 +81,7 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the details of a user.
 	 *
-	 * @param id - The username/id of the target user.
+	 * @param id - The username/id(s) of the target user/users.
 	 *
 	 * @returns
 	 * The details of the given user.
@@ -126,25 +123,40 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async details(id: string): Promise<User | undefined> {
+	public async details<T extends string | string[]>(id: T): Promise<T extends string ? User | undefined : User[]> {
 		let resource: EResourceType;
 
-		// If username is given
-		if (isNaN(Number(id))) {
-			resource = EResourceType.USER_DETAILS_BY_USERNAME;
+		// If details of multiple users required
+		if (Array.isArray(id)) {
+			resource = EResourceType.USER_DETAILS_BY_IDS_BULK;
+
+			// Fetching raw details
+			const response = await this.request<IUserDetailsResponse>(resource, { ids: id });
+
+			// Deserializing response
+			const data = extractors[resource](response, id);
+
+			return data as T extends string ? User | undefined : User[];
 		}
-		// If id is given
+		// If details of single user required
 		else {
-			resource = EResourceType.USER_DETAILS_BY_ID;
-		}
+			// If username is given
+			if (isNaN(Number(id))) {
+				resource = EResourceType.USER_DETAILS_BY_USERNAME;
+			}
+			// If id is given
+			else {
+				resource = EResourceType.USER_DETAILS_BY_ID;
+			}
 
-		// Fetching raw details
-		const response = await this.request<IUserDetailsResponse>(resource, { id: id });
+			// Fetching raw details
+			const response = await this.request<IUserDetailsResponse>(resource, { id: id });
 
-		// Deserializing response
-		const data = extractors[resource](response);
+			// Deserializing response
+			const data = extractors[resource](response);
 
-		return data;
+			return data as T extends string ? User | undefined : User[];
+		}
 	}
 
 	/**
@@ -381,7 +393,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of likes
 		const response = await this.request<IUserLikesResponse>(resource, {
-			id: this.userId,
+			id: this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -502,7 +514,7 @@ export class UserService extends FetcherService {
 				first = false;
 			}
 
-			cursor = notifications.next.value;
+			cursor = notifications.next;
 		}
 	}
 

package/src/types/RettiwtConfig.ts

@@ -1,3 +1,4 @@
+import { ITidProvider } from './auth/TidProvider';
 import { IErrorHandler } from './ErrorHandler';
 
 /**
@@ -9,9 +10,6 @@ export interface IRettiwtConfig {
 	/** The apiKey (cookie) to use for authenticating Rettiwt against Twitter API. */
 	apiKey?: string;
 
-	/** The guestKey (guest token) to use for guest access to Twitter API. */
-	guestKey?: string;
-
 	/**
 	 * Optional URL to proxy server to use for requests to Twitter API.
 	 *
@@ -19,15 +17,6 @@ export interface IRettiwtConfig {
 	 */
 	proxyUrl?: URL;
 
-	/**
-	 * Optional URL to proxy server to use for authentication against Twitter API.
-	 *
-	 * @remarks Required when deploying to cloud platforms to bypass Error 429.
-	 *
-	 * @defaultValue Same as {@link IRettiwtConfig.proxyUrl}
-	 */
-	authProxyUrl?: URL;
-
 	/** The max wait time (in milli-seconds) for a response; if not set, Twitter server timeout is used. */
 	timeout?: number;
 
@@ -37,10 +26,20 @@ export interface IRettiwtConfig {
 	/** Optional custom error handler to define error conditions and process API/HTTP errors in responses. */
 	errorHandler?: IErrorHandler;
 
+	/** Optional custom `x-client-transaction-id` header provider. */
+	tidProvider?: ITidProvider;
+
 	/**
 	 * Optional custom HTTP headers to add to all requests to Twitter API.
 	 *
 	 * @remarks Custom headers can be useful for proxies, avoiding rate limits, etc.
 	 */
 	headers?: { [key: string]: string };
+
+	/**
+	 * The delay (in ms) to use between concurrent request.
+	 *
+	 * Can either be a number or a function that returns a number synchronously or asynchronously.
+	 */
+	delay?: number | (() => number | Promise<number>);
 }

package/src/types/args/FetchArgs.ts

@@ -1,5 +1,3 @@
-import { ESearchResultType, ITweetFilter } from 'rettiwt-core';
-
 /**
  * Options specifying the data that is to be fetched.
  *
@@ -51,14 +49,100 @@ export interface IFetchArgs {
 	id?: string;
 
 	/**
-	 * The type of search results to fetch. Can be one of:
-	 * - {@link EResourceType.LATEST}, for latest search results.
-	 * - {@link EResourceType.TOP}, for top search results.
+	 * The IDs of the target resources.
+	 *
+	 * @remarks
+	 * - Required only for {@link EResourceType.TWEET_DETAILS_BULK} and {@link EResourceType.USER_DETAILS_BY_IDS_BULK}.
+	 */
+	ids?: string[];
+}
+
+/**
+ * The filter to be used for searching tweets.
+ *
+ * @public
+ */
+export interface ITweetFilter {
+	/** The date upto which tweets are to be searched. */
+	endDate?: Date;
+
+	/** The list of words to exclude from search. */
+	excludeWords?: string[];
+
+	/**
+	 * The list of usernames whose tweets are to be searched.
+	 *
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	fromUsers?: string[];
+
+	/**
+	 * The list of hashtags to search.
+	 *
+	 * @remarks
+	 * '#' must be excluded from the hashtag!
+	 */
+	hashtags?: string[];
+
+	/** The exact phrase to search. */
+	includePhrase?: string;
+
+	/** The list of words to search. */
+	includeWords?: string[];
+
+	/** The language of the tweets to search. */
+	language?: string;
+
+	/** Whether to fetch tweets that are links or not. */
+	links?: boolean;
+
+	/** The list from which tweets are to be searched. */
+	list?: string;
+
+	/** The id of the tweet, before which the tweets are to be searched. */
+	maxId?: string;
+
+	/**
+	 * The list of username mentioned in the tweets to search.
 	 *
-	 * @defaultValue {@link ESearchResultType.LATEST}.
+	 * @remarks
+	 * '\@' must be excluded from the username!
+	 */
+	mentions?: string[];
+
+	/** The minimun number of likes to search by. */
+	minLikes?: number;
+
+	/** The minimum number of replies to search by. */
+	minReplies?: number;
+
+	/** The minimum number of retweets to search by. */
+	minRetweets?: number;
+
+	/** The optional words to search. */
+	optionalWords?: string[];
+
+	/** The id of the tweet which is quoted in the tweets to search. */
+	quoted?: string;
+
+	/** Whether to fetch tweets that are replies or not. */
+	replies?: boolean;
+
+	/** The id of the tweet, after which the tweets are to be searched. */
+	sinceId?: string;
+
+	/** The date starting from which tweets are to be searched. */
+	startDate?: Date;
+
+	/**
+	 * The list of username to whom the tweets to be searched, are adressed.
 	 *
 	 * @remarks
-	 * - Applicable only for {@link EResourceType.TWEET_SEARCH}.
+	 * '\@' must be excluded from the username!
 	 */
-	results?: ESearchResultType;
+	toUsers?: string[];
+
+	/** Whether to fetch top tweets or not. */
+	top?: boolean;
 }

package/src/types/args/PostArgs.ts

@@ -1,25 +1,3 @@
-import { INewTweet } from 'rettiwt-core';
-
-/**
- * Options specifying the media file to be uploaded.
- *
- * @public
- */
-export interface IUploadArgs {
-	/** The id allocated to the media file to be uploaded. */
-	id?: string;
-
-	/** The media file to be uploaded. */
-	media?: string | ArrayBuffer;
-
-	/**
-	 * The size (in bytes) of the media file to be uploaded.
-	 *
-	 * @remarks The size must be \<= 5242880 bytes.
-	 */
-	size?: number;
-}
-
 /**
  * Options specifying the data that is to be posted.
  *
@@ -60,3 +38,75 @@ export interface IPostArgs {
 	 */
 	upload?: IUploadArgs;
 }
+
+/**
+ * Configuration for the new tweet to be posted.
+ *
+ * @public
+ */
+export interface INewTweet {
+	/**
+	 * The list of media to be uploaded.
+	 *
+	 * @remarks
+	 * - The media first needs to be uploaded.
+	 * - After uploading, the returned id(s) can be used to reference the media here.
+	 * - Maximum number of media items that can be posted is 4.
+	 */
+	media?: INewTweetMedia[];
+
+	/** The id of the tweet to quote. */
+	quote?: string;
+
+	/** The id of the Tweet to which the given Tweet must be a reply. */
+	replyTo?: string;
+
+	/** The date/time at which the tweet is to be scheduled for posting. */
+	scheduleFor?: Date;
+
+	/**
+	 * The text for the tweet to be created.
+	 *
+	 * @remarks
+	 * Length of the tweet must be \<= 280 characters.
+	 */
+	text?: string;
+}
+
+/**
+ * Configuration for the media to be uploaded.
+ *
+ * @public
+ */
+export interface INewTweetMedia {
+	/** The id of the media to upload. */
+	id: string;
+
+	/**
+	 * The list of id of the users to tag in the media.
+	 *
+	 * @remarks
+	 * Maximum number of users that can be tagged is 10.
+	 */
+	tags?: string[];
+}
+
+/**
+ * Options specifying the media file to be uploaded.
+ *
+ * @public
+ */
+export interface IUploadArgs {
+	/** The id allocated to the media file to be uploaded. */
+	id?: string;
+
+	/** The media file to be uploaded. */
+	media?: string | ArrayBuffer;
+
+	/**
+	 * The size (in bytes) of the media file to be uploaded.
+	 *
+	 * @remarks The size must be \<= 5242880 bytes.
+	 */
+	size?: number;
+}

package/src/types/auth/AuthCookie.ts

@@ -1,5 +1,7 @@
 /**
  * The cookie containing the tokens that are used to authenticate against Twitter.
+ *
+ * @public
  */
 export interface IAuthCookie {
 	/* eslint-disable @typescript-eslint/naming-convention */

package/src/types/auth/AuthCredential.ts

@@ -7,6 +7,8 @@ import { EAuthenticationType } from '../../enums/Authentication';
  * - authToken, guestToken =\> Guest authentication.
  * - authToken, csrfToken, cookie =\> User authentication.
  * - authToken, guestToken, cookie =\> Guest authentication while logging in.
+ *
+ * @public
  */
 export interface IAuthCredential {
 	/** The bearer token from twitter.com. */

package/src/types/auth/TidDynamicArgs.ts

@@ -0,0 +1,10 @@
+/**
+ * Internal args used for generating trasaction ID.
+ *
+ * @internal
+ */
+export interface ITidDynamicArgs {
+	verificationKey: string;
+	frames: number[][][];
+	indices: number[];
+}

package/src/types/auth/TidHeader.ts

@@ -0,0 +1,12 @@
+/**
+ * The header for the transaction ID.
+ *
+ * @public
+ */
+export interface ITidHeader {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	'x-client-transaction-id': string;
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+}

package/src/types/auth/TidParams.ts

@@ -0,0 +1,36 @@
+/**
+ * The parameters for generating the transaction ID.
+ *
+ * @internal
+ */
+export interface ITidParams {
+	/** Secret used for transaction ID calculation. */
+	keyword: string;
+
+	/** Request method. */
+	method: string;
+
+	/** Endpoint path without query parameters. */
+	path: string;
+
+	/** Twitter verification key received from HTML. */
+	verificationKey: string;
+
+	/** Animation frames extracted from HTML. */
+	frames: number[][][];
+
+	/** Indices used for getting the correct verification key bytes during animation key calculation. */
+	indices: number[];
+
+	/** Final byte of the transaction ID. */
+	extraByte: number;
+
+	/** Current time */
+	time?: number;
+
+	/** XOR byte used for final hash calculation, must be in 0-255 range. */
+	xorByte?: number;
+
+	/** Precomputed animation key. */
+	animationKey?: string;
+}

package/src/types/auth/TidProvider.ts

@@ -0,0 +1,19 @@
+/**
+ * Service responsible for generating the `x-client-transaction-id` header.
+ *
+ * @public
+ */
+export interface ITidProvider {
+	/**
+	 * Generates new `x-client-transaction-id` header.
+	 *
+	 * @param method - Request method.
+	 * @param path - Endpoint path without query parameters.
+	 */
+	generate(method: string, path: string): Promise<string | undefined>;
+
+	/**
+	 * Refresh arguments obtained from parsing the HTML page, if any.
+	 */
+	refreshDynamicArgs(): Promise<void>;
+}

package/src/types/data/CursoredData.ts

@@ -14,15 +14,5 @@ export interface ICursoredData<T extends INotification | ITweet | IUser> {
 	list: T[];
 
 	/** The cursor to the next batch of data. */
-	next: ICursor;
-}
-
-/**
- * The cursor to the batch of data to fetch.
- *
- * @public
- */
-export interface ICursor {
-	/** The cursor string. */
-	value: string;
+	next: string;
 }

package/src/types/data/Notification.ts

@@ -1,4 +1,4 @@
-import { ENotificationType } from '../../enums/Data';
+import { ENotificationType } from '../../enums/Notification';
 
 /**
  * The details of a single notification.
@@ -16,7 +16,7 @@ export interface INotification {
 	message: string;
 
 	/** The date/time at which the notification was received. */
-	receivedAt: Date;
+	receivedAt: string;
 
 	/** The list of id of the target tweet(s) of the notification. */
 	target: string[];

package/src/types/data/Tweet.ts

@@ -1,4 +1,4 @@
-import { EMediaType } from 'rettiwt-core';
+import { EMediaType } from '../../enums/Media';
 
 import { IUser } from './User';
 
@@ -14,7 +14,7 @@ export interface ITweet {
 	/** The ID of tweet which started the current conversation. */
 	conversationId: string;
 
-	/** The date and time of creation of the tweet, in UTC string format. */
+	/** The creation date of the tweet. */
 	createdAt: string;
 
 	/** Additional tweet entities like urls, mentions, etc. */

package/src/types/params/Variables.ts

@@ -0,0 +1,41 @@
+/**
+ * Media to be sent as payload.
+ *
+ * @internal
+ */
+export interface IMediaVariable {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	media_entities: IMediaEntityVariable[];
+	possibly_sensitive: boolean;
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+}
+
+/**
+ * Each media item in the media payload.
+ *
+ * @internal
+ */
+export interface IMediaEntityVariable {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	media_id: string;
+	tagged_users: string[];
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+}
+
+/**
+ * Reply specific details to be sent in payload.
+ *
+ * @internal
+ */
+export interface IReplyVariable {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	exclude_reply_user_ids: string[];
+	in_reply_to_tweet_id: string;
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+}

package/src/types/raw/base/Analytic.ts

@@ -0,0 +1,26 @@
+/* eslint-disable */
+
+/**
+ * Represents the raw data of the analytic result of the User.
+ *
+ * @public
+ */
+export interface IAnalytics {
+	__typename: string;
+	organic_metrics_time_series: IAnalyticsMetric[];
+	id: string;
+}
+
+export interface IAnalyticsMetric {
+	metric_value: IAnalyticsMetricValue[];
+	timestamp: IAnalyticsTimeStamp;
+}
+
+export interface IAnalyticsMetricValue {
+	metric_value: number;
+	metric_type: string;
+}
+
+export interface IAnalyticsTimeStamp {
+	iso8601_time: string;
+}

package/src/types/raw/base/Cursor.ts

@@ -0,0 +1,13 @@
+/* eslint-disable */
+
+/**
+ * Represents a cursor object used for pagination.
+ *
+ * @public
+ */
+export interface ICursor {
+	entryType: string;
+	__typename: string;
+	value: string;
+	cursorType: string;
+}

package/src/types/raw/base/LimitedVisibilityTweet.ts

@@ -0,0 +1,40 @@
+/* eslint-disable */
+
+import { ITweet } from './Tweet';
+
+/**
+ * Represents the raw data of a single Tweet with limited visibility actions.
+ *
+ * @public
+ */
+export interface ILimitedVisibilityTweet {
+	__typename: string;
+	tweet: ITweet;
+	limitedActionResults: ITweetLimitedActionResults;
+}
+
+export interface ITweetLimitedActionResults {
+	limited_actions: ITweetLimitedAction[];
+}
+
+export interface ITweetLimitedAction {
+	action: string;
+	prompt: ILimitedActionPrompt;
+}
+
+export interface ILimitedActionPrompt {
+	__typename: string;
+	cta_type: string;
+	headline: IPromptHeadline;
+	subtext: IPromptSubtext;
+}
+
+export interface IPromptHeadline {
+	text: string;
+	entities: any[];
+}
+
+export interface IPromptSubtext {
+	text: string;
+	entities: any[];
+}