[feature] Extend your CLI tool as a Python library

[lcheylus]

First, thanks for your awesome tool to get infos, posts, likes... from X/Twitter without API access 🥇

In addition to your CLI, I would like to have a Python library to manipulate datas from X/Twitter => extension of your CLI tool as a Python library.
For example, instead of twitter feed to get home timeline => Python function get_timeline.

Tweepy is a very good Python library to get datas from X (but via access to Twitter API :( ).

I could fork your repository and hack your code to have a Python library ; but I would prefer if it were directly available in your project.

[jackwener]

Thanks for the suggestion! This is a great idea and something I've been thinking about too 🙂

This is a relatively big feature that needs careful design — I want to make sure the library API is clean, stable, and well-documented before exposing it. A few things I'm considering:

Current architecture
The core logic (TwitterClient, cookie extraction, GraphQL parsing) is already modular and separated from the CLI layer. In theory, you could already do:

from twitter_cli.auth import get_cookies
from twitter_cli.client import TwitterClient

cookies = get_cookies()
client = TwitterClient(cookies['auth_token'], cookies['ct0'], cookie_string=cookies.get('cookie_string'))
tweets = client.fetch_home_timeline(count=20)

However, this is internal API and may break between versions.

What needs to be designed

• A stable, public-facing Python API (e.g. twitter.api.get_timeline(), twitter.api.get_user())
• Proper error handling and return types (dataclasses vs dicts)
• Session management (reusable client instance vs per-call)
• Documentation and versioning guarantees
• Whether to split into twitter-cli (CLI) + twitter-sdk (library), or keep as one package

I'll label this as enhancement and keep it open for design discussion. If you have specific API patterns you'd like to see (inspired by Tweepy or others), feel free to share — it will help shape the design!

In the meantime, the internal TwitterClient class should work for prototyping if you need something right now.