rettiwt-api 2.2.1 → 2.3.0

package/src/models/internal/RettiwtConfig.ts

@@ -0,0 +1,29 @@
+// TYPES
+import { IRettiwtConfig } from '../../types/internal/RettiwtConfig';
+
+/**
+ * The configuration for initializing a new Rettiwt instance.
+ *
+ * @internal
+ */
+export class RettiwtConfig implements IRettiwtConfig {
+	/** The apiKey (cookie) to use for authenticating Rettiwt against Twitter API. */
+	public apiKey?: string;
+
+	/** Optional URL with proxy configuration to use for requests to Twitter API. */
+	public proxyUrl?: URL;
+
+	/** Whether to write logs to console or not. */
+	public logging?: boolean;
+
+	/**
+	 * Initializes a new configuration object from the given config.
+	 *
+	 * @param config - The configuration object.
+	 */
+	public constructor(config: RettiwtConfig) {
+		this.apiKey = config.apiKey;
+		this.proxyUrl = config.proxyUrl;
+		this.logging = config.logging;
+	}
+}

package/src/models/{CursoredData.ts → public/CursoredData.ts}

@@ -1,12 +1,9 @@
-// PACKAGES
-import { ITweet as IRawTweet, IUser as IRawUser } from 'rettiwt-core';
-
 // MODELS
 import { Tweet } from './Tweet';
 import { User } from './User';
 
 // TYPES
