rettiwt-api 1.1.2 → 1.1.7

package/src/index.ts

@@ -1,18 +1,30 @@
+// PACKAGES
+import 'reflect-metadata';
+
 // SERVICES
-import { AuthService } from "./services/AuthService";
+import { AuthService } from "./services/auth/AuthService";
 import { UserService } from "./services/data/UserService";
 import { TweetService } from "./services/data/TweetService";
-import { AccountService } from "./services/accounts/AccountService";
+import { AccountService } from "./services/auth/AccountService";
+
+// TYPES
+import { IAuthCookie } from './types/Authentication';
 
 /**
- * @param cookie The cookie string to use to fetch data
- * @returns The API for fetching user and tweet data
+ * The instance for fetching data from Twitter.
+ * 
+ * @public
+ * 
+ * @param cookie The cookie 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.
+ * To use the {@link AccountService.login} method, create a {@link Rettiwt} instance without passing any cookie .
  * 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
+export const Rettiwt = (cookie?: IAuthCookie) => {
+    // Creating new auth service instance using the given cookie
     const auth: AuthService = new AuthService(cookie);
 
     // Using the auth service instance to create data services instances
@@ -24,17 +36,27 @@ export const Rettiwt = (cookie: string = '') => {
 }
 
 // Exporting classes
-export * from './services/AuthService';
-export * from './services/CacheService';
-export * from './services/FetcherService';
-export * from './services/accounts/AccountService';
+export * from './services/auth/AuthService';
+export * from './services/auth/AccountService';
 export * from './services/data/TweetService';
 export * from './services/data/UserService';
+export * from './services/util/CacheService';
+export * from './services/util/FetcherService';
 
 // 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';
+export * from './types/Args';
+export { IAuthCookie } from './types/Authentication';
+export * from './types/Rettiwt';
+export * from './types/Service';
+export * from './types/Tweet';
+export * from './types/User';
+
+// Exporting models
+export * from './models/args/TweetFilter';
+export * from './models/args/TweetListArgs';
+export * from './models/args/UserListArgs';
+export * from './models/auth/AuthCookie';
+export * from './models/data/CursoredData';
+export * from './models/data/Tweet';
+export * from './models/data/User';
+export * from './models/errors/DataValidationError';

package/src/models/args/TweetFilter.ts

@@ -0,0 +1,119 @@
+// PACKAGE
+import { IsArray, IsBoolean, IsNumberString, IsString, IsOptional, IsDateString, validateSync } from 'class-validator';
+
+// TYPES
+import { ITweetFilter } from '../../types/Args';
+import { DataValidationError } from '../errors/DataValidationError';
+
+/**
+ * The filter to be used for fetching tweets from Twitter.
+ * 
+ * @internal
+ */
+export class TweetFilter implements ITweetFilter {
+    /** The list of words to search. */
+    @IsArray()
+    @IsString({ each: true })
+    @IsOptional()
+    words?: string[];
+
+    /** The list of hashtags to search.
+     *
+     * @remarks
+     * '#' must be excluded from the hashtag!
+     */
+    @IsArray()
+    @IsString({ each: true })
+    @IsOptional()
+    hashtags?: string[];
+
+    /** The list of usernames whose tweets are to be searched.
+     *
+     * @remarks
+     * '@' must be excluded from the username!
+     */
+    @IsArray()
+    @IsString({ each: true })
+    @IsOptional()
+    fromUsers?: string[];
+
+    /** The list of username to whom the tweets to be searched, are adressed.
+     *
+     * @remarks
+     * '@' must be excluded from the username!
+     */
+    @IsArray()
+    @IsString({ each: true })
+    @IsOptional()
+    toUsers?: string[];
+
+    /** The list of username mentioned in the tweets to search.
+     *
+     * @remarks
+     * '@' must be excluded from the username!
+     */
+    @IsArray()
+    @IsString({ each: true })
+    @IsOptional()
+    mentions?: string[];
+
+    /** The date starting from which tweets are to be searched.
+     *
+     * @remarks
+     * Must be in the format YYYY-MM-DD.
+     */
+    @IsOptional()
+    @IsDateString()
+    startDate?: string;
+
+    /** The date upto which tweets are to be searched.
+     *
+     * @remarks
+     * Must be in the format YYYY-MM-DD.
+     */
+    @IsOptional()
+    @IsDateString()
+    endDate?: string;
+
+    /** The id of the tweet, after which the tweets are to be searched. */
+    @IsNumberString()
+    @IsOptional()
+    sinceId?: string;
+
+    /** The id of the tweet which is quoted in the tweets to search. */
+    @IsNumberString()
+    @IsOptional()
+    quoted?: string;
+    
+    /** Whether to fetch tweets that are links or not.
+     *
+     * @defaultValue false
+     */
+    @IsBoolean()
+    @IsOptional()
+    links?: boolean;
+
+    /**
+     * @param filter The incoming filter in JSON format.
+     */
+    constructor(filter: TweetFilter) {
+        this.endDate = filter.endDate;
+        this.fromUsers = filter.fromUsers;
+        this.hashtags = filter.hashtags;
+        this.links = filter.links;
+        this.mentions = filter.mentions;
+        this.quoted = filter.quoted;
+        this.sinceId = filter.sinceId;
+        this.startDate = filter.startDate;
+        this.toUsers = filter.toUsers;
+        this.words = filter.words;
+
+        // Validating the filter
+        const validationResult = validateSync(this);
+
+        // If valiation error occured
+        if (validationResult.length) {
+            throw new DataValidationError(validationResult);
+        }
+    }
+}

