rettiwt-api 5.0.0-alpha.3 → 5.0.0

package/src/services/public/UserService.ts

@@ -5,8 +5,10 @@ import { Notification } from '../../models/data/Notification';
 import { Tweet } from '../../models/data/Tweet';
 import { User } from '../../models/data/User';
 import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IUserAffiliatesResponse } from '../../types/raw/user/Affiliates';
 import { IUserBookmarksResponse } from '../../types/raw/user/Bookmarks';
 import { IUserDetailsResponse } from '../../types/raw/user/Details';
+import { IUserDetailsBulkResponse } from '../../types/raw/user/DetailsBulk';
 import { IUserFollowResponse } from '../../types/raw/user/Follow';
 import { IUserFollowedResponse } from '../../types/raw/user/Followed';
 import { IUserFollowersResponse } from '../../types/raw/user/Followers';
@@ -38,6 +40,49 @@ export class UserService extends FetcherService {
 		super(config);
 	}
 
+	/**
+	 * Get the list affiliates of a user.
+	 *
+	 * @param id - The ID of the target user. If no id is provided, the logged-in user's id is used.
+	 * @param count - The number of affiliates to fetch, must be \<= 100.
+	 * @param cursor - The cursor to the batch of affiliates to fetch.
+	 *
+	 * @returns The list of users affiliated to the target user.
+	 *
+	 * @example
+	 *
+	 * ```ts
+	 * 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 affiliates of the User with id '1234567890'
+	 * rettiwt.user.affiliates('1234567890')
+	 * .then(res => {
+	 * 	console.log(res);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async affiliates(id?: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+		const resource = EResourceType.USER_AFFILIATES;
+
+		// Fetching raw list of affiliates
+		const response = await this.request<IUserAffiliatesResponse>(resource, {
+			id: id ?? this.config.userId,
+			count: count,
+			cursor: cursor,
+		});
+
+		// Deserializing response
+		const data = extractors[resource](response);
+
+		return data;
+	}
+
 	/**
 	 * Get the list of bookmarks of the logged in user.
 	 *
@@ -47,7 +92,8 @@ export class UserService extends FetcherService {
 	 * @returns The list of tweets bookmarked by the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -81,15 +127,19 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the details of a user.
 	 *
-	 * @param id - The username/id(s) of the target user/users.
+	 * @param id - The username/ID/IDs of the target user/users. If no ID is provided, the logged-in user's ID is used.
 	 *
 	 * @returns
 	 * The details of the given user.
+	 *
+	 * If more than one ID is provided, returns a list.
+	 *
 	 * If no user matches the given id, returns `undefined`.
 	 *
 	 * @example
-	 * Fetching the details using username
-	 * ```
+	 *
+	 * #### Fetching the details of a single user using username
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -106,8 +156,9 @@ export class UserService extends FetcherService {
 	 * ```
 	 *
 	 * @example
-	 * Fetching the details using id
-	 * ```
+	 *
+	 * #### Fetching the details of a single user using ID
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -116,14 +167,34 @@ export class UserService extends FetcherService {
 	 * // Fetching the details of the User with id '1234567890'
 	 * rettiwt.user.details('1234567890')
 	 * .then(res => {
-	 * 	console.log(res);
+	 * 	console.log(res);	# 'res' is a single tweet
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 * * @example
+	 *
+	 * #### Fetching the details of multiple users
+	 * ```ts
+	 * 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 users with IDs '123', '456', '789'
+	 * rettiwt.user.details(['123', '456', '789'])
+	 * .then(res => {
+	 * 	console.log(res);	# 'res' is an array of users
 	 * })
 	 * .catch(err => {
 	 * 	console.log(err);
 	 * });
 	 * ```
 	 */
