rettiwt-api 2.7.1 → 3.0.0

package/src/models/args/PostArgs.ts

@@ -0,0 +1,263 @@
+import {
+	ArrayMaxSize,
+	IsArray,
+	IsNotEmpty,
+	IsNumberString,
+	IsObject,
+	IsOptional,
+	IsString,
+	Max,
+	MaxLength,
+	validateSync,
+} from 'class-validator';
+
+import { NewTweet, NewTweetMedia } from 'rettiwt-core';
+
+import { EResourceType } from '../../enums/Resource';
+import { DataValidationError } from '../errors/DataValidationError';
+
+/**
+ * Options specifying the data that is to be posted.
+ *
+ * @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}
+	 */
+	@IsOptional()
+	@IsNotEmpty({
+		groups: [
+			EResourceType.TWEET_LIKE,
+			EResourceType.TWEET_RETWEET,
+			EResourceType.TWEET_UNLIKE,
+			EResourceType.TWEET_UNPOST,
+			EResourceType.TWEET_UNRETWEET,
+			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.USER_FOLLOW,
+			EResourceType.USER_UNFOLLOW,
+		],
+	})
+	public id?: string;
+
+	/**
+	 * The tweet that is to be posted.
+	 *
+	 * @remarks
+	 * Required only when posting a tweet using {@link EResourceType.TWEET_POST}
+	 */
+	@IsOptional()
+	@IsNotEmpty({ groups: [EResourceType.TWEET_POST] })
+	@IsObject({ groups: [EResourceType.TWEET_POST] })
+	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}
+	 */
+	@IsOptional()
+	@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.
+	 */
+	public constructor(resource: EResourceType, args: PostArgs) {
+		this.id = args.id;
+		this.tweet = args.tweet ? new TweetArgs(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()
+	@IsArray()
+	@ArrayMaxSize(4)
+	@IsObject({ each: true })
+	public media?: TweetMediaArgs[];
+
+	/** The id of the tweet to quote. */
+	@IsOptional()
+	@IsNumberString()
+	public quote?: string;
+
+	/** The id of the tweet to which the given tweet must be a reply. */
+	@IsOptional()
+	@IsNumberString()
+	public replyTo?: string;
+
+	/**
+	 * The text for the tweet to be created.
+	 *
+	 * @remarks
+	 * Length of the tweet must be \<= 280 characters.
+	 */
+	@IsNotEmpty()
+	@IsString()
+	@MaxLength(280)
+	public text: string;
+
+	/**
+	 * @param args - Arguments specifying the tweet to be posted.
+	 */
+	public constructor(args: TweetArgs) {
+		super();
+		this.text = args.text;
+		this.quote = args.quote;
+		this.media = args.media ? args.media.map((item) => new TweetMediaArgs(item)) : undefined;
+		this.replyTo = args.replyTo;
+
+		// Validating this object
+		const validationResult = validateSync(this);
+
+		// If valiation error occured
+		if (validationResult.length) {
+			throw new DataValidationError(validationResult);
+		}
+	}
+}
+
+/**
+ * Options specifying the media 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. */
+	@IsOptional()
+	@IsNotEmpty({ groups: [EResourceType.MEDIA_UPLOAD_APPEND, EResourceType.MEDIA_UPLOAD_FINALIZE] })
+	@IsNumberString(undefined, { groups: [EResourceType.MEDIA_UPLOAD_APPEND, EResourceType.MEDIA_UPLOAD_FINALIZE] })
+	public id?: string;
+
+	/** The media file to be uploaded. */
+	@IsOptional()
+	@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.
+	 */
+	@IsOptional()
+	@IsNotEmpty({ groups: [EResourceType.MEDIA_UPLOAD_INITIALIZE] })
+	@Max(5242880, { groups: [EResourceType.MEDIA_UPLOAD_INITIALIZE] })
+	public size?: number;
+
+	/**
+	 * @param step - The upload step.
+	 * @param args - The upload arguments for uploading the media file.
+	 */
+	public constructor(step: EResourceType, args: UploadArgs) {
+		this.size = args.size;
+		this.media = args.media;
+		this.id = args.id;
+
+		// Validating this object
+		const validationResult = validateSync(this, { groups: [step] });
+
+		// If validation error occured
+		if (validationResult.length) {
+			throw new DataValidationError(validationResult);
+		}
+	}
+}

package/src/models/data/CursoredData.ts

