rettiwt-api 4.2.0 → 5.0.0-alpha.1

package/src/models/args/PostArgs.ts

@@ -1,311 +1,46 @@
-import {
-	ArrayMaxSize,
-	IsArray,
-	IsDate,
-	IsEmpty,
-	IsNotEmpty,
-	IsNumberString,
-	IsObject,
-	IsOptional,
-	IsString,
-	Max,
-	MaxLength,
-	MinDate,
-	validateSync,
-} from 'class-validator';
-
-import { NewTweet, NewTweetMedia } from 'rettiwt-core';
+import { NewTweet } from 'rettiwt-core';
 
 import { EResourceType } from '../../enums/Resource';
-import { DataValidationError } from '../errors/DataValidationError';
+import { IPostArgs, IUploadArgs } from '../../types/args/PostArgs';
 
 /**
- * Options specifying the data that is to be posted.
+ * Options specifying the media file to be uploaded.
  *
  * @public
  */
-export class PostArgs {
-	/**
-	 * The id of the target resource.
-	 *
-	 * @remarks
-	 * Required only when posting using the following resources:
-	 * - {@link EResourceType.TWEET_LIKE}
-	 * - {@link EResourceType.TWEET_RETWEET}
-	 * - {@link EResourceType.TWEET_UNLIKE}
-	 * - {@link EResourceType.TWEET_UNPOST}
-	 * - {@link EResourceType.TWEET_UNRETWEET}
-	 * - {@link EResourceType.USER_FOLLOW}
-	 * - {@link EResourceType.USER_UNFOLLOW}
-	 */
-	@IsEmpty({
-		groups: [
-			EResourceType.MEDIA_UPLOAD_APPEND,
-			EResourceType.MEDIA_UPLOAD_FINALIZE,
-			EResourceType.MEDIA_UPLOAD_INITIALIZE,
-			EResourceType.TWEET_POST,
-			EResourceType.TWEET_SCHEDULE,
-		],
-	})
-	@IsNotEmpty({
-		groups: [
-			EResourceType.TWEET_LIKE,
-			EResourceType.TWEET_RETWEET,
-			EResourceType.TWEET_UNLIKE,
-			EResourceType.TWEET_UNPOST,
-			EResourceType.TWEET_UNRETWEET,
-			EResourceType.TWEET_UNSCHEDULE,
-			EResourceType.USER_FOLLOW,
-			EResourceType.USER_UNFOLLOW,
-		],
-	})
-	@IsNumberString(undefined, {
-		groups: [
-			EResourceType.TWEET_LIKE,
-			EResourceType.TWEET_RETWEET,
-			EResourceType.TWEET_UNLIKE,
-			EResourceType.TWEET_UNPOST,
-			EResourceType.TWEET_UNRETWEET,
-			EResourceType.TWEET_UNSCHEDULE,
-			EResourceType.USER_FOLLOW,
-			EResourceType.USER_UNFOLLOW,
-		],
-	})
+export class UploadArgs implements IUploadArgs {
 	public id?: string;
+	public media?: string | ArrayBuffer;
+	public size?: number;
 
 	/**
-	 * The tweet that is to be posted.
-	 *
-	 * @remarks
-	 * Required only when posting a tweet using {@link EResourceType.TWEET_POST}
-	 */
-	@IsEmpty({
-		groups: [
-			EResourceType.MEDIA_UPLOAD_APPEND,
-			EResourceType.MEDIA_UPLOAD_FINALIZE,
-			EResourceType.MEDIA_UPLOAD_INITIALIZE,
-			EResourceType.TWEET_LIKE,
-			EResourceType.TWEET_RETWEET,
-			EResourceType.TWEET_UNLIKE,
-			EResourceType.TWEET_UNPOST,
-			EResourceType.TWEET_UNRETWEET,
-			EResourceType.TWEET_UNSCHEDULE,
-			EResourceType.USER_FOLLOW,
-			EResourceType.USER_UNFOLLOW,
-		],
-	})
-	@IsNotEmpty({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@IsObject({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	public tweet?: TweetArgs;
-
-	/**
-	 * The media file to be uploaded.
-	 *
-	 * @remarks
-	 * Required only when uploading a media using the following resources:
-	 * - {@link EResourceType.MEDIA_UPLOAD_APPEND}
-	 * - {@link EResourceType.MEDIA_UPLOAD_FINALIZE}
-	 * - {@link EResourceType.MEDIA_UPLOAD_INITIALIZE}
-	 */
-	@IsEmpty({
-		groups: [
-			EResourceType.TWEET_LIKE,
-			EResourceType.TWEET_POST,
-			EResourceType.TWEET_RETWEET,
-			EResourceType.TWEET_SCHEDULE,
-			EResourceType.TWEET_UNLIKE,
-			EResourceType.TWEET_UNPOST,
-			EResourceType.TWEET_UNRETWEET,
-			EResourceType.TWEET_UNSCHEDULE,
-			EResourceType.USER_FOLLOW,
-			EResourceType.USER_UNFOLLOW,
-		],
-	})
-	@IsNotEmpty({
-		groups: [
-			EResourceType.MEDIA_UPLOAD_INITIALIZE,
-			EResourceType.MEDIA_UPLOAD_APPEND,
-			EResourceType.MEDIA_UPLOAD_FINALIZE,
-		],
-	})
-	@IsObject({
-		groups: [
-			EResourceType.MEDIA_UPLOAD_INITIALIZE,
-			EResourceType.MEDIA_UPLOAD_APPEND,
-			EResourceType.MEDIA_UPLOAD_FINALIZE,
-		],
-	})
-	public upload?: UploadArgs;
-
-	/**
-	 * @param resource - The resource to be posted.
-	 * @param args - Additional user-defined arguments for posting the resource.
+	 * @param step - The upload step.
+	 * @param args - The upload arguments for uploading the media file.
 	 */
-	public constructor(resource: EResourceType, args: PostArgs) {
+	public constructor(step: EResourceType, args: IUploadArgs) {
+		this.size = args.size;
+		this.media = args.media;
 		this.id = args.id;
-		this.tweet = args.tweet ? new TweetArgs(resource, args.tweet) : undefined;
-		this.upload = args.upload ? new UploadArgs(resource, args.upload) : undefined;
-
-		// Validating this object
-		const validationResult = validateSync(this, { groups: [resource] });
-
-		// If valiation error occured
-		if (validationResult.length) {
-			throw new DataValidationError(validationResult);
-		}
-	}
-}
-
-/**
- * Options specifying the tweet that is to be posted.
- *
- * @public
- */
-export class TweetArgs extends NewTweet {
-	/**
-	 * The list of media to be uploaded.
-	 *
-	 * @remarks
-	 * Maximum number of media items that can be posted is 4.
-	 */
-	@IsOptional({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@IsArray({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@ArrayMaxSize(4, { groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@IsObject({ each: true, groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	public media?: TweetMediaArgs[];
-
-	/** The id of the tweet to quote. */
-	@IsOptional({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@IsNumberString(undefined, { groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	public quote?: string;
-
-	/** The id of the tweet to which the given tweet must be a reply. */
-	@IsOptional({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@IsNumberString(undefined, { groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	public replyTo?: string;
-
-	/** The date/time at which the tweet must be scheduled to be posted. */
-	@IsEmpty({ groups: [EResourceType.TWEET_POST] })
-	@IsNotEmpty({ groups: [EResourceType.TWEET_SCHEDULE] })
-	@IsDate({ groups: [EResourceType.TWEET_SCHEDULE] })
-	@MinDate(() => new Date(), { groups: [EResourceType.TWEET_SCHEDULE] })
-	public scheduleFor?: Date;
-
-	/**
-	 * The text for the tweet to be created.
-	 *
-	 * @remarks
-	 * Length of the tweet must be \<= 280 characters.
-	 */
-	@IsNotEmpty({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@IsString({ groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	@MaxLength(280, { groups: [EResourceType.TWEET_POST, EResourceType.TWEET_SCHEDULE] })
-	public text: string;
-
-	/**
-	 * @param args - Arguments specifying the tweet to be posted.
-	 */
-	public constructor(resource: EResourceType, args: TweetArgs) {
-		super();
-		this.media = args.media ? args.media.map((item) => new TweetMediaArgs(item)) : undefined;
-		this.quote = args.quote;
-		this.replyTo = args.replyTo;
-		this.scheduleFor = args.scheduleFor;
-		this.text = args.text;
-
-		// Validating this object
-		const validationResult = validateSync(this, { groups: [resource] });
-
-		// If valiation error occured
-		if (validationResult.length) {
-			throw new DataValidationError(validationResult);
-		}
 	}
 }
 
 /**
- * Options specifying the media that is to be posted.
+ * Options specifying the data that is to be posted.
  *
  * @public
  */
-export class TweetMediaArgs extends NewTweetMedia {
-	/** The id of the media to post. */
-	@IsNotEmpty()
-	@IsNumberString()
-	public id: string;
-
-	/**
-	 * The list of id of the users tagged in the media.
-	 *
-	 * @remarks
-	 * Maximum number of users that can be tagged is 10.
-	 */
-	@IsOptional()
-	@IsArray()
-	@ArrayMaxSize(10)
-	@IsNumberString(undefined, { each: true })
-	public tags?: string[];
-
-	/**
-	 * @param args - Arguments specifying the media to be posted.
-	 */
-	public constructor(args: TweetMediaArgs) {
-		super();
-		this.id = args.id;
-		this.tags = args.tags ?? [];
-
-		// Validating this object
-		const validationResult = validateSync(this);
-
-		// If validation error occured
-		if (validationResult.length) {
-			throw new DataValidationError(validationResult);
-		}
-	}
-}
-
-/**
- * Options specifying the media file to be uploaded.
- *
- * @internal
- */
-export class UploadArgs {
-	/** The id allocated to the media file to be uploaded. */
-	@IsEmpty({ groups: [EResourceType.MEDIA_UPLOAD_INITIALIZE] })
-	@IsNotEmpty({ groups: [EResourceType.MEDIA_UPLOAD_APPEND, EResourceType.MEDIA_UPLOAD_FINALIZE] })
-	@IsNumberString(undefined, { groups: [EResourceType.MEDIA_UPLOAD_APPEND, EResourceType.MEDIA_UPLOAD_FINALIZE] })
+export class PostArgs implements IPostArgs {
 	public id?: string;
-
-	/** The media file to be uploaded. */
-	@IsEmpty({ groups: [EResourceType.MEDIA_UPLOAD_FINALIZE, EResourceType.MEDIA_UPLOAD_INITIALIZE] })
-	@IsNotEmpty({ groups: [EResourceType.MEDIA_UPLOAD_APPEND] })
-	public media?: string | ArrayBuffer;
-
-	/**
-	 * The size (in bytes) of the media file to be uploaded.
-	 *
-	 * @remarks The size must be \<= 5242880 bytes.
-	 */
-	@IsEmpty({ groups: [EResourceType.MEDIA_UPLOAD_APPEND, EResourceType.MEDIA_UPLOAD_FINALIZE] })
-	@IsNotEmpty({ groups: [EResourceType.MEDIA_UPLOAD_INITIALIZE] })
-	@Max(5242880, { groups: [EResourceType.MEDIA_UPLOAD_INITIALIZE] })
-	public size?: number;
+	public tweet?: NewTweet;
+	public upload?: UploadArgs;
 
 	/**
-	 * @param step - The upload step.
-	 * @param args - The upload arguments for uploading the media file.
+	 * @param resource - The resource to be posted.
+	 * @param args - Additional user-defined arguments for posting the resource.
 	 */
-	public constructor(step: EResourceType, args: UploadArgs) {
-		this.size = args.size;
-		this.media = args.media;
+	public constructor(resource: EResourceType, args: IPostArgs) {
 		this.id = args.id;
-
-		// Validating this object
-		const validationResult = validateSync(this, { groups: [step] });
-
-		// If validation error occured
-		if (validationResult.length) {
-			throw new DataValidationError(validationResult);
-		}
+		this.tweet = args.tweet ? new NewTweet(args.tweet) : undefined;
+		this.upload = args.upload ? new UploadArgs(resource, args.upload) : undefined;
 	}
 }

package/src/models/auth/AccountCredential.ts

@@ -0,0 +1,19 @@
+import { IAccountCredential } from '../../types/auth/AccountCredential';
+
+/**
+ * The credentials of the Twitter account to be logged into.
+ */
+export class AccountCredential implements IAccountCredential {
+	public email: string;
+	public password: string;
+	public userName: string;
+
+	/**
+	 * @param cred - The credentials to the Twitter account.
+	 */
+	public constructor(cred: IAccountCredential) {
+		this.email = cred.email;
+		this.userName = cred.userName;
+		this.password = cred.password;
+	}
+}

package/src/models/auth/AuthCookie.ts

@@ -0,0 +1,56 @@
+import { Cookie } from 'cookiejar';
+
+import { IAuthCookie } from '../../types/auth/AuthCookie';
+
+/**
+ * The cookie containing the tokens that are used to authenticate against Twitter.
+ */
+export class AuthCookie implements IAuthCookie {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	public auth_token: string;
+	public ct0: string;
+	public kdt: string;
+	public twid: string;
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+
+	/**
+	 * @param cookies - The cookie list obtained from the browser.
+	 */
+	public constructor(cookies: Cookie[]) {
+		// Initializing defaults
+		this.auth_token = '';
+		this.ct0 = '';
+		this.kdt = '';
+		this.twid = '';
+
+		// Parsing the cookies
+		for (const cookie of cookies) {
+			if (cookie.name == 'kdt') {
+				this.kdt = cookie.value;
+			} else if (cookie.name == 'twid') {
+				this.twid = cookie.value;
+			} else if (cookie.name == 'ct0') {
+				this.ct0 = cookie.value;
+			} else if (cookie.name == 'auth_token') {
+				this.auth_token = cookie.value;
+			}
+		}
+	}
+
+	/**
+	 * @returns the string representation of 'this' object.
+	 */
+	public toString(): string {
+		/** The string representation of 'this' object. */
+		let outStr = '';
+
+		// Iterating through the (key, value) pairs of this cookie
+		for (const [key, value] of Object.entries(this)) {
+			outStr += `${key}=${value as string};`;
+		}
+
+		return outStr;
+	}
+}

package/src/models/auth/AuthCredential.ts

@@ -0,0 +1,83 @@
+import { AxiosHeaders, AxiosRequestHeaders } from 'axios';
+
+import { Cookie } from 'cookiejar';
+
+import { EAuthenticationType } from '../../enums/Authentication';
+import { IAuthCredential } from '../../types/auth/AuthCredential';
+
+import { AuthCookie } from './AuthCookie';
+
+/**
+ * The credentials for authenticating against Twitter.
+ *
+ * Depending on which tokens are present, the authentication type is determined as follows:
+ * - authToken, guestToken =\> Guest authentication.
+ * - authToken, csrfToken, cookie =\> User authentication.
+ * - authToken, guestToken, cookie =\> Guest authentication while logging in.
+ */
+export class AuthCredential implements IAuthCredential {
+	public authToken?: string;
+	public authenticationType?: EAuthenticationType;
+	public cookies?: string;
+	public csrfToken?: string;
+	public guestToken?: string;
+
+	/**
+	 * @param cookies - The list of cookies to be used for authenticating against Twitter.
+	 * @param guestToken - The guest token to be used to authenticate a guest session.
+	 */
+	public constructor(cookies?: Cookie[], guestToken?: string) {
+		this.authToken =
+			'AAAAAAAAAAAAAAAAAAAAANRILgAAAAAAnNwIzUejRCOuH5E6I8xnZz4puTs%3D1Zv7ttfk8LF81IUq16cHjhLTvJu4FA33AGWWjCpTnA';
+		// If guest credentials given
+		if (!cookies && guestToken) {
+			this.guestToken = guestToken;
+			this.authenticationType = EAuthenticationType.GUEST;
+		}
+		// If login credentials given
+		else if (cookies && guestToken) {
+			// Parsing the cookies
+			const parsedCookie: AuthCookie = new AuthCookie(cookies);
+
+			this.cookies = parsedCookie.toString();
+			this.guestToken = guestToken;
+			this.authenticationType = EAuthenticationType.LOGIN;
+		}
+		// If user credentials given
+		else if (cookies && !guestToken) {
+			// Parsing the cookies
+			const parsedCookie: AuthCookie = new AuthCookie(cookies);
+
+			this.cookies = parsedCookie.toString();
+			this.csrfToken = parsedCookie.ct0;
+			this.authenticationType = EAuthenticationType.USER;
+		}
+	}
+
+	/**
+	 * @returns The HTTP header representation of 'this' object.
+	 */
+	public toHeader(): AxiosRequestHeaders {
+		const headers = new AxiosHeaders();
+
+		/**
+		 * Conditionally initializing only those data which are supplied.
+		 *
+		 * This is done to ensure that the data that is not supplied, is not included in output, not even undefined.
+		 */
+		if (this.authToken) {
+			headers.set('authorization', `Bearer ${this.authToken}`);
+		}
+		if (this.guestToken) {
+			headers.set('x-guest-token', this.guestToken);
+		}
+		if (this.csrfToken) {
+			headers.set('x-csrf-token', this.csrfToken);
+		}
+		if (this.cookies) {
+			headers.set('cookie', this.cookies);
+		}
+
+		return headers;
+	}
+}

package/src/models/data/CursoredData.ts

@@ -1,9 +1,11 @@
-import { ICursor } from 'rettiwt-core';
+import { ICursor as IRawCursor } from 'rettiwt-core';
 
 import { EBaseType } from '../../enums/Data';
 
 import { findByFilter } from '../../helper/JsonUtils';
 
+import { ICursor, ICursoredData } from '../../types/data/CursoredData';
+
 import { Notification } from './Notification';
 import { Tweet } from './Tweet';
 import { User } from './User';
@@ -15,11 +17,8 @@ import { User } from './User';
  *
  * @public
  */
-export class CursoredData<T extends Notification | Tweet | User> {
-	/** The batch of data of the given type. */
+export class CursoredData<T extends Notification | Tweet | User> implements ICursoredData<T> {
 	public list: T[] = [];
-
-	/** The cursor to the next batch of data. */
 	public next: Cursor = new Cursor('');
 
 	/**
@@ -27,15 +26,19 @@ export class CursoredData<T extends Notification | Tweet | User> {
 	 * @param type - The base type of the data included in the batch.
 	 */
 	public constructor(response: NonNullable<unknown>, type: EBaseType) {
+		// Initializing defaults
+		this.list = [];
+		this.next = new Cursor('');
+
 		if (type == EBaseType.TWEET) {
 			this.list = Tweet.list(response) as T[];
-			this.next = new Cursor(findByFilter<ICursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '');
+			this.next = new Cursor(findByFilter<IRawCursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '');
 		} else if (type == EBaseType.USER) {
 			this.list = User.list(response) as T[];
-			this.next = new Cursor(findByFilter<ICursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '');
+			this.next = new Cursor(findByFilter<IRawCursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '');
 		} else if (type == EBaseType.NOTIFICATION) {
 			this.list = Notification.list(response) as T[];
-			this.next = new Cursor(findByFilter<ICursor>(response, 'cursorType', 'Top')[0]?.value ?? '');
+			this.next = new Cursor(findByFilter<IRawCursor>(response, 'cursorType', 'Top')[0]?.value ?? '');
 		}
 	}
 }
@@ -45,7 +48,7 @@ export class CursoredData<T extends Notification | Tweet | User> {
  *
  * @public
  */
-export class Cursor {
+export class Cursor implements ICursor {
 	/** The cursor string. */
 	public value: string;
 

package/src/models/data/List.ts

@@ -1,30 +1,19 @@
 import { IList as IRawList } from 'rettiwt-core';
 
+import { IList } from '../../types/data/List';
+
 /**
  * The details of a single Twitter List.
  *
  * @public
  */
-export class List {
-	/** The date and time of creation of the list, int UTC string format. */
+export class List implements IList {
 	public createdAt: string;
-
-	/** The rest id of the user who created the list. */
 	public createdBy: string;
-
-	/** The list description. */
 	public description?: string;
-
-	/** The rest id of the list. */
 	public id: string;
-
-	/** The number of memeber of the list. */
 	public memberCount: number;
-
-	/** The name of the list. */
 	public name: string;
-
-	/** The number of subscribers of the list. */
 	public subscriberCount: number;
 
 	/**

package/src/models/data/Notification.ts

@@ -1,52 +1,30 @@
 import {
 	ENotificationType as ENotificationTypeOriginal,
-	INotification,
+	INotification as IRawNotification,
 	IUserNotificationsResponse,
 } from 'rettiwt-core';
 
+import { ENotificationType } from '../../enums/Data';
 import { findKeyByValue } from '../../helper/JsonUtils';
-
-/**
- * The different types of notifications.
- *
- * @public
- */
-export enum ENotificationType {
-	RECOMMENDATION = 'RECOMMENDATION',
-	INFORMATION = 'INFORMATION',
-	LIVE = 'LIVE',
-	ALERT = 'ALERT',
-	UNDEFINED = 'UNDEFINED',
-}
+import { INotification } from '../../types/data/Notification';
 
 /**
  * The details of a single notification.
  *
  * @public
  */
-export class Notification {
-	/** The list of id of the users from whom the notification was received. */
+export class Notification implements INotification {
 	public from: string[];
-
-	/** The id of the notification. */
 	public id: string;
-
-	/** The text contents of the notification. */
 	public message: string;
-
-	/** The date/time at which the notification was received. */
 	public receivedAt: Date;
-
-	/** The list of id of the target tweet(s) of the notification. */
 	public target: string[];
-
-	/** The type of notification. */
 	public type?: ENotificationType;
 
 	/**
 	 * @param notification - The raw notification details.
 	 */
-	public constructor(notification: INotification) {
+	public constructor(notification: IRawNotification) {
 		// Getting the original notification type
 		const notificationType: string | undefined = findKeyByValue(ENotificationTypeOriginal, notification.icon.id);
 
@@ -82,7 +60,7 @@ export class Notification {
 			for (const [, value] of Object.entries(
 				(response as IUserNotificationsResponse).globalObjects.notifications,
 			)) {
-				notifications.push(new Notification(value as INotification));
+				notifications.push(new Notification(value as IRawNotification));
 			}
 		}