-	public async details<T extends string | string[]>(id: T): Promise<T extends string ? User | undefined : User[]> {
+	public async details<T extends string | string[] | undefined>(
+		id: T,
+	): Promise<T extends string | undefined ? User | undefined : User[]> {
 		let resource: EResourceType;
 
 		// If details of multiple users required
@@ -131,45 +202,51 @@ export class UserService extends FetcherService {
 			resource = EResourceType.USER_DETAILS_BY_IDS_BULK;
 
 			// Fetching raw details
-			const response = await this.request<IUserDetailsResponse>(resource, { ids: id });
+			const response = await this.request<IUserDetailsBulkResponse>(resource, { ids: id });
 
 			// Deserializing response
 			const data = extractors[resource](response, id);
 
-			return data as T extends string ? User | undefined : User[];
+			return data as T extends string | undefined ? User | undefined : User[];
 		}
 		// If details of single user required
 		else {
 			// If username is given
-			if (isNaN(Number(id))) {
+			if (id && isNaN(Number(id))) {
 				resource = EResourceType.USER_DETAILS_BY_USERNAME;
 			}
-			// If id is given
+			// If id is given (or not, for self details)
 			else {
 				resource = EResourceType.USER_DETAILS_BY_ID;
 			}
 
+			// If no ID is given, and not authenticated, skip
+			if (!id && !this.config.userId) {
+				return undefined as T extends string | undefined ? User | undefined : User[];
+			}
+
 			// Fetching raw details
-			const response = await this.request<IUserDetailsResponse>(resource, { id: id });
+			const response = await this.request<IUserDetailsResponse>(resource, { id: id ?? this.config.userId });
 
 			// Deserializing response
 			const data = extractors[resource](response);
 
-			return data as T extends string ? User | undefined : User[];
+			return data as T extends string | undefined ? User | undefined : User[];
 		}
 	}
 
 	/**
 	 * Follow a user.
 	 *
-	 * @param id - The id the user to be followed.
+	 * @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
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -205,7 +282,8 @@ export class UserService extends FetcherService {
 	 * @returns - The followed feed of the logged-in user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -240,14 +318,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the list followers of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @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
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -263,12 +342,12 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async followers(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+	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,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -282,14 +361,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the list of users who are followed by a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @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
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -305,12 +385,12 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async following(id: string, count?: number, cursor?: string): Promise<CursoredData<User>> {
+	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,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -324,14 +404,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the highlighted tweets of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @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 highlighted tweets of the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -352,7 +433,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of highlights
 		const response = await this.request<IUserHighlightsResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -372,7 +453,8 @@ export class UserService extends FetcherService {
 	 * @returns The list of tweets liked by the target user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -407,14 +489,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the media timeline of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @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
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -430,12 +513,12 @@ export class UserService extends FetcherService {
 	 * });
 	 * ```
 	 */
-	public async media(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>> {
+	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,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -454,7 +537,8 @@ export class UserService extends FetcherService {
 	 * @returns An async generator that yields new notifications as they are received.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -464,7 +548,7 @@ export class UserService extends FetcherService {
 	 * async function streamNotifications() {
 	 * 	try {
 	 * 		// Awaiting for the notifications returned by the AsyncGenerator returned by the method
-	 * 		for await (const notification of rettiwt.user.notifications(1000)) {
+	 * 		for await (const notification of rettiwt.user.notifications(5000)) {
 	 * 			console.log(notification.message);
 	 * 		}
 	 * 	}
@@ -526,7 +610,8 @@ export class UserService extends FetcherService {
 	 * @returns - The recommended feed of the logged-in user.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -561,14 +646,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the reply timeline of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @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
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -584,14 +670,16 @@ 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.
+	 * @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>> {
+	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,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -605,14 +693,17 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the list of subscriptions of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @deprecated Currently not working.
+	 *
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @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
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -633,7 +724,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of subscriptions
 		const response = await this.request<IUserSubscriptionsResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -647,14 +738,15 @@ export class UserService extends FetcherService {
 	/**
 	 * Get the tweet timeline of a user.
 	 *
-	 * @param id - The id of the target user.
+	 * @param id - The ID of the target user. If no ID is provided, the logged-in user's ID is used.
 	 * @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.
 	 *
 	 * @example
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'
@@ -671,6 +763,7 @@ export class UserService extends FetcherService {
 	 * ```
 	 *
 	 * @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.
 	 */
@@ -679,7 +772,7 @@ export class UserService extends FetcherService {
 
 		// Fetching raw list of tweets
 		const response = await this.request<IUserTweetsResponse>(resource, {
-			id: id,
+			id: id ?? this.config.userId,
 			count: count,
 			cursor: cursor,
 		});
@@ -693,14 +786,13 @@ export class UserService extends FetcherService {
 	/**
 	 * Unfollow a user.
 	 *
-	 * @param id - The id the user to be unfollowed.
+	 * @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
-	 * ```
+	 *
+	 * ```ts
 	 * import { Rettiwt } from 'rettiwt-api';
 	 *
 	 * // Creating a new Rettiwt instance using the given 'API_KEY'

package/src/types/args/FetchArgs.ts

@@ -1,3 +1,5 @@
+import { ETweetRepliesSortType } from '../../enums/Tweet';
+
 /**
  * Options specifying the data that is to be fetched.
  *
@@ -55,6 +57,14 @@ export interface IFetchArgs {
 	 * - Required only for {@link EResourceType.TWEET_DETAILS_BULK} and {@link EResourceType.USER_DETAILS_BY_IDS_BULK}.
 	 */
 	ids?: string[];
+
+	/**
+	 * The sorting to use for tweet results.
+	 *
+	 * @remarks
+	 * - Only works for {@link EResourceType.TWEET_REPLIES}.
+	 */
+	sortBy?: ETweetRepliesSortType;
 }
 
 /**

package/src/types/errors/TwitterError.ts

@@ -0,0 +1,37 @@
+/**
+ * The error thrown by Twitter API.
+ *
+ * @public
+ */
+export interface ITwitterError extends Error {
+	/** The details of each error. */
+	details: ITwitterErrorDetails[];
+
+	/** The error message in the response. */
+	message: string;
+
+	/** The name of the error response. */
+	name: string;
+
+	/** The response status code. */
+	status: number;
+}
+
+/**
+ * The error details.
+ *
+ * @public
+ */
+export interface ITwitterErrorDetails {
+	/** The internal error code. */
+	code: number;
+
+	/** The message associated with the error. */
+	message: string;
+
+	/** The name of the error. */
+	name?: string;
+
+	/** The type of error. */
+	type?: string;
+}

package/src/types/raw/base/Error.ts

@@ -0,0 +1,37 @@
+/* eslint-disable */
+
+/**
+ * Error details for multiple errors.
+ *
+ * @public
+ */
+export interface IErrorData {
+	errors: IErrorDetails[];
+}
+
+/**
+ * Error details of a single error.
+ *
+ * @public
+ */
+export interface IErrorDetails {
+	message: string;
+	extensions?: IErrorExtensions;
+	code: number;
+	kind?: string;
+	name?: string;
+	source?: string;
+	tracing?: IErrorTracing;
+}
+
+export interface IErrorExtensions {
+	name: string;
+	source: string;
+	code: number;
+	kind: string;
+	tracing: IErrorTracing;
+}
+
+export interface IErrorTracing {
+	trace_id: string;
+}

package/src/types/raw/generic/Response.ts

@@ -1,5 +1,3 @@
-import { IError } from './Error';
-
 /**
  * The generic raw data received.
  *
@@ -9,5 +7,4 @@ import { IError } from './Error';
  */
 export interface IResponse<DataType> {
 	data: DataType;
-	errors?: IError[];
 }