rettiwt-api 1.0.1

package/src/services/CacheService.ts

@@ -0,0 +1,70 @@
+// PACKAGES
+import NodeCache from 'node-cache';
+
+// PARSERS
+import * as Parsers from './helper/Parser';
+
+/**
+ * @summary 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.
+ */
+export class CacheService {
+    // MEMBER DATA
+    private static instance: CacheService;                              // To store the current instance of this service
+    private client: NodeCache;                                          // To store the redis client instance
+
+    // MEMBER METHODS
+    private constructor() {
+        // Initializing new cache
+        this.client = new NodeCache();
+    }
+
+    /**
+     * @returns The current working instance of CacheService
+     */
+    static async getInstance(): Promise<CacheService> {
+        // If an instance doesnt exists already
+        if (!this.instance) {
+            this.instance = new CacheService();
+            return this.instance;
+        }
+        // If an instance already exists, returning it
+        else {
+            return this.instance;
+        }
+    }
+
+    /**
+     * @summary Stores the input data into the cache.
+     * @returns Whether writing to cache was successful or not
+     * @param data The input data to store
+     */
+    async write(data: any): Promise<void> {
+        // Converting the data to a list of data
+        data = Parsers.dataToList(data);
+
+        // Iterating over the list of data
+        for (let item of data) {
+            // Storing whether data is already cached or not
+            let cached = this.client.has(Parsers.findJSONKey(item, 'id'));
+
+            // If data does not already exist in cache
+            if(!cached) {
+                // Adding data to cache
+                this.client.set(Parsers.findJSONKey(item, 'id'), item);
+            }
+        }
+    }
+
+    /**
+     * @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
+     */
+    async read(id: string): Promise<any> {
+        // Getting data from cache
+        let res = this.client.get(id);
+
+        return res;
+    }
+}

package/src/services/FetcherService.ts

@@ -0,0 +1,84 @@
+// PACKAGES
+import { curly, CurlyResult } from 'node-libcurl';
+
+// SERVICES
+import { AuthService } from './AuthService';
+import { CacheService } from './CacheService';
+
+// TYPES
+import { HttpStatus } from "../types/HTTP";
+import { Result as RawUser } from '../types/raw/user/User';
+import { Result as RawTweet } from '../types/raw/tweet/Tweet';
+
+// HELPERS
+import * as Headers from './helper/Headers'
+import * as Deserializers from './helper/Deserializers';
+
+/**
+ * @service The base serivice 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
+
+    // MEMBER METHODS
+    constructor(auth: AuthService) {
+        this.auth = auth;
+    }
+
+    /**
+    * @summary Throws the appropriate http error after evaluation of the status code of reponse
+    * @param res The response object received from http communication
+    */
+    private handleHTTPError(res: CurlyResult): CurlyResult {
+        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 authenticated Whether to authenticate requests or not
+     */
+    protected async request<DataType>(url: string, authenticated: boolean = false): Promise<CurlyResult<DataType>> {
+        // Fetching the data
+        let res = await curly.get(url, {
+            httpHeader: authenticated ? Headers.authorizedHeader(await this.auth.getAuthCredentials()) : Headers.guestHeader(await this.auth.getGuestCredentials()),
+            sslVerifyPeer: false
+        }).then(res => this.handleHTTPError(res));
+
+        return res;
+    }
+
+    /**
+     * @summary Caches the extracted data
+     * @param data The extracted data to be cached
+     */
+    protected async cacheData(data: any): Promise<void> {
+        // Creating an instance of cache
+        let cache = await CacheService.getInstance();
+
+        // Parsing the extracted data
+        let users = data.users.map((user: RawUser) => Deserializers.toUser(user));
+        let tweets = data.tweets.map((tweet: RawTweet) => Deserializers.toTweet(tweet));
+
+        // Caching the data
+        cache.write(users);
+        cache.write(tweets);
+    }
+
+    /**
+     * @returns The data with the given id (if it exists in cache)
+     * @param id The id of the data to be read from cache
+     */
+    protected async readData(id: string): Promise<any> {
+        // Creating an instance of cache
+        let cache = await CacheService.getInstance();
+
+        // Reading data from cache
+        return cache.read(id);
+    }
+}

package/src/services/data/TweetService.ts

