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

package/src/types/args/PostArgs.ts

@@ -0,0 +1,112 @@
+/**
+ * Options specifying the data that is to be posted.
+ *
+ * @public
+ */
+export interface IPostArgs {
+	/**
+	 * The id of the target resource.
+	 *
+	 * @remarks
+	 * Required only when posting using the following resources:
+	 * - {@link EResourceType.TWEET_LIKE}
+	 * - {@link EResourceType.TWEET_RETWEET}
+	 * - {@link EResourceType.TWEET_UNLIKE}
+	 * - {@link EResourceType.TWEET_UNPOST}
+	 * - {@link EResourceType.TWEET_UNRETWEET}
+	 * - {@link EResourceType.USER_FOLLOW}
+	 * - {@link EResourceType.USER_UNFOLLOW}
+	 */
+	id?: string;
+
+	/**
+	 * The tweet that is to be posted.
+	 *
+	 * @remarks
+	 * Required only when posting a tweet using {@link EResourceType.TWEET_POST}
+	 */
+	tweet?: INewTweet;
+
+	/**
+	 * The media file to be uploaded.
+	 *
+	 * @remarks
+	 * Required only when uploading a media using the following resources:
+	 * - {@link EResourceType.MEDIA_UPLOAD_APPEND}
+	 * - {@link EResourceType.MEDIA_UPLOAD_FINALIZE}
+	 * - {@link EResourceType.MEDIA_UPLOAD_INITIALIZE}
+	 */
+	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

@@ -0,0 +1,22 @@
+/**
+ * The cookie containing the tokens that are used to authenticate against Twitter.
+ *
+ * @public
+ */
+export interface IAuthCookie {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	/** The bearer token from twitter.com. */
+	auth_token: string;
+
+	/** The CSRF token for the session. */
+	ct0: string;
+
+	/** Token used to authenticate a device. */
+	kdt: string;
+
+	/** Token used to authenticate a user using a Twitter ID. */
+	twid: string;
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+}

package/src/types/auth/AuthCredential.ts

@@ -0,0 +1,28 @@
+import { EAuthenticationType } from '../../enums/Authentication';
+
+/**
+ * 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.
+ *
+ * @public
+ */
+export interface IAuthCredential {
+	/** The bearer token from twitter.com. */
+	authToken?: string;
+
+	/** The type of authentication. */
+	authenticationType?: EAuthenticationType;
+
+	/** The cookie of the twitter account, which is used to authenticate against twitter. */
+	cookies?: string;
+
+	/** The CSRF token for the session. */
+	csrfToken?: string;
+
+	/** The guest token provided by Twitter API. */
+	guestToken?: string;
+}

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

@@ -0,0 +1,18 @@
+import { INotification } from './Notification';
+import { ITweet } from './Tweet';
+import { IUser } from './User';
+
+/**
+ * The data that is fetched batch-wise using a cursor.
+ *
+ * @typeParam T - Type of data to be stored.
+ *
+ * @public
+ */
+export interface ICursoredData<T extends INotification | ITweet | IUser> {
+	/** The batch of data of the given type. */
+	list: T[];
+
+	/** The cursor to the next batch of data. */
+	next: string;
+}

package/src/types/data/List.ts

@@ -0,0 +1,27 @@
+/**
+ * The details of a single Twitter List.
+ *
+ * @public
+ */
+export interface IList {
+	/** The date and time of creation of the list, int UTC string format. */
+	createdAt: string;
+
+	/** The rest id of the user who created the list. */
+	createdBy: string;
+
+	/** The list description. */
+	description?: string;
+
+	/** The rest id of the list. */
+	id: string;
+
+	/** The number of memeber of the list. */
+	memberCount: number;
+
+	/** The name of the list. */
+	name: string;
+
+	/** The number of subscribers of the list. */
+	subscriberCount: number;
+}

package/src/types/data/Notification.ts

@@ -0,0 +1,26 @@
+import { ENotificationType } from '../../enums/Notification';
+
+/**
+ * The details of a single notification.
+ *
+ * @public
+ */
+export interface INotification {
+	/** The list of id of the users from whom the notification was received. */
+	from: string[];
+
+	/** The id of the notification. */
+	id: string;
+
+	/** The text contents of the notification. */
+	message: string;
+
+	/** The date/time at which the notification was received. */
+	receivedAt: string;
+
+	/** The list of id of the target tweet(s) of the notification. */
+	target: string[];
+
+	/** The type of notification. */
+	type?: ENotificationType;
+}

package/src/types/data/Tweet.ts

@@ -0,0 +1,96 @@
+import { EMediaType } from '../../enums/Media';
+
+import { IUser } from './User';
+
+/**
+ * The details of a single tweet.
+ *
+ * @public
+ */
+export interface ITweet {
+	/** The number of bookmarks of a tweet. */
+	bookmarkCount: number;
+
+	/** The ID of tweet which started the current conversation. */
+	conversationId: string;
+
+	/** The creation date of the tweet. */
+	createdAt: string;
+
+	/** Additional tweet entities like urls, mentions, etc. */
+	entities: ITweetEntities;
+
+	/** The full text content of the tweet. */
+	fullText: string;
+
+	/** The rest id of the tweet. */
+	id: string;
+
+	/** The language in which the tweet is written. */
+	lang: string;
+
+	/** The number of likes of the tweet. */
+	likeCount: number;
+
+	/** The urls of the media contents of the tweet (if any). */
+	media?: ITweetMedia[];
+
+	/** The number of quotes of the tweet. */
+	quoteCount: number;
+
+	/** The tweet which is quoted in the tweet. */
+	quoted?: ITweet;
+
+	/** The number of replies to the tweet. */
+	replyCount: number;
+
+	/** The rest id of the tweet to which the tweet is a reply. */
+	replyTo?: string;
+
+	/** The number of retweets of the tweet. */
+	retweetCount: number;
+
+	/** The tweet which is retweeted in this tweet (if any). */
+	retweetedTweet?: ITweet;
+
+	/** The details of the user who made the tweet. */
+	tweetBy: IUser;
+
+	/** The URL to the tweet. */
+	url: string;
+
+	/** The number of views of a tweet. */
+	viewCount: number;
+}
+
+/**
+ * The different types parsed entities like urls, media, mentions, hashtags, etc.
+ *
+ * @public
+ */
+export interface ITweetEntities {
+	/** The list of hashtags mentioned in the tweet. */
+	hashtags: string[];
+
+	/** The list of IDs of users mentioned in the tweet. */
+	mentionedUsers: string[];
+
+	/** The list of urls mentioned in the tweet. */
+	urls: string[];
+}
+
+/**
+ * The details of a single media content included in a tweet.
+ *
+ * @public
+ */
+export interface ITweetMedia {
+	/** The thumbnail URL for the video content of the tweet. */
+	thumbnailUrl?: string;
+
+	/** The type of media. */
+	type: EMediaType;
+
+	/** The direct URL to the media. */
+	url: string;
+}

package/src/types/data/User.ts

@@ -0,0 +1,48 @@
+/**
+ * The details of a single user.
+ *
+ * @public
+ */
+export interface IUser {
+	/** The creation date of user's account. */
+	createdAt: string;
+
+	/** The user's description. */
+	description?: string;
+
+	/** The number of followers of the user. */
+	followersCount: number;
+
+	/** The number of following of the user. */
+	followingsCount: number;
+
+	/** The full name of the user. */
+	fullName: string;
+
+	/** The rest id of the user. */
+	id: string;
+
+	/** Whether the account is verified or not. */
+	isVerified: boolean;
+
+	/** The number of tweets liked by the user. */
+	likeCount: number;
+
+	/** The location of user as provided by user. */
+	location?: string;
+
+	/** The rest id of the tweet pinned in the user's profile. */
+	pinnedTweet?: string;
+
+	/** The url of the profile banner image. */
+	profileBanner?: string;
+
+	/** The url of the profile image. */
+	profileImage: string;
+
+	/** The number of tweets made by the user. */
+	statusesCount: number;
+
+	/** The username/screenname of the user. */
+	userName: string;
+}

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[];
+}

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

