rettiwt-api 1.1.2 → 1.1.7

package/src/services/{accounts → auth}/AccountService.ts

@@ -2,15 +2,17 @@
 import { curly, CurlyResult } from 'node-libcurl';
 
 // SERVICES
-import { AuthService } from '../AuthService';
+import { AuthService } from './AuthService';
 
 // TYPES
-import { GuestCredentials } from '../../types/Authentication';
-import { HttpStatus } from '../../types/HTTP';
-import { AuthenticationErrors } from '../../types/data/Errors';
+import { IGuestCredentials, IAuthCookie } from '../../types/Authentication';
+
+// ENUMS
+import { HttpStatus } from '../../enums/HTTP';
+import { AuthenticationErrors } from '../../enums/Errors';
 
 // HELPERS
-import LoginFlows from './LoginFlows';
+import LoginFlows from '../helper/payloads/LoginFlows';
 import { loginHeader } from '../helper/Headers';
 import { Cookie, CookieJar } from 'cookiejar';
 
@@ -19,12 +21,11 @@ import { Cookie, CookieJar } from 'cookiejar';
  * @public
  */
 export class AccountService {
-    // MEMBER DATA
     /** The AuthService instance to use for authentication. */
     private auth: AuthService;
     
     /** The current guest credentials to use. */
-    private guestCreds: GuestCredentials;
+    private guestCreds: IGuestCredentials;
 
     /** The cookies received from Twitter after logging in. */
     private cookies: Cookie[];
@@ -32,7 +33,6 @@ export class AccountService {
     /** The flow token received after execution of current flow. */
     private flowToken: string;
 
-    // MEMBER METHODS
     constructor() {
         this.auth = new AuthService();
         this.guestCreds = { authToken: '', guestToken: '' };
@@ -43,7 +43,7 @@ export class AccountService {
     /**
      * @returns The current guest credentials to use. If if does not exists, then a new one is created
      */
-    private async getGuestCredentials(): Promise<GuestCredentials> {
+    private async getGuestCredentials(): Promise<IGuestCredentials> {
         // If a guest credential has not been already set, get a new one
         if (!this.guestCreds.guestToken) {
             this.guestCreds = await this.auth.getGuestCredentials();
@@ -176,15 +176,15 @@ export class AccountService {
     }
 
     /**
-     * Login to Twitter using the given credentials and get back the cookies.
-     * @public
+     * Execute all the flows required to login to Twitter, using the given credentials, then set the response cookies.
+     * 
+     * @internal
      * 
-     * @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
+     * @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.
      */
-    public async login(email: string, userName: string, password: string): Promise<string> {
+    private async executeLoginFlows(email: string, userName: string, password: string): Promise<void> {
         /**
          * 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.
@@ -197,9 +197,61 @@ export class AccountService {
         await this.enterUserIdentifier(email);
         await this.enterAlternateUserIdentifier(userName);
         await this.enterPassword(password);
-        await this.accountDuplicationCheck();
+        await this.accountDuplicationCheck(); 
+    }
+
+    /**
+     * Parse the authentication cookies recieved from Twitter into known format.
+     * 
+     * @internal
+     * 
+     * @param cookies The raw cookies received from Twitter.
+     * 
+     * @returns The parsed cookies of type {@link AuthCookie}
+     */
+    private parseCookies(cookies: Cookie[]): IAuthCookie {
+        /** The tempoorary parsed cookies. */
+        let tempCookies: any = {};
+        
+        /**
+         * Parsing the cookies into a standard JSON format.
+         * The format is 'cookie_name': 'cookie_value'.
+         * All other cookie parameters like expiry, etc are dropped.
+         */
+        cookies.forEach(cookie => {
+            tempCookies[cookie.name] = cookie.value;
+        });
+
+        return {
+            kdt: tempCookies['kdt'],
+            twid: tempCookies['twid'],
+            ct0: tempCookies['ct0'],
+            auth_token: tempCookies['auth_token']
+        };
+    }
+
+    /**
+     * 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<IAuthCookie> {
+        /** The parsed cookies that will be returned. */
+        let parsedCookies: IAuthCookie;
+        
+        // Executing all login flows
+        await this.executeLoginFlows(email, userName, password);
+
+        // Parsing the cookies
+        parsedCookies = this.parseCookies(this.cookies);
         
-        // Returning the final cookies
-        return this.cookies.join(';');
+        // Returning the final parsed cookies
+        return parsedCookies;
     }
 }

package/src/services/auth/AuthService.ts

@@ -0,0 +1,81 @@
+// PACKAGE
+import axios from 'axios';
+
+// URLS
+import { guestTokenUrl } from '../helper/urls/Authentication';
+
+// MODELS
+import { AuthCookie } from '../../models/auth/AuthCookie';
+
+// TYPES
+import { IGuestCredentials, IAuthCredentials } from '../../types/Authentication';
+
+// CONFIGS
+import { config } from '../../config/env';
+
+/**
+ * Handles authentication of http requests and other authentication related tasks.
+ * 
+ * @internal
+ */
+export class AuthService {
+    /** The common bearer token for authentication. */
+    private authToken: string;
+
+    /** The current authentication credentials. */
+    private credentials: IAuthCredentials;
+
+    /** Whether instance has been authenticated or not. */
+    public isAuthenticated: boolean;
+
+    /**
+     * @param cookie The cookie to be used for authenticating.
+     * 
+     * @remarks
+     * 
+     * If no cookie is supplied, then guest authentication is used.
+     */
+    constructor(cookie?: AuthCookie) {
+        // Reading the auth token from the config, since it's always the same
+        this.authToken = config.twitter_auth_token;
+
+        // Setting authentication status
+        this.isAuthenticated = (cookie?.auth_token && cookie?.ct0 && cookie?.kdt && cookie?.twid) ? true : false;
+
+        // If a cookies is supplied, initializing authenticated credentials
+        if (this.isAuthenticated) {
+            // Converting the cookie from JSON to object
+            cookie = new AuthCookie(cookie);
+
+            // Setting up the authenticated credentials
+            this.credentials = { authToken: this.authToken, csrfToken: cookie.ct0, cookie: cookie.toString() };
+        }
+        // If no cookie has been supplied, initializing empty credentials
+        else {
+            // Setting up the authenticated credentials
+            this.credentials = { authToken: this.authToken, csrfToken: '', cookie: '' };
+        }
+    }
+    
+    /**
+     * @returns The current authentication credentials. A different credential is returned each time this is invoked
+     */
+    async getAuthCredentials(): Promise<IAuthCredentials> {
+        return this.credentials;
+    }
+
+    /**
+     * @returns The guest credentials fetched from twitter.
+     */
+    async getGuestCredentials(): Promise<IGuestCredentials> {
+        // Getting the guest credentials from twitter
+        return await axios.post<{ guest_token: string }>(guestTokenUrl(), null, {
+            headers: {
+                'Authorization': this.authToken
+            }
+        }).then(res => ({
+            authToken: this.authToken,
+            guestToken: res.data.guest_token
+        }));
+    }
+}

package/src/services/data/TweetService.ts

@@ -1,17 +1,23 @@
 // SERVICES
-import { FetcherService } from "../FetcherService";
-import { AuthService } from "../AuthService";
+import { FetcherService } from "../util/FetcherService";
+import { AuthService } from "../auth/AuthService";
+
+// MODELS
+import { Tweet } from "../../models/data/Tweet";
+import { User } from "../../models/data/User";
+import { TweetListArgs } from "../../models/args/TweetListArgs";
+import { TweetFilter } from "../../models/args/TweetFilter";
+import { CursoredData } from '../../models/data/CursoredData';
 
 // TYPES
-import { TweetFilter, Tweet } from "../../types/data/Tweet";
-import { User } from "../../types/data/User";
-import { CursoredData } from '../../types/data/Service';
 import RawTweet, { Result as TweetData } from '../../types/raw/tweet/Tweet';
 import { Result as UserData } from "../../types/raw/user/User";
 import RawTweets from '../../types/raw/tweet/Tweets';
 import RawLikers from '../../types/raw/tweet/Favouriters';
 import RawRetweeters from '../../types/raw/tweet/Retweeters';
-import * as Errors from '../../types/data/Errors';
+
+// ENUMS
+import { AuthenticationErrors } from '../../enums/Errors';
 
 // URLS
 import * as TweetUrls from '../helper/urls/Tweets';
@@ -19,10 +25,6 @@ import * as TweetUrls from '../helper/urls/Tweets';
 // EXTRACTORS
 import * as TweetExtractors from "../helper/extractors/Tweets";
 
-// DESERIALIZERS
-import * as UserDeserializers from '../helper/deserializers/Users';
-import * as TweetDeserializers from '../helper/deserializers/Tweets';
-
 // PARSERS
 import { toQueryString } from '../helper/Parser';
 
@@ -31,7 +33,6 @@ import { toQueryString } from '../helper/Parser';
  * @public
  */
 export class TweetService extends FetcherService {
-    // MEMBER METHODS
     /**
      * @param auth The AuthService instance to use for authentication.
      */
@@ -41,19 +42,24 @@ export class TweetService extends FetcherService {
 
     /**
      * @param filter The filter be used for searching the tweets.
-     * @param count The number of tweets to fetch.
+     * @param count The number of tweets to fetch, must be >= 10 and <= 20
      * @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.
+     * 
+     * @throws {@link Errors.ValidationErrors.InvalidCount} error, if an invalid count has been provided.
+     * 
+     * @remarks
+     * 
+     * Cookies are required to use this method!
      */
-    async getTweets(filter: TweetFilter, count: number, cursor: string): Promise<CursoredData<Tweet>> {
-        // If invalid count provided
-        if (count < 1 && !cursor) {
-            throw new Error(Errors.ValidationErrors.InvalidCount);
-        }
+    async getTweets(query: TweetFilter, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+        // Objectifying parameters
+        let filter: TweetFilter = new TweetFilter(query);
+        let args: TweetListArgs = new TweetListArgs(count, cursor);
 
         // Getting the raw data
-        let res = await this.request<RawTweets>(TweetUrls.tweetsUrl(toQueryString(filter), count, cursor), false).then(res => res.data);
+        let res = await this.request<RawTweets>(TweetUrls.tweetsUrl(toQueryString(filter), args.count, args.cursor), this.isAuthenticated).then(res => res.data);
 
         // Extracting data
         let data = TweetExtractors.extractTweets(res);
@@ -62,62 +68,75 @@ export class TweetService extends FetcherService {
         this.cacheData(data);
 
         // Parsing data
-        let tweets = data.required.map((item: TweetData) => TweetDeserializers.toTweet(item));
+        let tweets = data.required.map((item: TweetData) => new Tweet(item));
 
-        return {
-            list: tweets,
-            next: { value: data.cursor }
-        };
+        // Sorting the tweets by date, from recent to oldest
+        tweets.sort((a, b) => new Date(b.createdAt).valueOf() - new Date(a.createdAt).valueOf());
+
+        return new CursoredData<Tweet>(tweets, data.cursor);
     }
 
     /**
-     * @param tweetId The rest id of the target tweet.
+     * @param id The id of the target tweet.
+     * 
      * @returns The details of a single tweet with the given tweet id.
+     * 
+     * @throws {@link Errors.DataErrors.TweetNotFound} error, if no tweet with the given id was found.
+     * 
+     * @remarks
+     * 
+     * No cookies are required to use this method.
      */
-    async getTweetById(tweetId: string): Promise<Tweet> {
+    async getTweetDetails(id: string): Promise<Tweet> {
         // Getting data from cache
-        let cachedData = await this.readData(tweetId);
+        let cachedData = await this.readData(id);
 
         // If data exists in cache
         if (cachedData) {
             return cachedData;
         }
-        
+
         // Fetching the raw data
-        let res = await this.request<RawTweet>(TweetUrls.tweetDetailsUrl(tweetId), false).then(res => res.data);
+        let res = await this.request<RawTweet>(TweetUrls.tweetDetailsUrl(id), false).then(res => res.data);
 
         // Extracting data
-        let data = TweetExtractors.extractTweet(res, tweetId);
+        let data = TweetExtractors.extractTweet(res, id);
 
         // Caching data
         this.cacheData(data);
 
         // Parsing data
-        let tweet = TweetDeserializers.toTweet(data.required[0]);
+        let tweet = new Tweet(data.required[0]);
 
         return tweet;
     }
 
     /**
      * @param tweetId The rest id of the target tweet.
-     * @param count The batch size of the list.
+     * @param count The batch size of the list, must be >= 10 (when no cursor is provided) and <= 20.
      * @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.
+     * 
+     * @throws {@link Errors.AuthenticationErrors.NotAuthenticated} error, if no cookies have been provided.
+     * @throws {@link Errors.ValidationErrors.InvalidCount} error, if invalid count is provided.
+     * @throws {@link Errors.DataErrors.TweetNotFound} error, if no tweet with the given id was found.
+     * 
+     * @remarks
+     * 
+     * Cookies are required to use this method!
      */
-    async getTweetLikers(tweetId: string, count: number, cursor: string): Promise<CursoredData<User>> {
+    async getTweetLikers(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
         // If user is not authenticated, abort
-        if(!this.isAuthenticated) {
-            throw new Error(Errors.AuthenticationErrors.NotAuthenticated);
+        if (!this.isAuthenticated) {
+            throw new Error(AuthenticationErrors.NotAuthenticated);
         }
 
-        // If invalid count provided
-        if (count < 10 && !cursor) {
-            throw new Error(Errors.ValidationErrors.InvalidCount);
-        }
-        
+        // Objectifying parameters
+        let args: TweetListArgs = new TweetListArgs(count, cursor);
+
         // Fetching the raw data
-        let res = await this.request<RawLikers>(TweetUrls.tweetLikesUrl(tweetId, count, cursor)).then(res => res.data);
+        let res = await this.request<RawLikers>(TweetUrls.tweetLikesUrl(tweetId, args.count, args.cursor)).then(res => res.data);
 
         // Extracting data
         let data = TweetExtractors.extractTweetLikers(res);
@@ -126,34 +145,37 @@ export class TweetService extends FetcherService {
         this.cacheData(data);
 
         // Parsing data
-        let users = data.required.map((item: UserData) => UserDeserializers.toUser(item));
+        let users = data.required.map((item: UserData) => new User(item));
 
-        return {
-            list: users,
-            next: { value: data.cursor }
-        };
+        return new CursoredData<User>(users, data.cursor);
     }
 
     /**
      * @param tweetId The rest id of the target tweet.
-     * @param count The batch size of the list.
+     * @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.
+     * 
      * @returns The list of users who retweeted the given tweet.
-     * @remarks count must be >= 10 (when no cursor is provided) and <= 100.
+     * 
+     * @throws {@link Errors.AuthenticationErrors.NotAuthenticated} error, if no cookies have been provided.
+     * @throws {@link Errors.ValidationErrors.InvalidCount} error, if invalid count is provided.
+     * @throws {@link Errors.DataErrors.TweetNotFound} error, if no tweet with the given id was found.
+     * 
+     * @remarks
+     * 
+     * Cookies are required to use this method!
      */
-    async getTweetRetweeters(tweetId: string, count: number, cursor: string): Promise<CursoredData<User>> {
+    async getTweetRetweeters(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
         // If user is not authenticated, abort
-        if(!this.isAuthenticated) {
-            throw new Error(Errors.AuthenticationErrors.NotAuthenticated);
+        if (!this.isAuthenticated) {
+            throw new Error(AuthenticationErrors.NotAuthenticated);
         }
 
-        // If invalid count provided
-        if (count < 10 && !cursor) {
-            throw new Error(Errors.ValidationErrors.InvalidCount);
-        }
+        // Objectifying parameters
+        let args: TweetListArgs = new TweetListArgs(count, cursor);
 
         // Fetching the raw data
-        let res = await this.request<RawRetweeters>(TweetUrls.tweetRetweetUrl(tweetId, count, cursor)).then(res => res.data);
+        let res = await this.request<RawRetweeters>(TweetUrls.tweetRetweetUrl(tweetId, args.count, args.cursor)).then(res => res.data);
 
         // Extracting data
         let data = TweetExtractors.extractTweetRetweeters(res);
@@ -162,12 +184,9 @@ export class TweetService extends FetcherService {
         this.cacheData(data);
 
         // Parsing data
-        let users = data.required.map((item: UserData) => UserDeserializers.toUser(item));
+        let users = data.required.map((item: UserData) => new User(item));
 
-        return {
-            list: users,
-            next: { value: data.cursor }
-        };
+        return new CursoredData<User>(users, data.cursor);
     }
 
     /**