@@ -0,0 +1,163 @@
+// SERVICES
+import { FetcherService } from "../FetcherService";
+import { AuthService } from "../AuthService";
+
+// TYPES
+import { TweetFilter, Tweet } from "../../types/Tweet";
+import { User } from "../../types/UserAccount";
+import { CursoredData } from '../../types/Service';
+import RawTweet from '../../types/raw/tweet/Tweet';
+import RawTweets from '../../types/raw/tweet/Tweets';
+import RawLikers from '../../types/raw/tweet/Favouriters';
+import RawRetweeters from '../../types/raw/tweet/Retweeters';
+
+// URLS
+import * as Urls from '../helper/Urls';
+
+// EXTRACTORS
+import * as Extractors from "../helper/Extractors";
+
+// DESERIALIZERS
+import * as Deserializers from '../helper/Deserializers';
+
+// PARSERS
+import { toQueryString } from '../helper/Parser';
+
+/**
+ * A service that deals with fetching of data related to tweets
+ */
+export class TweetService extends FetcherService {
+    // MEMBER METHODS
+    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
+     * @param cursor The cursor to the next batch of tweets. If blank, first batch is fetched
+     */
+    async getTweets(filter: TweetFilter, count: number, cursor: string): Promise<CursoredData<Tweet>> {
+        // Getting the raw data
+        let res = await this.request<RawTweets>(Urls.tweetsUrl(toQueryString(filter), count, cursor), false).then(res => res.data);
+
+        // Extracting data
+        let data = Extractors.extractTweets(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let tweets = data.required.map(item => Deserializers.toTweet(item));
+
+        return {
+            list: tweets,
+            next: { value: data.cursor }
+        };
+    }
+
+    /**
+     * @returns The details of a single tweet with the given tweet id
+     * @param tweetId The rest id of the target tweet
+     */
+    async getTweetById(tweetId: string): Promise<Tweet> {
+        // Getting data from cache
+        let cachedData = await this.readData(tweetId);
+
+        // If data exists in cache
+        if (cachedData) {
+            return cachedData;
+        }
+        // If data does not exist in cache
+        else {
+            // Fetching the raw data
+            let res = await this.request<RawTweet>(Urls.tweetDetailsUrl(tweetId)).then(res => res.data);
+
+            // Extracting data
+            let data = Extractors.extractTweet(res, tweetId);
+
+            // Caching data
+            this.cacheData(data);
+
+            // Parsing data
+            let tweet = Deserializers.toTweet(data.required[0]);
+
+            return tweet;
+        }
+    }
+
+    /**
+     * @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
+     * @param cursor The cursor to the next batch of users. If blank, first batch is fetched
+     */
+    async getTweetLikers(tweetId: string, count: number, cursor: string): Promise<CursoredData<User>> {
+        // Fetching the raw data
+        let res = await this.request<RawLikers>(Urls.tweetLikesUrl(tweetId, count, cursor)).then(res => res.data);
+
+        // Extracting data
+        let data = Extractors.extractTweetLikers(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let users = data.required.map(item => Deserializers.toUser(item));
+
+        return {
+            list: users,
+            next: { value: data.cursor }
+        };
+    }
+
+    /**
+     * @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
+     * @param cursor The cursor to the next batch of users. If blank, first batch is fetched
+     */
+    async getTweetRetweeters(tweetId: string, count: number, cursor: string): Promise<CursoredData<User>> {
+        // Fetching the raw data
+        let res = await this.request<RawRetweeters>(Urls.tweetRetweetUrl(tweetId, count, cursor)).then(res => res.data);
+
+        // Extracting data
+        let data = Extractors.extractTweetRetweeters(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let users = data.required.map(item => Deserializers.toUser(item));
+
+        return {
+            list: users,
+            next: { value: data.cursor }
+        };
+    }
+
+    /**
+     * @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
+     */
+    async getTweetReplies(tweetId: string, cursor: string): Promise<CursoredData<Tweet>> {
+        // Fetching the raw data
+        let res = await this.request<RawTweet>(Urls.tweetRepliesUrl(tweetId, cursor)).then(res => res.data);
+
+        // Extracting data
+        let data = Extractors.extractTweetReplies(res, tweetId);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let tweets = data.required.map(item => Deserializers.toTweet(item));
+
+        return {
+            list: tweets,
+            next: { value: data.cursor }
+        };
+    }
+}

package/src/services/data/UserAccountService.ts

@@ -0,0 +1,187 @@
+// SERVICES
+import { FetcherService } from '../FetcherService';
+import { AuthService } from '../AuthService';
+
+// TYPES
+import { User } from '../../types/UserAccount';
+import { Tweet } from '../../types/Tweet';
+import { CursoredData } from '../../types/Service';
+import RawUser from '../../types/raw/user/User';
+import RawUserTweets from '../../types/raw/user/Tweets';
+import RawUserFollowers from '../../types/raw/user/Followers';
+import RawUserFollowing from '../../types/raw/user/Following';
+import RawUserLikes from '../../types/raw/user/Likes';
+
+// URLS
+import * as Urls from '../helper/Urls';
+
+// EXTRACTORS
+import * as Extractors from '../helper/Extractors';
+
+// DESERIALIZERS
+import * as Deserializers from '../helper/Deserializers';
+
+/**
+ * A service that deals with fetching of data related to user account
+ */
+export class UserAccountService extends FetcherService {
+    // MEMBER METHODS
+    constructor(auth: AuthService) {
+        super(auth);
+    }
+
+    /**
+     * @returns The user account details of the given user
+     * @param screenName The screen name of the target user.
+     */
+    async getUserAccountDetails(screenName: string): Promise<User> {
+        // Fetching the raw data
+        let res: RawUser = await this.request<RawUser>(Urls.userAccountUrl(screenName), false).then(res => res.data);
+        
+        // Extracting data
+        let data = Extractors.extractUserAccountDetails(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let user = Deserializers.toUser(data.required[0]);
+            
+        return user;
+    }
+
+    /**
+     * @returns The user account details of the user with given rest id
+     * @param restId The screen name of the target user.
+     */
+    async getUserAccountDetailsById(restId: string): Promise<User> {
+        // Getting data from cache
+        let cachedData = await this.readData(restId);
+
+        // If data exists in cache
+        if(cachedData) {
+            return cachedData;
+        }
+        // If data does not exist in cache
+        else {
+            // Fetchin the raw data
+            let res = await this.request<RawUser>(Urls.userAccountByIdUrl(restId), false).then(res => res.data);
+
+            // Extracting data
+            let data = Extractors.extractUserAccountDetails(res);
+
+            // Caching data
+            this.cacheData(data);
+
+            // Parsing data
+            let user = Deserializers.toUser(data.required[0]);
+                
+            return user;
+        }
+    }
+
+    /**
+     * @returns The list of users followed by the target user
+     * @param userId The rest id of the target user
+     * @param count The batch size of the list
+     * @param cursor The cursor to next batch. If blank, first batch is fetched
+     */
+    async getUserFollowing(userId: string, count: number, cursor: string): Promise<CursoredData<User>> {
+        // Fetchin the raw data
+        let res = await this.request<RawUserFollowing>(Urls.userFollowingUrl(userId, count, cursor)).then(res => res.data);
+        
+        // Extracting data
+        let data = Extractors.extractUserFollow(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let users = data.required.map(item => Deserializers.toUser(item));
+
+        return {
+            list: users,
+            next: { value: data.cursor }
+        };
+    }
+
+    /**
+     * @returns The list of users following the target user
+     * @param userId The rest id of the target user
+     * @param count The batch size of the list
+     * @param cursor The cursor to next batch. If blank, first batch is fetched
+     */
+    async getUserFollowers(userId: string, count: number, cursor: string): Promise<CursoredData<User>> {
+        /**
+         * When fetching list of followers, the official Twitter API seems to be fetching n + 20 followers,
+         * where n is the actual required number of followers.
+         * So changing count to count - 20, fixes fetching more than required number of follower
+         */
+        // Fetching the raw data
+        let res = await this.request<RawUserFollowers>(Urls.userFollowersUrl(userId, (count > 20) ? (count - 20) : count, cursor)).then(res => res.data);
+        
+        // Extracting data
+        let data = Extractors.extractUserFollow(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let users = data.required.map(item => Deserializers.toUser(item));
+
+        return {
+            list: users,
+            next: { value: data.cursor }
+        };
+    }
+
+    /**
+     * @returns The list of tweets liked by the target user
+     * @param userId The rest id of the target user
+     * @param count The batch size of the list
+     * @param cursor The cursor to next batch. If blank, first batch is fetched
+     */
+    async getUserLikes(userId: string, count: number, cursor: string): Promise<CursoredData<Tweet>> {
+        // Fetching the raw data
+        let res = await this.request<RawUserLikes>(Urls.userLikesUrl(userId, count, cursor)).then(res => res.data);
+        
+        // Extracting data
+        let data = Extractors.extractUserLikes(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let tweets = data.required.map(item => Deserializers.toTweet(item));
+
+        return {
+            list: tweets,
+            next: { value: data.cursor }
+        };
+    }
+
+    /**
+     * @returns The list of tweets made by the target user
+     * @param userId The rest id of the target user
+     * @param count The batch size of the list
+     * @param cursor The cursor to next batch. If blank, first batch is fetched
+     */
+    async getUserTweets(userId: string, count: number, cursor: string): Promise<CursoredData<Tweet>> {
+        // Fetching the raw data
+        let res = await this.request<RawUserTweets>(Urls.userTweetsUrl(userId, count, cursor)).then(res => res.data);
+
+        // Extracting data
+        let data = Extractors.extractUserTweets(res);
+
+        // Caching data
+        this.cacheData(data);
+
+        // Parsing data
+        let tweets = data.required.map(item => Deserializers.toTweet(item));
+
+        return {
+            list: tweets,
+            next: { value: data.cursor }
+        };
+    }
+};

package/src/services/helper/Deserializers.ts

@@ -0,0 +1,95 @@
+// TYPES
+import { User } from '../../types/UserAccount';
+import { Tweet, TweetEntities } from '../../types/Tweet';
+import { Result as RawUser } from '../../types/raw/user/User';
+import { Result as RawTweet, Entities2 as RawTweetEntities } from '../../types/raw/tweet/Tweet';
+
+// PARSERS
+import * as Parsers from './Parser';
+
+/**
+ * @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
+    };
+}
+
+/**
+ * @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
+    };
+}