package/src/models/args/TweetListArgs.ts

@@ -0,0 +1,47 @@
+// PACKAGES
+import { IsInt, IsString, IsOptional, Min, validateSync, Max, ValidateIf } from 'class-validator';
+
+// TYPES
+import { IListArgs } from '../../types/Args';
+import { DataValidationError } from '../errors/DataValidationError';
+
+/**
+ * The arguments for fetching cursored list in TweetService.
+ * 
+ * @internal
+ */
+export class TweetListArgs implements IListArgs {
+    /** The number of data items to fetch.
+     * 
+     * @defaultValue 10
+     * @remarks Must be >= 10 and <= 100
+     */
+    @IsInt()
+    @IsOptional()
+    @Max(100)
+    @ValidateIf(ob => ob.cursor.length == 0)
+    @Min(10)    
+    count: number;
+
+    /** The cursor to the batch of data to fetch. */
+    @IsString()
+    @IsOptional()
+    cursor: string;
+
+    /**
+     * @param count The number of data items to fetch.
+     * @param cursor The cursor to the batch of data to fetch.
+     */
+    constructor(count: number = 10, cursor: string = '') {
+        this.count = count;
+        this.cursor = cursor;
+
+        // Validating the arguments
+        const validationResult = validateSync(this);
+
+        // If valiation error occured
+        if (validationResult.length) {
+            throw new DataValidationError(validationResult);
+        }
+    }
+}

package/src/models/args/UserListArgs.ts

@@ -0,0 +1,47 @@
+// PACKAGES
+import { IsInt, IsString, IsOptional, Min, validateSync, Max, ValidateIf } from 'class-validator';
+
+// TYPES
+import { IListArgs } from '../../types/Args';
+import { DataValidationError } from '../errors/DataValidationError';
+
+/**
+ * The arguments for fetching cursored list in TweetService.
+ * 
+ * @internal
+ */
+export class UserListArgs implements IListArgs {
+    /** The number of data items to fetch.
+     * 
+     * @defaultValue 40
+     * @remarks Must be >= 40 and <= 100
+     */
+    @IsInt()
+    @IsOptional()
+    @Max(100)
+    @ValidateIf(ob => ob.cursor.length == 0)
+    @Min(40)
+    count: number;
+
+    /** The cursor to the batch of data to fetch. */
+    @IsString()
+    @IsOptional()
+    cursor: string;
+
+    /**
+     * @param count The number of data items to fetch.
+     * @param cursor The cursor to the batch of data to fetch.
+     */
+    constructor(count: number = 40, cursor: string = '') {
+        this.count = count;
+        this.cursor = cursor;
+
+        // Validating the arguments
+        const validationResult = validateSync(this);
+
+        // If valiation error occured
+        if (validationResult.length) {
+            throw new DataValidationError(validationResult);
+        }
+    }
+}

