rettiwt-api 1.1.0 → 1.1.2

package/dist/types/raw/user/Tweets.js

@@ -0,0 +1,3 @@
+"use strict";
+exports.__esModule = true;
+//# sourceMappingURL=Tweets.js.map

package/dist/types/raw/user/Tweets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tweets.js","sourceRoot":"","sources":["../../../../src/types/raw/user/Tweets.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "rettiwt-api",
-	"version": "1.1.0",
+	"version": "1.1.2",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
 	"description": "An API for fetching data from TwitterAPI, without any rate limits!",
@@ -21,9 +21,9 @@
 	"bugs": {
 		"url": "https://github.com/Rishikant181/Rettiwt-API/issues"
 	},
-	"homepage": "https://github.com/Rishikant181/Rettiwt-API#readme",
+	"homepage": "https://rishikant181.github.io/Rettiwt-API/",
 	"dependencies": {
-		"axios": "^1.3.2",
+		"axios": "1.3.2",
 		"cookiejar": "2.1.4",
 		"express": "4.18.2",
 		"express-graphql": "0.12.0",
@@ -32,11 +32,12 @@
 		"node-libcurl": "3.0.0"
 	},
 	"devDependencies": {
-		"@types/cookiejar": "^2.1.2",
+		"@types/cookiejar": "2.1.2",
 		"@types/express": "4.17.13",
 		"@types/graphql": "14.5.0",
 		"@types/node": "17.0.24",
 		"nodemon": "2.0.20",
+		"typedoc": "0.23.26",
 		"typescript": "4.6.4"
 	}
 }

package/src/index.ts

@@ -5,8 +5,11 @@ import { TweetService } from "./services/data/TweetService";
 import { AccountService } from "./services/accounts/AccountService";
 
 /**
- * @param cookie The cookies string to use to fetch data
+ * @param cookie The cookie string to use to fetch data
  * @returns The API for fetching user and tweet data
+ * @remarks The cookie can be obtained by using {@link AccountService.login} method.
+ * To use the {@link AccountService.login} method, create a {@link Rettiwt} instance without passing any cookie string.
+ * Then use the {@link AccountService.login} method of {@link AccountService} to get the cookie.
  */
 export const Rettiwt = (cookie: string = '') => {
     // Creating new auth service instance using the given cookie string
@@ -20,8 +23,18 @@ export const Rettiwt = (cookie: string = '') => {
     };
 }
 
-// Exporting additional types
-export { User } from './types/data/User';
-export { Tweet, TweetEntities, TweetFilter } from './types/data/Tweet';
-export { Cursor, CursoredData } from './types/data/Service';
-export { AuthenticationErrors, ValidationErrors, DataErrors } from './types/data/Errors';
+// Exporting classes
+export * from './services/AuthService';
+export * from './services/CacheService';
+export * from './services/FetcherService';
+export * from './services/accounts/AccountService';
+export * from './services/data/TweetService';
+export * from './services/data/UserService';
+
+// Exporting types
+export * from './types/data/Errors';
+export * from './types/data/Service';
+export * from './types/data/Tweet';
+export * from './types/data/User';
+export * from './types/Authentication';
+export * from './types/HTTP';

package/src/services/AuthService.ts

@@ -11,13 +11,19 @@ import { GuestCredentials, AuthCredentials } from '../types/Authentication';
 import { config } from '../config/env';
 
 /**
- * @summary Handles authentication of http requests and other authentication related tasks
+ * Handles authentication of http requests and other authentication related tasks.
+ * @internal
  */
 export class AuthService {
     // MEMBER DATA
-    private authToken: string;                                               // To store the common auth token
-    private credentials: AuthCredentials;                                    // To store the current authentication credentials
-    public isAuthenticated: boolean;                                         // To store whether authenticated or not
+    /** The common bearer token for authentication. */
+    private authToken: string;
+
+    /** The current authentication credentials. */
+    private credentials: AuthCredentials;
+
+    /** Whether instance has been authenticated or not. */
+    public isAuthenticated: boolean;
 
     // MEMBER METHODS
     constructor(cookie: string = '') {
@@ -32,7 +38,7 @@ export class AuthService {
          * The following regex pattern is used to extract the csrfToken from the cookie string.
          * This is done by matching any string between the characters 'ct0=' and nearest enclosing ';'.
          * (?<=pattern) starts matching after the given pattern.
-         * (?=pattern) stops matching just before the pattern
+         * (?=pattern) stops matching just before the pattern.
          */
         this.credentials = { authToken: this.authToken, csrfToken: cookie.match(/(?<=ct0=).+?(?=;)/) + '', cookie: cookie};
         
@@ -46,7 +52,7 @@ export class AuthService {
     }
 
     /**
-     * @returns The guest credentials fetched from twitter
+     * @returns The guest credentials fetched from twitter.
      */
     async getGuestCredentials(): Promise<GuestCredentials> {
         // Getting the guest credentials from twitter
@@ -59,4 +65,4 @@ export class AuthService {
             guestToken: res.data.guest_token
         }));
     }
-}
+}

