@glagan/rettiwt-api 7.0.0

package/src/types/ErrorHandler.ts

@@ -0,0 +1,13 @@
+/**
+ * Defines the error handler that processes API/HTTP errors in the responses.
+ *
+ * @public
+ */
+export interface IErrorHandler {
+	/**
+	 * The method called when an error response is received from Twitter API.
+	 *
+	 * @param error - The error caught while making request to Twitter API.
+	 */
+	handle(error: unknown): void;
+}

package/src/types/Fetch.ts

@@ -0,0 +1,3 @@
+import { FetchOptions } from 'ofetch';
+
+export type FetchConfig = FetchOptions & { url: string };

package/src/types/RettiwtConfig.ts

@@ -0,0 +1,48 @@
+import { IErrorHandler } from './ErrorHandler';
+
+/**
+ * The configuration for initializing a new Rettiwt instance.
+ *
+ * @public
+ */
+export interface IRettiwtConfig {
+	/** The apiKey (cookie) to use for authenticating Rettiwt against Twitter API. */
+	apiKey?: string;
+
+	/**
+	 * Optional URL to proxy server to use for requests to Twitter API.
+	 *
+	 * @remarks When deploying to cloud platforms, if setting {@link IRettiwtConfig.authProxyUrl} does not resolve Error 429, then this might be required.
+	 */
+	proxyUrl?: URL;
+
+	/** The max wait time (in milli-seconds) for a response; if not set, Twitter server timeout is used. */
+	timeout?: number;
+
+	/** Whether to write logs to console or not. */
+	logging?: boolean;
+
+	/** Optional custom error handler to define error conditions and process API/HTTP errors in responses. */
+	errorHandler?: IErrorHandler;
+
+	/**
+	 * 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>);
+
+	/**
+	 * The maximum number of retries to use.
+	 *
+	 * @remarks Recommended to use a value of 5 combined with a `delay` of 1000 to prevent error 404.
+	 */
+	maxRetries?: number;
+}

package/src/types/args/FetchArgs.ts

@@ -0,0 +1,233 @@
+import { RawAnalyticsGranularity, RawAnalyticsMetric } from '../../enums/raw/Analytics';
+import { TweetRepliesSortType } from '../../enums/Tweet';
+
+/**
+ * Options specifying the data that is to be fetched.
+ *
+ * @public
+ */
+export interface IFetchArgs {
+	/**
+	 * The id of the active conversation.
+	 *
+	 * @remarks
+	 * - Required only for {@link ResourceType.DM_USER_UPDATES}.
+	 */
+	activeConversationId?: string;
+
+	/**
+	 * The maximum id of the data to fetch.
+	 *
+	 * @remarks
+	 * - May be used for {@link ResourceType.DM_INBOX_TIMELINE} and {@link ResourceType.DM_CONVERSATION}.
+	 */
+	maxId?: string;
+
+	/**
+	 * The id of the conversation to fetch.
+	 *
+	 * @remarks
+	 * - Required only for {@link ResourceType.DM_CONVERSATION} and {@link ResourceType.DM_DELETE_CONVERSATION}.
+	 */
+	conversationId?: string;
+
+	/**
+	 * The number of data items to fetch.
+	 *
+	 * @remarks
+	 * - Works only for cursored resources.
+	 * - Does not work for {@link ResourceType.TWEET_REPLIES}.
+	 * - Must be \<= 20 for:
+	 * 	- {@link ResourceType.USER_TIMELINE}
+	 * 	- {@link ResourceType.USER_TIMELINE}
+	 * 	- {@link ResourceType.USER_TIMELINE_AND_REPLIES}
+	 * - Must be \<= 100 for all other cursored resources.
+	 * - Due a bug on Twitter's end, count does not work for {@link ResourceType.USER_FOLLOWERS} and {@link ResourceType.USER_FOLLOWING}.
+	 * - Has not effect for:
+	 * 	- {@link ResourceType.USER_FEED_FOLLOWED}
+	 * 	- {@link ResourceType.USER_FEED_RECOMMENDED}
+	 */
+	count?: number;
+
+	/**
+	 * The cursor to the batch of data to fetch.
+	 *
+	 * @remarks
+	 * - May be used for cursored resources.
+	 * - Has no effect for other resources.
+	 */
+	cursor?: string;
+
+	/**
+	 * The filter for searching tweets.
+	 *
+	 * @remarks
+	 * Required when searching for tweets using {@link ResourceType.TWEET_SEARCH}.
+	 */
+	filter?: ITweetFilter;
+
+	/**
+	 * The id of the target resource.
+	 *
+	 * @remarks
+	 * - Required for all resources except {@link ResourceType.TWEET_SEARCH} and {@link ResourceType.USER_TIMELINE_RECOMMENDED}.
+	 * - For {@link ResourceType.USER_DETAILS_BY_USERNAME} and {@link ResourceType.USER_SEARCH}, can be alphanumeric, while for others, is strictly numeric.
+	 */
+	id?: string;
+
+	/**
+	 * The IDs of the target resources.
+	 *
+	 * @remarks
+	 * - Required only for {@link ResourceType.TWEET_DETAILS_BULK} and {@link ResourceType.USER_DETAILS_BY_IDS_BULK}.
+	 */
+	ids?: string[];
+
+	/**
+	 * The sorting to use for tweet results.
+	 *
+	 * @remarks
+	 * - Only works for {@link ResourceType.TWEET_REPLIES}.
+	 */
+	sortBy?: TweetRepliesSortType;
+
+	/**
+	 * The date to start fetching data from.
+	 *
+	 * @remarks
+	 * - Only works for {@link EResourceType.USER_ANALYTICS}.
+	 */
+	fromTime?: Date;
+
+	/**
+	 * The date to end fetching data at.
+	 *
+	 * @remarks
+	 * - Only works for {@link EResourceType.USER_ANALYTICS}.
+	 */
+	toTime?: Date;
+
+	/**
+	 * The granularity of the data to fetch.
+	 *
+	 * @remarks
+	 * - Only works for {@link EResourceType.USER_ANALYTICS}.
+	 */
+	granularity?: RawAnalyticsGranularity;
+
+	/**
+	 * The metrics to fetch.
+	 *
+	 * @remarks
+	 * - Only works for {@link EResourceType.USER_ANALYTICS}.
+	 */
+	metrics?: RawAnalyticsMetric[];
+
+	/**
+	 * Show the verified follower count and relationship counts in the response.
+	 *
+	 * @remarks
+	 * - Only works for {@link EResourceType.USER_ANALYTICS}.
+	 */
+	showVerifiedFollowers?: boolean;
+}
+
+/**
+ * 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;
+
+	/** 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.
+	 *
+	 * @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;
+
+	/**
+	 * Whether to search only posts that contain links.
+	 *
+	 * @remarks 'links' includes things like media, quotes, retweets, etc.
+	 */
+	onlyLinks?: boolean;
+
+	/** Whether to search only original posts. */
+	onlyOriginal?: boolean;
+
+	/** Whether to search only replies */
+	onlyReplies?: boolean;
+
+	/** Whether to search posts that only contain text. */
+	onlyText?: boolean;
+
+	/** The optional words to search. */
+	optionalWords?: string[];
+
+	/** The id of the tweet which is quoted in the tweets to search. */
+	quoted?: string;
+
+	/** 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
+	 * '\@' must be excluded from the username!
+	 */
+	toUsers?: string[];
+
+	/** Whether to fetch top tweets or not. */
+	top?: boolean;
+}