package/src/models/auth/AuthCookie.ts

@@ -0,0 +1,43 @@
+// TYPES
+import { IAuthCookie } from '../../types/Authentication';
+
+/**
+ * The cookie containing the tokens that are used to authenticate against Twitter.
+ * 
+ * @internal
+ */
+export class AuthCookie implements 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;
+
+    constructor(cookie?: IAuthCookie) {
+        this.auth_token = cookie?.auth_token ?? '';
+        this.ct0 = cookie?.ct0 ?? '';
+        this.kdt = cookie?.kdt ?? '';
+        this.twid = cookie?.twid ?? '';
+    }
+
+    /**
+     * @returns The string respresentation of this cookie in the valid cookie string format.
+     */
+    toString(): string {
+        /** The string representation of this cookie. */
+        let cookieString: string = '';
+        
+        // Iterating through the (key, value) pairs of this cookie
+        for (let [key, value] of Object.entries(this)) {
+            cookieString += `${key}=${value};`;
+        }
+
+        return cookieString;
+    }
+}

package/src/models/data/CursoredData.ts

@@ -0,0 +1,45 @@
+// TYPES
+import { ICursor,ICursoredData } from "../../types/Service";
+
+/**
+ * The cursor to the batch of data to be fetched.
+ * 
+ * @internal
+ */
+export class Cursor implements ICursor {
+    /** The cursor string. */
+    value: string;
+
+    /**
+     * Initializes a new cursor from the given cursor string.
+     * 
+     * @param cursorStr The string representation of the cursor.
+     */
+    constructor(cursorStr: string) {
+        this.value = cursorStr;
+    }
+}
+
+/**
+ * The data that us fetched batch-wise along with a cursor.
+ * 
+ * @internal
+ * 
+ * @typeParam Type - The type of data present in the list.
+ */
+export class CursoredData<T> implements ICursoredData<T> {
+    /** The list of data of the given type. */
+    list: T[];
+
+    /** The cursor to the next batch of data. */
+    next: Cursor;
+
+    /**
+     * @param list The list of data item to store.
+     * @param next The cursor to the next batch of data.
+     */
+    constructor(list: T[] = [], next: string = '') {
+        this.list = list;
+        this.next = new Cursor(next);
+    }
+}

package/src/models/data/Tweet.ts

@@ -0,0 +1,118 @@
+// TYPES
+import { ITweet, ITweetEntities } from '../../types/Tweet';
+import { Result as RawTweet, Entities2 as RawTweetEntities } from '../../types/raw/tweet/Tweet';
+
+// PARSERS
+import * as Parsers from '../../services/helper/Parser';
+
+/**
+ * The different types parsed entities like urls, media, mentions, hashtags, etc.
+ * 
+ * @internal
+ */
+export class TweetEntities implements ITweetEntities {
+    // MEMBER DATA
+    /** 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[] = [];
+
+    // MEMBER METHODS
+    constructor(entities: RawTweetEntities) {
+        // Extracting user mentions
+        if (entities.user_mentions) {
+            for (let user of entities.user_mentions) {
+                this.mentionedUsers.push(user.id_str);
+            }
+        }
+
+        // Extracting urls
+        if (entities.urls) {
+            for (let url of entities.urls) {
+                this.urls.push(url.expanded_url);
+            }
+        }
+
+        // Extracting hashtags
+        if (entities.hashtags) {
+            for (let hashtag of entities.hashtags) {
+                this.hashtags.push(hashtag.text);
+            }
+        }
+
+        // Extracting media urls (if any)
+        if (entities.media) {
+            for (const media of entities.media) {
+                this.media.push(media.media_url_https);
+            }
+        }
+    }
+}
+
+/**
+ * The details of a single Tweet.
+ * 
+ * @internal
+ */
+export class Tweet implements 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: TweetEntities;
+
+    /** 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;
+
+    /**
+     * @param tweet The raw tweet data.
+     */
+    constructor(tweet: RawTweet) {
+        this.id = tweet.rest_id;
+        this.createdAt = tweet.legacy.created_at;
+        this.tweetBy = tweet.legacy.user_id_str;
+        this.entities = new TweetEntities(tweet.legacy.entities);
+        this.quoted = tweet.legacy.quoted_status_id_str;
+        this.fullText = Parsers.normalizeText(tweet.legacy.full_text);
+        this.replyTo = tweet.legacy.in_reply_to_status_id_str;
+        this.lang = tweet.legacy.lang;
+        this.quoteCount = tweet.legacy.quote_count;
+        this.replyCount = tweet.legacy.reply_count;
+        this.retweetCount = tweet.legacy.retweet_count;
+        this.likeCount = tweet.legacy.favorite_count;
+    }
+}

