rettiwt-api 6.1.7 → 6.2.1

package/playground/README.md

@@ -23,7 +23,7 @@ This playground is intended for developers to test and experiment with features
 2. **Environment Variables**
    Create a `.env` file in the `playground` directory with your API credentials:
     ```env
-    ACCESS_TOKEN=your_access_token_here
+    API_KEY=your_api_key_here
     ```
 
 ### Usage

package/playground/index.js

@@ -1,7 +1,7 @@
 import { Rettiwt } from 'rettiwt-api';
 import 'dotenv/config';
 
-const rettiwt = new Rettiwt({ apiKey: process.env.ACCESS_TOKEN });
+const rettiwt = new Rettiwt({ apiKey: process.env.API_KEY });
 
 async function userDetails() {
 	try {

package/playground/package.json

@@ -10,6 +10,6 @@
 	},
 	"dependencies": {
 		"dotenv": "^17.2.0",
-		"rettiwt-api": "workspace"
+		"rettiwt-api": "file:../"
 	}
 }

package/src/collections/Extractors.ts

@@ -1,5 +1,6 @@
 import { BaseType } from '../enums/Data';
 import { Analytics } from '../models/data/Analytics';
+import { BookmarkFolder } from '../models/data/BookmarkFolder';
 import { Conversation } from '../models/data/Conversation';
 import { CursoredData } from '../models/data/CursoredData';
 import { Inbox } from '../models/data/Inbox';
@@ -34,6 +35,8 @@ import { ITweetUnretweetResponse } from '../types/raw/tweet/Unretweet';
 import { ITweetUnscheduleResponse } from '../types/raw/tweet/Unschedule';
 import { IUserAffiliatesResponse } from '../types/raw/user/Affiliates';
 import { IUserAnalyticsResponse } from '../types/raw/user/Analytics';
+import { IUserBookmarkFoldersResponse } from '../types/raw/user/BookmarkFolders';
+import { IUserBookmarkFolderTweetsResponse } from '../types/raw/user/BookmarkFolderTweets';
 import { IUserBookmarksResponse } from '../types/raw/user/Bookmarks';
 import { IUserDetailsResponse } from '../types/raw/user/Details';
 import { IUserDetailsBulkResponse } from '../types/raw/user/DetailsBulk';
@@ -46,6 +49,7 @@ import { IUserLikesResponse } from '../types/raw/user/Likes';
 import { IUserListsResponse } from '../types/raw/user/Lists';
 import { IUserMediaResponse } from '../types/raw/user/Media';
 import { IUserNotificationsResponse } from '../types/raw/user/Notifications';
+import { IUserProfileUpdateResponse } from '../types/raw/user/ProfileUpdate';
 import { IUserRecommendedResponse } from '../types/raw/user/Recommended';
 import { IUserSubscriptionsResponse } from '../types/raw/user/Subscriptions';
 import { IUserTweetsResponse } from '../types/raw/user/Tweets';
