rettiwt-api 2.7.0 → 3.0.0

package/src/services/public/UserService.ts

@@ -1,21 +1,27 @@
-// PACKAGES
-import { EResourceType } from 'rettiwt-core';
+import {
+	IUserDetailsResponse,
+	IUserFollowersResponse,
+	IUserFollowingResponse,
+	IUserFollowResponse,
+	IUserHighlightsResponse,
+	IUserLikesResponse,
+	IUserMediaResponse,
+	IUserSubscriptionsResponse,
+	IUserTweetsAndRepliesResponse,
+	IUserTweetsResponse,
+	IUserUnfollowResponse,
+} from 'rettiwt-core';
 
-// SERVICES
-import { FetcherService } from '../internal/FetcherService';
-
-// TYPES
-import { IRettiwtConfig } from '../../types/RettiwtConfig';
-
-// MODELS
-import { User } from '../../models/data/User';
+import { EResourceType } from '../../enums/Resource';
+import { CursoredData } from '../../models/data/CursoredData';
 import { Tweet } from '../../models/data/Tweet';
+import { User } from '../../models/data/User';
+import { IRettiwtConfig } from '../../types/RettiwtConfig';
 
-// TYPES
-import { CursoredData } from '../../models/data/CursoredData';
+import { FetcherService } from './FetcherService';
 
 /**
- * Handles fetching of data related to user account
+ * Handles interacting with resources related to user account
  *
  * @public
  */
@@ -33,9 +39,13 @@ export class UserService extends FetcherService {
 	 * Get the details of a user.
 	 *
 	 * @param id - The username/id of the target user.
-	 * @returns The details of the given user.
 	 *
-	 * @example Fetching the details of the Twitter user with username 'user1'
+	 * @returns
+	 * The details of the given user.
+	 * If no user matches the given id, returns `undefined`.
+	 *
+	 * @example
+	 * Fetching the details using username
 	 * ```
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
@@ -52,15 +62,16 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 *
-	 * @example Fetching the details of the Twitter user with id '12345678'
+	 * @example
+	 * Fetching the details using id
 	 * ```
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
 	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
 	 *
-	 * // Fetching the details of the User with id '12345678'
-	 * rettiwt.user.details('12345678')
+	 * // Fetching the details of the User with id '1234567890'
+	 * rettiwt.user.details('1234567890')
 	 * .then(res => {
 	 * 	console.log(res);
 	 * })
@@ -68,32 +79,113 @@ export class UserService extends FetcherService {
 	 * 	console.log(err);
 	 * });
 	 * ```
-	 *
-	 * @public
 	 */
-	public async details(id: string): Promise<User> {
-		let data: CursoredData<User>;
+	public async details(id: string): Promise<User | undefined> {
+		let resource: EResourceType;
 
 		// If username is given
 		if (isNaN(Number(id))) {
-			// Fetching the requested data
-			data = await this.fetch<User>(EResourceType.USER_DETAILS, { id: id });
+			resource = EResourceType.USER_DETAILS_BY_USERNAME;
 		}
 		// If id is given
 		else {
-			// Fetching the requested data
-			data = await this.fetch<User>(EResourceType.USER_DETAILS_BY_ID, { id: id });
+			resource = EResourceType.USER_DETAILS_BY_ID;
 		}
 
-		return data.list[0];
+		// Fetching raw details
+		const response = await this.request<IUserDetailsResponse>(resource, { id: id });
+
+		// Deserializing response
+		const data = this.extract<User>(response, resource);
+
+		return data;
+	}
+
+	/**
+	 * Follow a user.
+	 *
+	 * @param id - The id the user to be followed.
+	 *
+	 * @returns Whether following was successful or not.
+	 *
+	 * @throws Code 108 if given user id is invalid.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Following the User with id '1234567890'
+	 * rettiwt.user.follow('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async follow(id: string): Promise<boolean> {
+		// Following the user
+		const response = await this.request<IUserFollowResponse>(EResourceType.USER_FOLLOW, { id: id });
+
+		// Deserializing the response
+		const data = this.extract<boolean>(response, EResourceType.USER_FOLLOW) ?? false;
+
+		return data;
+	}
+
+	/**
+	 * Get the list followers of a user.
+	 *
+	 * @param id - The id of the target user.
+	 * @param count - The number of followers to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of followers to fetch.
+	 *
+	 * @returns The list of users following the target user.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 100 followers of the User with id '1234567890'
+	 * rettiwt.user.followers('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async followers(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		const resource = EResourceType.USER_FOLLOWERS;
+
+		// Fetching raw list of followers
+		const response = await this.request<IUserFollowersResponse>(resource, {
+			id: id,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = this.extract<CursoredData<User>>(response, resource)!;
+
+		return data;
 	}
 
 	/**
-	 * Get the list of users who are followed by the given user.
+	 * Get the list of users who are followed by a user.
 	 *
-	 * @param userId - The rest id of the target user.
+	 * @param id - The id of the target user.
 	 * @param count - The number of following to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of following to fetch.
+	 *
 	 * @returns The list of users followed by the target user.
 	 *
 	 * @example
@@ -103,8 +195,8 @@ export class UserService extends FetcherService {
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
 	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
 	 *
-	 * // Fetching the first 100 following of the User with id '12345678'
-	 * rettiwt.user.following('12345678')
+	 * // Fetching the first 100 following of the User with id '1234567890'
+	 * rettiwt.user.following('1234567890')
 	 * .then(res => {
 	 * 	console.log(res);
 	 * })
@@ -112,27 +204,31 @@ export class UserService extends FetcherService {
 	 * 	console.log(err);
 	 * });
 	 * ```