package/src/types/args/PostArgs.ts

@@ -0,0 +1,142 @@
+import { IProfileUpdateOptions } from './ProfileArgs';
+
+/**
+ * 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 ResourceType.TWEET_BOOKMARK}
+	 * - {@link ResourceType.TWEET_LIKE}
+	 * - {@link ResourceType.TWEET_RETWEET}
+	 * - {@link ResourceType.TWEET_UNBOOKMARK}
+	 * - {@link ResourceType.TWEET_UNLIKE}
+	 * - {@link ResourceType.TWEET_UNPOST}
+	 * - {@link ResourceType.TWEET_UNRETWEET}
+	 * - {@link ResourceType.USER_FOLLOW}
+	 * - {@link ResourceType.USER_UNFOLLOW}
+	 */
+	id?: string;
+
+	/**
+	 * The tweet that is to be posted.
+	 *
+	 * @remarks
+	 * Required only when posting a tweet using {@link ResourceType.TWEET_POST}
+	 */
+	tweet?: INewTweet;
+
+	/**
+	 * The media file to be uploaded.
+	 *
+	 * @remarks
+	 * Required only when uploading a media using the following resources:
+	 * - {@link ResourceType.MEDIA_UPLOAD_APPEND}
+	 * - {@link ResourceType.MEDIA_UPLOAD_FINALIZE}
+	 * - {@link ResourceType.MEDIA_UPLOAD_INITIALIZE}
+	 */
+	upload?: IUploadArgs;
+
+	/**
+	 * The id of the target user.
+	 *
+	 * @remarks
+	 * Required only for the following resources:
+	 * - {@link ResourceType.LIST_MEMBER_ADD}
+	 * - {@link ResourceType.LIST_MEMBER_REMOVE}
+	 */
+	userId?: string;
+
+	/**
+	 * The id of the conversation to delete.
+	 *
+	 * @remarks
+	 * Required only when deleting a conversation using {@link ResourceType.DM_DELETE_CONVERSATION}
+	 */
+	conversationId?: string;
+
+	/**
+	 * Profile update options.
+	 *
+	 * @remarks
+	 * Required only when updating user profile using {@link ResourceType.USER_PROFILE_UPDATE}
+	 */
+	profileOptions?: IProfileUpdateOptions;
+}
+
+/**
+ * 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/args/ProfileArgs.ts

@@ -0,0 +1,33 @@
+/**
+ * Profile update options.
+ *
+ * @public
+ */
+export interface IProfileUpdateOptions {
+	/**
+	 * Bio/description of the user (max 160 characters).
+	 */
+	description?: string;
+
+	/**
+	 * Location of the user (max 30 characters).
+	 */
+	location?: string;
+
+	/**
+	 * Display name (max 50 characters).
+	 *
+	 * @remarks
+	 * The name field represents the user's display name shown on their profile.
+	 * This is different from the username (screen_name/handle).
+	 */
+	name?: string;
+
+	/**
+	 * URL associated with the profile.
+	 *
+	 * @remarks
+	 * Will be prepended with http:// if not present.
+	 */
+	url?: string;
+}

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 { AuthenticationType } 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?: AuthenticationType;
+
+	/** 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/TransactionHeader.ts

@@ -0,0 +1,8 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+
+/**
+ * The transaction information for Twitter.
+ */
+export interface ITransactionHeader {
+	'x-client-transaction-id': string;
+}

