Enabled premium users to query to bookmark folders and their respective tweets

[andre-cavalheiro]

🔗 Related Issue

Closes #814

❓ Type of Change

• 📖 Documentation (docs, README, or comments)
• 🐞 Bug fix (non-breaking fix for an issue)
• 👌 Enhancement (improvement to existing functionality)
• ✨ New feature (adds new functionality)
• 🧹 Chore (build, tooling, dependencies)
• ⚠️ Breaking change (affects existing usage)

📚 Description

This PR adds read-only support for Twitter/X bookmark folders, enabling users to:

• List bookmark folders - Retrieve all bookmark folders for the authenticated user
• Get folder tweets - Fetch tweets from specific bookmark folders with pagination support

New API Methods:

• rettiwt.user.bookmarkFolders(cursor?) - Returns CursoredData<BookmarkFolder>
• rettiwt.user.bookmarkFolderTweets(folderId, count?, cursor?) - Returns CursoredData<Tweet>

New CLI Commands:

• rettiwt user bookmark-folders [cursor]
• rettiwt user bookmark-folder-tweets <folderId> [count] [cursor]

New Types/Models:

• BookmarkFolder class with id and name properties
• IBookmarkFolder interface
• Raw response types for both endpoints

📝 Checklist

• Issue/discussion linked above.
• Documentation updated (if needed).
• Code follows project conventions and ESLint rules.
• No sensitive data or credentials are included.

Example

API:

import { Rettiwt } from 'rettiwt-api';

const rettiwt = new Rettiwt({ apiKey: API_KEY });

// Get all bookmark folders
const folders = await rettiwt.user.bookmarkFolders();
console.log(folders.list); // Array of BookmarkFolder objects

// Get tweets from a specific folder
const tweets = await rettiwt.user.bookmarkFolderTweets(folders.list[0].id, 20);
console.log(tweets.list); // Array of Tweet objects

CLI:

# List folders
rettiwt user bookmark-folders

# Get tweets from folder
rettiwt user bookmark-folder-tweets "ID" 20

@Rishikant181

[Rishikant181]

@andre-cavalheiro Thanks for PR!

I look at it over the weekend.

[andre-cavalheiro]

Take your time, just don't forget 🙏

[vachmara]

@Rishikant181, let me know if you want me to test it with my premium account

[Rishikant181]

@andre-cavalheiro Sorry for the very long delay. Got caught up in work and then went on a vacation. I'm still afk.

@vachmara If you can, please test it out. If tests go through, I'll merge this.

[vachmara]

I'm not able to deserialize the tweets, maybe it's a different CursoredData object?

[Rettiwt-API] [2026-01-06T14:21:44.192Z] [REQUEST] {"resource":"USER_BOOKMARK_FOLDER_TWEETS","args":{"id":"1962078514531754373","count":20}}
[Rettiwt-API] [2026-01-06T14:21:44.192Z] [AUTHORIZATION] {"authenticated":true}
[Rettiwt-API] [2026-01-06T14:21:44.193Z] [VALIDATE] {"target":"FETCH_ARGS"}
[Rettiwt-API] [2026-01-06T14:21:44.193Z] [GET] {"target":"USER_CREDENTIAL"}
[Rettiwt-API] [2026-01-06T14:21:45.566Z] [DESERIALIZE] {"id":"1990109109446721774"}
D:\Projet\Rettiwt-API\dist\models\data\User.js:39
        this.createdAt = new Date(user.legacy.created_at).toISOString();
                                                          ^

RangeError: Invalid time value
    at Date.toISOString (<anonymous>)
    at new User (D:\Projet\Rettiwt-API\dist\models\data\User.js:39:59)
    at new Tweet (D:\Projet\Rettiwt-API\dist\models\data\Tweet.js:44:24)
    at Tweet.timeline (D:\Projet\Rettiwt-API\dist\models\data\Tweet.js:198:29)
    at new CursoredData (D:\Projet\Rettiwt-API\dist\models\data\CursoredData.js:30:39)
    at Object.USER_BOOKMARK_FOLDER_TWEETS (D:\Projet\Rettiwt-API\dist\collections\Extractors.js:51:48)
    at UserService.bookmarkFolderTweets (D:\Projet\Rettiwt-API\dist\services\public\UserService.js:145:55)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async file:///D:/Projet/Rettiwt-API/playground/index.js:11:16

[Rishikant181]

I know this issue: it's because of the created_at field being moved to a different location in the raw data from some endpoints. It has been addressed after the PR was opened.

@andre-cavalheiro Can you update your PR with latest changes from the dev branch? That should resolve this issue.

[vachmara]

I'll try with pulling the dev branch too!

[andre-cavalheiro]

Just rebased :)

Lmk if you need anything else

[Rishikant181]

@vachmara Did it work?

[vachmara]

@vachmara Did it work?

Yes! All good on my side

[Rishikant181]

@andre-cavalheiro @vachmara Thanks!

[Rishikant181]

Was waiting for this one before releasing 6.2.0 lol. Target release date is on Monday.