rettiwt-api 3.1.1 → 4.1.0-alpha.0

package/src/models/args/PostArgs.ts

@@ -1,6 +1,8 @@
 import {
 	ArrayMaxSize,
 	IsArray,
+	IsDate,
+	IsEmpty,
 	IsNotEmpty,
 	IsNumberString,
 	IsObject,
@@ -8,6 +10,7 @@ import {
 	IsString,
 	Max,
 	MaxLength,
+	MinDate,
 	validateSync,
 } from 'class-validator';
 
@@ -35,7 +38,15 @@ export class PostArgs {
 	 * - {@link EResourceType.USER_FOLLOW}
 	 * - {@link EResourceType.USER_UNFOLLOW}
 	 */
-	@IsOptional()
+	@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,
@@ -43,6 +54,7 @@ export class PostArgs {
 			EResourceType.TWEET_UNLIKE,
 			EResourceType.TWEET_UNPOST,
 			EResourceType.TWEET_UNRETWEET,
+			EResourceType.TWEET_UNSCHEDULE,
 			EResourceType.USER_FOLLOW,
 			EResourceType.USER_UNFOLLOW,
 		],
@@ -54,6 +66,7 @@ export class PostArgs {
 			EResourceType.TWEET_UNLIKE,
 			EResourceType.TWEET_UNPOST,
 			EResourceType.TWEET_UNRETWEET,
+			EResourceType.TWEET_UNSCHEDULE,
 			EResourceType.USER_FOLLOW,
 			EResourceType.USER_UNFOLLOW,
 		],
@@ -66,9 +79,23 @@ export class PostArgs {
 	 * @remarks
 	 * Required only when posting a tweet using {@link EResourceType.TWEET_POST}
 	 */
-	@IsOptional()
-	@IsNotEmpty({ groups: [EResourceType.TWEET_POST] })
-	@IsObject({ groups: [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;
 
 	/**
@@ -80,7 +107,13 @@ export class PostArgs {
 	 * - {@link EResourceType.MEDIA_UPLOAD_FINALIZE}
 	 * - {@link EResourceType.MEDIA_UPLOAD_INITIALIZE}
 	 */
-	@IsOptional()
+	@IsEmpty({
+		groups: [
+			EResourceType.MEDIA_UPLOAD_APPEND,
+			EResourceType.MEDIA_UPLOAD_FINALIZE,
+			EResourceType.MEDIA_UPLOAD_INITIALIZE,
+		],
+	})
 	@IsNotEmpty({
 		groups: [
 			EResourceType.MEDIA_UPLOAD_INITIALIZE,
@@ -103,7 +136,7 @@ export class PostArgs {
 	 */
 	public constructor(resource: EResourceType, args: PostArgs) {
 		this.id = args.id;
-		this.tweet = args.tweet ? new TweetArgs(args.tweet) : undefined;
+		this.tweet = args.tweet ? new TweetArgs(resource, args.tweet) : undefined;
 		this.upload = args.upload ? new UploadArgs(resource, args.upload) : undefined;
 
 		// Validating this object
@@ -128,45 +161,53 @@ export class TweetArgs extends NewTweet {
 	 * @remarks
 	 * Maximum number of media items that can be posted is 4.
 	 */
-	@IsOptional()
-	@IsArray()
-	@ArrayMaxSize(4)
-	@IsObject({ each: true })
+	@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()
-	@IsNumberString()
+	@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()
-	@IsNumberString()
+	@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()
-	@IsString()
-	@MaxLength(280)
+	@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(args: TweetArgs) {
+	public constructor(resource: EResourceType, args: TweetArgs) {
 		super();
-		this.text = args.text;
-		this.quote = args.quote;
 		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);
+		const validationResult = validateSync(this, { groups: [resource] });
 
 		// If valiation error occured
 		if (validationResult.length) {
@@ -223,13 +264,13 @@ export class TweetMediaArgs extends NewTweetMedia {
  */
 export class UploadArgs {
 	/** The id allocated to the media file to be uploaded. */
-	@IsOptional()
+	@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] })
 	public id?: string;
 
 	/** The media file to be uploaded. */
-	@IsOptional()
+	@IsEmpty({ groups: [EResourceType.MEDIA_UPLOAD_FINALIZE, EResourceType.MEDIA_UPLOAD_INITIALIZE] })
 	@IsNotEmpty({ groups: [EResourceType.MEDIA_UPLOAD_APPEND] })
 	public media?: string | ArrayBuffer;
 
@@ -238,7 +279,7 @@ export class UploadArgs {
 	 *
 	 * @remarks The size must be \<= 5242880 bytes.
 	 */
-	@IsOptional()
+	@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;

package/src/models/data/CursoredData.ts

@@ -1,9 +1,10 @@
-import { ICursor, IResponse } from 'rettiwt-core';
+import { ICursor } from 'rettiwt-core';
 
 import { EBaseType } from '../../enums/Data';
 
 import { findByFilter } from '../../helper/JsonUtils';
 
+import { Notification } from './Notification';
 import { Tweet } from './Tweet';
 import { User } from './User';
 
@@ -14,7 +15,7 @@ import { User } from './User';
  *
  * @public
  */
-export class CursoredData<T extends Tweet | User> {
+export class CursoredData<T extends Notification | Tweet | User> {
 	/** The batch of data of the given type. */
 	public list: T[] = [];
 
@@ -25,11 +26,13 @@ export class CursoredData<T extends Tweet | User> {
 	 * @param response - The raw response.
 	 * @param type - The base type of the data included in the batch.
 	 */
-	public constructor(response: IResponse<unknown>, type: EBaseType) {
+	public constructor(response: NonNullable<unknown>, type: EBaseType) {
 		if (type == EBaseType.TWEET) {
 			this.list = Tweet.list(response) as T[];
-		} else {
+		} else if (type == EBaseType.USER) {
 			this.list = User.list(response) as T[];
+		} else if (type == EBaseType.NOTIFICATION) {
+			this.list = Notification.list(response) as T[];
 		}
 
 		this.next = new Cursor(findByFilter<ICursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '');

package/src/models/data/Notification.ts

@@ -0,0 +1,91 @@
+import {
+	ENotificationType as ENotificationTypeOriginal,
+	INotification,
+	IUserNotifications as IUserNotificationsResponse,
+} from 'rettiwt-core';
+
+import { findKeyByValue } from '../../helper/JsonUtils';
+
+/**
+ * The different types of notifications.
+ *
+ * @public
+ */
+export enum ENotificationType {
+	RECOMMENDATION = 'RECOMMENDATION',
+	INFORMATION = 'INFORMATION',
+	LIVE = 'LIVE',
+	ALERT = 'ALERT',
+	UNDEFINED = 'UNDEFINED',
+}
+
+/**
+ * The details of a single notification.
+ *
+ * @public
+ */
+export class Notification {
+	/** The list of id of the users from whom the notification was received. */
+	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) {
+		// Getting the original notification type
+		const notificationType: string | undefined = findKeyByValue(ENotificationTypeOriginal, notification.icon.id);
+
+		this.from = notification.template?.aggregateUserActionsV1?.fromUsers
+			? notification.template.aggregateUserActionsV1.fromUsers.map((item) => item.user.id)
+			: [];
+		this.id = notification.id;
+		this.message = notification.message.text;
+		this.receivedAt = new Date(Number(notification.timestampMs));
+		this.target = notification.template?.aggregateUserActionsV1?.targetObjects
+			? notification.template.aggregateUserActionsV1.targetObjects.map((item) => item.tweet.id)
+			: [];
+		this.type = notificationType
+			? ENotificationType[notificationType as keyof typeof ENotificationType]
+			: ENotificationType.UNDEFINED;
+	}
+
+	/**
+	 * Extracts and deserializes the list of notifications from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized list of notifications.
+	 *
+	 * @internal
+	 */
+	public static list(response: NonNullable<unknown>): Notification[] {
+		const notifications: Notification[] = [];
+
+		// Extracting notifications
+		if ((response as IUserNotificationsResponse).globalObjects.notifications) {
+			// Iterating over the raw list of notifications
+			for (const [, value] of Object.entries(
+				(response as IUserNotificationsResponse).globalObjects.notifications,
+			)) {
+				notifications.push(new Notification(value as INotification));
+			}
+		}
+
+		return notifications;
+	}
+}

package/src/models/data/Tweet.ts

@@ -3,7 +3,6 @@ import {
 	IExtendedMedia as IRawExtendedMedia,
 	ITweet as IRawTweet,
 	IEntities as IRawTweetEntities,
-	IResponse,
 	ITimelineTweet,
 	ITweet,
 } from 'rettiwt-core';
@@ -48,8 +47,8 @@ export class Tweet {
 	/** 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 tweet which is quoted in the tweet. */
+	public quoted?: Tweet;
 
 	/** The number of replies to the tweet. */
 	public replyCount: number;
@@ -60,7 +59,7 @@ export class Tweet {
 	/** The number of retweets of the tweet. */
 	public retweetCount: number;
 
-	/** The tweet which was retweeted in this tweet (if any). */
+	/** The tweet which is retweeted in this tweet (if any). */
 	public retweetedTweet?: Tweet;
 
 	/** The details of the user who made the tweet. */
@@ -78,7 +77,7 @@ export class Tweet {
 		this.tweetBy = new User(tweet.core.user_results.result);
 		this.entities = new TweetEntities(tweet.legacy.entities);
 		this.media = tweet.legacy.extended_entities?.media?.map((media) => new TweetMedia(media));
-		this.quoted = tweet.legacy.quoted_status_id_str;
+		this.quoted = tweet.quoted_status_result ? new Tweet(tweet.quoted_status_result.result) : undefined;
 		this.fullText = tweet.note_tweet ? tweet.note_tweet.note_tweet_results.result.text : tweet.legacy.full_text;
 		this.replyTo = tweet.legacy.in_reply_to_status_id_str;
 		this.lang = tweet.legacy.lang;
@@ -102,7 +101,7 @@ export class Tweet {
 	 *
 	 * @internal
 	 */
-	public static list(response: IResponse<unknown>): Tweet[] {
+	public static list(response: NonNullable<unknown>): Tweet[] {
 		const tweets: Tweet[] = [];
 
 		// Extracting the matching data
@@ -137,7 +136,7 @@ export class Tweet {
 	 *
 	 * @internal
 	 */
-	public static single(response: IResponse<unknown>, id: string): Tweet | undefined {
+	public static single(response: NonNullable<unknown>, id: string): Tweet | undefined {
 		const tweets: Tweet[] = [];
 
 		// Extracting the matching data

package/src/models/data/User.ts

@@ -1,4 +1,4 @@
-import { IUser as IRawUser, IResponse, ITimelineUser, IUser } from 'rettiwt-core';
+import { IUser as IRawUser, ITimelineUser, IUser } from 'rettiwt-core';
 
 import { ELogActions } from '../../enums/Logging';
 import { findByFilter } from '../../helper/JsonUtils';
@@ -81,7 +81,7 @@ export class User {
 	 *
 	 * @internal
 	 */
-	public static list(response: IResponse<unknown>): User[] {
+	public static list(response: NonNullable<unknown>): User[] {
 		const users: User[] = [];
 
 		// Extracting the matching data
@@ -115,7 +115,7 @@ export class User {
 	 *
 	 * @internal
 	 */
-	public static single(response: IResponse<unknown>): User | undefined {
+	public static single(response: NonNullable<unknown>): User | undefined {
 		const users: User[] = [];
 
 		// Extracting the matching data

package/src/services/public/AuthService.ts

@@ -1,5 +1,6 @@
 import { Auth } from 'rettiwt-auth';
 
+import { EApiErrors } from '../../enums/Api';
 import { IRettiwtConfig } from '../../types/RettiwtConfig';
 
 import { FetcherService } from './FetcherService';
@@ -19,6 +20,55 @@ export class AuthService extends FetcherService {
 		super(config);
 	}
 
+	/**
+	 * Decodes the encoded cookie string.
+	 *
+	 * @param encodedCookies - The encoded cookie string to decode.
+	 * @returns The decoded cookie string.
+	 */
+	public static decodeCookie(encodedCookies: string): string {
+		// Decoding the encoded cookie string
+		const decodedCookies: string = Buffer.from(encodedCookies, 'base64').toString('ascii');
+
+		return decodedCookies;
+	}
+
+	/**
+	 * Encodes the given cookie string.
+	 *
+	 * @param cookieString - The cookie string to encode.
+	 * @returns The encoded cookie string.
+	 */
+	public static encodeCookie(cookieString: string): string {
+		// Encoding the cookie string to base64
+		const encodedCookies: string = Buffer.from(cookieString).toString('base64');
+
+		return encodedCookies;
+	}
+
+	/**
+	 * Gets the user's id from the given API key.
+	 *
+	 * @param apiKey - The API key.
+	 * @returns The user id associated with the API key.
+	 */
+	public static getUserId(apiKey: string): string {
+		// Getting the cookie string from the API key
+		const cookieString: string = AuthService.decodeCookie(apiKey);
+
+		// Searching for the user id in the cookie string
+		const searchResults: string[] | null = cookieString.match(/((?<=twid="u=)(.*)(?="))|((?<=twid=u%3D)(.*)(?=;))/);
+
+		// If user id was found
+		if (searchResults) {
+			return searchResults[0];
+		}
+		// If user id was not found
+		else {
+			throw new Error(EApiErrors.BAD_AUTHENTICATION);
+		}
+	}
+
 	/**
 	 * Login to twitter as guest.
 	 *
@@ -91,7 +141,7 @@ export class AuthService extends FetcherService {
 			).toHeader().cookie as string) ?? '';
 
 		// Converting the credentials to base64 string
-		apiKey = Buffer.from(apiKey).toString('base64');
+		apiKey = AuthService.encodeCookie(apiKey);
 
 		return apiKey;
 	}

package/src/services/public/FetcherService.ts

@@ -17,6 +17,8 @@ import { IRettiwtConfig } from '../../types/RettiwtConfig';
 import { ErrorService } from '../internal/ErrorService';
 import { LogService } from '../internal/LogService';
 
+import { AuthService } from './AuthService';
+
 /**
  * The base service that handles all HTTP requests.
  *
@@ -32,9 +34,6 @@ export class FetcherService {
 	/** The guest key to use for authenticating against Twitter API as guest. */
 	private readonly guestKey?: string;
 
-	/** Whether the instance is authenticated or not. */
-	private readonly isAuthenticated: boolean;
-
 	/** The URL To the proxy server to use for all others. */
 	private readonly proxyUrl?: URL;
 
@@ -44,6 +43,9 @@ export class FetcherService {
 	/** The URL to the proxy server to use only for authentication. */
 	protected readonly authProxyUrl?: URL;
 
+	/** The id of the authenticated user (if any). */
+	protected readonly userId?: string;
+
 	/**
 	 * @param config - The config object for configuring the Rettiwt instance.
 	 */
@@ -51,7 +53,7 @@ export class FetcherService {
 		LogService.enabled = config?.logging ?? false;
 		this.apiKey = config?.apiKey;
 		this.guestKey = config?.guestKey;
-		this.isAuthenticated = config?.apiKey ? true : false;
+		this.userId = config?.apiKey ? AuthService.getUserId(config.apiKey) : undefined;
 		this.authProxyUrl = config?.authProxyUrl ?? config?.proxyUrl;
 		this.proxyUrl = config?.proxyUrl;
 		this.timeout = config?.timeout ?? 0;
@@ -67,10 +69,10 @@ export class FetcherService {
 	 */
 	private checkAuthorization(resource: EResourceType): void {
 		// Logging
-		LogService.log(ELogActions.AUTHORIZATION, { authenticated: this.isAuthenticated });
+		LogService.log(ELogActions.AUTHORIZATION, { authenticated: this.userId != undefined });
 
 		// Checking authorization status
-		if (!allowGuestAuthentication.includes(resource) && this.isAuthenticated == false) {
+		if (!allowGuestAuthentication.includes(resource) && this.userId == undefined) {
 			throw new Error(EApiErrors.RESOURCE_NOT_ALLOWED);
 		}
 	}
@@ -85,8 +87,7 @@ export class FetcherService {
 			// Logging
 			LogService.log(ELogActions.GET, { target: 'USER_CREDENTIAL' });
 
-			const cookies = Buffer.from(this.apiKey, 'base64').toString('ascii').split(';');
-			return new AuthCredential(cookies);
+			return new AuthCredential(AuthService.decodeCookie(this.apiKey).split(';'));
 		} else if (this.guestKey) {
 			// Logging
 			LogService.log(ELogActions.GET, { target: 'GUEST_CREDENTIAL' });