@@ -0,0 +1,50 @@
+/* eslint-disable */
+
+import { IDataResult } from '../composite/DataResult';
+import { IUser } from './User';
+
+/**
+ * Represents the raw data of a single List.
+ *
+ * @public
+ */
+export interface IList {
+	created_at: number;
+	default_banner_media: IDefaultBannerMedia;
+	default_banner_media_results: IDefaultBannerMediaResults;
+	description: string;
+	following: boolean;
+	id: string;
+	id_str: string;
+	is_member: boolean;
+	member_count: number;
+	mode: string;
+	muting: boolean;
+	name: string;
+	subscriber_count: number;
+	user_results: IDataResult<IUser>;
+	facepile_urls: string[];
+	followers_context: string;
+	members_context: string;
+}
+
+export interface IDefaultBannerMedia {
+	media_info: IBannerMediaInfo;
+}
+
+export interface IDefaultBannerMediaResults {
+	result: IBannerMediaResult;
+}
+
+export interface IBannerMediaResult {
+	id: string;
+	media_key: string;
+	media_id: string;
+	media_info: IBannerMediaInfo;
+}
+
+export interface IBannerMediaInfo {
+	original_img_url: string;
+	original_img_width: number;
+	original_img_height: number;
+}

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

@@ -0,0 +1,53 @@
+/* eslint-disable */
+
+import { ERawMediaType } from '../../../enums/raw/Media';
+
+/**
+ * Represents the raw data of a single Media.
+ *
+ * @public
+ */
+export interface IMedia {
+	display_url: string;
+	expanded_url: string;
+	id_str: string;
+	media_url_https: string;
+	type: ERawMediaType;
+	url: string;
+}
+
+export interface IExtendedMedia extends IMedia {
+	media_key: string;
+	ext_media_availability: IMediaAvailability;
+	additional_media_info?: IAdditionalMediaInfo;
+	mediaStats?: IMediaStats;
+	video_info?: IVideoInfo;
+}
+
+export interface IMediaAvailability {
+	status: string;
+}
+
+export interface IAdditionalMediaInfo {
+	monetizable: boolean;
+}
+
+export interface IMediaStats {
+	viewCount: number;
+}
+
+export interface IMediaAvailability {
+	status: string;
+}
+
+export interface IVideoInfo {
+	aspect_ratio: number[];
+	duration_millis: number;
+	variants: IVideoVariant[];
+}
+
+export interface IVideoVariant {
+	bitrate: number;
+	content_type: string;
+	url: string;
+}