package/src/types/data/Analytics.ts

@@ -0,0 +1,58 @@
+import type { IAnalyticsMetric } from '../../types/raw/base/Analytic';
+/**
+ * The details of the analytic result of the connected User.
+ *
+ * @public
+ */
+export interface IAnalytics {
+	/** The creation date of user's account. */
+	createdAt: string;
+
+	/** Total followers number */
+	followers: number;
+
+	/** Total verified followers */
+	verifiedFollowers: number;
+
+	/** Total impressions on the given period */
+	impressions: number;
+
+	/** Total profile visits on the given period */
+	profileVisits: number;
+
+	/** Total Engagements on the given period */
+	engagements: number;
+
+	/** Total Follows on the given period */
+	follows: number;
+
+	/** Total Replies on the given period */
+	replies: number;
+
+	/** Total Likes on the given period */
+	likes: number;
+
+	/** Total Retweets on the given period */
+	retweets: number;
+
+	/** Total Bookmark on the given period */
+	bookmarks: number;
+
+	/** Total Shares on the given period */
+	shares: number;
+
+	/** Total CreateTweets on the given period */
+	createTweets: number;
+
+	/** Total CreateQuote on the given period */
+	createQuote: number;
+
+	/** Total Unfollows on the given period */
+	unfollows: number;
+
+	/** Total CreateReply on the given period */
+	createReply: number;
+
+	/** Organic metrics times series  */
+	organicMetricsTimeSeries: IAnalyticsMetric[];
+}

package/src/types/data/BookmarkFolder.ts

@@ -0,0 +1,12 @@
+/**
+ * The details of a single Bookmark Folder.
+ *
+ * @public
+ */
+export interface IBookmarkFolder {
+	/** The unique identifier for the folder. */
+	id: string;
+
+	/** The display name of the folder. */
+	name: string;
+}

package/src/types/data/Conversation.ts

@@ -0,0 +1,44 @@
+import { IDirectMessage } from './DirectMessage';
+
+/**
+ * The details of a single conversation.
+ *
+ * @public
+ */
+export interface IConversation {
+	/** The unique identifier of the conversation. */
+	id: string;
+
+	/** The type of conversation (ONE_TO_ONE or GROUP_DM). */
+	type: 'ONE_TO_ONE' | 'GROUP_DM';
+
+	/** Array of participant user IDs. */
+	participants: string[];
+
+	/** The name of the conversation (for group DMs). */
+	name?: string;
+
+	/** URL to the conversation avatar (for group DMs). */
+	avatarUrl?: string;
+
+	/** Whether the conversation is trusted. */
+	trusted: boolean;
+
+	/** Whether the conversation is muted. */
+	muted: boolean;
+
+	/** Whether notifications are disabled. */
+	notificationsDisabled: boolean;
+
+	/** The timestamp of the last activity (ISO 8601 format). */
+	lastActivityAt: string;
+
+	/** The ID of the last message. */
+	lastMessageId?: string;
+
+	/** Whether there are more messages to load. */
+	hasMore: boolean;
+
+	/** Array of messages in this conversation. */
+	messages: IDirectMessage[];
+}

package/src/types/data/CursoredData.ts

@@ -0,0 +1,24 @@
+import { IBookmarkFolder } from './BookmarkFolder';
+import { IConversation } from './Conversation';
+import { IDirectMessage } from './DirectMessage';
+import { IList } from './List';
+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 IDirectMessage | IConversation | INotification | ITweet | IUser | IList | IBookmarkFolder,
+> {
+	/** The batch of data of the given type. */
+	list: T[];
+
+	/** The cursor to the next batch of data. */
+	next: string;
+}