-import { ICursor, ICursoredData } from '../types/CursoredData';
+import { ICursor, ICursoredData } from '../../types/public/CursoredData';
 
 /**
  * The data that us fetched batch-wise along with a cursor.
@@ -17,29 +14,17 @@ import { ICursor, ICursoredData } from '../types/CursoredData';
  */
 export class CursoredData<T extends Tweet | User> implements ICursoredData<T> {
 	/** The list of data of the given type. */
-	list: T[] = [];
+	public list: T[] = [];
 
 	/** The cursor to the next batch of data. */
-	next: Cursor;
+	public next: Cursor;
 
 	/**
 	 * @param list - The list of data item to store.
 	 * @param next - The cursor to the next batch of data.
 	 */
-	constructor(list: (IRawTweet | IRawUser)[] = [], next: string = '') {
-		// Deserializing the input raw data and storing it in the list
-		for (const item of list) {
-			// If the item is a valid raw tweet
-			if (item.__typename == 'Tweet' && item.rest_id) {
-				this.list.push(new Tweet(item as IRawTweet) as T);
-			}
-			// If the item is a valid raw user
-			else if (item.__typename == 'User' && item.rest_id && (item as IRawUser).id) {
-				this.list.push(new User(item as IRawUser) as T);
-			}
-		}
-
-		// Initializing cursors
+	public constructor(list: T[] = [], next: string = '') {
+		this.list = list;
 		this.next = new Cursor(next);
 	}
 }
@@ -51,14 +36,14 @@ export class CursoredData<T extends Tweet | User> implements ICursoredData<T> {
  */
 export class Cursor implements ICursor {
 	/** The cursor string. */
-	value: string;
+	public value: string;
 
 	/**
 	 * Initializes a new cursor from the given cursor string.
 	 *
 	 * @param cursorStr - The string representation of the cursor.
 	 */
-	constructor(cursorStr: string) {
+	public constructor(cursorStr: string) {
 		this.value = cursorStr;
 	}
 }

package/src/models/{List.ts → public/List.ts}

@@ -2,7 +2,7 @@
 import { IList as IRawList } from 'rettiwt-core';
 
 // TYPES
-import { IList } from '../types/List';
+import { IList } from '../../types/public/List';
 
 /**
  * The details of a single Twitter List.
@@ -11,32 +11,32 @@ import { IList } from '../types/List';
  */
 export class List implements IList {
 	/** The rest id of the list. */
-	id: string;
+	public id: string;
 
 	/** The name of the list. */
-	name: string;
+	public name: string;
 
 	/** The date and time of creation of the list, int UTC string format. */
-	createdAt: string;
+	public createdAt: string;
 
 	/** The list description. */
-	description: string;
+	public description: string;
 
 	/** The number of memeber of the list. */
-	memberCount: number;
+	public memberCount: number;
 
 	/** The number of subscribers of the list. */
-	subscriberCount: number;
+	public subscriberCount: number;
 
 	/** The rest id of the user who created the list. */
-	createdBy: string;
+	public createdBy: string;
 
 	/**
 	 * Initializes a new Tweet List from the given raw list data.
 	 *
 	 * @param list - list The raw tweet list data.
 	 */
-	constructor(list: IRawList) {
+	public constructor(list: IRawList) {
 		this.id = list.id_str;
 		this.name = list.name;
 		this.createdAt = new Date(list.created_at).toISOString();

package/src/models/{Tweet.ts → public/Tweet.ts}

@@ -7,13 +7,13 @@ import {
 } from 'rettiwt-core';
 
 // TYPES
-import { ITweet, ITweetEntities } from '../types/Tweet';
+import { ITweet, ITweetEntities } from '../../types/public/Tweet';
 
 // MODELS
 import { User } from './User';
 
 // PARSERS
-import { normalizeText } from '../helper/JsonUtils';
+import { normalizeText } from '../../helper/JsonUtils';
 
 /**
  * The details of a single Tweet.
@@ -22,56 +22,56 @@ import { normalizeText } from '../helper/JsonUtils';
  */
 export class Tweet implements ITweet {
 	/** The rest id of the tweet. */
-	id: string;
+	public id: string;
 
 	/** The details of the user who made the tweet. */
-	tweetBy: User;
+	public tweetBy: User;
 
 	/** The date and time of creation of the tweet, in UTC string format. */
-	createdAt: string;
+	public createdAt: string;
 
 	/** Additional tweet entities like urls, mentions, etc. */
-	entities: TweetEntities;
+	public entities: TweetEntities;
 
 	/** The urls of the media contents of the tweet (if any). */
-	media: TweetMedia[];
+	public media: TweetMedia[];
 
 	/** The rest id of the tweet which is quoted in the tweet. */
-	quoted: string;
+	public quoted: string;
 
 	/** The full text content of the tweet. */
-	fullText: string;
+	public fullText: string;
 
 	/** The rest id of the user to which the tweet is a reply. */
-	replyTo: string;
+	public replyTo: string;
 
 	/** The language in which the tweet is written. */
-	lang: string;
+	public lang: string;
 
 	/** The number of quotes of the tweet. */
-	quoteCount: number;
+	public quoteCount: number;
 
 	/** The number of replies to the tweet. */
-	replyCount: number;
+	public replyCount: number;
 
 	/** The number of retweets of the tweet. */
-	retweetCount: number;
+	public retweetCount: number;
 
 	/** The number of likes of the tweet. */
-	likeCount: number;
+	public likeCount: number;
 
 	/** The number of views of a tweet. */
-	viewCount: number;
+	public viewCount: number;
 
 	/** The number of bookmarks of a tweet. */
-	bookmarkCount: number;
+	public bookmarkCount: number;
 
 	/**
 	 * Initializes a new Tweet from the given raw tweet data.
 	 *
 	 * @param tweet - The raw tweet data.
 	 */
-	constructor(tweet: IRawTweet) {
+	public constructor(tweet: IRawTweet) {
 		this.id = tweet.rest_id;
 		this.createdAt = tweet.legacy.created_at;
 		this.tweetBy = new User(tweet.core.user_results.result);
@@ -97,20 +97,20 @@ export class Tweet implements ITweet {
  */
 export class TweetEntities implements ITweetEntities {
 	/** The list of hashtags mentioned in the tweet. */
-	hashtags: string[] = [];
+	public hashtags: string[] = [];
 
 	/** The list of urls mentioned in the tweet. */
-	urls: string[] = [];
+	public urls: string[] = [];
 
 	/** The list of IDs of users mentioned in the tweet. */
-	mentionedUsers: string[] = [];
+	public mentionedUsers: string[] = [];
 
 	/**
 	 * Initializes the TweetEntities from the raw tweet entities.
 	 *
 	 * @param entities - The raw tweet entities.
 	 */
-	constructor(entities: IRawTweetEntities) {
+	public constructor(entities: IRawTweetEntities) {
 		// Extracting user mentions
 		if (entities.user_mentions) {
 			for (const user of entities.user_mentions) {
@@ -141,17 +141,17 @@ export class TweetEntities implements ITweetEntities {
  */
 export class TweetMedia {
 	/** The type of media. */
-	type: EMediaType;
+	public type: EMediaType;
 
 	/** The direct URL to the media. */
-	url: string = '';
+	public url: string = '';
 
 	/**
 	 * Initializes the TweetMedia from the raw tweet media.
 	 *
 	 * @param media - The raw tweet media.
 	 */
-	constructor(media: IRawExtendedMedia) {
+	public constructor(media: IRawExtendedMedia) {
 		this.type = media.type;
 
 		// If the media is a photo

package/src/models/{User.ts → public/User.ts}

@@ -2,7 +2,7 @@
 import { IUser as IRawUser } from 'rettiwt-core';
 
 // TYPES
-import { IUser } from '../types/User';
+import { IUser } from '../../types/public/User';
 
 /**
  * The details of a single user.
@@ -11,53 +11,53 @@ import { IUser } from '../types/User';
  */
 export class User implements IUser {
 	/** The rest id of the user. */
-	id: string;
+	public id: string;
 
 	/** The username/screenname of the user. */
-	userName: string;
+	public userName: string;
 
 	/** The full name of the user. */
-	fullName: string;
+	public fullName: string;
 
 	/** The creation date of user's account. */
-	createdAt: string;
+	public createdAt: string;
 
 	/** The user's description. */
-	description: string;
+	public description: string;
 
 	/** Whether the account is verified or not. */
-	isVerified: boolean;
+	public isVerified: boolean;
 
 	/** The number of tweets liked by the user. */
-	favouritesCount: number;
+	public favouritesCount: number;
 
 	/** The number of followers of the user. */
-	followersCount: number;
+	public followersCount: number;
 
 	/** The number of following of the user. */
-	followingsCount: number;
+	public followingsCount: number;
 
 	/** The number of tweets made by the user. */
-	statusesCount: number;
+	public statusesCount: number;
 
 	/** The location of user as provided by user. */
-	location: string;
+	public location: string;
 
 	/** The rest id of the tweet pinned in the user's profile. */
-	pinnedTweet: string;
+	public pinnedTweet: string;
 
 	/** The url of the profile banner image. */
-	profileBanner: string;
+	public profileBanner: string;
 
 	/** The url of the profile image. */
-	profileImage: string;
+	public profileImage: string;
 
 	/**
 	 * Initializes a new User from the given raw user data.
 	 *
 	 * @param user - The raw user data.
 	 */
-	constructor(user: IRawUser) {
+	public constructor(user: IRawUser) {
 		this.id = user.rest_id;
 		this.userName = user.legacy.screen_name;
 		this.fullName = user.legacy.name;

package/src/services/{FetcherService.ts → internal/FetcherService.ts}

@@ -13,20 +13,25 @@ import {
 } from 'rettiwt-core';
 import axios, { AxiosRequestConfig, AxiosRequestHeaders, AxiosResponse } from 'axios';
 import https, { Agent } from 'https';
-import { AuthCredential } from 'rettiwt-auth';
+import { AuthCredential, Auth } from 'rettiwt-auth';
 import { HttpsProxyAgent } from 'https-proxy-agent';
 
+// SERVICES
+import { LogService } from './LogService';
+
 // ENUMS
-import { EHttpStatus } from '../enums/HTTP';
-import { EApiErrors } from '../enums/ApiErrors';
+import { EHttpStatus } from '../../enums/HTTP';
+import { EApiErrors } from '../../enums/ApiErrors';
+import { ELogActions } from '../../enums/Logging';
 
 // MODELS
-import { CursoredData } from '../models/CursoredData';
-import { Tweet } from '../models/Tweet';
-import { User } from '../models/User';
+import { RettiwtConfig } from '../../models/internal/RettiwtConfig';
+import { CursoredData } from '../../models/public/CursoredData';
+import { Tweet } from '../../models/public/Tweet';
+import { User } from '../../models/public/User';
 
 // HELPERS
-import { findByFilter, findKeyByValue } from '../helper/JsonUtils';
+import { findByFilter, findKeyByValue } from '../../helper/JsonUtils';
 
 /**
  * The base service that handles all HTTP requests.
@@ -35,18 +40,25 @@ import { findByFilter, findKeyByValue } from '../helper/JsonUtils';
  */
 export class FetcherService {
 	/** The credential to use for authenticating against Twitter API. */
-	private cred: AuthCredential;
+	private cred?: AuthCredential;
+
+	/** Whether the instance is authenticated or not. */
+	private readonly isAuthenticated: boolean;
 
 	/** The HTTPS Agent to use for requests to Twitter API. */
 	private readonly httpsAgent: Agent;
 
+	/** The log service instance to use to logging. */
+	private readonly logger: LogService;
+
 	/**
-	 * @param apiKey - The apiKey (cookie) to use for authenticating Rettiwt against Twitter API.
-	 * @param proxyUrl - Optional URL with proxy configuration to use for requests to Twitter API.
+	 * @param config - The config object for configuring the Rettiwt instance.
 	 */
-	constructor(apiKey: string, proxyUrl?: URL) {
-		this.cred = this.getAuthCredential(apiKey);
-		this.httpsAgent = this.getHttpsAgent(proxyUrl);
+	public constructor(config?: RettiwtConfig) {
+		this.cred = config?.apiKey ? this.getAuthCredential(config.apiKey) : undefined;
+		this.isAuthenticated = config?.apiKey ? true : false;
+		this.httpsAgent = this.getHttpsAgent(config?.proxyUrl);
+		this.logger = new LogService(config?.logging);
 	}
 
 	/**
@@ -59,6 +71,27 @@ export class FetcherService {
 		return new AuthCredential(apiKey.split(';'));
 	}
 
+	/**
+	 * Checks the authorization status based on the requested resource.
+	 *
+	 * @param resourceType - The type of resource to fetch.
+	 * @throws An error if not authorized to access the requested resource.
+	 */
+	private checkAuthorization(resourceType: EResourceType): void {
+		// Logging
+		this.logger.log(ELogActions.AUTHORIZATION, { authenticated: this.isAuthenticated });
+
+		// Checking authorization status
+		if (
+			resourceType != EResourceType.TWEET_DETAILS &&
+			resourceType != EResourceType.USER_DETAILS &&
+			resourceType != EResourceType.USER_TWEETS &&
+			this.isAuthenticated == false
+		) {
+			throw new Error(EApiErrors.RESOURCE_NOT_ALLOWED);
+		}
+	}
+
 	/**
 	 * Gets the HttpsAgent based on whether a proxy is used or not.
 	 *
@@ -78,6 +111,7 @@ export class FetcherService {
 	 *
 	 * @param res - The response object received.
 	 * @returns The received response, if no HTTP errors are found.
+	 * @throws An error if any HTTP-related error has occured.
 	 */
 	private handleHttpError(res: AxiosResponse<IResponse<unknown>>): AxiosResponse<IResponse<unknown>> {
 		/**
@@ -95,6 +129,7 @@ export class FetcherService {
 	 *
 	 * @param res - The response object received.
 	 * @returns The received response, if no API errors are found.
+	 * @throws An error if any API-related error has occured.
 	 */
 	private handleApiError(res: AxiosResponse<IResponse<unknown>>): AxiosResponse<IResponse<unknown>> {
 		// If error exists
@@ -121,6 +156,12 @@ export class FetcherService {
 	 * @returns The response received.
 	 */
 	private async request(config: Request): Promise<AxiosResponse<IResponse<unknown>>> {
+		// Checking authorization for the requested resource
+		this.checkAuthorization(config.endpoint);
+
+		// If not authenticated, use guest authentication
+		this.cred = this.cred ?? (await new Auth().getGuestCredential());
+
 		/**
 		 * Creating axios request configuration from the input configuration.
 		 */
@@ -145,14 +186,18 @@ export class FetcherService {
 	 *
 	 * @param data - The data from which extraction is to be done.
 	 * @param type - The type of data to extract.
-	 * @typeParam BaseType - The base type of the raw data present in the input.
-	 * @typeParam DeserializedType - The type of data produced after deserialization of BaseType.
 	 * @returns The extracted data.
 	 */
-	private extractData<DeserializedType extends Tweet | User>(
+	private extractData(
 		data: NonNullable<unknown>,
 		type: EResourceType,
-	): CursoredData<DeserializedType> {
+	): {
+		/** The required extracted data. */
+		required: (IRawTweet | IRawUser)[];
+
+		/** The cursor string to the next batch of data. */
+		next: string;
+	} {
 		/**
 		 * The required extracted data.
 		 */
@@ -166,7 +211,8 @@ export class FetcherService {
 			type == EResourceType.TWEET_SEARCH ||
 			type == EResourceType.USER_LIKES ||
 			type == EResourceType.LIST_TWEETS ||
-			type == EResourceType.USER_TWEETS
+			type == EResourceType.USER_TWEETS ||
+			type == EResourceType.USER_TWEETS_AND_REPLIES
 		) {
 			required = findByFilter<ITimelineTweet>(data, '__typename', 'TimelineTweet').map(
 				(item) => item.tweet_results.result,
@@ -182,7 +228,47 @@ export class FetcherService {
 			);
 		}
 
-		return new CursoredData(required, findByFilter<IRawCursor>(data, 'cursorType', 'Bottom')[0]?.value);
+		return {
+			required: required,
+			next: findByFilter<IRawCursor>(data, 'cursorType', 'Bottom')[0]?.value,
+		};
+	}
+
+	/**
+	 * Deserializes the extracted data into a cursored list.
+	 *
+	 * @param extractedData - The list of extracted data.
+	 * @param next - The cursor to the next batch of data.
+	 * @returns The cursored data object.
+	 */
+	private deserializeData<OutType extends Tweet | User>(
+		extractedData: (IRawTweet | IRawUser)[] = [],
+		next: string = '',
+	): CursoredData<OutType> {
+		/** The list of deserialized data. */
+		const deserializedList: OutType[] = [];
+
+		// Deserializing the extracted raw data and storing it in the list
+		for (const item of extractedData) {
+			// If the item is a valid raw tweet
+			if (item && item.__typename == 'Tweet' && item.rest_id) {
+				// Logging
+				this.logger.log(ELogActions.DESERIALIZE, { type: item.__typename, id: item.rest_id });
+
+				// Adding deserialized Tweet to list
+				deserializedList.push(new Tweet(item as IRawTweet) as OutType);
+			}
+			// If the item is a valid raw user
+			else if (item && item.__typename == 'User' && item.rest_id && (item as IRawUser).id) {
+				// Logging
+				this.logger.log(ELogActions.DESERIALIZE, { type: item.__typename, id: item.rest_id });
+
+				// Adding deserialized User to list
+				deserializedList.push(new User(item as IRawUser) as OutType);
+			}
+		}
+
+		return new CursoredData<OutType>(deserializedList, next);
 	}
 
 	/**
@@ -197,6 +283,9 @@ export class FetcherService {
 		resourceType: EResourceType,
 		args: Args,
 	): Promise<CursoredData<OutType>> {
+		// Logging
+		this.logger.log(ELogActions.FETCH, { resourceType: resourceType, args: args });
+
 		// Preparing the HTTP request
 		const request: Request = new Request(resourceType, args);
 
@@ -204,9 +293,12 @@ export class FetcherService {
 		const res = await this.request(request).then((res) => res.data);
 
 		// Extracting data
-		const data = this.extractData<OutType>(res, resourceType);
+		const extractedData = this.extractData(res, resourceType);
+
+		// Deserializing data
+		const deserializedData = this.deserializeData<OutType>(extractedData.required, extractedData.next);
 
-		return data;
+		return deserializedData;
 	}
 
 	/**
@@ -217,6 +309,9 @@ export class FetcherService {
 	 * @returns Whether posting was successful or not.
 	 */
 	protected async post(resourceType: EResourceType, args: Args): Promise<boolean> {
+		// Logging
+		this.logger.log(ELogActions.POST, { resourceType: resourceType, args: args });
+
 		// Preparing the HTTP request
 		const request: Request = new Request(resourceType, args);
 

package/src/services/internal/LogService.ts

@@ -0,0 +1,39 @@
+// ENUMS
+import { ELogActions } from '../../enums/Logging';
+
+/**
+ * Handles logging of data for debug purpose.
+ *
+ * @internal
+ */
+export class LogService {
+	/** Whether logging is enabled or not. */
+	private readonly enabled: boolean;
+
+	/**
+	 * Initializes a new LogService instance.
+	 *
+	 * @param enable - Whether to enable logging or not.
+	 */
+	public constructor(enable?: boolean) {
+		this.enabled = enable ?? false;
+	}
+
+	/**
+	 * Logs the given data.
+	 *
+	 * @param data - The data to be logged.
+	 */
+	public log(action: ELogActions, data: NonNullable<unknown>): void {
+		// Proceed to log only if logging is enabled
+		if (this.enabled) {
+			// Preparing the log message
+			const logMessage: string = `[Rettiwt-API] [${action}] [${new Date().toISOString()}] ${JSON.stringify(
+				data,
+			)}`;
+
+			// Logging
+			console.log(logMessage);
+		}
+	}
+}