@@ -110,6 +114,10 @@ export const Extractors = {
 		new Analytics(response.data.viewer_v2.user_results.result),
 	USER_BOOKMARKS: (response: IUserBookmarksResponse): CursoredData<Tweet> =>
 		new CursoredData<Tweet>(response, BaseType.TWEET),
+	USER_BOOKMARK_FOLDERS: (response: IUserBookmarkFoldersResponse): CursoredData<BookmarkFolder> =>
+		new CursoredData<BookmarkFolder>(response, BaseType.BOOKMARK_FOLDER),
+	USER_BOOKMARK_FOLDER_TWEETS: (response: IUserBookmarkFolderTweetsResponse): CursoredData<Tweet> =>
+		new CursoredData<Tweet>(response, BaseType.TWEET),
 	USER_DETAILS_BY_USERNAME: (response: IUserDetailsResponse): User | undefined => User.single(response),
 	USER_DETAILS_BY_ID: (response: IUserDetailsResponse): User | undefined => User.single(response),
 	USER_DETAILS_BY_IDS_BULK: (response: IUserDetailsBulkResponse, ids: string[]): User[] =>
@@ -139,6 +147,7 @@ export const Extractors = {
 	USER_TIMELINE_AND_REPLIES: (response: IUserTweetsAndRepliesResponse): CursoredData<Tweet> =>
 		new CursoredData<Tweet>(response, BaseType.TWEET),
 	USER_UNFOLLOW: (response: IUserUnfollowResponse): boolean => (response?.id ? true : false),
+	USER_PROFILE_UPDATE: (response: IUserProfileUpdateResponse): boolean => (response?.name ? true : false),
 
 	/* eslint-enable @typescript-eslint/naming-convention */
 };

package/src/collections/Groups.ts

@@ -33,6 +33,8 @@ export const FetchResourcesGroup = [
 	ResourceType.USER_AFFILIATES,
 	ResourceType.USER_ANALYTICS,
 	ResourceType.USER_BOOKMARKS,
+	ResourceType.USER_BOOKMARK_FOLDERS,
+	ResourceType.USER_BOOKMARK_FOLDER_TWEETS,
 	ResourceType.USER_DETAILS_BY_USERNAME,
 	ResourceType.USER_DETAILS_BY_ID,
 	ResourceType.USER_DETAILS_BY_IDS_BULK,
@@ -74,4 +76,5 @@ export const PostResourcesGroup = [
 	ResourceType.TWEET_UNSCHEDULE,
 	ResourceType.USER_FOLLOW,
 	ResourceType.USER_UNFOLLOW,
+	ResourceType.USER_PROFILE_UPDATE,
 ];

package/src/collections/Requests.ts

@@ -63,6 +63,9 @@ export const Requests: { [key in keyof typeof ResourceType]: (args: IFetchArgs |
 			args.showVerifiedFollowers!,
 		),
 	USER_BOOKMARKS: (args: IFetchArgs) => UserRequests.bookmarks(args.count, args.cursor),
+	USER_BOOKMARK_FOLDERS: (args: IFetchArgs) => UserRequests.bookmarkFolders(args.cursor),
+	USER_BOOKMARK_FOLDER_TWEETS: (args: IFetchArgs) =>
+		UserRequests.bookmarkFolderTweets(args.id!, args.count, args.cursor),
 	USER_DETAILS_BY_USERNAME: (args: IFetchArgs) => UserRequests.detailsByUsername(args.id!),
 	USER_DETAILS_BY_ID: (args: IFetchArgs) => UserRequests.detailsById(args.id!),
 	USER_DETAILS_BY_IDS_BULK: (args: IFetchArgs) => UserRequests.bulkDetailsByIds(args.ids!),
@@ -80,6 +83,7 @@ export const Requests: { [key in keyof typeof ResourceType]: (args: IFetchArgs |
 	USER_TIMELINE: (args: IFetchArgs) => UserRequests.tweets(args.id!, args.count, args.cursor),
 	USER_TIMELINE_AND_REPLIES: (args: IFetchArgs) => UserRequests.tweetsAndReplies(args.id!, args.count, args.cursor),
 	USER_UNFOLLOW: (args: IPostArgs) => UserRequests.unfollow(args.id!),
+	USER_PROFILE_UPDATE: (args: IPostArgs) => UserRequests.updateProfile(args.profileOptions!),
 
 	/* eslint-enable @typescript-eslint/naming-convention */
 };

package/src/commands/User.ts

@@ -80,6 +80,36 @@ function createUserCommand(rettiwt: Rettiwt): Command {
 			}
 		});
 
+	user.command('bookmark-folders')
+		.description('Fetch your list of bookmark folders')
+		.argument('[cursor]', 'The cursor to the batch of bookmark folders to fetch')
+		.action(async (cursor?: string) => {
+			try {
+				const folders = await rettiwt.user.bookmarkFolders(cursor);
+				output(folders);
+			} catch (error) {
+				output(error);
+			}
+		});
+
+	user.command('bookmark-folder-tweets')
+		.description('Fetch tweets from a specific bookmark folder')
+		.argument('<folderId>', 'The ID of the bookmark folder')
+		.argument('[count]', 'The number of tweets to fetch')
+		.argument('[cursor]', 'The cursor to the batch of tweets to fetch')
+		.action(async (folderId: string, count?: string, cursor?: string) => {
+			try {
+				const tweets = await rettiwt.user.bookmarkFolderTweets(
+					folderId,
+					count ? parseInt(count) : undefined,
+					cursor,
+				);
+				output(tweets);
+			} catch (error) {
+				output(error);
+			}
+		});
+
 	// Details
 	user.command('details')
 		.description('Fetch the details of the user with the given id/username')
@@ -274,6 +304,27 @@ function createUserCommand(rettiwt: Rettiwt): Command {
 			}
 		});
 
+	// Update Profile
+	user.command('update-profile')
+		.description('Update your profile information')
+		.option('-n, --name <string>', 'Display name (max 50 characters)')
+		.option('-u, --url <string>', 'Profile URL')
+		.option('-l, --location <string>', 'Location (max 30 characters)')
+		.option('-d, --description <string>', 'Description/bio (max 160 characters)')
+		.action(async (options?: UserProfileUpdateOptions) => {
+			try {
+				const result = await rettiwt.user.updateProfile({
+					name: options?.name,
+					url: options?.url,
+					location: options?.location,
+					description: options?.description,
+				});
+				output(result);
+			} catch (error) {
+				output(error);
+			}
+		});
+
 	return user;
 }
 