package/src/services/CacheService.ts

@@ -5,9 +5,12 @@ import NodeCache from 'node-cache';
 import * as Parsers from './helper/Parser';
 
 /**
- * @summary Handles reading and writing of data from and to cache.
+ * Handles reading and writing of data from and to cache.
  * 
- * **Note**: To be able to CacheService, the data to be cached must have a unique "id" field.
+ * This services uses a local node-cache instance to cache data, since the data to be cached has no real purpose outside of the server session.
+ * This serivce follows a singleton pattern, where at any point, only a single instance of this class exists.
+ * This is done so that all the data is cached in a single instance, which makes sharing of cached data between different endpoints possible.
+ * @internal
  */
 export class CacheService {
     // MEMBER DATA
@@ -34,9 +37,11 @@ export class CacheService {
     }
 
     /**
-     * @summary Stores the input data into the cache.
-     * @returns Whether writing to cache was successful or not
-     * @param data The input data to store
+     * Stores the input data in the cache.
+     * 
+     * @param data The input data to store.
+     * @returns Whether writing to cache was successful or not.
+     * @remarks In order to cache data, the data to be cached must have a unique 'id' field.
      */
     public write(data: any): void {
         // Converting the data to a list of data
@@ -56,8 +61,8 @@ export class CacheService {
     }
 
     /**
-     * @returns The data with the given id/rest id from cache
-     * @param id The id/rest id of the data to be fetched from cache
+     * @param id The id id of the data to be fetched from cache.
+     * @returns The data with the given id.
      */
     public read(id: string): any {
         // Getting data from cache

package/src/services/FetcherService.ts

@@ -17,7 +17,7 @@ import * as TweetDeserializers from './helper/deserializers/Tweets';
 import { CurlyOptions } from 'node-libcurl/dist/curly';
 
 /**
- * @summary Stores all the different type of http requests
+ * The different types of http requests.
  */
 export enum HttpMethods {
     POST = "POST",
@@ -25,15 +25,26 @@ export enum HttpMethods {
 };
 
 /**
- * @service The base serivice from which all other data services derive their behaviour
+ * Handles all HTTP requests.
+ * @internal
+ * 
+ * This serves as the base service from which all other data services derive their behaviour.
  */
 export class FetcherService {
     // MEMBER DATA
-    private auth: AuthService;                                              // To store the auth service instance to use for authentication
-    private cache: CacheService;                                            // To stoer the cache service instance to use for caching data
-    protected isAuthenticated: boolean;                                     // To store whether user is authenticated or not
+    /** The authentication service instance. */
+    private auth: AuthService;
+
+    /** The caching service instance. */
+    private cache: CacheService;
+
+    /** Whether instance has been authenticated or not. */
+    protected isAuthenticated: boolean;
 
     // MEMBER METHODS
+    /**
+     * @param auth The AuthService instance to use for authentication.
+     */
     constructor(auth: AuthService) {
         this.auth = auth;
         this.cache = CacheService.getInstance();
@@ -41,47 +52,75 @@ export class FetcherService {
     }
 
     /**
-    * @summary Throws the appropriate http error after evaluation of the status code of reponse
-    * @param res The response object received from http communication
+    * The middleware for handling any HTTP error.
+    * 
+    * @param res The response object received.
+    * @throws {@link HttpStatus}.
+    * @returns The received response, if no HTTP errors are found.
     */
     private handleHTTPError(res: CurlyResult): CurlyResult {
+        /**
+         * If the status code is not 200 => the HTTP request was not successful. hence throwing error
+         */
         if (res.statusCode != 200 && res.statusCode in HttpStatus) {
             throw new Error(HttpStatus[res.statusCode])
         }
-
+        
         return res;
     }
 
     /**
-     * @returns The absolute raw json data from give url
-     * @param url The url to fetch data from
-     * @param authenticate Whether to authenticate requests or not
-     * @param method The HTTP method to use
-     * @param data The data to be sent along with the request (works with only POST method)
+     * Creates an HTTP request according to the given parameters.
+     * 
+     * This method internally uses node-libcurl library to make curl requests to the URL, instead of node-fetch.
+     * This has been done since that way it better mimics the HTTP requests made from browser.
+     * 
+     * @param url The url to fetch data from.
+     * @param authenticate Whether to authenticate requests or not.
+     * @param method The HTTP method (from {@link HttpMethods}) to use.
+     * @param data The data to be sent along with the request (for POST request).
+     * @returns The {@link CurlyResult} received.
      */
     protected async request<DataType>(url: string, authenticate: boolean = true, method: HttpMethods = HttpMethods.GET, data?: any): Promise<CurlyResult<DataType>> {
-        // Creating the configuration for the http request
+        /**
+         * Creating the request configuration based on the params
+         */
         let config: CurlyOptions = {
+            /**
+             * If authorization is required, using the authenticated header, using the authentication credentiials.
+             * Else, using the guest header, using the guest credentials.
+             */
             httpHeader: authenticate ? Headers.authorizedHeader(await this.auth.getAuthCredentials()) : Headers.guestHeader(await this.auth.getGuestCredentials()),
+            /** 
+             * Disabling SSL peer verification because verification causes Error 404 (only while fetching tweets), likely because peer verification fails.
+             */
             sslVerifyPeer: false,
         };
 
-        // If post request is to be made
+        /**
+         * While making requests, if data is to be sent, the JSON data first need to be stringified.
+         * After making the request, the response is then passed to HTTP error handling middlware for HTTP error handling.
+         */
+        // If POST request is to be made
         if (method == HttpMethods.POST) {
             return await curly.post(url, { ...config, postFields: JSON.stringify(data) }).then(res => this.handleHTTPError(res));
         }
-        // If get request is to be made
+        // If GET request is to be made
         else {
             return await curly.get(url, config).then(res => this.handleHTTPError(res));
         }
     }
 
     /**
-     * @summary Caches the extracted data
+     * Caches the extracted data into the {@link CacheService} instance.
+     * 
      * @param data The extracted data to be cached
      */
     protected cacheData(data: any): void {
-        // Parsing the extracted data
+        /**
+         * The extracted data is in raw form.
+         * This raw data is deserialized into the respective known types.
+         */
         let users = data.users.map((user: RawUser) => UserDeserializers.toUser(user));
         let tweets = data.tweets.map((tweet: RawTweet) => TweetDeserializers.toTweet(tweet));
 
@@ -91,11 +130,13 @@ export class FetcherService {
     }
 
     /**
-     * @returns The data with the given id (if it exists in cache)
-     * @param id The id of the data to be read from cache
+     * Fetches the data with the given id from the cache.
+     * 
+     * @param id The id of the data to be read from cache.
+     * @returns The data with the given id. If does not exists, returns undefined.
      */
     protected readData(id: string): any {
         // Reading data from cache
         return this.cache.read(id);
     }
-}
+}

package/src/services/accounts/AccountService.ts

@@ -6,18 +6,31 @@ import { AuthService } from '../AuthService';
 
 // TYPES
 import { GuestCredentials } from '../../types/Authentication';
+import { HttpStatus } from '../../types/HTTP';
+import { AuthenticationErrors } from '../../types/data/Errors';
 
 // HELPERS
 import LoginFlows from './LoginFlows';
 import { loginHeader } from '../helper/Headers';
 import { Cookie, CookieJar } from 'cookiejar';
 
+/**
+ * Handles all operations related to a user's account, such as loggin in, managing account, etc
+ * @public
+ */
 export class AccountService {
     // MEMBER DATA
-    private auth: AuthService;                                                  // To store the auth service instance to use
-    private guestCreds: GuestCredentials;                                       // To store the guest credentials to use
-    private cookies: Cookie[];                                                  // To store the cookies received from twitter
-    private flowToken: string;                                                  // To store the flow token received from current flow
+    /** The AuthService instance to use for authentication. */
+    private auth: AuthService;
+    
+    /** The current guest credentials to use. */
+    private guestCreds: GuestCredentials;
+
+    /** The cookies received from Twitter after logging in. */
+    private cookies: Cookie[];
+
+    /** The flow token received after execution of current flow. */
+    private flowToken: string;
 
     // MEMBER METHODS
     constructor() {
@@ -40,7 +53,8 @@ export class AccountService {
     }
 
     /**
-     * @summary Step 1: Initiates login
+     * Step 1: Initiates login
+     * @internal
      */
     private async initiateLogin(): Promise<void> {
         // Initiating the login process
@@ -58,7 +72,8 @@ export class AccountService {
     }
 
     /**
-     * @summary Step 2: Does something
+     * Step 2: Does something
+     * @internal
      */
     private async jsInstrumentationSubtask(): Promise<void> {
         // Executing the flow
@@ -73,7 +88,10 @@ export class AccountService {
     }
 
     /**
-     * @summary Step 3: Takes the email for login
+     * Step 3: Takes the email for login
+     * @internal
+     * 
+     * @throws {@link AuthenticationErrors.InvalidEmail}, if email does not exist.
      */
     private async enterUserIdentifier(email: string): Promise<void> {
         // Executing the flow
@@ -83,12 +101,20 @@ export class AccountService {
             postFields: JSON.stringify(LoginFlows.EnterUserIdentifier.body(this.flowToken, email))
         });
 
+        // If no account found with given email
+        if (res.statusCode == HttpStatus.BadRequest && res.data.errors[0].code == 399) {
+            throw new Error(AuthenticationErrors.InvalidEmail);
+        }
+
         // Getting the flow token
         this.flowToken = res.data['flow_token'];
     }
 
     /**
-     * @summary Step 4: Takes the username for login
+     * Step 4: Takes the username for login
+     * @internal
+     * 
+     * @throws {@link AuthenticationErrors.InvalidUsername}, if wrong username entered.
      */
     private async enterAlternateUserIdentifier(userName: string): Promise<void> {
         // Executing the flow
@@ -98,12 +124,20 @@ export class AccountService {
             postFields: JSON.stringify(LoginFlows.EnterAlternateUserIdentifier.body(this.flowToken, userName))
         });
 
+        // If invalid username for the given account
+        if (res.statusCode == HttpStatus.BadRequest && res.data.errors[0].code == 399) {
+            throw new Error(AuthenticationErrors.InvalidUsername);
+        }
+
         // Getting the flow token
         this.flowToken = res.data['flow_token'];
     }
 
     /**
-     * @summary Step 5: Takes the password for login
+     * Step 5: Takes the password for login
+     * @internal
+     * 
+     * @throws {@link AuthenticationErrors.InvalidPassword}, incorrect password entered.
      */
     private async enterPassword(password: string): Promise<void> {
         // Executing the flow
@@ -113,12 +147,18 @@ export class AccountService {
             postFields: JSON.stringify(LoginFlows.EnterPassword.body(this.flowToken, password))
         });
 
+        // If invalid password for the given account
+        if (res.statusCode == HttpStatus.BadRequest && res.data.errors[0].code == 399) {
+            throw new Error(AuthenticationErrors.InvalidPassword);
+        }
+
         // Getting the flow token
         this.flowToken = res.data['flow_token'];
     }
 
     /**
-     * @summary Step 6: Gets the actual cookies
+     * Step 6: Gets the actual cookies
+     * @internal
      */
     private async accountDuplicationCheck(): Promise<void> {
         // Executing the flow
@@ -128,7 +168,7 @@ export class AccountService {
             postFields: JSON.stringify(LoginFlows.AccountDuplicationCheck.body(this.flowToken))
         });
 
-        // Storing cookies received
+        // Getting the cookies from the set-cookie header of the reponse.
         this.cookies = new CookieJar().setCookies(res.headers[0]['Set-Cookie'] as string[]);
 
         // Getting the flow token
@@ -136,13 +176,22 @@ export class AccountService {
     }
 
     /**
+     * Login to Twitter using the given credentials and get back the cookies.
+     * @public
+     * 
      * @param email The email of the account to be logged into
      * @param userName The username associated with the given account
      * @param password The password to the account
      * @returns The cookies for authenticating with the given account
      */
     public async login(email: string, userName: string, password: string): Promise<string> {
-        // Executing each step of login flow
+        /**
+         * This works by sending a chain of request that are required for login to twitter.
+         * Each method in the chain returns a flow token that must be provied as payload in the next method in the chain.
+         * Each such method is called a subtask.
+         * Each subtask sets the {@link flowToken} property of the class which is then given in the payload of the next subtask.
+         * The final subtask returns the headers which actually contains the cookie in the 'set-cookie' field.
+         */
         await this.initiateLogin();
         await this.jsInstrumentationSubtask();
         await this.enterUserIdentifier(email);

package/src/services/data/TweetService.ts

@@ -27,19 +27,24 @@ import * as TweetDeserializers from '../helper/deserializers/Tweets';
 import { toQueryString } from '../helper/Parser';
 
 /**
- * A service that deals with fetching of data related to tweets
+ * Handles fetching of data related to tweets.
+ * @public
  */
 export class TweetService extends FetcherService {
     // MEMBER METHODS
+    /**
+     * @param auth The AuthService instance to use for authentication.
+     */
     constructor(auth: AuthService) {
         super(auth);
     }
 
     /**
-     * @returns The list of tweets that match the given filter
-     * @param filter The filter be used for searching the tweets
-     * @param count The number of tweets to fetch, must be >= 1 and <= 100
-     * @param cursor The cursor to the next batch of tweets. If blank, first batch is fetched
+     * @param filter The filter be used for searching the tweets.
+     * @param count The number of tweets to fetch.
+     * @param cursor The cursor to the next batch of tweets. If blank, first batch is fetched.
+     * @returns The list of tweets that match the given filter.
+     * @remarks count must be >= 1 and <= 100.
      */
     async getTweets(filter: TweetFilter, count: number, cursor: string): Promise<CursoredData<Tweet>> {
         // If invalid count provided
@@ -66,8 +71,8 @@ export class TweetService extends FetcherService {
     }
 
     /**
-     * @returns The details of a single tweet with the given tweet id
-     * @param tweetId The rest id of the target tweet
+     * @param tweetId The rest id of the target tweet.
+     * @returns The details of a single tweet with the given tweet id.
      */
     async getTweetById(tweetId: string): Promise<Tweet> {
         // Getting data from cache
@@ -94,10 +99,11 @@ export class TweetService extends FetcherService {
     }
 
     /**
-     * @returns The list of users who liked the given tweet
-     * @param tweetId The rest id of the target tweet
-     * @param count The batch size of the list, must be >= 10 (when no cursor is provided) and <= 100
-     * @param cursor The cursor to the next batch of users. If blank, first batch is fetched
+     * @param tweetId The rest id of the target tweet.
+     * @param count The batch size of the list.
+     * @param cursor The cursor to the next batch of users. If blank, first batch is fetched.
+     * @returns The list of users who liked the given tweet.
+     * @remarks count must be >= 10 (when no cursor is provided) and <= 100.
      */
     async getTweetLikers(tweetId: string, count: number, cursor: string): Promise<CursoredData<User>> {
         // If user is not authenticated, abort
@@ -129,10 +135,11 @@ export class TweetService extends FetcherService {
     }
 
     /**
-     * @returns The list of users who retweeted the given tweet     
-     * @param tweetId The rest id of the target tweet
-     * @param count The batch size of the list, must be >= 10 (when no cursor is provided) and <= 100
-     * @param cursor The cursor to the next batch of users. If blank, first batch is fetched
+     * @param tweetId The rest id of the target tweet.
+     * @param count The batch size of the list.
+     * @param cursor The cursor to the next batch of users. If blank, first batch is fetched.
+     * @returns The list of users who retweeted the given tweet.
+     * @remarks count must be >= 10 (when no cursor is provided) and <= 100.
      */
     async getTweetRetweeters(tweetId: string, count: number, cursor: string): Promise<CursoredData<User>> {
         // If user is not authenticated, abort
@@ -167,9 +174,9 @@ export class TweetService extends FetcherService {
      * THIS IS DISABLED FOR USE FOR NOW BECAUSE TWITTER DOESN'T HAVE ANY ENDPOINT FOR FETCHING REPLIES.
      * THE DATA THIS RETURNS IS INCONSISTENT!
      * 
-     * @returns The list of replies to the given tweet
-     * @param tweetId The rest id of the target tweet
-     * @param cursor The cursor to the next batch of replies. If blank, first batch is fetched
+     * @param tweetId The rest id of the target tweet.
+     * @param cursor The cursor to the next batch of replies. If blank, first batch is fetched.
+     * @returns The list of replies to the given tweet.
      */
     /*
     async getTweetReplies(tweetId: string, cursor: string): Promise<CursoredData<Tweet>> {

package/src/services/data/UserService.ts

@@ -24,17 +24,20 @@ import * as UserDeserializers from '../helper/deserializers/Users';
 import * as TweetDeserializers from '../helper/deserializers/Tweets';
 
 /**
- * A service that deals with fetching of data related to user account
+ * Handles fetching of data related to user account
  */
 export class UserService extends FetcherService {
     // MEMBER METHODS
+    /**
+     * @param auth The AuthService instance to use for authentication.
+     */
     constructor(auth: AuthService) {
         super(auth);
     }
 
     /**
-     * @returns The details of the given user
      * @param screenName The screen name of the target user.
+     * @returns The details of the given user.
      */
     async getUserDetails(screenName: string): Promise<User> {
         // Fetching the raw data
@@ -53,8 +56,8 @@ export class UserService extends FetcherService {
     }
 
     /**
-     * @returns The details of the user with given rest id
      * @param restId The screen name of the target user.
+     * @returns The details of the user with given rest id.
      */
     async getUserDetailsById(restId: string): Promise<User> {
         // Getting data from cache
@@ -81,10 +84,11 @@ export class UserService extends FetcherService {
     }
 
     /**
-     * @returns The list of users followed by the target user
-     * @param userId The rest id of the target user
-     * @param count The number of following to fetch, should be >= 40 (when no cursor is provided) and <=100
-     * @param cursor The cursor to next batch. If blank, first batch is fetched
+     * @param userId The rest id of the target user.
+     * @param count The number of following to fetch.
+     * @param cursor The cursor to next batch. If blank, first batch is fetched.
+     * @returns The list of users followed by the target user.
+     * @remarks count must be >= 40 (when no cursor is provided) and <=100.
      */
     async getUserFollowing(userId: string, count: number, cursor: string): Promise<CursoredData<User>> {
         // If user is not authenticated, abort
@@ -116,10 +120,11 @@ export class UserService extends FetcherService {
     }
 
     /**
-     * @returns The list of users following the target user
-     * @param userId The rest id of the target user
-     * @param count The number of followers to fetch, should be >= 40 (when no cursor is provided) and <=100
-     * @param cursor The cursor to next batch. If blank, first batch is fetched
+     * @param userId The rest id of the target user.
+     * @param count The number of followers to fetch.
+     * @param cursor The cursor to next batch. If blank, first batch is fetched.
+     * @returns The list of users following the target user.
+     * @remarks count must be >= 40 (when no cursor is provided) and <=100.
      */
     async getUserFollowers(userId: string, count: number, cursor: string): Promise<CursoredData<User>> {
         // If user is not authenticated, abort
@@ -151,10 +156,11 @@ export class UserService extends FetcherService {
     }
 
     /**
-     * @returns The list of tweets liked by the target user
-     * @param userId The rest id of the target user
-     * @param count The number of likes to fetch, must be >= 40 (when no cursor is provided) and <= 100
-     * @param cursor The cursor to next batch. If blank, first batch is fetched
+     * @param userId The rest id of the target user.
+     * @param count The number of likes to fetch.
+     * @param cursor The cursor to next batch. If blank, first batch is fetched.
+     * @returns The list of tweets liked by the target user.
+     * @remarks count must be >= 40 (when no cursor is provided) and <= 100.
      */
     async getUserLikes(userId: string, count: number, cursor: string): Promise<CursoredData<Tweet>> {
         // If user is not authenticated, abort