feat: Add Space Search functionality and documentation

[lekkerelou]

🔗 Related Issue

N/A

❓ 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

feat: Add Space Search functionality and documentation
node dist/cli.js space search tbvxyz

[
    {
        "id": "1YqKDNoNQYDJV",
        "state": "Ended",
        "title": "What Consensus Don’t Say",
        "mediaKey": "28_2016160145940926464",
        "createdAt": "2026-01-27T14:43:31.875Z",
        "scheduledStart": "2026-02-05T11:00:00.000Z",
        "startedAt": "2026-02-05T10:59:16.994Z",
        "endedAt": "2026-02-05T11:58:49.059Z",
        "updatedAt": "2026-02-05T11:58:50.162Z",
        "creatorId": "1815883810480795648",
        "conversationControls": 0,
        "disallowJoin": false,
        "isEmployeeOnly": false,
        "isLocked": false,
        "isMuted": false,
        "isSpaceAvailableForClipping": false,
        "noIncognito": false,
        "totalLiveListeners": 761,
        "totalReplayWatched": 139,
        "participantCount": 0,
        "isSubscribed": false,
        "participants": {
            "total": 0,
            "admins": [
                {
                    "id": "1815883810480795648",
                    "screenName": "tbvxyz",
                    "displayName": "tbv",
                    "avatarUrl": "https://pbs.twimg.com/profile_images/1827584478929416194/T5wsExtf_normal.jpg",
                    "isVerified": true,
                    "isMutedByAdmin": false,
                    "isMutedByGuest": false
                }
            ],
            "speakers": [
                {
                    "id": "1202380258739138562",
                    "screenName": "Brickken",
                    "displayName": "Brickken",
                    "avatarUrl": "https://pbs.twimg.com/profile_images/1915410629524922368/a186skqx_normal.jpg",
                    "isVerified": true,
                    "isMutedByAdmin": false,
                    "isMutedByGuest": true
                }
            ],
            "listeners": []
        }
    }
]

📝 Checklist

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

@Rishikant181

[Rishikant181]

@lekkerelou I've added a comment. If possible, please address that and we'll be good to merge. Thanks!

[lekkerelou]

I don't see any comment on my PR

[Rishikant181]

We should not be nesting one API call within another, in this case, space.details within space.search. Let's say a search result returns 20 spaces, this implementation will results in a total of 21 API calls (1 for initial search result and 20 for each space result). Almost all functions of Rettiwt represent 1:1 API calls i.e, one function call results in one API call. This is done so that we leave as much freedom to the user as possible, in regards to rate limiting.

I'm curious, what does the search result for spaces look like? Is it truncated that we have to fetch the details again? If that's the case, we should return the truncated results (define additional type if necessary) from the space.search function, and leave it up to the user whether to fetch full details via space.details or not.

[Rishikant181]

@lekkerelou I forgot to submit review lol.

You should be able to see it now.

[lekkerelou]

What's the best?

Using the Tweet structure:

{
    "list": [
        {
            "bookmarkCount": 0,
            "conversationId": "2019374131100500127",
            "createdAt": "2026-02-05T11:34:46.000Z",
            "entities": {
                "hashtags": [],
                "mentionedUsers": [],
                "urls": [
                    "https://x.com/i/spaces/1YqKDNoNQYDJV"
                ]
            },
            "fullText": "https://t.co/Vx6vo6N7XF",
            "id": "2019374135970050410",
            "lang": "zxx",
            "likeCount": 1,
            "quoteCount": 0,
            "replyCount": 1,
            "replyTo": "2019374131100500127",
            "spaceId": "1YqKDNoNQYDJV",
            "retweetCount": 0,
            "tweetBy": {
                "createdAt": "2024-07-23T22:57:06.000Z",
                "description": "TBV is an early-stage web3 venture capital fund focusing on leading investment deals backed by a strong ecosystem of investors, founders, & builders.",
                "followersCount": 1963,
                "followingsCount": 133,
                "fullName": "tbv",
                "id": "1815883810480795648",
                "isVerified": true,
                "likeCount": 749,
                "location": "Singapore",
                "pinnedTweet": "2020693670060851236",
                "profileBanner": "https://pbs.twimg.com/profile_banners/1815883810480795648/1724565036",
                "profileImage": "https://pbs.twimg.com/profile_images/1827584478929416194/T5wsExtf_normal.jpg",
                "statusesCount": 945,
                "userName": "tbvxyz"
            },
            "url": "https://x.com/tbvxyz/status/2019374135970050410",
            "viewCount": 97
        }
    ],
    "next": "XXXXX"
}

And they can fetch the space with the spaceId. or we setup a "SpaceSearch" Object:

{
    "list": [
        {
            "id": "1YqKDNoNQYDJV",
            "url": "https://x.com/i/spaces/1YqKDNoNQYDJV",
            "tweetId": "2019365922759462996",
            "text": "🎙️Tune in with us & @tbvxyz! \n\n https://t.co/vLcdLNMGnP",
            "createdAt": "2026-02-05T11:02:08.000Z",
            "creatorId": "1511774198003376128",
            "creatorUserName": "consensus_hk",
            "creatorName": "Consensus Hong Kong"
        }
    ],
    "next": "XXXXX"
}

What's the best?

[Rishikant181]

@lekkerelou From the raw response, it seems like space search raw results are nothing but raw tweets, which happen to contain space information. So it makes sense that space search results return array of Tweet (the first approach in your suggestion).

So, we can just add a new optional field called spaceId to Tweet (and ITweet). The presence of the field indicates that the tweet is for a space, while it's absense indicates it's a simple tweet.

On that note, we also don't need to separate space.search - we can just make use of the filter:space in tweet.search, since the results will still be just tweets. That will simplify things a lot.

[Rishikant181]

On further thought, I've come to conclude that we don't even need the additional SPACE_SEARCH resource. We can just simplify this to adding an additional TweetFilter option called space, which can be either true or false/undefined.

If space filter option is set to true while searching for tweets using tweet.search, it will get all tweets which reference a space. The space URL will be then available in the entities.urls field of the tweet.search results.

[lekkerelou]

Alright, will send a new commit with the changes