@@ -288,4 +339,14 @@ type UserAnalyticsOptions = {
 	verifiedFollowers?: boolean;
 };
 
+/**
+ * The options for updating user profile.
+ */
+type UserProfileUpdateOptions = {
+	name?: string;
+	url?: string;
+	location?: string;
+	description?: string;
+};
+
 export default createUserCommand;

package/src/enums/Data.ts

@@ -9,4 +9,5 @@ export enum BaseType {
 	TWEET = 'TWEET',
 	USER = 'USER',
 	LIST = 'LIST',
+	BOOKMARK_FOLDER = 'BOOKMARK_FOLDER',
 }

package/src/enums/Resource.ts

@@ -45,6 +45,8 @@ export enum ResourceType {
 	USER_AFFILIATES = 'USER_AFFILIATES',
 	USER_ANALYTICS = 'USER_ANALYTICS',
 	USER_BOOKMARKS = 'USER_BOOKMARKS',
+	USER_BOOKMARK_FOLDERS = 'USER_BOOKMARK_FOLDERS',
+	USER_BOOKMARK_FOLDER_TWEETS = 'USER_BOOKMARK_FOLDER_TWEETS',
 	USER_DETAILS_BY_USERNAME = 'USER_DETAILS_BY_USERNAME',
 	USER_DETAILS_BY_ID = 'USER_DETAILS_BY_ID',
 	USER_DETAILS_BY_IDS_BULK = 'USER_DETAILS_BY_IDS_BULK',
@@ -62,4 +64,5 @@ export enum ResourceType {
 	USER_TIMELINE = 'USER_TIMELINE',
 	USER_TIMELINE_AND_REPLIES = 'USER_TIMELINE_AND_REPLIES',
 	USER_UNFOLLOW = 'USER_UNFOLLOW',
+	USER_PROFILE_UPDATE = 'USER_PROFILE_UPDATE',
 }

package/src/index.ts

@@ -18,6 +18,8 @@ export * from './enums/Tweet';
 // MODELS
 export * from './models/args/FetchArgs';
 export * from './models/args/PostArgs';
+export * from './models/args/ProfileArgs';
+export * from './models/data/BookmarkFolder';
 export * from './models/data/Conversation';
 export * from './models/data/CursoredData';
 export * from './models/data/DirectMessage';
@@ -45,6 +47,8 @@ export * from './services/public/UserService';
 // TYPES
 export * from './types/args/FetchArgs';
 export * from './types/args/PostArgs';
+export * from './types/args/ProfileArgs';
+export * from './types/data/BookmarkFolder';
 export * from './types/data/Conversation';
 export * from './types/data/CursoredData';
 export * from './types/data/DirectMessage';
@@ -56,6 +60,7 @@ export * from './types/data/User';
 export * from './types/errors/TwitterError';
 export * from './types/params/Variables';
 export { IAnalytics as IRawAnalytics } from './types/raw/base/Analytic';
+export { IBookmarkFolder as IRawBookmarkFolder } from './types/raw/base/BookmarkFolder';
 export { ICursor as IRawCursor } from './types/raw/base/Cursor';
 export { IErrorData as IRawErrorData, IErrorDetails as IRawErrorDetails } from './types/raw/base/Error';
 export { ILimitedVisibilityTweet as IRawLimitedVisibilityTweet } from './types/raw/base/LimitedVisibilityTweet';
@@ -94,6 +99,8 @@ export { ITweetUnretweetResponse as IRawTweetUnretweetResponse } from './types/r
 export { ITweetUnscheduleResponse as ITRawTweetUnscheduleResponse } from './types/raw/tweet/Unschedule';
 export { IUserAffiliatesResponse as IRawUserAffiliatesResponse } from './types/raw/user/Affiliates';
 export { IUserAnalyticsResponse as IRawUserAnalyticsResponse } from './types/raw/user/Analytics';
+export { IUserBookmarkFoldersResponse as IRawUserBookmarkFoldersResponse } from './types/raw/user/BookmarkFolders';
+export { IUserBookmarkFolderTweetsResponse as IRawUserBookmarkFolderTweetsResponse } from './types/raw/user/BookmarkFolderTweets';
 export { IUserBookmarksResponse as IRawUserBookmarksResponse } from './types/raw/user/Bookmarks';
 export { IUserDetailsResponse as IRawUserDetailsResponse } from './types/raw/user/Details';
 export { IUserDetailsBulkResponse as IRawUserDetailsBulkResponse } from './types/raw/user/DetailsBulk';
@@ -111,6 +118,7 @@ export { IUserSubscriptionsResponse as IRawUserSubscriptionsResponse } from './t
 export { IUserTweetsResponse as IRawUserTweetsResponse } from './types/raw/user/Tweets';
 export { IUserTweetsAndRepliesResponse as IRawUserTweetsAndRepliesResponse } from './types/raw/user/TweetsAndReplies';
 export { IUserUnfollowResponse as IRawUserUnfollowResponse } from './types/raw/user/Unfollow';
+export { IUserProfileUpdateResponse as IRawUserProfileUpdateResponse } from './types/raw/user/ProfileUpdate';
 export * from './types/ErrorHandler';
 export * from './types/RettiwtConfig';
 export { IConversationTimelineResponse as IRawConversationTimelineResponse } from './types/raw/dm/Conversation';

package/src/models/args/PostArgs.ts

@@ -1,12 +1,16 @@
 import { INewTweet, INewTweetMedia, IPostArgs, IUploadArgs } from '../../types/args/PostArgs';
 
+import { ProfileUpdateOptions } from './ProfileArgs';
+
 /**
  * Options specifying the data that is to be posted.
  *
  * @public
  */
 export class PostArgs implements IPostArgs {
+	public conversationId?: string;
 	public id?: string;
+	public profileOptions?: ProfileUpdateOptions;
 	public tweet?: NewTweet;
 	public upload?: UploadArgs;
 	public userId?: string;
@@ -20,6 +24,8 @@ export class PostArgs implements IPostArgs {
 		this.tweet = args.tweet ? new NewTweet(args.tweet) : undefined;
 		this.upload = args.upload ? new UploadArgs(args.upload) : undefined;
 		this.userId = args.userId;
+		this.conversationId = args.conversationId;
+		this.profileOptions = args.profileOptions ? new ProfileUpdateOptions(args.profileOptions) : undefined;
 	}
 }
 

package/src/models/args/ProfileArgs.ts

@@ -0,0 +1,68 @@
+import { IProfileUpdateOptions } from '../../types/args/ProfileArgs';
+
+/**
+ * Configuration for profile update.
+ *
+ * @public
+ */
+export class ProfileUpdateOptions implements IProfileUpdateOptions {
+	public description?: string;
+	public location?: string;
+	public name?: string;
+	public url?: string;
+
+	/**
+	 * @param options - The options specifying the profile fields to update.
+	 */
+	public constructor(options: IProfileUpdateOptions) {
+		this.description = options.description;
+		this.location = options.location;
+		this.name = options.name;
+		this.url = options.url;
+
+		// At least one field must be provided
+		if (
+			this.name === undefined &&
+			this.url === undefined &&
+			this.location === undefined &&
+			this.description === undefined
+		) {
+			throw new Error('At least one profile field must be provided');
+		}
+
+		// Name validation
+		if (this.name !== undefined) {
+			if (this.name.trim().length === 0) {
+				throw new Error('Name cannot be empty');
+			}
+			if (this.name.length > 50) {
+				throw new Error('Name cannot exceed 50 characters');
+			}
+		}
+
+		// URL validation (minimal - just check if not empty when provided)
+		if (this.url !== undefined && this.url.trim().length === 0) {
+			throw new Error('URL cannot be empty');
+		}
+
+		// Location validation
+		if (this.location !== undefined) {
+			if (this.location.trim().length === 0) {
+				throw new Error('Location cannot be empty');
+			}
+			if (this.location.length > 30) {
+				throw new Error('Location cannot exceed 30 characters');
+			}
+		}
+
+		// Description validation
+		if (this.description !== undefined) {
+			if (this.description.trim().length === 0) {
+				throw new Error('Description cannot be empty');
+			}
+			if (this.description.length > 160) {
+				throw new Error('Description cannot exceed 160 characters');
+			}
+		}
+	}
+}

package/src/models/data/BookmarkFolder.ts

@@ -0,0 +1,73 @@
+import { LogActions } from '../../enums/Logging';
+import { LogService } from '../../services/internal/LogService';
+import { IBookmarkFolder } from '../../types/data/BookmarkFolder';
+import { IBookmarkFolder as IRawBookmarkFolder } from '../../types/raw/base/BookmarkFolder';
+import { IUserBookmarkFoldersResponse } from '../../types/raw/user/BookmarkFolders';
+
+/**
+ * The details of a single Bookmark Folder.
+ *
+ * @public
+ */
+export class BookmarkFolder implements IBookmarkFolder {
+	/** The raw bookmark folder details. */
+	private readonly _raw: IRawBookmarkFolder;
+
+	public id: string;
+	public name: string;
+
+	/**
+	 * @param folder - The raw bookmark folder details.
+	 */
+	public constructor(folder: IRawBookmarkFolder) {
+		this._raw = { ...folder };
+		this.id = folder.id;
+		this.name = folder.name;
+	}
+
+	/** The raw bookmark folder details. */
+	public get raw(): IRawBookmarkFolder {
+		return { ...this._raw };
+	}
+
+	/**
+	 * Extracts and deserializes bookmark folders from the given raw response data.
+	 *
+	 * @param response - The raw response data.
+	 *
+	 * @returns The deserialized list of bookmark folders.
+	 */
+	public static list(response: NonNullable<unknown>): BookmarkFolder[] {
+		const folders: BookmarkFolder[] = [];
+
+		// Extract items from the response structure
+		const items = (response as IUserBookmarkFoldersResponse)?.data?.viewer?.user_results?.result
+			?.bookmark_collections_slice?.items;
+
+		if (!items || !Array.isArray(items)) {
+			return folders;
+		}
+
+		// Deserialize valid folders
+		for (const item of items) {
+			if (item && item.id) {
+				// Logging
+				LogService.log(LogActions.DESERIALIZE, { id: item.id });
+
+				folders.push(new BookmarkFolder(item));
+			}
+		}
+
+		return folders;
+	}
+
+	/**
+	 * @returns A serializable JSON representation of `this` object.
+	 */
+	public toJSON(): IBookmarkFolder {
+		return {
+			id: this.id,
+			name: this.name,
+		};
+	}
+}

package/src/models/data/CursoredData.ts

@@ -4,9 +4,10 @@ import { findByFilter } from '../../helper/JsonUtils';
 
 import { ICursoredData } from '../../types/data/CursoredData';
 import { ICursor as IRawCursor } from '../../types/raw/base/Cursor';
+import { IUserBookmarkFoldersResponse } from '../../types/raw/user/BookmarkFolders';
 
+import { BookmarkFolder } from './BookmarkFolder';
 import { List } from './List';
-
 import { Notification } from './Notification';
 import { Tweet } from './Tweet';
 import { User } from './User';
@@ -18,7 +19,7 @@ import { User } from './User';
  *
  * @public
  */
-export class CursoredData<T extends Notification | Tweet | User | List> implements ICursoredData<T> {
+export class CursoredData<T extends Notification | Tweet | User | List | BookmarkFolder> implements ICursoredData<T> {
 	public list: T[];
 	public next: string;
 
@@ -43,6 +44,11 @@ export class CursoredData<T extends Notification | Tweet | User | List> implemen
 		} else if (type == BaseType.NOTIFICATION) {
 			this.list = Notification.list(response) as T[];
 			this.next = findByFilter<IRawCursor>(response, 'cursorType', 'Bottom')[0]?.value ?? '';
+		} else if (type == BaseType.BOOKMARK_FOLDER) {
+			this.list = BookmarkFolder.list(response) as T[];
+			const sliceInfo = (response as IUserBookmarkFoldersResponse)?.data?.viewer?.user_results?.result
+				?.bookmark_collections_slice?.slice_info;
+			this.next = sliceInfo?.next_cursor ?? '';
 		}
 	}
 

package/src/models/data/Tweet.ts

@@ -272,7 +272,7 @@ export class Tweet implements ITweet {
  *
  * @public
  */
-export class TweetEntities {
+export class TweetEntities implements ITweetEntities {
 	/** The list of hashtags mentioned in the tweet. */
 	public hashtags: string[] = [];
 
@@ -325,7 +325,10 @@ export class TweetEntities {
  *
  * @public
  */
-export class TweetMedia {
+export class TweetMedia implements ITweetMedia {
+	/** The ID of the media. */
+	public id: string;
+
 	/** The thumbnail URL for the video content of the tweet. */
 	public thumbnailUrl?: string;
 
@@ -339,6 +342,8 @@ export class TweetMedia {
 	 * @param media - The raw media details.
 	 */
 	public constructor(media: IRawExtendedMedia) {
+		this.id = media.id_str;
+
 		// If the media is a photo
 		if (media.type == RawMediaType.PHOTO) {
 			this.type = MediaType.PHOTO;
@@ -374,6 +379,7 @@ export class TweetMedia {
 	 */
 	public toJSON(): ITweetMedia {
 		return {
+			id: this.id,
 			thumbnailUrl: this.thumbnailUrl,
 			type: this.type,
 			url: this.url,