package/src/models/data/User.ts

@@ -0,0 +1,72 @@
+// TYPES
+import { IUser } from '../../types/User';
+import { Result as RawUser } from '../../types/raw/user/User';
+
+/**
+ * The details of a single user.
+ * 
+ * @internal
+ */
+export class User implements 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;
+
+    /**
+     * @param user The raw user data.
+     */
+    constructor(user: RawUser) {
+        this.id = user.rest_id;
+        this.userName = user.legacy.screen_name;
+        this.fullName = user.legacy.name;
+        this.createdAt = user.legacy.created_at;
+        this.description = user.legacy.description;
+        this.isVerified = user.legacy.verified;
+        this.favouritesCount = user.legacy.favourites_count;
+        this.followersCount = user.legacy.followers_count;
+        this.followingsCount = user.legacy.friends_count;
+        this.statusesCount = user.legacy.statuses_count;
+        this.location = user.legacy.location;
+        this.pinnedTweet = user.legacy.pinned_tweet_ids_str[0];
+        this.profileBanner = user.legacy.profile_banner_url;
+        this.profileImage = user.legacy.profile_image_url_https;
+    }
+}

package/src/models/errors/DataValidationError.ts

@@ -0,0 +1,29 @@
+// PACKAGES
+import { ValidationError } from "class-validator";
+
+/**
+ * Error when any fields of a JSON data fails to validate.
+ * 
+ * @internal
+ * 
+ * @param errorDetails The details of about the specific fields that failed to validate.
+ */
+export class DataValidationError implements Error {
+    /** The name of the error. */
+    name: string;
+
+    /** The user-friendly error message. */
+    message: string;
+
+    /** The error data. */
+    data: ValidationError[];
+
+    /**
+     * @param data The error details.
+     */
+    constructor(errorDetails: ValidationError[]) {
+        this.name = 'ValidationError';
+        this.message = 'One or more validation errors occured. Refer to data for details';
+        this.data = errorDetails;
+    }
+}

package/src/server.ts

@@ -2,12 +2,10 @@
 import express from 'express';
 import { graphqlHTTP } from 'express-graphql';
 import { GraphQLSchema } from 'graphql';
+import 'reflect-metadata';
 
-// Services
-import { UserService } from './services/data/UserService';
-import { TweetService } from './services/data/TweetService';
-import { AccountService } from './services/accounts/AccountService';
-import { AuthService } from './services/AuthService';
+// SERVICES
+import { Rettiwt } from '.';
 
 // SCHEMA
 import { rootQuery } from './graphql/queries/RootQuery';
@@ -23,11 +21,12 @@ app.use('/graphql', graphqlHTTP(req => ({
     schema: new GraphQLSchema({
         query: rootQuery
     }),
-    context: {
-        users: new UserService(new AuthService(req.headers.cookie as string)),
-        tweets: new TweetService(new AuthService(req.headers.cookie as string)),
-        account: new AccountService()
-    },
+    context: Rettiwt({
+        auth_token: req.headers['auth_token'] as string,
+        ct0: req.headers['ct0'] as string,
+        kdt: req.headers['kdt'] as string,
+        twid: req.headers['twid'] as string,
+    }),
     // If app is running in development environment, enable graphiql
     graphiql: config.is_development
 })));