-	 *
-	 * @public
 	 */
-	public async following(userId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
-		// Fetching the requested data
-		const data = await this.fetch<User>(EResourceType.USER_FOLLOWING, {
-			id: userId,
+	public async following(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		const resource = EResourceType.USER_FOLLOWING;
+
+		// Fetching raw list of following
+		const response = await this.request<IUserFollowingResponse>(resource, {
+			id: id,
 			count: count,
 			cursor: cursor,
 		});
 
+		// Deserializing response
+		const data = this.extract<CursoredData<User>>(response, resource)!;
+
 		return data;
 	}
 
 	/**
-	 * Get the list followers of a given user.
+	 * Get the highlighted tweets of a user.
 	 *
-	 * @param userId - The rest id of the target user.
+	 * @param id - The id of the target user.
 	 * @param count - The number of followers to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of followers to fetch.
-	 * @returns The list of users following the target user.
+	 *
+	 * @returns The list of highlighted tweets of the target user.
 	 *
 	 * @example
 	 * ```
@@ -141,8 +237,8 @@ export class UserService extends FetcherService {
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
 	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
 	 *
-	 * // Fetching the first 100 followers of the User with id '12345678'
-	 * rettiwt.user.followers('12345678')
+	 * // Fetching the top 100 highlights of the User with id '1234567890'
+	 * rettiwt.user.highlights('1234567890')
 	 * .then(res => {
 	 * 	console.log(res);
 	 * })
@@ -150,26 +246,30 @@ export class UserService extends FetcherService {
 	 * 	console.log(err);
 	 * });
 	 * ```
-	 *
-	 * @public
 	 */
-	public async followers(userId: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
-		// Fetching the requested data
-		const data = await this.fetch<User>(EResourceType.USER_FOLLOWERS, {
-			id: userId,
+	public async highlights(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		const resource = EResourceType.USER_HIGHLIGHTS;
+
+		// Fetching raw list of highlights
+		const response = await this.request<IUserHighlightsResponse>(resource, {
+			id: id,
 			count: count,
 			cursor: cursor,
 		});
 
+		// Deserializing response
+		const data = this.extract<CursoredData<Tweet>>(response, resource)!;
+
 		return data;
 	}
 
 	/**
-	 * Get the list of tweets liked by the given user.
+	 * Get the list of tweets liked by a user.
 	 *
-	 * @param userId - The rest id of the target user.
+	 * @param id - The id of the target user.
 	 * @param count - The number of likes to fetch, must be \<= 100.
 	 * @param cursor - The cursor to the batch of likes to fetch.
+	 *
 	 * @returns The list of tweets liked by the target user.
 	 *
 	 * @example
@@ -179,8 +279,8 @@ export class UserService extends FetcherService {
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
 	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
 	 *
-	 * // Fetching the most recent 100 liked Tweets of the User with id '12345678'
-	 * rettiwt.user.likes('12345678')
+	 * // Fetching the most recent 100 liked Tweets of the User with id '1234567890'
+	 * rettiwt.user.likes('1234567890')
 	 * .then(res => {
 	 * 	console.log(res);
 	 * })
@@ -188,27 +288,31 @@ export class UserService extends FetcherService {
 	 * 	console.log(err);
 	 * });
 	 * ```
-	 *
-	 * @public
 	 */
-	public async likes(userId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
-		// Fetching the requested data
-		const data = await this.fetch<Tweet>(EResourceType.USER_LIKES, {
-			id: userId,
+	public async likes(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		const resource = EResourceType.USER_LIKES;
+
+		// Fetching raw list of likes
+		const response = await this.request<IUserLikesResponse>(resource, {
+			id: id,
 			count: count,
 			cursor: cursor,
 		});
 
+		// Deserializing response
+		const data = this.extract<CursoredData<Tweet>>(response, resource)!;
+
 		return data;
 	}
 
 	/**
-	 * Get the timeline of the given user.
+	 * Get the media timeline of a user
 	 *
-	 * @param userId - The rest id of the target user.
-	 * @param count - The number of timeline items to fetch, must be \<= 20.
-	 * @param cursor - The cursor to the batch of timeline items to fetch.
-	 * @returns The timeline of the target user.
+	 * @param id - The id of the target user.
+	 * @param count - The number of media to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of media to fetch
+	 *
+	 * @returns The media timeline of the target user.
 	 *
 	 * @example
 	 * ```
@@ -217,8 +321,8 @@ export class UserService extends FetcherService {
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
 	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
 	 *
-	 * // Fetching the first 20 timeline tweets of the User with id '12345678'
-	 * rettiwt.user.timeline('12345678')
+	 * // Fetching the first 100 timeline media tweets of the User with id '1234567890'
+	 * rettiwt.user.timeline('1234567890')
 	 * .then(res => {
 	 * 	console.log(res);
 	 * })
@@ -226,30 +330,30 @@ export class UserService extends FetcherService {
 	 * 	console.log(err);
 	 * });
 	 * ```
-	 *
-	 * @remarks
-	 * - If the target user has a pinned tweet, the returned timeline has one item extra and this is always the pinned tweet.
-	 * - If timeline is fetched without authenticating, then the most popular tweets of the target user are returned instead.
-	 *
-	 * @public
 	 */
-	public async timeline(userId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
-		// Fetching the requested data
-		const data = await this.fetch<Tweet>(EResourceType.USER_TWEETS, {
-			id: userId,
+	public async media(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		const resource = EResourceType.USER_MEDIA;
+
+		// Fetching raw list of media
+		const response = await this.request<IUserMediaResponse>(resource, {
+			id: id,
 			count: count,
 			cursor: cursor,
 		});
 
+		// Deserializing response
+		const data = this.extract<CursoredData<Tweet>>(response, resource)!;
+
 		return data;
 	}
 
 	/**
-	 * Get the reply timeline of the given user.
+	 * Get the reply timeline of a user.
 	 *
-	 * @param userId - The rest id of the target user.
+	 * @param id - The id of the target user.
 	 * @param count - The number of replies to fetch, must be \<= 20.
 	 * @param cursor - The cursor to the batch of replies to fetch.
+	 *
 	 * @returns The reply timeline of the target user.
 	 *
 	 * @example
@@ -259,8 +363,8 @@ export class UserService extends FetcherService {
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
 	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
 	 *
-	 * // Fetching the first 100 timeline replies of the User with id '12345678'
-	 * rettiwt.user.replies('12345678')
+	 * // Fetching the first 100 timeline replies of the User with id '1234567890'
+	 * rettiwt.user.replies('1234567890')
 	 * .then(res => {
 	 * 	console.log(res);
 	 * })
@@ -270,19 +374,143 @@ export class UserService extends FetcherService {
 	 * ```
 	 *
 	 * @remarks If the target user has a pinned tweet, the returned reply timeline has one item extra and this is always the pinned tweet.
+	 */
+	public async replies(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		const resource = EResourceType.USER_TIMELINE_AND_REPLIES;
+
+		// Fetching raw list of replies
+		const response = await this.request<IUserTweetsAndRepliesResponse>(resource, {
+			id: id,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = this.extract<CursoredData<Tweet>>(response, resource)!;
+
+		return data;
+	}
+
+	/**
+	 * Get the list of subscriptions of a user.
+	 *
+	 * @param id - The id of the target user.
+	 * @param count - The number of subscriptions to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of subscriptions to fetch.
+	 *
+	 * @returns The list of subscriptions by the target user.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 100 subscriptions of the User with id '1234567890'
+	 * rettiwt.user.subscriptions('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async subscriptions(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		const resource = EResourceType.USER_SUBSCRIPTIONS;
+
+		// Fetching raw list of subscriptions
+		const response = await this.request<IUserSubscriptionsResponse>(resource, {
+			id: id,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = this.extract<CursoredData<User>>(response, resource)!;
+
+		return data;
+	}
+
+	/**
+	 * Get the tweet timeline of a user.
+	 *
+	 * @param id - The id of the target user.
+	 * @param count - The number of timeline items to fetch, must be \<= 20.
+	 * @param cursor - The cursor to the batch of timeline items to fetch.
 	 *
-	 * @public
+	 * @returns The timeline of the target user.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Fetching the first 20 timeline tweets of the User with id '1234567890'
+	 * rettiwt.user.timeline('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 *
+	 * @remarks
+	 * - If the target user has a pinned tweet, the returned timeline has one item extra and this is always the pinned tweet.
+	 * - If timeline is fetched without authenticating, then the most popular tweets of the target user are returned instead.
 	 */
-	public async replies(userId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
-		// Fetching the requested data
-		const data = await this.fetch<Tweet>(EResourceType.USER_TWEETS_AND_REPLIES, {
-			id: userId,
+	public async timeline(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+		const resource = EResourceType.USER_TIMELINE;
+
+		// Fetching raw list of tweets
+		const response = await this.request<IUserTweetsResponse>(resource, {
+			id: id,
 			count: count,
 			cursor: cursor,
 		});
 
-		// Filtering out other tweets made by other users in the same threads
-		data.list = data.list.filter((tweet) => tweet.tweetBy.id == userId);
+		// Deserializing response
+		const data = this.extract<CursoredData<Tweet>>(response, resource)!;
+
+		return data;
+	}
+
+	/**
+	 * Unfollow a user.
+	 *
+	 * @param id - The id the user to be unfollowed.
+	 *
+	 * @returns Whether unfollowing was successful or not.
+	 *
+	 * @throws Code 34 if given user id is invalid.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 *
+	 * // Unfollowing the User with id '12345678'
+	 * rettiwt.user.unfollow('12345678')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async unfollow(id: string): Promise<boolean> {
+		// Unfollowing the user
+		const response = await this.request<IUserUnfollowResponse>(EResourceType.USER_UNFOLLOW, { id: id });
+
+		// Deserializing the response
+		const data = this.extract<boolean>(response, EResourceType.USER_UNFOLLOW) ?? false;
 
 		return data;
 	}

package/src/types/RettiwtConfig.ts

@@ -1,4 +1,3 @@
-// TYPES
 import { IErrorHandler } from './ErrorHandler';
 
 /**

package/src/types/ReturnTypes.ts

@@ -0,0 +1,24 @@
+import { CursoredData } from '../models/data/CursoredData';
+import { Tweet } from '../models/data/Tweet';
+import { User } from '../models/data/User';
+
+/**
+ * Collection of all return types.
+ *
+ * @internal
+ */
+export type AllReturnTypes = boolean | CursoredData<Tweet> | CursoredData<User> | string | Tweet | User;
+
+/**
+ * Return type of fetch requests.
+ *
+ * @internal
+ */
+export type FetchReturnType = boolean | CursoredData<Tweet> | CursoredData<User> | Tweet | User;
+
+/**
+ * Return type of post requests.
+ *
+ * @internal
+ */
+export type PostReturnType = boolean;

package/dist/models/args/TweetArgs.d.ts

@@ -1,44 +0,0 @@
-/**
- * The arguments specifying the tweet to be posted.
- */
-export declare class TweetArgs {
-    /**
-     * The text content of the tweet.
-     *
-     * @remarks Length must be \<= 280 characters.
-     */
-    text: string;
-    /**
-     * The media content of the tweet.
-     *
-     * @remarks Max number of media that can be posted is 4.
-     */
-    media?: TweetMediaArgs[];
-    /**
-     * @param tweet - The tweet arguments specifying the tweet.
-     */
-    constructor(tweet: TweetArgs);
-}
-/**
- * The arguments specifying the media to be posted in a single tweet.
- *
- * @public
- */
-export declare class TweetMediaArgs {
-    /**
-     * The path to the media file.
-     *
-     * @remarks The size of the media file must be \<= 5242880 bytes.
-     */
-    path: string;
-    /**
-     * The list of id of users to be tagged in the media.
-     *
-     * @remarks Max number of tags is 10.
-     */
-    tags?: string[];
-    /**
-     * @param media - The media arguments specifying the media.
-     */
-    constructor(media: TweetMediaArgs);
-}