rettiwt-api 2.3.0 → 2.4.0

package/src/models/public/List.ts

@@ -10,25 +10,12 @@ import { IList } from '../../types/public/List';
  * @public
  */
 export class List implements IList {
-	/** The rest id of the list. */
 	public id: string;
-
-	/** The name of the list. */
 	public name: string;
-
-	/** The date and time of creation of the list, int UTC string format. */
 	public createdAt: string;
-
-	/** The list description. */
 	public description: string;
-
-	/** The number of memeber of the list. */
 	public memberCount: number;
-
-	/** The number of subscribers of the list. */
 	public subscriberCount: number;
-
-	/** The rest id of the user who created the list. */
 	public createdBy: string;
 
 	/**

package/src/models/public/Tweet.ts

@@ -21,49 +21,20 @@ import { normalizeText } from '../../helper/JsonUtils';
  * @public
  */
 export class Tweet implements ITweet {
-	/** The rest id of the tweet. */
 	public id: string;
-
-	/** The details of the user who made the tweet. */
 	public tweetBy: User;
-
-	/** The date and time of creation of the tweet, in UTC string format. */
 	public createdAt: string;
-
-	/** Additional tweet entities like urls, mentions, etc. */
 	public entities: TweetEntities;
-
-	/** The urls of the media contents of the tweet (if any). */
 	public media: TweetMedia[];
-
-	/** The rest id of the tweet which is quoted in the tweet. */
 	public quoted: string;
-
-	/** The full text content of the tweet. */
 	public fullText: string;
-
-	/** The rest id of the user to which the tweet is a reply. */
 	public replyTo: string;
-
-	/** The language in which the tweet is written. */
 	public lang: string;
-
-	/** The number of quotes of the tweet. */
 	public quoteCount: number;
-
-	/** The number of replies to the tweet. */
 	public replyCount: number;
-
-	/** The number of retweets of the tweet. */
 	public retweetCount: number;
-
-	/** The number of likes of the tweet. */
 	public likeCount: number;
-
-	/** The number of views of a tweet. */
 	public viewCount: number;
-
-	/** The number of bookmarks of a tweet. */
 	public bookmarkCount: number;
 
 	/**
@@ -96,13 +67,8 @@ export class Tweet implements ITweet {
  * @public
  */
 export class TweetEntities implements ITweetEntities {
-	/** The list of hashtags mentioned in the tweet. */
 	public hashtags: string[] = [];
-
-	/** The list of urls mentioned in the tweet. */
 	public urls: string[] = [];
-
-	/** The list of IDs of users mentioned in the tweet. */
 	public mentionedUsers: string[] = [];
 
 	/**
@@ -140,10 +106,7 @@ export class TweetEntities implements ITweetEntities {
  * @public
  */
 export class TweetMedia {
-	/** The type of media. */
 	public type: EMediaType;
-
-	/** The direct URL to the media. */
 	public url: string = '';
 
 	/**

package/src/models/public/User.ts

@@ -10,46 +10,19 @@ import { IUser } from '../../types/public/User';
  * @public
  */
 export class User implements IUser {
-	/** The rest id of the user. */
 	public id: string;
-
-	/** The username/screenname of the user. */
 	public userName: string;
-
-	/** The full name of the user. */
 	public fullName: string;
-
-	/** The creation date of user's account. */
 	public createdAt: string;
-
-	/** The user's description. */
 	public description: string;
-
-	/** Whether the account is verified or not. */
 	public isVerified: boolean;
-
-	/** The number of tweets liked by the user. */
 	public favouritesCount: number;
-
-	/** The number of followers of the user. */
 	public followersCount: number;
-
-	/** The number of following of the user. */
 	public followingsCount: number;
-
-	/** The number of tweets made by the user. */
 	public statusesCount: number;
-
-	/** The location of user as provided by user. */
 	public location: string;
-
-	/** The rest id of the tweet pinned in the user's profile. */
 	public pinnedTweet: string;
-
-	/** The url of the profile banner image. */
 	public profileBanner: string;
-
-	/** The url of the profile image. */
 	public profileImage: string;
 
 	/**

package/src/services/internal/FetcherService.ts

@@ -55,7 +55,18 @@ export class FetcherService {
 	 * @param config - The config object for configuring the Rettiwt instance.
 	 */
 	public constructor(config?: RettiwtConfig) {
-		this.cred = config?.apiKey ? this.getAuthCredential(config.apiKey) : undefined;
+		// If API key is supplied
+		if (config?.apiKey) {
+			this.cred = this.getAuthCredential(config.apiKey);
+		}
+		// If guest key is supplied
+		else if (config?.guestKey) {
+			this.cred = this.getGuestCredential(config.guestKey);
+		}
+		// If no key is supplied
+		else {
+			this.cred = undefined;
+		}
 		this.isAuthenticated = config?.apiKey ? true : false;
 		this.httpsAgent = this.getHttpsAgent(config?.proxyUrl);
 		this.logger = new LogService(config?.logging);
@@ -68,9 +79,25 @@ export class FetcherService {
 	 * @returns The generated AuthCredential.
 	 */
 	private getAuthCredential(apiKey: string): AuthCredential {
+		// Converting apiKey from base64 to string
+		apiKey = Buffer.from(apiKey, 'base64').toString('ascii');
+
 		return new AuthCredential(apiKey.split(';'));
 	}
 
+	/**
+	 * Returns an AuthCredential generated using the given guest key.
+	 *
+	 * @param guestKey - The guest key to use for authenticating as guest.
+	 * @returns The generated AuthCredential.
+	 */
+	private getGuestCredential(guestKey: string): AuthCredential {
+		// Converting guestKey from base64 to string
+		guestKey = Buffer.from(guestKey).toString('ascii');
+
+		return new AuthCredential(undefined, guestKey);
+	}
+
 	/**
 	 * Checks the authorization status based on the requested resource.
 	 *

package/src/services/public/TweetService.ts

@@ -31,6 +31,23 @@ export class TweetService extends FetcherService {
 	 * @param id - The id of the target tweet.
 	 * @returns The details of a single tweet with the given tweet id.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the details of the tweet with the id '12345678'
+	 * rettiwt.tweet.details('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async details(id: string): Promise<Tweet> {
@@ -48,6 +65,25 @@ export class TweetService extends FetcherService {
 	 * @param cursor - The cursor to the batch of tweets to fetch.
 	 * @returns The list of tweets that match the given filter.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the most recent 5 tweets from user 'user1'
+	 * rettiwt.tweet.search({ fromUsers: ['user1'] }, 5)
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
+	 * @remarks For details about available filters, refer to {@link TweetFilter}
+	 *
 	 * @public
 	 */
 	public async search(query: TweetFilter, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
@@ -72,6 +108,23 @@ export class TweetService extends FetcherService {
 	 * @param cursor - The cursor to the batch of tweets to fetch.
 	 * @returns The list tweets present in the given list.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the most recent 100 tweets of the Twitter list with id '12345678'
+	 * rettiwt.tweet.list('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @remarks Due a bug in Twitter API, the count is ignored when no cursor is provided and defaults to 100.
 	 */
 	public async list(listId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
@@ -96,6 +149,23 @@ export class TweetService extends FetcherService {
 	 * @param cursor - The cursor to the batch of favoriters to fetch.
 	 * @returns The list of users who liked the given tweet.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the most recent 100 likers of the Tweet with id '12345678'
+	 * rettiwt.tweet.favoriters('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async favoriters(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
@@ -117,6 +187,23 @@ export class TweetService extends FetcherService {
 	 * @param cursor - The cursor to the batch of retweeters to fetch.
 	 * @returns The list of users who retweeted the given tweet.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the most recent 100 retweeters of the Tweet with id '12345678'
+	 * rettiwt.tweet.retweeters('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async retweeters(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
@@ -136,6 +223,23 @@ export class TweetService extends FetcherService {
 	 * @param tweetText - The text to be posted, length must be \<= 280 characters.
 	 * @returns Whether posting was successful or not.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Posting a tweet to twitter
+	 * rettiwt.tweet.tweet('Hello World!')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async tweet(tweetText: string): Promise<boolean> {
@@ -151,6 +255,23 @@ export class TweetService extends FetcherService {
 	 * @param tweetId - The id of the tweet to be favorited.
 	 * @returns Whether favoriting was successful or not.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Liking the Tweet with id '12345678'
+	 * rettiwt.tweet.favorite('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async favorite(tweetId: string): Promise<boolean> {
@@ -166,6 +287,23 @@ export class TweetService extends FetcherService {
 	 * @param tweetId - The id of the tweet with the given id.
 	 * @returns Whether retweeting was successful or not.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Retweeting the Tweet with id '12345678'
+	 * rettiwt.tweet.retweet('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async retweet(tweetId: string): Promise<boolean> {

package/src/services/public/UserService.ts

@@ -33,6 +33,40 @@ export class UserService extends FetcherService {
 	 * @param id - The username/id of the target user.
 	 * @returns The details of the given user.
 	 *
+	 * @example Fetching the details of the Twitter user with username 'user1'
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the details of the User with username 'user1'
+	 * rettiwt.user.details('user1')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
+	 * @example Fetching the details of the Twitter user with id '12345678'
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the details of the User with id '12345678'
+	 * rettiwt.user.details('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async details(id: string): Promise<User> {
@@ -60,6 +94,23 @@ export class UserService extends FetcherService {
 	 * @param cursor - The cursor to the batch of following to fetch.
 	 * @returns The list of users followed by the target user.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 100 following of the User with id '12345678'
+	 * rettiwt.user.following('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async following(userId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
@@ -81,6 +132,23 @@ export class UserService extends FetcherService {
 	 * @param cursor - The cursor to the batch of followers to fetch.
 	 * @returns The list of users following the target user.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 100 followers of the User with id '12345678'
+	 * rettiwt.user.followers('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async followers(userId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
@@ -102,6 +170,23 @@ export class UserService extends FetcherService {
 	 * @param cursor - The cursor to the batch of likes to fetch.
 	 * @returns The list of tweets liked by the target user.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the most recent 100 liked Tweets of the User with id '12345678'
+	 * rettiwt.user.likes('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @public
 	 */
 	public async likes(userId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
@@ -123,7 +208,26 @@ export class UserService extends FetcherService {
 	 * @param cursor - The cursor to the batch of timeline items to fetch.
 	 * @returns The timeline of the target user.
 	 *
-	 * @remarks If the target user has a pinned tweet, the returned timeline has one item extra and this is always the pinned tweet.
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 20 timeline tweets of the User with id '12345678'
+	 * rettiwt.user.timeline('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
+	 * @remarks
+	 * - If the target user has a pinned tweet, the returned timeline has one item extra and this is always the pinned tweet.
+	 * - If timeline is fetched without authenticating, then the most popular tweets of the target user are returned instead.
 	 *
 	 * @public
 	 */
@@ -146,6 +250,23 @@ export class UserService extends FetcherService {
 	 * @param cursor - The cursor to the batch of replies to fetch.
 	 * @returns The reply timeline of the target user.
 	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 100 timeline replies of the User with id '12345678'
+	 * rettiwt.user.replies('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
 	 * @remarks If the target user has a pinned tweet, the returned reply timeline has one item extra and this is always the pinned tweet.
 	 *
 	 * @public

package/src/types/internal/RettiwtConfig.ts

@@ -7,6 +7,9 @@ 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 with proxy configuration to use for requests to Twitter API. */
 	proxyUrl?: URL;