@@ -1,33 +1,43 @@
-// MODELS
+import { ICursor, IResponse } from 'rettiwt-core';
+
+import { EBaseType } from '../../enums/Data';
+
+import { findByFilter } from '../../helper/JsonUtils';
+
 import { Tweet } from './Tweet';
 import { User } from './User';
 
 /**
- * The data that us fetched batch-wise along with a cursor.
+ * The data that is fetched batch-wise using a cursor.
  *
- * @typeParam T - Type of data to be stored in the list.
+ * @typeParam T - Type of data to be stored.
  *
  * @public
  */
 export class CursoredData<T extends Tweet | User> {
-	/** The list of data of the given type. */
+	/** The batch of data of the given type. */
 	public list: T[] = [];
 
 	/** The cursor to the next batch of data. */
 	public next: Cursor;
 
 	/**
-	 * @param list - The list of data item to store.
-	 * @param next - The cursor to the next batch of data.
+	 * @param response - The raw response.
+	 * @param type - The base type of the data included in the batch.
 	 */
-	public constructor(list: T[] = [], next: string = '') {
-		this.list = list;
-		this.next = new Cursor(next);
+	public constructor(response: IResponse<unknown>, type: EBaseType) {
+		if (type == EBaseType.TWEET) {
+			this.list = Tweet.list(response) as T[];
+		} else {
+			this.list = User.list(response) as T[];
+		}
+
+		this.next = new Cursor(findByFilter<ICursor>(response, 'cursorType', 'Bottom')[0].value);
 	}
 }
 
 /**
- * The cursor to the batch of data to be fetched.
+ * The cursor to the batch of data to fetch.
  *
  * @public
  */
@@ -36,11 +46,9 @@ export class Cursor {
 	public value: string;
 
 	/**
-	 * Initializes a new cursor from the given cursor string.
-	 *
-	 * @param cursorStr - The string representation of the cursor.
+	 * @param cursor - The cursor string.
 	 */
-	public constructor(cursorStr: string) {
-		this.value = cursorStr;
+	public constructor(cursor: string) {
+		this.value = cursor;
 	}
 }

package/src/models/data/List.ts

@@ -1,4 +1,3 @@
-// PACKAGES
 import { IList as IRawList } from 'rettiwt-core';
 
 /**
@@ -7,37 +6,35 @@ import { IList as IRawList } from 'rettiwt-core';
  * @public
  */
 export class List {
-	/** The rest id of the list. */
-	public id: string;
-
-	/** The name of the list. */
-	public name: string;
-
 	/** The date and time of creation of the list, int UTC string format. */
 	public createdAt: string;
 
+	/** The rest id of the user who created the list. */
+	public createdBy: string;
+
 	/** The list description. */
-	public description: string;
+	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;
 
-	/** The rest id of the user who created the list. */
-	public createdBy: string;
-
 	/**
-	 * Initializes a new Tweet List from the given raw list data.
-	 *
-	 * @param list - list The raw tweet list data.
+	 * @param list - The raw list details.
 	 */
 	public constructor(list: IRawList) {
 		this.id = list.id_str;
 		this.name = list.name;
 		this.createdAt = new Date(list.created_at).toISOString();
-		this.description = list.description;
+		this.description = list.description.length ? list.description : undefined;
 		this.memberCount = list.member_count;
 		this.subscriberCount = list.subscriber_count;
 		this.createdBy = list.user_results.result.id;

package/src/models/data/Tweet.ts

@@ -1,25 +1,28 @@
-// PACKAGES
 import {
+	EMediaType,
+	IExtendedMedia as IRawExtendedMedia,
 	ITweet as IRawTweet,
 	IEntities as IRawTweetEntities,
-	IExtendedMedia as IRawExtendedMedia,
-	EMediaType,
+	IResponse,
+	ITimelineTweet,
+	ITweet,
 } from 'rettiwt-core';
 
-// MODELS
+import { ELogActions } from '../../enums/Logging';
+import { findByFilter } from '../../helper/JsonUtils';
+
+import { LogService } from '../../services/internal/LogService';
+
 import { User } from './User';
 
 /**
- * The details of a single Tweet.
+ * The details of a single tweet.
  *
  * @public
  */
 export class Tweet {
-	/** The rest id of the tweet. */
-	public id: string;
-
-	/** The details of the user who made the tweet. */
-	public tweetBy: User;
+	/** The number of bookmarks of a tweet. */
+	public bookmarkCount: number;
 
 	/** The date and time of creation of the tweet, in UTC string format. */
 	public createdAt: string;
@@ -27,46 +30,47 @@ export class Tweet {
 	/** Additional tweet entities like urls, mentions, etc. */
 	public entities: TweetEntities;
 
-	/** The urls of the media contents of the tweet (if any). */
-	public media: TweetMedia[];
-
-	/** The rest id of the tweet which is quoted in the tweet. */
-	public quoted: string;
-
 	/** The full text content of the tweet. */
 	public fullText: string;
 
-	/** The rest id of the tweet to which the tweet is a reply. */
-	public replyTo: string;
+	/** The rest id of the tweet. */
+	public id: string;
 
 	/** The language in which the tweet is written. */
 	public lang: string;
 
+	/** The number of likes of the tweet. */
+	public likeCount: number;
+
+	/** The urls of the media contents of the tweet (if any). */
+	public media?: TweetMedia[];
+
 	/** The number of quotes of the tweet. */
 	public quoteCount: number;
 
+	/** The rest id of the tweet which is quoted in the tweet. */
+	public quoted?: string;
+
 	/** The number of replies to the tweet. */
 	public replyCount: number;
 
+	/** The rest id of the tweet to which the tweet is a reply. */
+	public replyTo?: string;
+
 	/** The number of retweets of the tweet. */
 	public retweetCount: number;
 
-	/** The number of likes of the tweet. */
-	public likeCount: number;
+	/** The tweet which was retweeted in this tweet (if any). */
+	public retweetedTweet?: Tweet;
+
+	/** The details of the user who made the tweet. */
+	public tweetBy: User;
 
 	/** The number of views of a tweet. */
 	public viewCount: number;
 
-	/** The number of bookmarks of a tweet. */
-	public bookmarkCount: number;
-
-	/** The tweet which was retweeted in this tweet (if any). */
-	public retweetedTweet?: Tweet;
-
 	/**
-	 * Initializes a new Tweet from the given raw tweet data.
-	 *
-	 * @param tweet - The raw tweet data.
+	 * @param tweet - The raw tweet details.
 	 */
 	public constructor(tweet: IRawTweet) {
 		this.id = tweet.rest_id;
@@ -82,12 +86,78 @@ export class Tweet {
 		this.replyCount = tweet.legacy.reply_count;
 		this.retweetCount = tweet.legacy.retweet_count;
 		this.likeCount = tweet.legacy.favorite_count;
-		this.viewCount = parseInt(tweet.views.count);
+		this.viewCount = tweet.views.count ? parseInt(tweet.views.count) : 0;
 		this.bookmarkCount = tweet.legacy.bookmark_count;
 		this.retweetedTweet = tweet.legacy.retweeted_status_result?.result?.rest_id
 			? new Tweet(tweet.legacy.retweeted_status_result.result)
 			: undefined;
 	}
+
+	/**
+	 * Extracts and deserializes the list of tweets from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @returns The deserialized list of tweets.
+	 *
+	 * @internal
+	 */
+	public static list(response: IResponse<unknown>): Tweet[] {
+		const tweets: Tweet[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<ITimelineTweet>(response, '__typename', 'TimelineTweet');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.tweet_results?.result?.legacy) {
+				// Logging
+				LogService.log(ELogActions.DESERIALIZE, { id: item.tweet_results.result.rest_id });
+
+				tweets.push(new Tweet(item.tweet_results.result));
+			} else {
+				// Logging
+				LogService.log(ELogActions.WARNING, {
+					action: ELogActions.DESERIALIZE,
+					message: `Tweet not found, skipping`,
+				});
+			}
+		}
+
+		return tweets;
+	}
+
+	/**
+	 * Extracts and deserializes a single target tweet from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 * @returns The target deserialized tweet.
+	 *
+	 * @internal
+	 */
+	public static single(response: IResponse<unknown>): Tweet | undefined {
+		const tweets: Tweet[] = [];
+
+		// Extracting the matching data
+		const extract = findByFilter<ITweet>(response, '__typename', 'Tweet');
+
+		// Deserializing valid data
+		for (const item of extract) {
+			if (item.legacy) {
+				// Logging
+				LogService.log(ELogActions.DESERIALIZE, { id: item.rest_id });
+
+				tweets.push(new Tweet(item));
+			} else {
+				// Logging
+				LogService.log(ELogActions.WARNING, {
+					action: ELogActions.DESERIALIZE,
+					message: `Tweet not found, skipping`,
+				});
+			}
+		}
+
+		return tweets.length ? tweets[0] : undefined;
+	}
 }
 
 /**
@@ -99,15 +169,13 @@ export class TweetEntities {
 	/** The list of hashtags mentioned in the tweet. */
 	public hashtags: string[] = [];
 
-	/** The list of urls mentioned in the tweet. */
-	public urls: string[] = [];
-
 	/** The list of IDs of users mentioned in the tweet. */
 	public mentionedUsers: string[] = [];
 
+	/** The list of urls mentioned in the tweet. */
+	public urls: string[] = [];
+
 	/**
-	 * Initializes the TweetEntities from the raw tweet entities.
-	 *
 	 * @param entities - The raw tweet entities.
 	 */
 	public constructor(entities: IRawTweetEntities) {
@@ -135,7 +203,7 @@ export class TweetEntities {
 }
 
 /**
- * A single media content.
+ * The details of a single media content included in a tweet.
  *
  * @public
  */
@@ -147,9 +215,7 @@ export class TweetMedia {
 	public url: string = '';
 
 	/**
-	 * Initializes the TweetMedia from the raw tweet media.
-	 *
-	 * @param media - The raw tweet media.
+	 * @param media - The raw media details.
 	 */
 	public constructor(media: IRawExtendedMedia) {
 		this.type = media.type;