rettiwt-api 1.1.1 → 1.1.5

package/src/services/helper/extractors/Users.ts

@@ -1,6 +1,6 @@
 // TYPES
-import { DataExtract } from '../../../types/Resolvers'
-import { DataErrors } from '../../../types/data/Errors';
+import { IDataExtract } from '../../../types/Resolvers'
+import { DataErrors } from '../../../enums/Errors';
 import RawUser from '../../../types/raw/user/User';
 import RawUserFollowers from '../../../types/raw/user/Followers';
 import RawUserFollowing from '../../../types/raw/user/Following';
@@ -13,7 +13,7 @@ import * as Parsers from '../Parser';
  * @returns The raw user account data formatted and sorted into required and additional data
  * @param res The raw response received from Twitter
  */
-export function extractUserDetails(res: RawUser): DataExtract {
+export function extractUserDetails(res: RawUser): IDataExtract {
     let required: any[] = [];                                               // To store the reqruied raw data
     let cursor: string = '';                                                // To store the cursor to next batch
     let users: any[] = [];                                                  // To store additional user data
@@ -41,7 +41,7 @@ export function extractUserDetails(res: RawUser): DataExtract {
  * @returns The raw user following/followers data formatted and sorted into required and additional data
  * @param res The raw response received from TwitterAPI
  */
-export function extractUserFollow(res: RawUserFollowers | RawUserFollowing): DataExtract {
+export function extractUserFollow(res: RawUserFollowers | RawUserFollowing): IDataExtract {
     let required: any[] = [];                                               // To store the reqruied raw data
     let cursor: string = '';                                                // To store the cursor to next batch
     let users: any[] = [];                                                  // To store additional user data
@@ -94,7 +94,7 @@ export function extractUserFollow(res: RawUserFollowers | RawUserFollowing): Dat
  * @returns The raw user likes data formatted and sorted into required and additional data
  * @param res The raw response received from TwitterAPI
  */
-export function extractUserLikes(res: RawUserLikes): DataExtract {
+export function extractUserLikes(res: RawUserLikes): IDataExtract {
     let required: any[] = [];                                               // To store the reqruied raw data
     let cursor: string = '';                                                // To store the cursor to next batch
     let users: any[] = [];                                                  // To store additional user data

package/src/services/{CacheService.ts → util/CacheService.ts}

@@ -2,7 +2,7 @@
 import NodeCache from 'node-cache';
 
 // PARSERS
-import * as Parsers from './helper/Parser';
+import * as Parsers from '../helper/Parser';
 
 /**
  * Handles reading and writing of data from and to cache.
@@ -40,7 +40,9 @@ export class CacheService {
      * 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 {
@@ -62,6 +64,7 @@ export class CacheService {
 
     /**
      * @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 {

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

@@ -2,18 +2,22 @@
 import { curly, CurlyResult } from 'node-libcurl';
 
 // SERVICES
-import { AuthService } from './AuthService';
+import { AuthService } from '../auth/AuthService';
 import { CacheService } from './CacheService';
 
+// MODELS
+import { Tweet } from '../../models/data/Tweet';
+import { User } from '../../models/data/User';
+
 // TYPES
-import { HttpStatus } from "../types/HTTP";
-import { Result as RawUser } from '../types/raw/user/User';
-import { Result as RawTweet } from '../types/raw/tweet/Tweet';
+import { Result as RawUser } from '../../types/raw/user/User';
+import { Result as RawTweet } from '../../types/raw/tweet/Tweet';
+
+// ENUMS
+import { HttpStatus } from "../../enums/HTTP";
 
 // HELPERS
-import * as Headers from './helper/Headers'
-import * as UserDeserializers from './helper/deserializers/Users';
-import * as TweetDeserializers from './helper/deserializers/Tweets';
+import * as Headers from '../helper/Headers'
 import { CurlyOptions } from 'node-libcurl/dist/curly';
 
 /**
@@ -55,8 +59,10 @@ export class FetcherService {
     * 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.
+    * 
+    * @throws {@link HttpStatus} error, if any HTTP error is found.
     */
     private handleHTTPError(res: CurlyResult): CurlyResult {
         /**
@@ -79,6 +85,7 @@ export class FetcherService {
      * @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>> {
@@ -114,15 +121,15 @@ export class FetcherService {
     /**
      * Caches the extracted data into the {@link CacheService} instance.
      * 
-     * @param data The extracted data to be cached
+     * @param data The extracted data to be cached.
      */
     protected cacheData(data: any): void {
         /**
          * 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));
+        let users = data.users.map((user: RawUser) => new User(user));
+        let tweets = data.tweets.map((tweet: RawTweet) => new Tweet(tweet));
 
         // Caching the data
         this.cache.write(users);
@@ -133,6 +140,7 @@ export class FetcherService {
      * 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 {

package/src/types/Args.ts

@@ -0,0 +1,49 @@
+/**
+ * The filter to be used for fetching tweets from Twitter.
+ * 
+ * @public
+ */
+export interface ITweetFilter {
+    /** The list of words to search. */
+    words?: string[];
+
+    /** The list of hashtags to search. */
+    hashtags?: string[];
+
+    /** The list of usernames whose tweets are to be searched. */
+    fromUsers?: string[];
+    
+    /** The list of username to whom the tweets to be searched, are adressed. */
+    toUsers?: string[];
+
+    /** The list of username mentioned in the tweets to search. */
+    mentions?: string[];
+
+    /** The date starting from which tweets are to be searched. */
+    startDate?: string;
+
+    /** The date upto which tweets are to be searched. */
+    endDate?: string;
+
+    /** The id of the tweet, after which the tweets are to be searched. */
+    sinceId?: string;
+
+    /** The id of the tweet which is quoted in the tweets to search. */
+    quoted?: string;
+
+    /** Whether to fetch tweets that are links or not. */
+    links?: boolean;
+};
+
+/**
+ * The arguments for fetching cursored list.
+ * 
+ * @public
+ */
+export interface IListArgs {
+    /** The number of data items to fetch. */
+    count?: number;
+
+    /** The cursor to the batch of data to fetch. */
+    cursor?: string;
+};

package/src/types/Authentication.ts

@@ -3,17 +3,18 @@
  * 
  * @internal
  */
-export interface GuestCredentials {
+export interface IGuestCredentials {
     /** The bearer token from twitter.com.
      * 
      * @remarks This is a static bearer token from twitter.com.
      */
-    authToken: string,
+    authToken: string;
+
     /** The guest token.
      * 
      * @remarks This is generated from twitter.com by calling GETTING https://api.twitter.com/1.1/guest/activate.json endpoint.
      */
-    guestToken: string
+    guestToken: string;
 };
 
 /**
@@ -21,21 +22,42 @@ export interface GuestCredentials {
  * 
  * @internal
  */
-export interface AuthCredentials {
+export interface IAuthCredentials {
     /** The bearer token from twitter.com.
      * 
      * @remarks This is a static bearer token from twitter.com.
      */
-    authToken: string,
+    authToken: string;
+
     /** The guest token.
      * 
      * @remarks This is generated from twitter.com by calling GETTING https://api.twitter.com/1.1/guest/activate.json endpoint.
      */
-    csrfToken: string,
+    csrfToken: string;
+
     /** The cookie of the twitter account, which is used to authenticate against twitter.
      * 
      * @remarks The cookie can be obtained/scraped from any one of the outgoing HTTP request headers to twitter.com.
      * It can also be obtained after logging in to twitter, from the 'set-cookie' field of response.
      */
-    cookie: string
+    cookie: string;
+};
+
+/**
+ * The cookie containing the tokens that are used to authenticate against Twitter.
+ * 
+ * @public
+ */
+export interface IAuthCookie {
+    /** Token used to authenticate a device. */
+    kdt: string;
+
+    /** Token used to authenticate a user using a Twitter ID. */
+    twid: string;
+
+    /** The CSRF token of the session. */
+    ct0: string;
+
+    /** The authentication token used while logging in to the account. */
+    auth_token: string;
 };

package/src/types/Resolvers.ts

@@ -1,17 +1,18 @@
 /**
  * The data returned from extractor methods.
+ * 
  * @internal
  */
-export interface DataExtract {
+export interface IDataExtract {
     /** The required data. */
-    required: any;
+    required: any[];
 
     /** The cursor string to the next batch of data. */
     cursor: string;
 
     /** Additional extracted user details. */
-    users: any;
+    users: any[];
 
     /** Additional extracted tweet details */
-    tweets: any;
+    tweets: any[];
 }

package/src/types/Rettiwt.ts

@@ -0,0 +1,20 @@
+// SERVICES
+import { AccountService } from "../services/auth/AccountService";
+import { TweetService } from "../services/data/TweetService";
+import { UserService } from "../services/data/UserService";
+
+/**
+ * The data context from where data is to be fetched.
+ * 
+ * @public
+ */
+export interface IDataContext {
+    /** Handles data related to users. */
+    users: UserService,
+
+    /** Handles data related to tweets. */
+    tweets: TweetService,
+
+    /** Handles account related operations. */
+    account: AccountService
+}

package/src/types/Service.ts

@@ -0,0 +1,24 @@
+/**
+ * The cursor to the batch of data to be fetched.
+ * 
+ * @public
+ */
+export interface ICursor {
+    /** The cursor string. */
+    value: string;
+};
+
+/**
+ * The data that us fetched batch-wise along with a cursor.
+ * 
+ * @typeParam Type - The type of data present in the list.
+ * 
+ * @public
+ */
+export interface ICursoredData<Type> {
+    /** The list of data of the given type. */
+    list: Type[];
+
+    /** The cursor to the next batch of data. */
+    next: ICursor;
+};

package/src/types/Tweet.ts

@@ -0,0 +1,61 @@
+/**
+ * The different types parsed entities like urls, media, mentions, hashtags, etc.
+ * 
+ * @public
+ */
+export interface ITweetEntities {
+    /** The list of hashtags mentioned in the tweet. */
+    hashtags: string[];
+
+    /** The list of urls mentioned in the tweet. */
+    urls: string[];
+
+    /** The list of IDs of users mentioned in the tweet. */
+    mentionedUsers: string[];
+
+    /** The list of urls to various media mentioned in the tweet. */
+    media: string[];
+}
+
+/**
+ * The details of a single Tweet.
+ * 
+ * @public
+ */
+export interface ITweet {
+    /** The rest id of the tweet. */
+    id: string;
+
+    /** The rest id of the user who made the tweet. */
+    tweetBy: string;
+
+    /** The date and time of creation of the tweet, in UTC string format. */
+    createdAt: string;
+
+    /** Additional tweet entities like urls, mentions, etc. */
+    entities: ITweetEntities;
+
+    /** The rest id of the tweet which is quoted in the tweet. */
+    quoted: string;
+
+    /** The full text content of the tweet. */
+    fullText: string;
+
+    /** The rest id of the user to which the tweet is a reply. */
+    replyTo: string;
+
+    /** The language in which the tweet is written. */
+    lang: string;
+
+    /** The number of quotes of the tweet. */
+    quoteCount: number;
+
+    /** The number of replies to the tweet. */
+    replyCount: number;
+
+    /** The number of retweets of the tweet. */
+    retweetCount: number;
+
+    /** The number of likes of the tweet. */
+    likeCount: number;
+}

package/src/types/User.ts

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

package/tsconfig.json

@@ -12,8 +12,8 @@
 		// "target": "es2016",                               /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
 		// "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
 		// "jsx": "preserve",                                /* Specify what JSX code is generated. */
-		// "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */
-		// "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+		"experimentalDecorators": true,                      /* Enable experimental support for TC39 stage 2 draft decorators. */
+		"emitDecoratorMetadata": true,                       /* Emit design-type metadata for decorated declarations in source files. */
 		// "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
 		// "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
 		// "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */

package/src/services/AuthService.ts

@@ -1,68 +0,0 @@
-// PACKAGE
-import axios from 'axios';
-
-// URLS
-import { guestTokenUrl } from './helper/urls/Authentication';
-
-// TYPES
-import { GuestCredentials, AuthCredentials } from '../types/Authentication';
-
-// CONFIGS
-import { config } from '../config/env';
-
-/**
- * Handles authentication of http requests and other authentication related tasks.
- * @internal
- */
-export class AuthService {
-    // MEMBER DATA
-    /** 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 = '') {
-        // 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 != '';
-
-        // Setting up the authenticated credentials
-        /**
-         * 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.
-         */
-        this.credentials = { authToken: this.authToken, csrfToken: cookie.match(/(?<=ct0=).+?(?=;)/) + '', cookie: cookie};
-        
-    }
-    
-    /**
-     * @returns The current authentication credentials. A different credential is returned each time this is invoked
-     */
-    async getAuthCredentials(): Promise<AuthCredentials> {
-        return this.credentials;
-    }
-
-    /**
-     * @returns The guest credentials fetched from twitter.
-     */
-    async getGuestCredentials(): Promise<GuestCredentials> {
-        // 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/helper/deserializers/Tweets.ts

@@ -1,70 +0,0 @@
-// TYPES
-import { Tweet, TweetEntities } from '../../../types/data/Tweet';
-import { Result as RawTweet, Entities2 as RawTweetEntities } from '../../../types/raw/tweet/Tweet';
-
-// PARSERS
-import * as Parsers from '../Parser';
-
-/**
- * @returns A TweetEntities object containing the various tweet entities
- * @param data The raw tweet entities data from the response received from TwitterAPI
- */
-export function toTweetEntities(data: RawTweetEntities): TweetEntities {
-    let entities: TweetEntities = {
-        mentionedUsers: [],
-        urls: [],
-        media: [],
-        hashtags: []
-    };
-    
-    // Extracting user mentions
-    if(data.user_mentions) {
-        for(let user of data.user_mentions) {
-            entities.mentionedUsers.push(user.id_str);
-        }
-    }
-
-    // Extracting urls
-    if(data.urls) {
-        for(let url of data.urls) {
-            entities.urls.push(url.expanded_url);
-        }
-    }
-    
-    // Extracting hashtags
-    if(data.hashtags) {
-        for(let hashtag of data.hashtags) {
-            entities.hashtags.push(hashtag.text);
-        }
-    }
-
-    // Extracting media urls (if any)
-    if(data.media) {
-        for(const media of data.media) {
-            entities.media.push(media.media_url_https);
-        }
-    }
-
-    return entities;
-}
-
-/**
- * @returns A Tweet object containing the tweet data
- * @param data The raw tweet data from the response received from TwitterAPI
- */
-export function toTweet(data: RawTweet): Tweet {
-    return {
-        id: data.rest_id,
-        createdAt: data.legacy.created_at,
-        tweetBy: data.legacy.user_id_str,
-        entities: toTweetEntities(data.legacy.entities),
-        quoted: data.legacy.quoted_status_id_str,
-        fullText: Parsers.normalizeText(data.legacy.full_text),
-        replyTo: data.legacy.in_reply_to_status_id_str,
-        lang: data.legacy.lang,
-        quoteCount: data.legacy.quote_count,
-        replyCount: data.legacy.reply_count,
-        retweetCount: data.legacy.retweet_count,
-        likeCount: data.legacy.favorite_count
-    };
-}

package/src/services/helper/deserializers/Users.ts

@@ -1,26 +0,0 @@
-// TYPES
-import { User } from '../../../types/data/User';
-import { Result as RawUser } from '../../../types/raw/user/User';
-
-/**
- * @returns A User object containing the user details
- * @param data The raw user data from Twitter API
- */
-export function toUser(data: RawUser): User {
-    return {
-        id: data.rest_id,
-        userName: data.legacy.screen_name,
-        fullName: data.legacy.name,
-        createdAt: data.legacy.created_at,
-        description: data.legacy.description,
-        isVerified: data.legacy.verified,
-        favouritesCount: data.legacy.favourites_count,
-        followersCount: data.legacy.followers_count,
-        followingsCount: data.legacy.friends_count,
-        statusesCount: data.legacy.statuses_count,
-        location: data.legacy.location,
-        pinnedTweet: data.legacy.pinned_tweet_ids_str[0],
-        profileBanner: data.legacy.profile_banner_url,
-        profileImage: data.legacy.profile_image_url_https
-    };
-}

package/src/types/data/Errors.ts

@@ -1,34 +0,0 @@
-/**
- * Different types of error messages related to authentication.
- *
- * @public
- */
-export enum AuthenticationErrors {
-    NotAuthenticated = "Cannot fetch this data without authentication",
-};
-
-/**
- * Different types error messages for validation errors.
- *
- * @public
- */
-export enum ValidationErrors {
-    InvalidTweetFilter = "Atleast one of fromUsers/toUsers/mentions/hashtags/words argument is required",
-    NoUserIdentification = "Either userName or id must be given",
-    InvalidCount = "Invalid count provided"
-};
-
-/**
- * Different type of error messages that are returned by services.
- *
- * @public
- */
-export enum DataErrors {
-    UserNotFound = "An account with given username/id was not found",
-    TweetNotFound = "A tweet with the given id was not found",
-    NoTweetsFound = "No tweets matching the given criteria found",
-    NoLikersFound = "No likers found for the tweet with the given id",
-    NoRetweetersFound = "No retweeters found for the tweet with the given id",
-    NoFollowsFound = "No follow details were found for the user with the given id",
-    NoLikedTweetsFound = "No liked tweets were found for the user with the given id"
-};