Skip to main content

twikit/
client.rs

1//! Async clients for authenticated and guest Twitter/X web API access.
2
3use std::path::Path;
4use std::sync::Arc;
5use std::time::{Duration, SystemTime, UNIX_EPOCH};
6
7use cookie_store::CookieStore;
8use data_encoding::BASE32_NOPAD;
9use futures_util::FutureExt;
10use hmac::{Hmac, Mac};
11use percent_encoding::percent_decode_str;
12use reqwest::header::{
13    HeaderMap, HeaderValue, ACCEPT_LANGUAGE, AUTHORIZATION, CONTENT_TYPE, REFERER, USER_AGENT,
14};
15use reqwest::{Method, Proxy};
16use reqwest_cookie_store::CookieStoreMutex as ReqwestCookieStoreMutex;
17use serde_json::{json, Value};
18use sha1::Sha1;
19use tokio::fs;
20use tokio::sync::Mutex;
21use tokio::time::sleep;
22use url::Url;
23
24use crate::captcha::Capsolver;
25use crate::constants::{self, TOKEN};
26use crate::endpoints::{self, GqlEndpoint};
27use crate::error::{kind_for_status, ApiErrorKind, Error, Result};
28use crate::flow::Flow;
29use crate::models::{
30    BookmarkFolder, Community, CommunityMember, CommunityNote, Group, GroupMessage, List, Location,
31    Message, Notification, Place, PlaceTrends, Poll, ScheduledTweet, Trend, Tweet, User,
32};
33use crate::result::Timeline;
34use crate::transaction::ClientTransaction;
35use crate::ui_metrics::solve_ui_metrics;
36use crate::utils::{build_user_data, find_first, find_values, flatten_params};
37
38type TimelineParser<T> = Arc<dyn Fn(Value, &Client) -> Timeline<T> + Send + Sync>;
39
40#[derive(Debug, Clone, Copy)]
41enum GqlPageMethod {
42    Get,
43    Post,
44}
45
46/// Tweet search product.
47#[derive(Debug, Clone, Copy, PartialEq, Eq)]
48pub enum TweetSearchProduct {
49    /// Top search.
50    Top,
51    /// Latest search.
52    Latest,
53    /// Media search.
54    Media,
55}
56
57impl TweetSearchProduct {
58    fn as_str(self) -> &'static str {
59        match self {
60            Self::Top => "Top",
61            Self::Latest => "Latest",
62            Self::Media => "Media",
63        }
64    }
65}
66
67/// User timeline type.
68#[derive(Debug, Clone, Copy, PartialEq, Eq)]
69pub enum TweetType {
70    /// User posts.
71    Tweets,
72    /// Tweets and replies.
73    Replies,
74    /// User media.
75    Media,
76    /// User likes.
77    Likes,
78}
79
80fn search_tweet_variables(
81    query: String,
82    product: TweetSearchProduct,
83    count: i64,
84    cursor: Option<String>,
85) -> Value {
86    let mut variables = json!({
87        "rawQuery": query,
88        "count": count,
89        "querySource": "typed_query",
90        "product": product.as_str()
91    });
92    if let Some(cursor) = cursor {
93        variables["cursor"] = cursor.into();
94    }
95    variables
96}
97
98fn user_tweets_variables(user_id: String, count: i64, cursor: Option<String>) -> Value {
99    let mut variables = json!({
100        "userId": user_id,
101        "count": count,
102        "includePromotedContent": true,
103        "withQuickPromoteEligibilityTweetFields": true,
104        "withVoice": true,
105        "withV2Timeline": true
106    });
107    if let Some(cursor) = cursor {
108        variables["cursor"] = cursor.into();
109    }
110    variables
111}
112
113fn user_highlights_variables(user_id: String, count: i64, cursor: Option<String>) -> Value {
114    let mut variables = json!({
115        "userId": user_id,
116        "count": count,
117        "includePromotedContent": true,
118        "withVoice": true
119    });
120    if let Some(cursor) = cursor {
121        variables["cursor"] = cursor.into();
122    }
123    variables
124}
125
126fn home_timeline_variables(
127    count: i64,
128    seen_tweet_ids: Vec<String>,
129    cursor: Option<String>,
130) -> Value {
131    let mut variables = json!({
132        "count": count,
133        "includePromotedContent": true,
134        "latestControlAvailable": true,
135        "requestContext": "launch",
136        "withCommunity": true,
137        "seenTweetIds": seen_tweet_ids
138    });
139    if let Some(cursor) = cursor {
140        variables["cursor"] = cursor.into();
141    }
142    variables
143}
144
145fn search_user_variables(query: String, count: i64, cursor: Option<String>) -> Value {
146    let mut variables = json!({
147        "rawQuery": query,
148        "count": count,
149        "querySource": "typed_query",
150        "product": "People"
151    });
152    if let Some(cursor) = cursor {
153        variables["cursor"] = cursor.into();
154    }
155    variables
156}
157
158fn bookmarks_variables(count: i64, folder_id: Option<String>, cursor: Option<String>) -> Value {
159    let mut variables = json!({"count": count, "includePromotedContent": false});
160    if let Some(cursor) = cursor {
161        variables["cursor"] = cursor.into();
162    }
163    if let Some(folder_id) = folder_id {
164        variables["bookmark_collection_id"] = folder_id.into();
165    }
166    variables
167}
168
169fn id_count_variables(
170    id_key: &'static str,
171    id: String,
172    count: i64,
173    cursor: Option<String>,
174) -> Value {
175    let mut variables = json!({id_key: id, "count": count});
176    if let Some(cursor) = cursor {
177        variables["cursor"] = cursor.into();
178    }
179    variables
180}
181
182fn friendship_variables(user_id: String, count: i64, cursor: Option<String>) -> Value {
183    let mut variables = json!({"userId": user_id, "count": count, "includePromotedContent": false});
184    if let Some(cursor) = cursor {
185        variables["cursor"] = cursor.into();
186    }
187    variables
188}
189
190fn tweet_engagement_variables(tweet_id: String, count: i64, cursor: Option<String>) -> Value {
191    let mut variables =
192        json!({"tweetId": tweet_id, "count": count, "includePromotedContent": true});
193    if let Some(cursor) = cursor {
194        variables["cursor"] = cursor.into();
195    }
196    variables
197}
198
199fn tweet_detail_variables(tweet_id: String, cursor: Option<String>) -> Value {
200    let mut variables = json!({
201        "focalTweetId": tweet_id,
202        "with_rux_injections": false,
203        "includePromotedContent": true,
204        "withCommunity": true,
205        "withQuickPromoteEligibilityTweetFields": true,
206        "withBirdwatchNotes": true,
207        "withVoice": true,
208        "withV2Timeline": true
209    });
210    if let Some(cursor) = cursor {
211        variables["cursor"] = cursor.into();
212    }
213    variables
214}
215
216fn count_variables(count: i64, cursor: Option<String>) -> Value {
217    let mut variables = json!({"count": count});
218    if let Some(cursor) = cursor {
219        variables["cursor"] = cursor.into();
220    }
221    variables
222}
223
224fn communities_variables(count: i64, cursor: Option<String>) -> Value {
225    let mut variables = json!({"count": count, "withCommunity": true});
226    if let Some(cursor) = cursor {
227        variables["cursor"] = cursor.into();
228    }
229    variables
230}
231
232fn community_tweets_variables(
233    community_id: String,
234    ranking_mode: String,
235    count: i64,
236    cursor: Option<String>,
237) -> Value {
238    let mut variables = json!({
239        "communityId": community_id,
240        "count": count,
241        "withCommunity": true,
242        "rankingMode": ranking_mode
243    });
244    if let Some(cursor) = cursor {
245        variables["cursor"] = cursor.into();
246    }
247    variables
248}
249
250fn community_search_tweet_variables(
251    community_id: String,
252    query: String,
253    count: i64,
254    cursor: Option<String>,
255) -> Value {
256    let mut variables = json!({
257        "count": count,
258        "query": query,
259        "communityId": community_id,
260        "includePromotedContent": false,
261        "withBirdwatchNotes": true,
262        "withVoice": false,
263        "isListMemberTargetUserId": "0",
264        "withCommunity": false,
265        "withSafetyModeUserFields": true
266    });
267    if let Some(cursor) = cursor {
268        variables["cursor"] = cursor.into();
269    }
270    variables
271}
272
273fn search_list_variables(query: String, count: i64, cursor: Option<String>) -> Value {
274    let mut variables = json!({
275        "rawQuery": query,
276        "count": count,
277        "querySource": "typed_query",
278        "product": "Lists"
279    });
280    if let Some(cursor) = cursor {
281        variables["cursor"] = cursor.into();
282    }
283    variables
284}
285
286fn search_community_variables(query: String, cursor: Option<String>) -> Value {
287    let mut variables = json!({"query": query});
288    if let Some(cursor) = cursor {
289        variables["cursor"] = cursor.into();
290    }
291    variables
292}
293
294fn friendship_params(
295    user_id: Option<String>,
296    screen_name: Option<String>,
297    count: i64,
298    cursor: Option<String>,
299) -> Vec<(String, String)> {
300    let mut params = vec![("count".into(), count.to_string())];
301    if let Some(user_id) = user_id {
302        params.push(("user_id".into(), user_id));
303    }
304    if let Some(screen_name) = screen_name {
305        params.push(("screen_name".into(), screen_name));
306    }
307    if let Some(cursor) = cursor {
308        params.push(("cursor".into(), cursor));
309    }
310    params
311}
312
313fn create_tweet_variables(
314    text: String,
315    media_entities: Vec<Value>,
316    options: CreateTweetOptions,
317) -> Value {
318    let mut variables = json!({
319        "tweet_text": text,
320        "dark_request": false,
321        "media": {"media_entities": media_entities, "possibly_sensitive": false},
322        "semantic_annotation_ids": []
323    });
324    if let Some(poll_uri) = options.poll_uri {
325        variables["card_uri"] = poll_uri.into();
326    }
327    if let Some(reply_to) = options.reply_to {
328        variables["reply"] =
329            json!({"in_reply_to_tweet_id": reply_to, "exclude_reply_user_ids": []});
330    }
331    if let Some(conversation_control) = options.conversation_control {
332        variables["conversation_control"] = json!({"mode": conversation_control.limit_mode()});
333    }
334    if let Some(attachment_url) = options.attachment_url {
335        variables["attachment_url"] = attachment_url.into();
336    }
337    if let Some(community_id) = options.community_id {
338        variables["semantic_annotation_ids"] =
339            json!([{"entity_id": community_id, "group_id": "8", "domain_id": "31"}]);
340        variables["broadcast"] = options.share_with_followers.into();
341    }
342    if let Some(richtext_options) = options.richtext_options {
343        variables["richtext_options"] = json!({"richtext_tags": richtext_options});
344    }
345    if let Some(edit_tweet_id) = options.edit_tweet_id {
346        variables["edit_options"] = json!({"previous_tweet_id": edit_tweet_id});
347    }
348    variables
349}
350
351/// Media source for upload.
352#[derive(Debug, Clone)]
353pub enum MediaSource {
354    /// Read bytes from a file path.
355    Path(std::path::PathBuf),
356    /// Upload in-memory bytes.
357    Bytes(Vec<u8>),
358}
359
360impl From<Vec<u8>> for MediaSource {
361    fn from(value: Vec<u8>) -> Self {
362        Self::Bytes(value)
363    }
364}
365
366impl From<&[u8]> for MediaSource {
367    fn from(value: &[u8]) -> Self {
368        Self::Bytes(value.to_vec())
369    }
370}
371
372impl From<std::path::PathBuf> for MediaSource {
373    fn from(value: std::path::PathBuf) -> Self {
374        Self::Path(value)
375    }
376}
377
378impl From<&Path> for MediaSource {
379    fn from(value: &Path) -> Self {
380        Self::Path(value.to_path_buf())
381    }
382}
383
384/// Options for media upload.
385#[derive(Debug, Clone, Default)]
386pub struct UploadMediaOptions {
387    /// Wait for async processing completion.
388    pub wait_for_completion: bool,
389    /// Status check interval. If absent, X-provided `check_after_secs` is used.
390    pub status_check_interval: Option<Duration>,
391    /// MIME type override.
392    pub media_type: Option<String>,
393    /// Media category such as `tweet_image`, `tweet_video`, `tweet_gif`.
394    pub media_category: Option<String>,
395    /// Use upload2 endpoint for long videos.
396    pub is_long_video: bool,
397}
398
399/// Conversation reply controls for tweet creation.
400#[derive(Debug, Clone, Copy, PartialEq, Eq)]
401pub enum ConversationControl {
402    /// Limit replies to followers.
403    Followers,
404    /// Limit replies to verified users.
405    Verified,
406    /// Limit replies to mentioned users.
407    Mentioned,
408}
409
410impl ConversationControl {
411    fn limit_mode(self) -> &'static str {
412        match self {
413            Self::Followers => "Community",
414            Self::Verified => "Verified",
415            Self::Mentioned => "ByInvitation",
416        }
417    }
418}
419
420/// Options for creating a tweet.
421#[derive(Debug, Clone, Default)]
422pub struct CreateTweetOptions {
423    /// Uploaded media ids to attach.
424    pub media_ids: Vec<String>,
425    /// Poll card URI from `create_poll`.
426    pub poll_uri: Option<String>,
427    /// Tweet id to reply to.
428    pub reply_to: Option<String>,
429    /// Reply control mode.
430    pub conversation_control: Option<ConversationControl>,
431    /// Tweet URL to quote.
432    pub attachment_url: Option<String>,
433    /// Community id to post into.
434    pub community_id: Option<String>,
435    /// Broadcast community tweet to followers.
436    pub share_with_followers: bool,
437    /// Use note tweet creation endpoint.
438    pub is_note_tweet: bool,
439    /// Rich text tags payload.
440    pub richtext_options: Option<Value>,
441    /// Previous tweet id for edit.
442    pub edit_tweet_id: Option<String>,
443}
444
445/// Options matching Python twikit login keyword arguments.
446#[derive(Debug, Clone)]
447pub struct LoginOptions {
448    /// TOTP secret used to compute a 2FA code automatically.
449    pub totp_secret: Option<String>,
450    /// Cookie file to load before login and save after successful login.
451    pub cookies_file: Option<std::path::PathBuf>,
452    /// Submit ui_metrics instrumentation during login.
453    pub enable_ui_metrics: bool,
454    /// Explicit verification/challenge code. Takes precedence over TOTP.
455    pub verification_code: Option<String>,
456}
457
458impl LoginOptions {
459    fn ui_metrics_enabled(&self) -> bool {
460        self.enable_ui_metrics
461    }
462}
463
464impl Default for LoginOptions {
465    fn default() -> Self {
466        Self {
467            totp_secret: None,
468            cookies_file: None,
469            enable_ui_metrics: true,
470            verification_code: None,
471        }
472    }
473}
474
475/// Raw request options for Python parity.
476pub struct RequestOptions {
477    /// Extra request headers.
478    pub headers: Option<HeaderMap>,
479    /// Query parameters.
480    pub params: Option<Vec<(String, String)>>,
481    /// Request body.
482    pub body: Option<RequestBody>,
483    /// Retry once via `unlock` when account locked and a captcha solver exists.
484    pub auto_unlock: bool,
485    /// Raise mapped API errors.
486    pub raise_exception: bool,
487}
488
489impl Default for RequestOptions {
490    fn default() -> Self {
491        Self {
492            headers: None,
493            params: None,
494            body: None,
495            auto_unlock: true,
496            raise_exception: true,
497        }
498    }
499}
500
501/// Options for geo search.
502#[derive(Debug, Clone, Default)]
503pub struct SearchGeoOptions {
504    /// Free-form query.
505    pub query: Option<String>,
506    /// Latitude.
507    pub lat: Option<f64>,
508    /// Longitude.
509    pub long: Option<f64>,
510    /// IP address fallback.
511    pub ip: Option<String>,
512    /// Minimum place granularity.
513    pub granularity: Option<String>,
514    /// Maximum results.
515    pub max_results: Option<i64>,
516}
517
518/// Options for guide trends.
519#[derive(Debug, Clone)]
520pub struct TrendsOptions {
521    /// Retry once when the guide response contains no trend entries.
522    pub retry: bool,
523    /// Additional v1.1 guide query parameters.
524    pub additional_request_params: Vec<(String, String)>,
525}
526
527impl Default for TrendsOptions {
528    fn default() -> Self {
529        Self {
530            retry: true,
531            additional_request_params: Vec::new(),
532        }
533    }
534}
535
536/// Raw HTTP/API response for Python tuple-style parity.
537#[derive(Debug, Clone)]
538pub struct RawApiResponse {
539    /// HTTP status code.
540    pub status: u16,
541    /// Response headers.
542    pub headers: HeaderMap,
543    /// Raw response body.
544    pub body: String,
545    /// Parsed JSON when available.
546    pub json: Option<Value>,
547}
548
549/// Rich TweetDetail result matching Python's local tweet thread assembly.
550#[derive(Debug)]
551pub struct TweetDetail {
552    /// Focal tweet.
553    pub tweet: Tweet,
554    /// Tweets this tweet replies to, when present in detail response.
555    pub reply_to: Vec<Tweet>,
556    /// Direct replies to the focal tweet.
557    pub replies: Timeline<Tweet>,
558    /// Related tweets from TweetDetail.
559    pub related_tweets: Vec<Tweet>,
560    /// Self-thread tweets.
561    pub thread: Vec<Tweet>,
562    /// Raw response JSON.
563    pub raw: Value,
564}
565
566/// Raw request body used by low-level clients.
567pub enum RequestBody {
568    /// JSON request body.
569    Json(Value),
570    /// Form-urlencoded request body.
571    Form(Vec<(String, String)>),
572    /// Multipart request body.
573    Multipart(reqwest::multipart::Form),
574}
575
576impl RequestBody {
577    fn try_clone_replayable(&self) -> Option<Self> {
578        match self {
579            Self::Json(value) => Some(Self::Json(value.clone())),
580            Self::Form(values) => Some(Self::Form(values.clone())),
581            Self::Multipart(_) => None,
582        }
583    }
584}
585
586/// Client builder.
587#[derive(Debug, Clone)]
588pub struct ClientBuilder {
589    language: Option<String>,
590    proxy: Option<String>,
591    user_agent: String,
592    captcha_solver: Option<Capsolver>,
593}
594
595impl Default for ClientBuilder {
596    fn default() -> Self {
597        Self {
598            language: Some("en-US".into()),
599            proxy: None,
600            user_agent: constants::DEFAULT_USER_AGENT.into(),
601            captcha_solver: None,
602        }
603    }
604}
605
606impl ClientBuilder {
607    /// Set language header.
608    pub fn language(mut self, language: impl Into<Option<String>>) -> Self {
609        self.language = language.into();
610        self
611    }
612
613    /// Set HTTP/SOCKS proxy URL.
614    pub fn proxy(mut self, proxy: impl Into<String>) -> Self {
615        let proxy = proxy.into();
616        self.proxy = (!proxy.trim().is_empty()).then_some(proxy);
617        self
618    }
619
620    /// Set user agent.
621    pub fn user_agent(mut self, user_agent: impl Into<String>) -> Self {
622        self.user_agent = user_agent.into();
623        self
624    }
625
626    /// Set captcha solver used by account unlock.
627    pub fn captcha_solver(mut self, captcha_solver: Capsolver) -> Self {
628        self.captcha_solver = Some(captcha_solver);
629        self
630    }
631
632    /// Build authenticated client.
633    pub fn build(self) -> Result<Client> {
634        let inner = InnerClient::new(self.language, self.proxy, self.user_agent, None)?;
635        Ok(Client {
636            inner,
637            captcha_solver: self.captcha_solver,
638        })
639    }
640
641    /// Build guest client.
642    pub fn build_guest(mut self) -> Result<GuestClient> {
643        if self.user_agent == constants::DEFAULT_USER_AGENT {
644            self.user_agent = constants::DEFAULT_GUEST_USER_AGENT.into();
645        }
646        let inner = InnerClient::new(self.language, self.proxy, self.user_agent, None)?;
647        Ok(GuestClient { inner })
648    }
649}
650
651#[derive(Clone)]
652struct InnerClient {
653    http: reqwest::Client,
654    cookie_store: Arc<ReqwestCookieStoreMutex>,
655    language: Option<String>,
656    user_agent: String,
657    token: String,
658    proxy: Option<String>,
659    guest_token: Option<String>,
660    transaction: Arc<Mutex<ClientTransaction>>,
661    act_as: Option<String>,
662}
663
664impl std::fmt::Debug for InnerClient {
665    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
666        f.debug_struct("InnerClient")
667            .field("language", &self.language)
668            .field("user_agent", &self.user_agent)
669            .field("proxy", &self.proxy)
670            .field("guest_token", &self.guest_token)
671            .field("act_as", &self.act_as)
672            .finish_non_exhaustive()
673    }
674}
675
676fn validate_proxy_url(proxy: &str) -> Result<()> {
677    if let Ok(url) = Url::parse(proxy) {
678        match url.scheme() {
679            "http" | "https" | "socks4" | "socks4a" | "socks5" | "socks5h" => Ok(()),
680            scheme => Err(Error::Unsupported(format!(
681                "unsupported proxy scheme: {scheme}; expected http, https, socks4, socks4a, socks5, or socks5h"
682            ))),
683        }
684    } else {
685        // Match reqwest's host:port behavior: it treats a URL without a scheme
686        // as an HTTP proxy by retrying with `http://`.
687        Ok(())
688    }
689}
690
691impl InnerClient {
692    fn build_http(
693        cookie_store: Arc<ReqwestCookieStoreMutex>,
694        user_agent: &str,
695        proxy: Option<&str>,
696    ) -> Result<reqwest::Client> {
697        if let Some(proxy) = proxy {
698            validate_proxy_url(proxy)?;
699        }
700        let mut builder = reqwest::Client::builder()
701            .cookie_provider(cookie_store)
702            .user_agent(user_agent.to_owned());
703        if let Some(proxy) = proxy {
704            let parsed = Url::parse(proxy)?;
705            let proxy_config = match parsed.scheme() {
706                "http" | "https" | "socks4" | "socks4a" | "socks5" | "socks5h" => {
707                    Proxy::all(proxy)?
708                }
709                _ => Proxy::http(proxy)?,
710            };
711            builder = builder.proxy(proxy_config);
712        }
713        Ok(builder.build()?)
714    }
715
716    fn new(
717        language: Option<String>,
718        proxy: Option<String>,
719        user_agent: String,
720        guest_token: Option<String>,
721    ) -> Result<Self> {
722        let cookie_store = Arc::new(ReqwestCookieStoreMutex::new(CookieStore::default()));
723        let http = Self::build_http(cookie_store.clone(), &user_agent, proxy.as_deref())?;
724        Ok(Self {
725            http,
726            cookie_store,
727            language,
728            user_agent,
729            token: TOKEN.into(),
730            proxy,
731            guest_token,
732            transaction: Arc::new(Mutex::new(ClientTransaction::new())),
733            act_as: None,
734        })
735    }
736
737    fn set_proxy(&mut self, proxy: Option<String>) -> Result<()> {
738        let http = Self::build_http(
739            self.cookie_store.clone(),
740            &self.user_agent,
741            proxy.as_deref(),
742        )?;
743        self.http = http;
744        self.proxy = proxy;
745        Ok(())
746    }
747
748    pub(crate) fn base_headers(&self) -> HeaderMap {
749        let mut headers = HeaderMap::new();
750        headers.insert(
751            AUTHORIZATION,
752            HeaderValue::from_str(&format!("Bearer {}", self.token)).expect("valid bearer token"),
753        );
754        headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
755        headers.insert(REFERER, HeaderValue::from_static("https://x.com"));
756        headers.insert(
757            USER_AGENT,
758            HeaderValue::from_str(&self.user_agent).expect("valid user agent"),
759        );
760        headers.insert("X-Twitter-Active-User", HeaderValue::from_static("yes"));
761
762        if let Some(language) = &self.language {
763            if let Ok(value) = HeaderValue::from_str(language) {
764                headers.insert(ACCEPT_LANGUAGE, value.clone());
765                headers.insert("X-Twitter-Client-Language", value);
766            }
767        }
768        if let Some(token) = &self.guest_token {
769            if let Ok(value) = HeaderValue::from_str(token) {
770                headers.insert("X-Guest-Token", value);
771            }
772        }
773        if let Ok(guard) = self.cookie_store.lock() {
774            if let Some(token) = guard
775                .iter_unexpired()
776                .find(|cookie| cookie.name() == "ct0")
777                .map(|cookie| cookie.value().to_string())
778            {
779                if let Ok(value) = HeaderValue::from_str(&token) {
780                    headers.insert("X-Csrf-Token", value);
781                }
782            }
783        }
784        if let Some(act_as) = &self.act_as {
785            if let Ok(value) = HeaderValue::from_str(act_as) {
786                headers.insert(
787                    "X-Twitter-Auth-Type",
788                    HeaderValue::from_static("OAuth2Session"),
789                );
790                headers.insert("X-Act-As-User-Id", value);
791            }
792        }
793        headers
794    }
795
796    fn remove_duplicate_ct0_cookie(&self) -> Result<()> {
797        let mut guard = self
798            .cookie_store
799            .lock()
800            .map_err(|e| Error::Cookie(e.to_string()))?;
801        let duplicate_keys: Vec<(String, String)> = guard
802            .iter_any()
803            .filter(|cookie| cookie.name() == "ct0")
804            .filter_map(|cookie| {
805                Some((
806                    cookie.domain.as_cow()?.into_owned(),
807                    cookie.path.as_ref().to_owned(),
808                ))
809            })
810            .skip(1)
811            .collect();
812
813        for (domain, path) in duplicate_keys {
814            guard.remove(&domain, &path, "ct0");
815        }
816        Ok(())
817    }
818
819    fn twid_user_id(&self) -> Result<Option<String>> {
820        let guard = self
821            .cookie_store
822            .lock()
823            .map_err(|e| Error::Cookie(e.to_string()))?;
824        let Some(twid) = guard
825            .iter_unexpired()
826            .find(|cookie| cookie.name() == "twid")
827            .map(|cookie| cookie.value().to_string())
828        else {
829            return Ok(None);
830        };
831        let decoded = percent_decode_str(&twid).decode_utf8_lossy();
832        Ok(decoded
833            .strip_prefix("u=")
834            .filter(|id| id.chars().all(|ch| ch.is_ascii_digit()))
835            .map(ToOwned::to_owned))
836    }
837
838    pub(crate) async fn request(
839        &self,
840        method: Method,
841        url: String,
842        headers: Option<HeaderMap>,
843        params: Option<Vec<(String, String)>>,
844        body: Option<RequestBody>,
845        raise_exception: bool,
846    ) -> Result<Value> {
847        let parsed = Url::parse(&url)?;
848        let mut merged = self.base_headers();
849        if let Some(extra) = headers {
850            merged.extend(extra);
851        }
852        let tid = {
853            let mut transaction = self.transaction.lock().await;
854            let path = parsed.path().to_owned();
855            if !transaction.is_initialized() {
856                let init_headers = merged.clone();
857                let http = self.http.clone();
858                let _ = transaction.init(&http, init_headers).await;
859            }
860            transaction.generate(method.as_str(), &path)
861        };
862        merged.insert(
863            "X-Client-Transaction-Id",
864            HeaderValue::from_str(&tid).expect("transaction id is header-safe"),
865        );
866
867        let mut req = self.http.request(method, parsed).headers(merged);
868        if let Some(params) = params {
869            req = req.query(&params);
870        }
871        if let Some(body) = body {
872            req = match body {
873                RequestBody::Json(json_body) => req.json(&json_body),
874                RequestBody::Form(form) => req.form(&form),
875                RequestBody::Multipart(multipart) => req.multipart(multipart),
876            };
877        }
878
879        let response = req.send().await?;
880        let _ = self.remove_duplicate_ct0_cookie();
881        let status = response.status().as_u16();
882        let headers = response.headers().clone();
883        let text = response.text().await?;
884        let json = serde_json::from_str::<Value>(&text).unwrap_or(Value::String(text.clone()));
885
886        if let Some(kind) = api_error_from_json(&json) {
887            if raise_exception {
888                return Err(Error::Api {
889                    kind,
890                    status,
891                    headers: Box::new(headers),
892                    body: text,
893                    json: Some(json),
894                });
895            }
896        }
897
898        if status >= 400 && raise_exception {
899            return Err(Error::Api {
900                kind: kind_for_status(status),
901                status,
902                headers: Box::new(headers),
903                body: text,
904                json: if json.is_string() { None } else { Some(json) },
905            });
906        }
907
908        Ok(json)
909    }
910
911    pub(crate) async fn request_response(
912        &self,
913        method: Method,
914        url: String,
915        headers: Option<HeaderMap>,
916        params: Option<Vec<(String, String)>>,
917        body: Option<RequestBody>,
918    ) -> Result<RawApiResponse> {
919        let parsed = Url::parse(&url)?;
920        let mut merged = self.base_headers();
921        if let Some(extra) = headers {
922            merged.extend(extra);
923        }
924        let tid = {
925            let mut transaction = self.transaction.lock().await;
926            let path = parsed.path().to_owned();
927            if !transaction.is_initialized() {
928                let init_headers = merged.clone();
929                let http = self.http.clone();
930                let _ = transaction.init(&http, init_headers).await;
931            }
932            transaction.generate(method.as_str(), &path)
933        };
934        merged.insert(
935            "X-Client-Transaction-Id",
936            HeaderValue::from_str(&tid).expect("transaction id is header-safe"),
937        );
938
939        let mut req = self.http.request(method, parsed).headers(merged);
940        if let Some(params) = params {
941            req = req.query(&params);
942        }
943        if let Some(body) = body {
944            req = match body {
945                RequestBody::Json(json_body) => req.json(&json_body),
946                RequestBody::Form(form) => req.form(&form),
947                RequestBody::Multipart(multipart) => req.multipart(multipart),
948            };
949        }
950
951        let response = req.send().await?;
952        let _ = self.remove_duplicate_ct0_cookie();
953        let status = response.status().as_u16();
954        let headers = response.headers().clone();
955        let body = response.text().await?;
956        let json = serde_json::from_str::<Value>(&body).ok();
957        Ok(RawApiResponse {
958            status,
959            headers,
960            body,
961            json,
962        })
963    }
964
965    async fn gql_get(
966        &self,
967        endpoint: GqlEndpoint,
968        variables: Value,
969        features: Option<Value>,
970        extra_params: Option<Value>,
971    ) -> Result<Value> {
972        let mut params = vec![("variables".to_string(), variables)];
973        if let Some(features) = features {
974            params.push(("features".to_string(), features));
975        }
976        if let Some(Value::Object(map)) = extra_params {
977            for (k, v) in map {
978                params.push((k, v));
979            }
980        }
981        let params = flatten_params(&params)?;
982        let json = self
983            .request(Method::GET, endpoint.url(), None, Some(params), None, true)
984            .await?;
985        Ok(json)
986    }
987
988    async fn gql_post(
989        &self,
990        endpoint: GqlEndpoint,
991        variables: Value,
992        features: Option<Value>,
993        extra_data: Option<Value>,
994    ) -> Result<Value> {
995        let mut body = json!({
996            "variables": variables,
997            "queryId": endpoint.query_id
998        });
999        if let Some(features) = features {
1000            body["features"] = features;
1001        }
1002        if let (Some(obj), Some(extra)) = (
1003            body.as_object_mut(),
1004            extra_data.and_then(|v| v.as_object().cloned()),
1005        ) {
1006            obj.extend(extra);
1007        }
1008        let json = self
1009            .request(
1010                Method::POST,
1011                endpoint.url(),
1012                None,
1013                None,
1014                Some(RequestBody::Json(body)),
1015                true,
1016            )
1017            .await?;
1018        Ok(json)
1019    }
1020}
1021
1022fn api_error_from_json(json: &Value) -> Option<ApiErrorKind> {
1023    let first_error = json
1024        .get("errors")
1025        .and_then(Value::as_array)
1026        .and_then(|errors| errors.first())?;
1027    let code = first_error.get("code").and_then(Value::as_i64)?;
1028    let message = first_error
1029        .get("message")
1030        .and_then(Value::as_str)
1031        .unwrap_or_default()
1032        .to_ascii_lowercase();
1033    match code {
1034        37 | 64 if message.contains("suspend") => Some(ApiErrorKind::AccountSuspended),
1035        50 => Some(ApiErrorKind::UserNotFound),
1036        63 => Some(ApiErrorKind::UserUnavailable),
1037        144 => Some(ApiErrorKind::TweetNotAvailable),
1038        187 => Some(ApiErrorKind::DuplicateTweet),
1039        324 => Some(ApiErrorKind::InvalidMedia),
1040        326 => Some(ApiErrorKind::AccountLocked),
1041        _ => None,
1042    }
1043}
1044
1045fn login_start_data() -> Value {
1046    serde_json::from_str(
1047        r#"{
1048            "input_flow_data": {
1049                "flow_context": {
1050                    "debug_overrides": {},
1051                    "start_location": {"location": "splash_screen"}
1052                }
1053            },
1054            "subtask_versions": {
1055                "action_list": 2,
1056                "alert_dialog": 1,
1057                "app_download_cta": 1,
1058                "check_logged_in_account": 1,
1059                "choice_selection": 3,
1060                "contacts_live_sync_permission_prompt": 0,
1061                "cta": 7,
1062                "email_verification": 2,
1063                "end_flow": 1,
1064                "enter_date": 1,
1065                "enter_email": 2,
1066                "enter_password": 5,
1067                "enter_phone": 2,
1068                "enter_recaptcha": 1,
1069                "enter_text": 5,
1070                "enter_username": 2,
1071                "generic_urt": 3,
1072                "in_app_notification": 1,
1073                "interest_picker": 3,
1074                "js_instrumentation": 1,
1075                "menu_dialog": 1,
1076                "notifications_permission_prompt": 2,
1077                "open_account": 2,
1078                "open_home_timeline": 1,
1079                "open_link": 1,
1080                "phone_verification": 4,
1081                "privacy_options": 1,
1082                "security_key": 3,
1083                "select_avatar": 4,
1084                "select_banner": 2,
1085                "settings_list": 7,
1086                "show_code": 1,
1087                "sign_up": 2,
1088                "sign_up_review": 4,
1089                "tweet_selection_urt": 1,
1090                "update_users": 1,
1091                "upload_media": 1,
1092                "user_recommendations_list": 4,
1093                "user_recommendations_urt": 1,
1094                "wait_spinner": 3,
1095                "web_modal": 1
1096            }
1097        }"#,
1098    )
1099    .expect("valid login start data")
1100}
1101
1102fn ensure_login_not_denied(flow: &Flow) -> Result<()> {
1103    if flow.task_id() == Some("DenyLoginSubtask") {
1104        return Err(Error::Interactive(
1105            flow_secondary_text(flow).unwrap_or("login denied").into(),
1106        ));
1107    }
1108    Ok(())
1109}
1110
1111fn flow_secondary_text(flow: &Flow) -> Option<&str> {
1112    fn walk(value: &Value) -> Option<&str> {
1113        match value {
1114            Value::Object(map) => {
1115                if let Some(text) = map
1116                    .get("secondary_text")
1117                    .and_then(|value| value.get("text"))
1118                    .and_then(Value::as_str)
1119                {
1120                    return Some(text);
1121                }
1122                map.values().find_map(walk)
1123            }
1124            Value::Array(values) => values.iter().find_map(walk),
1125            _ => None,
1126        }
1127    }
1128    flow.response.as_ref().and_then(walk)
1129}
1130
1131async fn submit_login_text(
1132    flow: &mut Flow,
1133    client: &Client,
1134    subtask_id: &str,
1135    text: &str,
1136) -> Result<()> {
1137    flow.execute_task(
1138        client,
1139        Some(json!({
1140            "subtask_id": subtask_id,
1141            "enter_text": {
1142                "text": text,
1143                "link": "next_link"
1144            }
1145        })),
1146        None,
1147        None,
1148    )
1149    .await
1150}
1151
1152async fn complete_account_duplication_check(flow: &mut Flow, client: &Client) -> Result<()> {
1153    if flow.task_id() == Some("AccountDuplicationCheck") {
1154        flow.execute_task(
1155            client,
1156            Some(json!({
1157                "subtask_id": "AccountDuplicationCheck",
1158                "check_logged_in_account": {
1159                    "link": "AccountDuplicationCheck_false"
1160                }
1161            })),
1162            None,
1163            None,
1164        )
1165        .await?;
1166    }
1167    Ok(())
1168}
1169
1170/// Authenticated Twitter/X client.
1171#[derive(Debug, Clone)]
1172pub struct Client {
1173    inner: InnerClient,
1174    captcha_solver: Option<Capsolver>,
1175}
1176
1177impl Client {
1178    fn pageable_gql_timeline<T, F>(
1179        &self,
1180        raw: Value,
1181        method: GqlPageMethod,
1182        endpoint: GqlEndpoint,
1183        features: Option<Value>,
1184        build_variables: F,
1185        parse: fn(Value, &Client) -> Timeline<T>,
1186    ) -> Timeline<T>
1187    where
1188        T: 'static,
1189        F: Fn(String) -> Value + Clone + Send + Sync + 'static,
1190    {
1191        let parser: TimelineParser<T> = Arc::new(parse);
1192        let build_variables: Arc<dyn Fn(String) -> Value + Send + Sync> = Arc::new(build_variables);
1193        self.pageable_gql_timeline_from_parser(
1194            raw,
1195            method,
1196            endpoint,
1197            features,
1198            build_variables,
1199            parser,
1200        )
1201    }
1202
1203    fn pageable_gql_timeline_from_parser<T>(
1204        &self,
1205        raw: Value,
1206        method: GqlPageMethod,
1207        endpoint: GqlEndpoint,
1208        features: Option<Value>,
1209        build_variables: Arc<dyn Fn(String) -> Value + Send + Sync>,
1210        parse: TimelineParser<T>,
1211    ) -> Timeline<T>
1212    where
1213        T: 'static,
1214    {
1215        let fetch = {
1216            let client = self.clone();
1217            let parser = parse.clone();
1218            let build_variables = build_variables.clone();
1219            let features = features.clone();
1220            Arc::new(move |cursor: String| {
1221                let client = client.clone();
1222                let parser = parser.clone();
1223                let build_variables = build_variables.clone();
1224                let features = features.clone();
1225                async move {
1226                    let raw = match method {
1227                        GqlPageMethod::Get => {
1228                            client
1229                                .inner
1230                                .gql_get(endpoint, build_variables(cursor), features.clone(), None)
1231                                .await?
1232                        }
1233                        GqlPageMethod::Post => {
1234                            client
1235                                .inner
1236                                .gql_post(endpoint, build_variables(cursor), features.clone(), None)
1237                                .await?
1238                        }
1239                    };
1240                    Ok(client.pageable_gql_timeline_from_parser(
1241                        raw,
1242                        method,
1243                        endpoint,
1244                        features,
1245                        build_variables,
1246                        parser,
1247                    ))
1248                }
1249                .boxed()
1250            })
1251        };
1252        parse(raw, self).with_page_fetchers(Some(fetch.clone()), Some(fetch))
1253    }
1254
1255    async fn search_timeline_raw(
1256        &self,
1257        variables: Value,
1258        features: Option<Value>,
1259    ) -> Result<(Value, GqlEndpoint)> {
1260        match self
1261            .inner
1262            .gql_post(
1263                endpoints::SEARCH_TIMELINE,
1264                variables.clone(),
1265                features.clone(),
1266                None,
1267            )
1268            .await
1269        {
1270            Ok(raw) => Ok((raw, endpoints::SEARCH_TIMELINE)),
1271            Err(Error::Api {
1272                kind: ApiErrorKind::NotFound,
1273                ..
1274            }) => self
1275                .inner
1276                .gql_post(endpoints::SEARCH_TIMELINE_ALT, variables, features, None)
1277                .await
1278                .map(|raw| (raw, endpoints::SEARCH_TIMELINE_ALT)),
1279            Err(err) => Err(err),
1280        }
1281    }
1282
1283    fn pageable_v11_timeline<T, F>(
1284        &self,
1285        raw: Value,
1286        build_url_params: F,
1287        parse: fn(Value, &Client) -> Timeline<T>,
1288    ) -> Timeline<T>
1289    where
1290        T: 'static,
1291        F: Fn(String) -> (String, Vec<(String, String)>) + Send + Sync + 'static,
1292    {
1293        let build_url_params: Arc<dyn Fn(String) -> (String, Vec<(String, String)>) + Send + Sync> =
1294            Arc::new(build_url_params);
1295        let parser: TimelineParser<T> = Arc::new(parse);
1296        self.pageable_v11_timeline_from_parser(raw, build_url_params, parser)
1297    }
1298
1299    fn pageable_v11_timeline_from_parser<T>(
1300        &self,
1301        raw: Value,
1302        build_url_params: Arc<dyn Fn(String) -> (String, Vec<(String, String)>) + Send + Sync>,
1303        parse: TimelineParser<T>,
1304    ) -> Timeline<T>
1305    where
1306        T: 'static,
1307    {
1308        let fetch = {
1309            let client = self.clone();
1310            let build_url_params = build_url_params.clone();
1311            let parser = parse.clone();
1312            Arc::new(move |cursor: String| {
1313                let client = client.clone();
1314                let build_url_params = build_url_params.clone();
1315                let parser = parser.clone();
1316                async move {
1317                    let (url, params) = build_url_params(cursor);
1318                    let raw = client
1319                        .inner
1320                        .request(Method::GET, url, None, Some(params), None, true)
1321                        .await?;
1322                    Ok(client.pageable_v11_timeline_from_parser(raw, build_url_params, parser))
1323                }
1324                .boxed()
1325            })
1326        };
1327        parse(raw, self).with_page_fetchers(Some(fetch.clone()), Some(fetch))
1328    }
1329
1330    /// Start building a client.
1331    pub fn builder() -> ClientBuilder {
1332        ClientBuilder::default()
1333    }
1334
1335    /// Create a client with default settings.
1336    pub fn new(language: impl Into<Option<String>>) -> Result<Self> {
1337        ClientBuilder::default().language(language).build()
1338    }
1339
1340    /// Low-level GraphQL GET for wrappers.
1341    pub async fn gql_get_raw(
1342        &self,
1343        endpoint: GqlEndpoint,
1344        variables: Value,
1345        features: Option<Value>,
1346        extra_params: Option<Value>,
1347    ) -> Result<Value> {
1348        self.inner
1349            .gql_get(endpoint, variables, features, extra_params)
1350            .await
1351    }
1352
1353    /// Low-level GraphQL POST for wrappers.
1354    pub async fn gql_post_raw(
1355        &self,
1356        endpoint: GqlEndpoint,
1357        variables: Value,
1358        features: Option<Value>,
1359        extra_data: Option<Value>,
1360    ) -> Result<Value> {
1361        self.inner
1362            .gql_post(endpoint, variables, features, extra_data)
1363            .await
1364    }
1365
1366    /// Base headers for low-level wrappers.
1367    pub fn base_headers(&self) -> HeaderMap {
1368        self.inner.base_headers()
1369    }
1370
1371    /// Python parity alias for base headers.
1372    pub fn _base_headers(&self) -> HeaderMap {
1373        self.base_headers()
1374    }
1375
1376    /// Python parity CSRF helper.
1377    pub fn _get_csrf_token(&self) -> Option<String> {
1378        let guard = self.inner.cookie_store.lock().ok()?;
1379        let token = guard
1380            .iter_unexpired()
1381            .find(|cookie| cookie.name() == "ct0")
1382            .map(|cookie| cookie.value().to_string());
1383        token
1384    }
1385
1386    /// Python parity duplicate-cookie cleanup helper.
1387    pub fn _remove_duplicate_ct0_cookie(&self) {
1388        let _ = self.inner.remove_duplicate_ct0_cookie();
1389    }
1390
1391    /// Set captcha solver used by account unlock.
1392    pub fn set_captcha_solver(&mut self, captcha_solver: Option<Capsolver>) {
1393        self.captcha_solver = captcha_solver;
1394    }
1395
1396    /// Clear all stored cookies.
1397    pub fn clear_cookies(&self) -> Result<()> {
1398        let mut guard = self
1399            .inner
1400            .cookie_store
1401            .lock()
1402            .map_err(|e| Error::Cookie(e.to_string()))?;
1403        guard.clear();
1404        Ok(())
1405    }
1406
1407    /// Raw request for low-level wrappers.
1408    pub async fn request_raw(
1409        &self,
1410        method: Method,
1411        url: impl Into<String>,
1412        headers: Option<HeaderMap>,
1413        params: Option<Vec<(String, String)>>,
1414        body: Option<RequestBody>,
1415        raise_exception: bool,
1416    ) -> Result<Value> {
1417        self.inner
1418            .request(method, url.into(), headers, params, body, raise_exception)
1419            .await
1420    }
1421
1422    /// Python parity raw request with options, including auto-unlock retry.
1423    pub async fn request_with_options(
1424        &self,
1425        method: Method,
1426        url: impl Into<String>,
1427        options: RequestOptions,
1428    ) -> Result<Value> {
1429        let url = url.into();
1430        let body_was_some = options.body.is_some();
1431        let retry_body = options
1432            .body
1433            .as_ref()
1434            .and_then(RequestBody::try_clone_replayable);
1435        let retry_headers = options.headers.clone();
1436        let retry_params = options.params.clone();
1437        let cookies_backup = self.cookie_store_snapshot()?;
1438        let result = self
1439            .inner
1440            .request(
1441                method.clone(),
1442                url.clone(),
1443                options.headers,
1444                options.params,
1445                options.body,
1446                options.raise_exception,
1447            )
1448            .await;
1449
1450        match result {
1451            Err(Error::Api {
1452                kind: ApiErrorKind::AccountLocked,
1453                ..
1454            }) if options.auto_unlock => {
1455                if body_was_some && retry_body.is_none() {
1456                    return Err(Error::Unsupported(
1457                        "cannot auto-unlock retry non-replayable multipart request".into(),
1458                    ));
1459                }
1460                self.unlock().await?;
1461                self.restore_cookie_store(cookies_backup)?;
1462                self.inner
1463                    .request(
1464                        method,
1465                        url,
1466                        retry_headers,
1467                        retry_params,
1468                        retry_body,
1469                        options.raise_exception,
1470                    )
1471                    .await
1472            }
1473            other => other,
1474        }
1475    }
1476
1477    /// Raw request returning response metadata and body.
1478    pub async fn request_response(
1479        &self,
1480        method: Method,
1481        url: impl Into<String>,
1482        options: RequestOptions,
1483    ) -> Result<RawApiResponse> {
1484        self.inner
1485            .request_response(
1486                method,
1487                url.into(),
1488                options.headers,
1489                options.params,
1490                options.body,
1491            )
1492            .await
1493    }
1494
1495    /// Python parity guest token helper.
1496    pub async fn _get_guest_token(&self) -> Result<String> {
1497        let mut guest = GuestClient {
1498            inner: self.inner.clone(),
1499        };
1500        guest.activate().await
1501    }
1502
1503    /// Python parity ui_metrics helper.
1504    pub async fn _ui_metrics(&self) -> Result<String> {
1505        let endpoint = if let Ok(base) = std::env::var("TWIKIT_RS_WEB_BASE") {
1506            format!("{}/i/js_inst?c_name=ui_metrics", base.trim_end_matches('/'))
1507        } else {
1508            "https://twitter.com/i/js_inst?c_name=ui_metrics".to_string()
1509        };
1510        let response = self.get(endpoint).await?;
1511        match response {
1512            Value::String(script) => solve_ui_metrics(&script),
1513            Value::Object(_) => Ok(response.to_string()),
1514            other => Err(Error::Interactive(format!(
1515                "unexpected ui_metrics response: {other}"
1516            ))),
1517        }
1518    }
1519
1520    /// Raw GET request.
1521    pub async fn get(&self, url: impl Into<String>) -> Result<Value> {
1522        self.inner
1523            .request(Method::GET, url.into(), None, None, None, true)
1524            .await
1525    }
1526
1527    /// Python parity raw request.
1528    pub async fn request(&self, method: Method, url: impl Into<String>) -> Result<Value> {
1529        self.inner
1530            .request(method, url.into(), None, None, None, true)
1531            .await
1532    }
1533
1534    /// Python parity raw POST alias.
1535    pub async fn post(&self, url: impl Into<String>, body: Option<Value>) -> Result<Value> {
1536        self.inner
1537            .request(
1538                Method::POST,
1539                url.into(),
1540                None,
1541                None,
1542                body.map(RequestBody::Json),
1543                true,
1544            )
1545            .await
1546    }
1547
1548    /// Current proxy URL if configured.
1549    pub fn proxy(&self) -> Option<String> {
1550        self.inner.proxy.clone()
1551    }
1552
1553    /// Set or clear proxy, preserving cookies and guest token.
1554    pub fn set_proxy(&mut self, proxy: Option<String>) -> Result<()> {
1555        self.inner.set_proxy(proxy)
1556    }
1557
1558    /// Raw POST JSON request.
1559    pub async fn post_json(&self, url: impl Into<String>, body: Value) -> Result<Value> {
1560        self.inner
1561            .request(
1562                Method::POST,
1563                url.into(),
1564                None,
1565                None,
1566                Some(RequestBody::Json(body)),
1567                true,
1568            )
1569            .await
1570    }
1571
1572    /// Raw POST form request.
1573    pub async fn post_form(
1574        &self,
1575        url: impl Into<String>,
1576        form: Vec<(String, String)>,
1577    ) -> Result<Value> {
1578        self.inner
1579            .request(
1580                Method::POST,
1581                url.into(),
1582                None,
1583                None,
1584                Some(RequestBody::Form(form)),
1585                true,
1586            )
1587            .await
1588    }
1589
1590    /// Load cookies from a JSON file produced by twikit or this crate.
1591    pub async fn load_cookies(&self, path: impl AsRef<Path>) -> Result<()> {
1592        load_cookies(self.inner.cookie_store.clone(), path.as_ref()).await
1593    }
1594
1595    /// Load browser-exported cookies shaped as `{ "cookies": [{ "name", "value", ... }] }`.
1596    pub async fn load_browser_cookies(&self, path: impl AsRef<Path>) -> Result<()> {
1597        let bytes = fs::read(path).await?;
1598        self.set_browser_cookies(parse_browser_cookies_json(&bytes)?)
1599    }
1600
1601    /// Save cookies to JSON.
1602    pub async fn save_cookies(&self, path: impl AsRef<Path>) -> Result<()> {
1603        save_cookies(self.inner.cookie_store.clone(), path.as_ref()).await
1604    }
1605
1606    /// Return cookies as a JSON-compatible object.
1607    pub fn get_cookies(&self) -> Result<Value> {
1608        let mut bytes = Vec::new();
1609        {
1610            let guard = self
1611                .inner
1612                .cookie_store
1613                .lock()
1614                .map_err(|e| Error::Cookie(e.to_string()))?;
1615            #[allow(deprecated)]
1616            guard
1617                .save_json(&mut bytes)
1618                .map_err(|e| Error::Cookie(e.to_string()))?;
1619        }
1620        Ok(serde_json::from_slice(&bytes)?)
1621    }
1622
1623    /// Replace cookies from a JSON-compatible cookie-store value.
1624    pub fn set_cookies(&self, cookies: Value) -> Result<()> {
1625        let bytes = serde_json::to_vec(&cookies)?;
1626        #[allow(deprecated)]
1627        let loaded = CookieStore::load_json(std::io::Cursor::new(bytes))
1628            .map_err(|e| Error::Cookie(e.to_string()))?;
1629        let mut guard = self
1630            .inner
1631            .cookie_store
1632            .lock()
1633            .map_err(|e| Error::Cookie(e.to_string()))?;
1634        *guard = loaded;
1635        Ok(())
1636    }
1637
1638    /// Replace cookies from a browser-style cookie export.
1639    pub fn set_browser_cookies(&self, cookies: Value) -> Result<()> {
1640        let loaded = browser_cookie_store(&cookies)?;
1641        let mut guard = self
1642            .inner
1643            .cookie_store
1644            .lock()
1645            .map_err(|e| Error::Cookie(e.to_string()))?;
1646        *guard = loaded;
1647        Ok(())
1648    }
1649
1650    /// Set delegated account id for subsequent requests.
1651    pub fn set_delegate_account(&mut self, user_id: Option<String>) {
1652        self.inner.act_as = user_id;
1653    }
1654
1655    /// Logout authenticated account.
1656    pub async fn logout(&self) -> Result<Value> {
1657        self.post_json(endpoints::v11::account_logout(), json!({}))
1658            .await
1659    }
1660
1661    /// Login through onboarding flow.
1662    ///
1663    /// This is the Rust entrypoint matching Python's method name. The complete
1664    /// interactive subtasks are exposed through `V11Client::onboarding_task`;
1665    /// callers can persist cookies with `save_cookies` after successful login.
1666    pub async fn login(
1667        &self,
1668        auth_info_1: &str,
1669        auth_info_2: Option<&str>,
1670        password: &str,
1671    ) -> Result<()> {
1672        self.login_with_options(auth_info_1, auth_info_2, password, LoginOptions::default())
1673            .await
1674    }
1675
1676    /// Login through onboarding flow with an explicit 2FA/challenge code.
1677    ///
1678    /// Python twikit can prompt for 2FA or derive it from `totp_secret`. This
1679    /// non-interactive variant lets Rust callers provide the already computed
1680    /// verification code while preserving the existing `login` signature.
1681    pub async fn login_with_verification_code(
1682        &self,
1683        auth_info_1: &str,
1684        auth_info_2: Option<&str>,
1685        password: &str,
1686        verification_code: Option<&str>,
1687    ) -> Result<()> {
1688        self.login_with_options(
1689            auth_info_1,
1690            auth_info_2,
1691            password,
1692            LoginOptions {
1693                verification_code: verification_code.map(ToOwned::to_owned),
1694                ..Default::default()
1695            },
1696        )
1697        .await
1698    }
1699
1700    /// Login through onboarding flow with Python twikit-style options.
1701    pub async fn login_with_options(
1702        &self,
1703        auth_info_1: &str,
1704        auth_info_2: Option<&str>,
1705        password: &str,
1706        options: LoginOptions,
1707    ) -> Result<()> {
1708        self.clear_cookies()?;
1709        if let Some(path) = options.cookies_file.as_deref() {
1710            if fs::try_exists(path).await? {
1711                self.load_cookies(path).await?;
1712                return Ok(());
1713            }
1714        }
1715
1716        let guest_token = self._get_guest_token().await?;
1717        let mut flow = Flow::new(guest_token);
1718
1719        flow.execute_task(
1720            self,
1721            None,
1722            Some(vec![("flow_name".into(), "login".into())]),
1723            Some(login_start_data()),
1724        )
1725        .await?;
1726        flow.sso_init(self, "apple").await?;
1727
1728        let ui_metrics_response = if options.ui_metrics_enabled() {
1729            self._ui_metrics().await.unwrap_or_default()
1730        } else {
1731            String::new()
1732        };
1733        flow.execute_task(
1734            self,
1735            Some(json!({
1736                "subtask_id": "LoginJsInstrumentationSubtask",
1737                "js_instrumentation": {
1738                    "response": ui_metrics_response,
1739                    "link": "next_link"
1740                }
1741            })),
1742            None,
1743            None,
1744        )
1745        .await?;
1746
1747        flow.execute_task(
1748            self,
1749            Some(json!({
1750                "subtask_id": "LoginEnterUserIdentifierSSO",
1751                "settings_list": {
1752                    "setting_responses": [{
1753                        "key": "user_identifier",
1754                        "response_data": {
1755                            "text_data": {"result": auth_info_1}
1756                        }
1757                    }],
1758                    "link": "next_link"
1759                }
1760            })),
1761            None,
1762            None,
1763        )
1764        .await?;
1765
1766        if flow.task_id() == Some("LoginEnterAlternateIdentifierSubtask") {
1767            let auth_info_2 = auth_info_2.ok_or(Error::Missing("auth_info_2"))?;
1768            flow.execute_task(
1769                self,
1770                Some(json!({
1771                    "subtask_id": "LoginEnterAlternateIdentifierSubtask",
1772                    "enter_text": {
1773                        "text": auth_info_2,
1774                        "link": "next_link"
1775                    }
1776                })),
1777                None,
1778                None,
1779            )
1780            .await?;
1781        }
1782
1783        ensure_login_not_denied(&flow)?;
1784
1785        flow.execute_task(
1786            self,
1787            Some(json!({
1788                "subtask_id": "LoginEnterPassword",
1789                "enter_password": {
1790                    "password": password,
1791                    "link": "next_link"
1792                }
1793            })),
1794            None,
1795            None,
1796        )
1797        .await?;
1798
1799        ensure_login_not_denied(&flow)?;
1800
1801        if flow.task_id() == Some("LoginAcid") {
1802            let auth_info_2 = auth_info_2.ok_or(Error::Missing("auth_info_2"))?;
1803            submit_login_text(&mut flow, self, "LoginAcid", auth_info_2).await?;
1804            ensure_login_not_denied(&flow)?;
1805        }
1806
1807        if flow.task_id() == Some("LoginTwoFactorAuthChallenge") {
1808            let computed_totp = if let Some(secret) = options.totp_secret.as_deref() {
1809                Some(current_totp(secret)?)
1810            } else {
1811                None
1812            };
1813            let code = options
1814                .verification_code
1815                .as_deref()
1816                .or(computed_totp.as_deref())
1817                .or(auth_info_2)
1818                .ok_or(Error::Missing("verification_code"))?;
1819            submit_login_text(&mut flow, self, "LoginTwoFactorAuthChallenge", code).await?;
1820            ensure_login_not_denied(&flow)?;
1821        }
1822
1823        complete_account_duplication_check(&mut flow, self).await?;
1824        if let Some(path) = options.cookies_file.as_deref() {
1825            self.save_cookies(path).await?;
1826        }
1827
1828        Ok(())
1829    }
1830
1831    /// Unlock account through configured captcha solver.
1832    pub async fn unlock(&self) -> Result<()> {
1833        let solver = self
1834            .captcha_solver
1835            .as_ref()
1836            .ok_or_else(|| Error::Interactive("captcha solver is not provided".into()))?;
1837        let mut html = solver.get_unlock_html_for(self).await?;
1838
1839        if html.delete_button {
1840            html = solver.confirm_unlock_for(self, &html, None, true).await?;
1841        }
1842
1843        if html.start_button || html.finish_button {
1844            html = solver.confirm_unlock_for(self, &html, None, true).await?;
1845        }
1846
1847        let cookies_backup = self.cookie_store_snapshot()?;
1848        for _ in 0..solver.max_attempts.max(1) {
1849            if html.authenticity_token.is_none() {
1850                html = solver.get_unlock_html_for(self).await?;
1851            }
1852
1853            let blob = html.blob.clone().unwrap_or_default();
1854            let result = solver.solve_funcaptcha(&blob).await?;
1855            if result.get("errorId").and_then(Value::as_i64) == Some(1) {
1856                continue;
1857            }
1858            let token = result
1859                .pointer("/solution/token")
1860                .and_then(Value::as_str)
1861                .ok_or(Error::Missing("solution.token"))?;
1862
1863            self.restore_cookie_store(cookies_backup.clone())?;
1864            html = solver
1865                .confirm_unlock_for(self, &html, Some(token), false)
1866                .await?;
1867
1868            if html.finish_button {
1869                html = solver.confirm_unlock_for(self, &html, None, true).await?;
1870            }
1871            if !html.needs_unlock && !html.start_button && !html.finish_button {
1872                return Ok(());
1873            }
1874        }
1875
1876        Err(Error::Interactive("could not unlock the account".into()))
1877    }
1878
1879    fn cookie_store_snapshot(&self) -> Result<CookieStore> {
1880        self.inner
1881            .cookie_store
1882            .lock()
1883            .map(|guard| guard.clone())
1884            .map_err(|e| Error::Cookie(e.to_string()))
1885    }
1886
1887    fn restore_cookie_store(&self, cookies: CookieStore) -> Result<()> {
1888        let mut guard = self
1889            .inner
1890            .cookie_store
1891            .lock()
1892            .map_err(|e| Error::Cookie(e.to_string()))?;
1893        *guard = cookies;
1894        Ok(())
1895    }
1896
1897    /// Search tweets.
1898    pub async fn search_tweet(
1899        &self,
1900        query: impl Into<String>,
1901        product: TweetSearchProduct,
1902        count: i64,
1903        cursor: Option<String>,
1904    ) -> Result<Timeline<Tweet>> {
1905        let query = query.into();
1906        let features = Some(constants::features());
1907        let (raw, endpoint) = self
1908            .search_timeline_raw(
1909                search_tweet_variables(query.clone(), product, count, cursor.clone()),
1910                features.clone(),
1911            )
1912            .await?;
1913        Ok(self.pageable_gql_timeline(
1914            raw,
1915            GqlPageMethod::Post,
1916            endpoint,
1917            features,
1918            move |cursor| search_tweet_variables(query.clone(), product, count, Some(cursor)),
1919            parse_tweet_timeline,
1920        ))
1921    }
1922
1923    /// Get user by screen name.
1924    pub async fn get_user_by_screen_name(&self, screen_name: impl Into<String>) -> Result<User> {
1925        let screen_name = screen_name.into();
1926        let raw = self
1927            .inner
1928            .gql_get(
1929                endpoints::USER_BY_SCREEN_NAME,
1930                json!({
1931                    "screen_name": screen_name.clone(),
1932                    "withGrokTranslatedBio": false,
1933                    "withSafetyModeUserFields": true
1934                }),
1935                Some(constants::user_features()),
1936                None,
1937            )
1938            .await?;
1939        let result = match raw.pointer("/data/user/result").cloned() {
1940            Some(result) => result,
1941            None => {
1942                let raw = self
1943                    .inner
1944                    .request(
1945                        Method::GET,
1946                        endpoints::v11::users_show(),
1947                        None,
1948                        Some(vec![("screen_name".to_string(), screen_name)]),
1949                        None,
1950                        true,
1951                    )
1952                    .await?;
1953                build_user_data(&raw)
1954            }
1955        };
1956        User::from_value_with_client(result, Some(self.clone()))
1957    }
1958
1959    /// Get user by id.
1960    pub async fn get_user_by_id(&self, user_id: impl Into<String>) -> Result<User> {
1961        let raw = self
1962            .inner
1963            .gql_get(
1964                endpoints::USER_BY_REST_ID,
1965                json!({"userId": user_id.into(), "withSafetyModeUserFields": true}),
1966                Some(constants::user_features()),
1967                None,
1968            )
1969            .await?;
1970        let result = raw
1971            .pointer("/data/user/result")
1972            .cloned()
1973            .ok_or(Error::Missing("data.user.result"))?;
1974        User::from_value_with_client(result, Some(self.clone()))
1975    }
1976
1977    /// Get a tweet by id.
1978    pub async fn get_tweet_by_id(&self, tweet_id: impl Into<String>) -> Result<Tweet> {
1979        self.get_tweet_by_id_with_cursor(tweet_id, None).await
1980    }
1981
1982    /// Get a tweet by id through TweetDetail, optionally with a cursor.
1983    pub async fn get_tweet_by_id_with_cursor(
1984        &self,
1985        tweet_id: impl Into<String>,
1986        cursor: Option<String>,
1987    ) -> Result<Tweet> {
1988        Ok(self.get_tweet_detail(tweet_id, cursor).await?.tweet)
1989    }
1990
1991    /// Get rich TweetDetail data assembled similarly to Python twikit.
1992    pub async fn get_tweet_detail(
1993        &self,
1994        tweet_id: impl Into<String>,
1995        cursor: Option<String>,
1996    ) -> Result<TweetDetail> {
1997        let tweet_id = tweet_id.into();
1998        let raw = self
1999            .inner
2000            .gql_get(
2001                endpoints::TWEET_DETAIL,
2002                tweet_detail_variables(tweet_id.clone(), cursor),
2003                Some(constants::features()),
2004                Some(json!({"fieldToggles": {"withAuxiliaryUserLabels": false}})),
2005            )
2006            .await?;
2007        self.parse_tweet_detail(tweet_id, raw)
2008    }
2009
2010    /// Get user tweets.
2011    pub async fn get_user_tweets(
2012        &self,
2013        user_id: impl Into<String>,
2014        tweet_type: TweetType,
2015        count: i64,
2016        cursor: Option<String>,
2017    ) -> Result<Timeline<Tweet>> {
2018        let user_id = user_id.into();
2019        let endpoint = match tweet_type {
2020            TweetType::Tweets => endpoints::USER_TWEETS,
2021            TweetType::Replies => endpoints::USER_TWEETS_AND_REPLIES,
2022            TweetType::Media => endpoints::USER_MEDIA,
2023            TweetType::Likes => endpoints::USER_LIKES,
2024        };
2025        let raw = self
2026            .inner
2027            .gql_get(
2028                endpoint,
2029                user_tweets_variables(user_id.clone(), count, cursor.clone()),
2030                Some(constants::features()),
2031                None,
2032            )
2033            .await?;
2034        Ok(self.pageable_gql_timeline(
2035            raw,
2036            GqlPageMethod::Get,
2037            endpoint,
2038            Some(constants::features()),
2039            move |cursor| user_tweets_variables(user_id.clone(), count, Some(cursor)),
2040            parse_tweet_timeline,
2041        ))
2042    }
2043
2044    /// Create a tweet.
2045    pub async fn create_tweet(
2046        &self,
2047        text: impl Into<String>,
2048        media_ids: &[String],
2049    ) -> Result<Tweet> {
2050        self.create_tweet_with_options(
2051            text,
2052            CreateTweetOptions {
2053                media_ids: media_ids.to_vec(),
2054                ..Default::default()
2055            },
2056        )
2057        .await
2058    }
2059
2060    /// Create a tweet with the extended options supported by Python twikit.
2061    pub async fn create_tweet_with_options(
2062        &self,
2063        text: impl Into<String>,
2064        options: CreateTweetOptions,
2065    ) -> Result<Tweet> {
2066        let media_entities: Vec<Value> = options
2067            .media_ids
2068            .iter()
2069            .map(|id| json!({"media_id": id, "tagged_users": []}))
2070            .collect();
2071        let raw = self
2072            .inner
2073            .gql_post(
2074                if options.is_note_tweet || options.richtext_options.is_some() {
2075                    endpoints::CREATE_NOTE_TWEET
2076                } else {
2077                    endpoints::CREATE_TWEET
2078                },
2079                create_tweet_variables(text.into(), media_entities, options.clone()),
2080                Some(
2081                    if options.is_note_tweet || options.richtext_options.is_some() {
2082                        constants::note_tweet_features()
2083                    } else {
2084                        constants::features()
2085                    },
2086                ),
2087                None,
2088            )
2089            .await?;
2090        let result = created_tweet_result(&raw).ok_or(Error::Missing("tweet_results.result"))?;
2091        Tweet::from_value_with_client(result, Some(self.clone()))
2092    }
2093
2094    /// Create a reply tweet.
2095    pub async fn create_tweet_reply(
2096        &self,
2097        text: impl Into<String>,
2098        in_reply_to_tweet_id: impl Into<String>,
2099        media_ids: &[String],
2100    ) -> Result<Tweet> {
2101        let media_entities: Vec<Value> = media_ids
2102            .iter()
2103            .map(|id| json!({"media_id": id, "tagged_users": []}))
2104            .collect();
2105        let raw = self
2106            .inner
2107            .gql_post(
2108                endpoints::CREATE_TWEET,
2109                json!({
2110                    "tweet_text": text.into(),
2111                    "dark_request": false,
2112                    "media": {"media_entities": media_entities, "possibly_sensitive": false},
2113                    "reply": {
2114                        "in_reply_to_tweet_id": in_reply_to_tweet_id.into(),
2115                        "exclude_reply_user_ids": []
2116                    },
2117                    "semantic_annotation_ids": []
2118                }),
2119                Some(constants::features()),
2120                None,
2121            )
2122            .await?;
2123        let result = find_first(&raw, "tweet_results")
2124            .and_then(|v| v.get("result"))
2125            .cloned()
2126            .ok_or(Error::Missing("tweet_results.result"))?;
2127        Tweet::from_value_with_client(result, Some(self.clone()))
2128    }
2129
2130    /// Favorite a tweet.
2131    pub async fn favorite_tweet(&self, tweet_id: impl Into<String>) -> Result<Value> {
2132        self.inner
2133            .gql_post(
2134                endpoints::FAVORITE_TWEET,
2135                json!({"tweet_id": tweet_id.into()}),
2136                None,
2137                None,
2138            )
2139            .await
2140    }
2141
2142    /// Remove favorite from a tweet.
2143    pub async fn unfavorite_tweet(&self, tweet_id: impl Into<String>) -> Result<Value> {
2144        self.inner
2145            .gql_post(
2146                endpoints::UNFAVORITE_TWEET,
2147                json!({"tweet_id": tweet_id.into()}),
2148                None,
2149                None,
2150            )
2151            .await
2152    }
2153
2154    /// Retweet.
2155    pub async fn retweet(&self, tweet_id: impl Into<String>) -> Result<Value> {
2156        self.inner
2157            .gql_post(
2158                endpoints::CREATE_RETWEET,
2159                json!({"tweet_id": tweet_id.into(), "dark_request": false}),
2160                None,
2161                None,
2162            )
2163            .await
2164    }
2165
2166    /// Delete retweet.
2167    pub async fn delete_retweet(&self, tweet_id: impl Into<String>) -> Result<Value> {
2168        self.inner
2169            .gql_post(
2170                endpoints::DELETE_RETWEET,
2171                json!({"source_tweet_id": tweet_id.into(), "dark_request": false}),
2172                None,
2173                None,
2174            )
2175            .await
2176    }
2177
2178    /// Delete tweet.
2179    pub async fn delete_tweet(&self, tweet_id: impl Into<String>) -> Result<Value> {
2180        self.inner
2181            .gql_post(
2182                endpoints::DELETE_TWEET,
2183                json!({"tweet_id": tweet_id.into(), "dark_request": false}),
2184                None,
2185                None,
2186            )
2187            .await
2188    }
2189
2190    /// Upload media and return the media id.
2191    pub async fn upload_media(
2192        &self,
2193        source: impl Into<MediaSource>,
2194        options: UploadMediaOptions,
2195    ) -> Result<String> {
2196        let source = source.into();
2197        let source_path = match &source {
2198            MediaSource::Path(path) => Some(path.clone()),
2199            MediaSource::Bytes(_) => None,
2200        };
2201        let bytes = match source {
2202            MediaSource::Path(path) => fs::read(path).await?,
2203            MediaSource::Bytes(bytes) => bytes,
2204        };
2205        let media_type = options
2206            .media_type
2207            .clone()
2208            .or_else(|| guess_media_type(source_path.as_deref()))
2209            .unwrap_or_else(|| "application/octet-stream".into());
2210        let total_bytes = bytes.len().to_string();
2211        let endpoint = if options.is_long_video {
2212            endpoints::v11::upload_media_2()
2213        } else {
2214            endpoints::v11::upload_media()
2215        };
2216
2217        let mut init = vec![
2218            ("command".into(), "INIT".into()),
2219            ("total_bytes".into(), total_bytes),
2220            ("media_type".into(), media_type.clone()),
2221        ];
2222        if let Some(category) = &options.media_category {
2223            init.push(("media_category".into(), category.clone()));
2224        }
2225        let init = self
2226            .inner
2227            .request(Method::POST, endpoint.clone(), None, Some(init), None, true)
2228            .await?;
2229        let media_id = init
2230            .get("media_id_string")
2231            .or_else(|| init.get("media_id"))
2232            .and_then(|v| {
2233                v.as_str()
2234                    .map(ToOwned::to_owned)
2235                    .or_else(|| v.as_i64().map(|i| i.to_string()))
2236            })
2237            .ok_or(Error::Missing("media_id"))?;
2238
2239        const MAX_SEGMENT_SIZE: usize = 8 * 1024 * 1024;
2240        for (segment_index, chunk) in bytes.chunks(MAX_SEGMENT_SIZE).enumerate() {
2241            let form = reqwest::multipart::Form::new().part(
2242                "media",
2243                reqwest::multipart::Part::bytes(chunk.to_vec())
2244                    .file_name("blob")
2245                    .mime_str("application/octet-stream")
2246                    .map_err(|e| Error::Unsupported(e.to_string()))?,
2247            );
2248            let params = vec![
2249                ("command".into(), "APPEND".into()),
2250                ("media_id".into(), media_id.clone()),
2251                ("segment_index".into(), segment_index.to_string()),
2252            ];
2253            self.inner
2254                .request(
2255                    Method::POST,
2256                    endpoint.clone(),
2257                    None,
2258                    Some(params),
2259                    Some(RequestBody::Multipart(form)),
2260                    true,
2261                )
2262                .await?;
2263        }
2264
2265        self.inner
2266            .request(
2267                Method::POST,
2268                endpoint.clone(),
2269                None,
2270                Some(vec![
2271                    ("command".into(), "FINALIZE".into()),
2272                    ("media_id".into(), media_id.clone()),
2273                ]),
2274                None,
2275                true,
2276            )
2277            .await?;
2278
2279        if options.wait_for_completion && !media_type.starts_with("image/") {
2280            loop {
2281                let status = self
2282                    .check_media_status(&media_id, options.is_long_video)
2283                    .await?;
2284                let state = status
2285                    .pointer("/processing_info/state")
2286                    .and_then(Value::as_str)
2287                    .unwrap_or("succeeded");
2288                if status.pointer("/processing_info/error").is_some() {
2289                    return Err(Error::Unsupported(format!("invalid media: {status}")));
2290                }
2291                if state == "succeeded" {
2292                    break;
2293                }
2294                let delay = options.status_check_interval.unwrap_or_else(|| {
2295                    Duration::from_secs(
2296                        status
2297                            .pointer("/processing_info/check_after_secs")
2298                            .and_then(Value::as_u64)
2299                            .unwrap_or(1),
2300                    )
2301                });
2302                sleep(delay).await;
2303            }
2304        }
2305
2306        Ok(media_id)
2307    }
2308
2309    /// Check uploaded media status.
2310    pub async fn check_media_status(&self, media_id: &str, is_long_video: bool) -> Result<Value> {
2311        let endpoint = if is_long_video {
2312            endpoints::v11::upload_media_2()
2313        } else {
2314            endpoints::v11::upload_media()
2315        };
2316        self.inner
2317            .request(
2318                Method::GET,
2319                endpoint,
2320                None,
2321                Some(vec![
2322                    ("command".into(), "STATUS".into()),
2323                    ("media_id".into(), media_id.into()),
2324                ]),
2325                None,
2326                true,
2327            )
2328            .await
2329    }
2330
2331    /// Create media metadata.
2332    pub async fn create_media_metadata(
2333        &self,
2334        media_id: impl Into<String>,
2335        alt_text: Option<String>,
2336        sensitive_warning: Option<Vec<String>>,
2337    ) -> Result<Value> {
2338        let mut body = json!({"media_id": media_id.into()});
2339        if let Some(text) = alt_text {
2340            body["alt_text"] = json!({"text": text});
2341        }
2342        if let Some(warning) = sensitive_warning {
2343            body["sensitive_media_warning"] = json!(warning);
2344        }
2345        self.inner
2346            .request(
2347                Method::POST,
2348                endpoints::v11::create_media_metadata(),
2349                None,
2350                None,
2351                Some(RequestBody::Json(body)),
2352                true,
2353            )
2354            .await
2355    }
2356
2357    /// Create a poll card and return the card URI.
2358    pub async fn create_poll(&self, choices: &[String], duration_minutes: i64) -> Result<String> {
2359        let mut card_data = serde_json::Map::new();
2360        card_data.insert(
2361            "twitter:card".into(),
2362            json!(format!("poll{}choice_text_only", choices.len())),
2363        );
2364        card_data.insert("twitter:api:api:endpoint".into(), json!("1"));
2365        card_data.insert(
2366            "twitter:long:duration_minutes".into(),
2367            json!(duration_minutes),
2368        );
2369        for (index, choice) in choices.iter().enumerate() {
2370            card_data.insert(
2371                format!("twitter:string:choice{}_label", index + 1),
2372                json!(choice),
2373            );
2374        }
2375        let raw = self
2376            .inner
2377            .request(
2378                Method::POST,
2379                endpoints::v11::create_card(),
2380                None,
2381                None,
2382                Some(RequestBody::Form(vec![(
2383                    "card_data".into(),
2384                    serde_json::to_string(&card_data)?,
2385                )])),
2386                true,
2387            )
2388            .await?;
2389        raw.get("card_uri")
2390            .and_then(Value::as_str)
2391            .map(ToOwned::to_owned)
2392            .ok_or(Error::Missing("card_uri"))
2393    }
2394
2395    /// Vote on a poll and return raw poll payload.
2396    pub async fn vote(
2397        &self,
2398        selected_choice: impl Into<String>,
2399        card_uri: impl Into<String>,
2400        tweet_id: impl Into<String>,
2401        card_name: impl Into<String>,
2402    ) -> Result<Poll> {
2403        let raw = self
2404            .inner
2405            .request(
2406                Method::POST,
2407                endpoints::v11::vote(),
2408                None,
2409                None,
2410                Some(RequestBody::Form(vec![
2411                    ("twitter:string:card_uri".into(), card_uri.into()),
2412                    ("twitter:long:original_tweet_id".into(), tweet_id.into()),
2413                    ("twitter:string:response_card_name".into(), card_name.into()),
2414                    ("twitter:string:cards_platform".into(), "Web-12".into()),
2415                    (
2416                        "twitter:string:selected_choice".into(),
2417                        selected_choice.into(),
2418                    ),
2419                ])),
2420                true,
2421            )
2422            .await?;
2423        Ok(Poll::from_value_with_client(raw, Some(self.clone())))
2424    }
2425
2426    /// Bookmark a tweet, optionally into a folder.
2427    pub async fn bookmark_tweet(
2428        &self,
2429        tweet_id: impl Into<String>,
2430        folder_id: Option<String>,
2431    ) -> Result<Value> {
2432        let tweet_id = tweet_id.into();
2433        if let Some(folder_id) = folder_id {
2434            self.inner
2435                .gql_post(
2436                    endpoints::BOOKMARK_TO_FOLDER,
2437                    json!({"tweet_id": tweet_id, "bookmark_collection_id": folder_id}),
2438                    None,
2439                    None,
2440                )
2441                .await
2442        } else {
2443            self.inner
2444                .gql_post(
2445                    endpoints::CREATE_BOOKMARK,
2446                    json!({"tweet_id": tweet_id}),
2447                    None,
2448                    None,
2449                )
2450                .await
2451        }
2452    }
2453
2454    /// Delete bookmark.
2455    pub async fn delete_bookmark(&self, tweet_id: impl Into<String>) -> Result<Value> {
2456        self.inner
2457            .gql_post(
2458                endpoints::DELETE_BOOKMARK,
2459                json!({"tweet_id": tweet_id.into()}),
2460                None,
2461                None,
2462            )
2463            .await
2464    }
2465
2466    /// Get bookmarks.
2467    pub async fn get_bookmarks(
2468        &self,
2469        count: i64,
2470        cursor: Option<String>,
2471        folder_id: Option<String>,
2472    ) -> Result<Timeline<Tweet>> {
2473        let folder_id_for_endpoint = folder_id.clone();
2474        let endpoint = if folder_id.is_some() {
2475            endpoints::BOOKMARK_FOLDER_TIMELINE
2476        } else {
2477            endpoints::BOOKMARKS
2478        };
2479        let raw = self
2480            .inner
2481            .gql_get(
2482                endpoint,
2483                bookmarks_variables(count, folder_id_for_endpoint.clone(), cursor.clone()),
2484                Some(constants::features()),
2485                None,
2486            )
2487            .await?;
2488        Ok(self.pageable_gql_timeline(
2489            raw,
2490            GqlPageMethod::Get,
2491            endpoint,
2492            Some(constants::features()),
2493            move |cursor| bookmarks_variables(count, folder_id_for_endpoint.clone(), Some(cursor)),
2494            parse_tweet_timeline,
2495        ))
2496    }
2497
2498    /// Delete all bookmarks.
2499    pub async fn delete_all_bookmarks(&self) -> Result<Value> {
2500        self.inner
2501            .gql_post(endpoints::BOOKMARKS_ALL_DELETE, json!({}), None, None)
2502            .await
2503    }
2504
2505    /// Get bookmark folders.
2506    pub async fn get_bookmark_folders(
2507        &self,
2508        cursor: Option<String>,
2509    ) -> Result<Timeline<BookmarkFolder>> {
2510        let mut variables = json!({"first": 100});
2511        if let Some(cursor) = cursor {
2512            variables["cursor"] = cursor.into();
2513        }
2514        let raw = self
2515            .inner
2516            .gql_get(endpoints::BOOKMARK_FOLDERS_SLICE, variables, None, None)
2517            .await?;
2518        let mut items = Vec::new();
2519        let mut values = Vec::new();
2520        find_values(&raw, "bookmark_collections_slice", &mut values);
2521        for value in values {
2522            if let Some(slice_items) = value.get("items").and_then(Value::as_array) {
2523                items.extend(slice_items.iter().cloned().map(|value| {
2524                    BookmarkFolder::from_value_with_client(value, Some(self.clone()))
2525                }));
2526            }
2527        }
2528        Ok(Timeline::new(items, None, None, raw))
2529    }
2530
2531    /// Create bookmark folder.
2532    pub async fn create_bookmark_folder(&self, name: impl Into<String>) -> Result<BookmarkFolder> {
2533        let raw = self
2534            .inner
2535            .gql_post(
2536                endpoints::CREATE_BOOKMARK_FOLDER,
2537                json!({"name": name.into()}),
2538                None,
2539                None,
2540            )
2541            .await?;
2542        Ok(BookmarkFolder::from_value_with_client(
2543            raw.pointer("/data/bookmark_collection_create")
2544                .cloned()
2545                .unwrap_or(raw),
2546            Some(self.clone()),
2547        ))
2548    }
2549
2550    /// Edit bookmark folder.
2551    pub async fn edit_bookmark_folder(
2552        &self,
2553        folder_id: impl Into<String>,
2554        name: impl Into<String>,
2555    ) -> Result<BookmarkFolder> {
2556        let raw = self
2557            .inner
2558            .gql_post(
2559                endpoints::EDIT_BOOKMARK_FOLDER,
2560                json!({"bookmark_collection_id": folder_id.into(), "name": name.into()}),
2561                None,
2562                None,
2563            )
2564            .await?;
2565        Ok(BookmarkFolder::from_value_with_client(
2566            raw.pointer("/data/bookmark_collection_update")
2567                .cloned()
2568                .unwrap_or(raw),
2569            Some(self.clone()),
2570        ))
2571    }
2572
2573    /// Delete bookmark folder.
2574    pub async fn delete_bookmark_folder(&self, folder_id: impl Into<String>) -> Result<Value> {
2575        self.inner
2576            .gql_post(
2577                endpoints::DELETE_BOOKMARK_FOLDER,
2578                json!({"bookmark_collection_id": folder_id.into()}),
2579                None,
2580                None,
2581            )
2582            .await
2583    }
2584
2585    /// Follow user and return updated user when present.
2586    pub async fn follow_user(&self, user_id: impl Into<String>) -> Result<User> {
2587        self.v11_user_form(endpoints::v11::create_friendships(), user_id.into())
2588            .await
2589    }
2590
2591    /// Unfollow user.
2592    pub async fn unfollow_user(&self, user_id: impl Into<String>) -> Result<User> {
2593        self.v11_user_form(endpoints::v11::destroy_friendships(), user_id.into())
2594            .await
2595    }
2596
2597    /// Block user.
2598    pub async fn block_user(&self, user_id: impl Into<String>) -> Result<User> {
2599        self.v11_user_form(endpoints::v11::create_blocks(), user_id.into())
2600            .await
2601    }
2602
2603    /// Unblock user.
2604    pub async fn unblock_user(&self, user_id: impl Into<String>) -> Result<User> {
2605        self.v11_user_form(endpoints::v11::destroy_blocks(), user_id.into())
2606            .await
2607    }
2608
2609    /// Mute user.
2610    pub async fn mute_user(&self, user_id: impl Into<String>) -> Result<User> {
2611        self.v11_user_form(endpoints::v11::create_mutes(), user_id.into())
2612            .await
2613    }
2614
2615    /// Unmute user.
2616    pub async fn unmute_user(&self, user_id: impl Into<String>) -> Result<User> {
2617        self.v11_user_form(endpoints::v11::destroy_mutes(), user_id.into())
2618            .await
2619    }
2620
2621    async fn v11_user_form(&self, endpoint: String, user_id: String) -> Result<User> {
2622        let raw = self
2623            .inner
2624            .request(
2625                Method::POST,
2626                endpoint,
2627                None,
2628                None,
2629                Some(RequestBody::Form(vec![("user_id".into(), user_id)])),
2630                true,
2631            )
2632            .await?;
2633        User::from_value_with_client(crate::utils::build_user_data(&raw), Some(self.clone()))
2634    }
2635
2636    /// Get available trend locations.
2637    pub async fn get_available_locations(&self) -> Result<Vec<Location>> {
2638        let raw = self
2639            .inner
2640            .request(
2641                Method::GET,
2642                endpoints::v11::available_trends(),
2643                None,
2644                None,
2645                None,
2646                true,
2647            )
2648            .await?;
2649        Ok(raw
2650            .as_array()
2651            .cloned()
2652            .unwrap_or_default()
2653            .into_iter()
2654            .map(|value| Location::from_value_with_client(value, Some(self.clone())))
2655            .collect())
2656    }
2657
2658    /// Get place trends.
2659    pub async fn get_place_trends(&self, woeid: i64) -> Result<PlaceTrends> {
2660        let raw = self
2661            .inner
2662            .request(
2663                Method::GET,
2664                endpoints::v11::trends_place(),
2665                None,
2666                Some(vec![("id".into(), woeid.to_string())]),
2667                None,
2668                true,
2669            )
2670            .await?;
2671        Ok(PlaceTrends::from_value_with_client(
2672            raw.as_array()
2673                .and_then(|a| a.first())
2674                .cloned()
2675                .unwrap_or(raw),
2676            Some(self.clone()),
2677        ))
2678    }
2679
2680    /// Get guide trends. Returns raw-backed trend items when parseable.
2681    pub async fn get_trends(&self, category: impl Into<String>, count: i64) -> Result<Vec<Trend>> {
2682        self.get_trends_with_options(category, count, TrendsOptions::default())
2683            .await
2684    }
2685
2686    /// Get guide trends with Python twikit-style options.
2687    pub async fn get_trends_with_options(
2688        &self,
2689        category: impl Into<String>,
2690        count: i64,
2691        options: TrendsOptions,
2692    ) -> Result<Vec<Trend>> {
2693        let category = category.into();
2694        let category = match category.to_ascii_lowercase().as_str() {
2695            "news" => "news_unified".to_string(),
2696            "sports" => "sports_unified".to_string(),
2697            "entertainment" => "entertainment_unified".to_string(),
2698            other => other.to_string(),
2699        };
2700        for attempt in 0..=usize::from(options.retry) {
2701            let mut params = vec![
2702                ("count".into(), count.to_string()),
2703                ("include_page_configuration".into(), "true".into()),
2704                ("initial_tab_id".into(), category.clone()),
2705            ];
2706            params.extend(options.additional_request_params.clone());
2707            let raw = self
2708                .inner
2709                .request(
2710                    Method::GET,
2711                    endpoints::v11::guide(),
2712                    None,
2713                    Some(params),
2714                    None,
2715                    true,
2716                )
2717                .await?;
2718            let trends = parse_guide_trends(&raw, &category, self);
2719            if !trends.is_empty() || attempt == usize::from(options.retry) {
2720                return Ok(trends);
2721            }
2722        }
2723        Ok(Vec::new())
2724    }
2725
2726    /// Reverse geocode.
2727    pub async fn reverse_geocode(
2728        &self,
2729        lat: f64,
2730        long: f64,
2731        accuracy: Option<String>,
2732        granularity: Option<String>,
2733        max_results: Option<i64>,
2734    ) -> Result<Vec<Place>> {
2735        let mut params = vec![
2736            ("lat".into(), lat.to_string()),
2737            ("long".into(), long.to_string()),
2738        ];
2739        if let Some(v) = accuracy {
2740            params.push(("accuracy".into(), v));
2741        }
2742        if let Some(v) = granularity {
2743            params.push(("granularity".into(), v));
2744        }
2745        if let Some(v) = max_results {
2746            params.push(("max_results".into(), v.to_string()));
2747        }
2748        let raw = self
2749            .inner
2750            .request(
2751                Method::GET,
2752                endpoints::v11::reverse_geocode(),
2753                None,
2754                Some(params),
2755                None,
2756                true,
2757            )
2758            .await?;
2759        Ok(parse_places(raw, self))
2760    }
2761
2762    /// Search geo.
2763    pub async fn search_geo(
2764        &self,
2765        query: Option<String>,
2766        lat: Option<f64>,
2767        long: Option<f64>,
2768    ) -> Result<Vec<Place>> {
2769        self.search_geo_with_options(SearchGeoOptions {
2770            query,
2771            lat,
2772            long,
2773            ..Default::default()
2774        })
2775        .await
2776    }
2777
2778    /// Search geo with Python twikit-style options.
2779    pub async fn search_geo_with_options(&self, options: SearchGeoOptions) -> Result<Vec<Place>> {
2780        let mut params = Vec::new();
2781        if let Some(v) = options.query {
2782            params.push(("query".into(), v));
2783        }
2784        if let Some(v) = options.lat {
2785            params.push(("lat".into(), v.to_string()));
2786        }
2787        if let Some(v) = options.long {
2788            params.push(("long".into(), v.to_string()));
2789        }
2790        if let Some(v) = options.ip {
2791            params.push(("ip".into(), v));
2792        }
2793        if let Some(v) = options.granularity {
2794            params.push(("granularity".into(), v));
2795        }
2796        if let Some(v) = options.max_results {
2797            params.push(("max_results".into(), v.to_string()));
2798        }
2799        let raw = self
2800            .inner
2801            .request(
2802                Method::GET,
2803                endpoints::v11::search_geo(),
2804                None,
2805                Some(params),
2806                None,
2807                true,
2808            )
2809            .await?;
2810        Ok(parse_places(raw, self))
2811    }
2812
2813    /// Get place by id.
2814    pub async fn get_place(&self, id: &str) -> Result<Place> {
2815        let raw = self
2816            .inner
2817            .request(
2818                Method::GET,
2819                endpoints::v11::get_place(id),
2820                None,
2821                None,
2822                None,
2823                true,
2824            )
2825            .await?;
2826        Ok(Place::from_value_with_client(raw, Some(self.clone())))
2827    }
2828
2829    /// Send DM to user conversation id.
2830    pub async fn send_dm(
2831        &self,
2832        user_id: impl Into<String>,
2833        text: impl Into<String>,
2834        media_id: Option<String>,
2835        reply_to: Option<String>,
2836    ) -> Result<Message> {
2837        let conversation_id = user_id.into();
2838        let mut body = json!({
2839            "cards_platform": "Web-12",
2840            "conversation_id": conversation_id,
2841            "dm_users": false,
2842            "include_cards": 1,
2843            "include_quote_count": true,
2844            "recipient_ids": false,
2845            "text": text.into()
2846        });
2847        if let Some(media_id) = media_id {
2848            body["media_id"] = media_id.into();
2849        }
2850        if let Some(reply_to) = reply_to {
2851            body["reply_to_dm_id"] = reply_to.into();
2852        }
2853        let raw = self
2854            .inner
2855            .request(
2856                Method::POST,
2857                endpoints::v11::dm_new(),
2858                None,
2859                None,
2860                Some(RequestBody::Json(body)),
2861                true,
2862            )
2863            .await?;
2864        let message = find_first(&raw, "message_data").cloned().unwrap_or(raw);
2865        Ok(Message::from_value_with_client(message, Some(self.clone())))
2866    }
2867
2868    /// Get DM conversation raw-backed messages.
2869    pub async fn get_dm_history(
2870        &self,
2871        conversation_id: impl Into<String>,
2872        max_id: Option<String>,
2873    ) -> Result<Timeline<Message>> {
2874        let mut params = vec![
2875            ("context".into(), "FETCH_DM_CONVERSATION_HISTORY".into()),
2876            ("include_conversation_info".into(), "true".into()),
2877        ];
2878        if let Some(max_id) = max_id {
2879            params.push(("max_id".into(), max_id));
2880        }
2881        let raw = self
2882            .inner
2883            .request(
2884                Method::GET,
2885                endpoints::v11::dm_conversation(&conversation_id.into()),
2886                None,
2887                Some(params),
2888                None,
2889                true,
2890            )
2891            .await?;
2892        let mut values = Vec::new();
2893        find_values(&raw, "message_data", &mut values);
2894        let messages = values
2895            .into_iter()
2896            .cloned()
2897            .map(|value| Message::from_value_with_client(value, Some(self.clone())))
2898            .collect();
2899        Ok(Timeline::new(messages, None, None, raw))
2900    }
2901
2902    /// Python parity helper for send DM.
2903    pub async fn _send_dm(
2904        &self,
2905        conversation_id: impl Into<String>,
2906        text: impl Into<String>,
2907        media_id: Option<String>,
2908        reply_to: Option<String>,
2909    ) -> Result<Message> {
2910        self.send_dm(conversation_id, text, media_id, reply_to)
2911            .await
2912    }
2913
2914    /// Python parity helper for DM history.
2915    pub async fn _get_dm_history(
2916        &self,
2917        conversation_id: impl Into<String>,
2918        max_id: Option<String>,
2919    ) -> Result<Timeline<Message>> {
2920        self.get_dm_history(conversation_id, max_id).await
2921    }
2922
2923    /// Send DM to a group.
2924    pub async fn send_dm_to_group(
2925        &self,
2926        group_id: impl Into<String>,
2927        text: impl Into<String>,
2928        media_id: Option<String>,
2929        reply_to: Option<String>,
2930    ) -> Result<GroupMessage> {
2931        Ok(GroupMessage::from_value_with_client(
2932            self.send_dm(group_id, text, media_id, reply_to).await?.raw,
2933            Some(self.clone()),
2934        ))
2935    }
2936
2937    /// Get group DM history.
2938    pub async fn get_group_dm_history(
2939        &self,
2940        group_id: impl Into<String>,
2941        max_id: Option<String>,
2942    ) -> Result<Timeline<GroupMessage>> {
2943        let timeline = self.get_dm_history(group_id, max_id).await?;
2944        Ok(Timeline::new(
2945            timeline
2946                .items
2947                .into_iter()
2948                .map(|message| {
2949                    GroupMessage::from_value_with_client(message.raw, Some(self.clone()))
2950                })
2951                .collect(),
2952            timeline.next_cursor,
2953            timeline.previous_cursor,
2954            timeline.raw,
2955        ))
2956    }
2957
2958    /// Get group raw model.
2959    pub async fn get_group(&self, group_id: impl Into<String>) -> Result<Group> {
2960        let timeline = self.get_dm_history(group_id, None).await?;
2961        Ok(Group::from_value_with_client(
2962            timeline.raw,
2963            Some(self.clone()),
2964        ))
2965    }
2966
2967    /// Add members to a group.
2968    pub async fn add_members_to_group(
2969        &self,
2970        group_id: impl Into<String>,
2971        user_ids: Vec<String>,
2972    ) -> Result<Value> {
2973        self.inner
2974            .gql_post(
2975                endpoints::ADD_PARTICIPANTS_MUTATION,
2976                json!({"conversation_id": group_id.into(), "participants": user_ids}),
2977                None,
2978                None,
2979            )
2980            .await
2981    }
2982
2983    /// Change group name.
2984    pub async fn change_group_name(
2985        &self,
2986        group_id: impl Into<String>,
2987        name: impl Into<String>,
2988    ) -> Result<Value> {
2989        self.inner
2990            .request(
2991                Method::POST,
2992                endpoints::v11::conversation_update_name(&group_id.into()),
2993                None,
2994                None,
2995                Some(RequestBody::Form(vec![("name".into(), name.into())])),
2996                true,
2997            )
2998            .await
2999    }
3000
3001    /// Add reaction to a DM.
3002    pub async fn add_reaction_to_message(
3003        &self,
3004        message_id: impl Into<String>,
3005        conversation_id: impl Into<String>,
3006        emoji: impl Into<String>,
3007    ) -> Result<Value> {
3008        self.inner
3009            .gql_post(
3010                endpoints::USER_DM_REACTION_MUTATION_ADD_MUTATION,
3011                json!({"message_id": message_id.into(), "conversation_id": conversation_id.into(), "reaction_types": [emoji.into()]}),
3012                None,
3013                None,
3014            )
3015            .await
3016    }
3017
3018    /// Remove reaction from a DM.
3019    pub async fn remove_reaction_from_message(
3020        &self,
3021        message_id: impl Into<String>,
3022        conversation_id: impl Into<String>,
3023        emoji: impl Into<String>,
3024    ) -> Result<Value> {
3025        self.inner
3026            .gql_post(
3027                endpoints::USER_DM_REACTION_MUTATION_REMOVE_MUTATION,
3028                json!({"message_id": message_id.into(), "conversation_id": conversation_id.into(), "reaction_types": [emoji.into()]}),
3029                None,
3030                None,
3031            )
3032            .await
3033    }
3034
3035    /// Delete DM.
3036    pub async fn delete_dm(&self, message_id: impl Into<String>) -> Result<Value> {
3037        self.inner
3038            .gql_post(
3039                endpoints::DM_MESSAGE_DELETE_MUTATION,
3040                json!({"message_id": message_id.into()}),
3041                None,
3042                None,
3043            )
3044            .await
3045    }
3046
3047    /// Create list.
3048    pub async fn create_list(
3049        &self,
3050        name: impl Into<String>,
3051        description: impl Into<String>,
3052        is_private: bool,
3053    ) -> Result<List> {
3054        let raw = self
3055            .inner
3056            .gql_post(
3057                endpoints::CREATE_LIST,
3058                json!({"name": name.into(), "description": description.into(), "isPrivate": is_private}),
3059                None,
3060                None,
3061            )
3062            .await?;
3063        Ok(List::from_value_with_client(
3064            find_first(&raw, "list").cloned().unwrap_or(raw),
3065            Some(self.clone()),
3066        ))
3067    }
3068
3069    /// Get list by id.
3070    pub async fn get_list(&self, list_id: impl Into<String>) -> Result<List> {
3071        let raw = self
3072            .inner
3073            .gql_get(
3074                endpoints::LIST_BY_REST_ID,
3075                json!({"listId": list_id.into()}),
3076                Some(constants::list_features()),
3077                None,
3078            )
3079            .await?;
3080        Ok(List::from_value_with_client(
3081            find_first(&raw, "list").cloned().unwrap_or(raw),
3082            Some(self.clone()),
3083        ))
3084    }
3085
3086    /// Get list tweets.
3087    pub async fn get_list_tweets(
3088        &self,
3089        list_id: impl Into<String>,
3090        count: i64,
3091        cursor: Option<String>,
3092    ) -> Result<Timeline<Tweet>> {
3093        let list_id = list_id.into();
3094        let raw = self
3095            .inner
3096            .gql_get(
3097                endpoints::LIST_LATEST_TWEETS_TIMELINE,
3098                id_count_variables("listId", list_id.clone(), count, cursor.clone()),
3099                Some(constants::features()),
3100                None,
3101            )
3102            .await?;
3103        Ok(self.pageable_gql_timeline(
3104            raw,
3105            GqlPageMethod::Get,
3106            endpoints::LIST_LATEST_TWEETS_TIMELINE,
3107            Some(constants::features()),
3108            move |cursor| id_count_variables("listId", list_id.clone(), count, Some(cursor)),
3109            parse_tweet_timeline,
3110        ))
3111    }
3112
3113    /// Edit list banner.
3114    pub async fn edit_list_banner(
3115        &self,
3116        list_id: impl Into<String>,
3117        media_id: impl Into<String>,
3118    ) -> Result<Value> {
3119        self.inner
3120            .gql_post(
3121                endpoints::EDIT_LIST_BANNER,
3122                json!({"listId": list_id.into(), "mediaId": media_id.into()}),
3123                Some(constants::list_features()),
3124                None,
3125            )
3126            .await
3127    }
3128
3129    /// Delete list banner.
3130    pub async fn delete_list_banner(&self, list_id: impl Into<String>) -> Result<Value> {
3131        self.inner
3132            .gql_post(
3133                endpoints::DELETE_LIST_BANNER,
3134                json!({"listId": list_id.into()}),
3135                Some(constants::list_features()),
3136                None,
3137            )
3138            .await
3139    }
3140
3141    /// Edit list metadata.
3142    pub async fn edit_list(
3143        &self,
3144        list_id: impl Into<String>,
3145        name: Option<String>,
3146        description: Option<String>,
3147        is_private: Option<bool>,
3148    ) -> Result<List> {
3149        let mut variables = json!({"listId": list_id.into()});
3150        if let Some(name) = name {
3151            variables["name"] = name.into();
3152        }
3153        if let Some(description) = description {
3154            variables["description"] = description.into();
3155        }
3156        if let Some(is_private) = is_private {
3157            variables["isPrivate"] = is_private.into();
3158        }
3159        let raw = self
3160            .inner
3161            .gql_post(
3162                endpoints::UPDATE_LIST,
3163                variables,
3164                Some(constants::list_features()),
3165                None,
3166            )
3167            .await?;
3168        Ok(List::from_value_with_client(
3169            find_first(&raw, "list").cloned().unwrap_or(raw),
3170            Some(self.clone()),
3171        ))
3172    }
3173
3174    /// Add list member.
3175    pub async fn add_list_member(
3176        &self,
3177        list_id: impl Into<String>,
3178        user_id: impl Into<String>,
3179    ) -> Result<List> {
3180        let raw = self
3181            .inner
3182            .gql_post(
3183                endpoints::LIST_ADD_MEMBER,
3184                json!({"listId": list_id.into(), "userId": user_id.into()}),
3185                Some(constants::list_features()),
3186                None,
3187            )
3188            .await?;
3189        Ok(List::from_value_with_client(
3190            find_first(&raw, "list").cloned().unwrap_or(raw),
3191            Some(self.clone()),
3192        ))
3193    }
3194
3195    /// Remove list member.
3196    pub async fn remove_list_member(
3197        &self,
3198        list_id: impl Into<String>,
3199        user_id: impl Into<String>,
3200    ) -> Result<List> {
3201        let raw = self
3202            .inner
3203            .gql_post(
3204                endpoints::LIST_REMOVE_MEMBER,
3205                json!({"listId": list_id.into(), "userId": user_id.into()}),
3206                Some(constants::list_features()),
3207                None,
3208            )
3209            .await?;
3210        Ok(List::from_value_with_client(
3211            find_first(&raw, "list").cloned().unwrap_or(raw),
3212            Some(self.clone()),
3213        ))
3214    }
3215
3216    /// Get current user's lists.
3217    pub async fn get_lists(&self, count: i64, cursor: Option<String>) -> Result<Timeline<List>> {
3218        let raw = self
3219            .inner
3220            .gql_get(
3221                endpoints::LIST_MANAGEMENT_PAGE_TIMELINE,
3222                count_variables(count, cursor.clone()),
3223                Some(constants::features()),
3224                None,
3225            )
3226            .await?;
3227        Ok(self.pageable_gql_timeline(
3228            raw,
3229            GqlPageMethod::Get,
3230            endpoints::LIST_MANAGEMENT_PAGE_TIMELINE,
3231            Some(constants::features()),
3232            move |cursor| count_variables(count, Some(cursor)),
3233            parse_list_timeline,
3234        ))
3235    }
3236
3237    /// Get list members.
3238    pub async fn get_list_members(
3239        &self,
3240        list_id: impl Into<String>,
3241        count: i64,
3242        cursor: Option<String>,
3243    ) -> Result<Timeline<User>> {
3244        self.list_users(endpoints::LIST_MEMBERS, list_id.into(), count, cursor)
3245            .await
3246    }
3247
3248    /// Get list subscribers.
3249    pub async fn get_list_subscribers(
3250        &self,
3251        list_id: impl Into<String>,
3252        count: i64,
3253        cursor: Option<String>,
3254    ) -> Result<Timeline<User>> {
3255        self.list_users(endpoints::LIST_SUBSCRIBERS, list_id.into(), count, cursor)
3256            .await
3257    }
3258
3259    async fn list_users(
3260        &self,
3261        endpoint: GqlEndpoint,
3262        list_id: String,
3263        count: i64,
3264        cursor: Option<String>,
3265    ) -> Result<Timeline<User>> {
3266        let raw = self
3267            .inner
3268            .gql_get(
3269                endpoint,
3270                id_count_variables("listId", list_id.clone(), count, cursor.clone()),
3271                Some(constants::features()),
3272                None,
3273            )
3274            .await?;
3275        Ok(self.pageable_gql_timeline(
3276            raw,
3277            GqlPageMethod::Get,
3278            endpoint,
3279            Some(constants::features()),
3280            move |cursor| id_count_variables("listId", list_id.clone(), count, Some(cursor)),
3281            parse_user_timeline,
3282        ))
3283    }
3284
3285    /// Python parity helper for list users.
3286    pub async fn _get_list_users(
3287        &self,
3288        endpoint: GqlEndpoint,
3289        list_id: impl Into<String>,
3290        count: i64,
3291        cursor: Option<String>,
3292    ) -> Result<Timeline<User>> {
3293        self.list_users(endpoint, list_id.into(), count, cursor)
3294            .await
3295    }
3296
3297    /// Get notifications as raw-backed models.
3298    pub async fn get_notifications(
3299        &self,
3300        notification_type: &str,
3301        count: i64,
3302        cursor: Option<String>,
3303    ) -> Result<Timeline<Notification>> {
3304        let endpoint = match notification_type.to_ascii_lowercase().as_str() {
3305            "verified" => endpoints::v11::notifications_verified(),
3306            "mentions" => endpoints::v11::notifications_mentions(),
3307            _ => endpoints::v11::notifications_all(),
3308        };
3309        let mut params = vec![("count".into(), count.to_string())];
3310        if let Some(cursor) = cursor {
3311            params.push(("cursor".into(), cursor));
3312        }
3313        let raw = self
3314            .inner
3315            .request(Method::GET, endpoint, None, Some(params), None, true)
3316            .await?;
3317        let notification_type = notification_type.to_ascii_lowercase();
3318        Ok(self.pageable_v11_timeline(
3319            raw,
3320            move |cursor| {
3321                let endpoint = match notification_type.as_str() {
3322                    "verified" => endpoints::v11::notifications_verified(),
3323                    "mentions" => endpoints::v11::notifications_mentions(),
3324                    _ => endpoints::v11::notifications_all(),
3325                };
3326                (
3327                    endpoint,
3328                    vec![
3329                        ("count".into(), count.to_string()),
3330                        ("cursor".into(), cursor),
3331                    ],
3332                )
3333            },
3334            parse_notification_timeline,
3335        ))
3336    }
3337
3338    /// Get community.
3339    pub async fn get_community(&self, community_id: impl Into<String>) -> Result<Community> {
3340        let raw = self
3341            .inner
3342            .gql_get(
3343                endpoints::COMMUNITY_QUERY,
3344                json!({"communityId": community_id.into()}),
3345                None,
3346                None,
3347            )
3348            .await?;
3349        Ok(Community::from_value_with_client(
3350            find_first(&raw, "community").cloned().unwrap_or(raw),
3351            Some(self.clone()),
3352        ))
3353    }
3354
3355    /// Get community tweets.
3356    pub async fn get_community_tweets(
3357        &self,
3358        community_id: impl Into<String>,
3359        ranking_mode: impl Into<String>,
3360        count: i64,
3361        cursor: Option<String>,
3362    ) -> Result<Timeline<Tweet>> {
3363        let community_id = community_id.into();
3364        let ranking_mode = ranking_mode.into();
3365        let raw = self
3366            .inner
3367            .gql_get(
3368                endpoints::COMMUNITY_TWEETS_TIMELINE,
3369                community_tweets_variables(
3370                    community_id.clone(),
3371                    ranking_mode.clone(),
3372                    count,
3373                    cursor.clone(),
3374                ),
3375                Some(constants::features()),
3376                None,
3377            )
3378            .await?;
3379        Ok(self.pageable_gql_timeline(
3380            raw,
3381            GqlPageMethod::Get,
3382            endpoints::COMMUNITY_TWEETS_TIMELINE,
3383            Some(constants::features()),
3384            move |cursor| {
3385                community_tweets_variables(
3386                    community_id.clone(),
3387                    ranking_mode.clone(),
3388                    count,
3389                    Some(cursor),
3390                )
3391            },
3392            parse_tweet_timeline,
3393        ))
3394    }
3395
3396    /// Get communities timeline.
3397    pub async fn get_communities_timeline(
3398        &self,
3399        count: i64,
3400        cursor: Option<String>,
3401    ) -> Result<Timeline<Community>> {
3402        let raw = self
3403            .inner
3404            .gql_get(
3405                endpoints::COMMUNITIES_MAIN_PAGE_TIMELINE,
3406                communities_variables(count, cursor.clone()),
3407                Some(constants::features()),
3408                None,
3409            )
3410            .await?;
3411        Ok(self.pageable_gql_timeline(
3412            raw,
3413            GqlPageMethod::Get,
3414            endpoints::COMMUNITIES_MAIN_PAGE_TIMELINE,
3415            Some(constants::features()),
3416            move |cursor| communities_variables(count, Some(cursor)),
3417            parse_community_timeline,
3418        ))
3419    }
3420
3421    /// Get community members.
3422    pub async fn get_community_members(
3423        &self,
3424        community_id: impl Into<String>,
3425        count: i64,
3426        cursor: Option<String>,
3427    ) -> Result<Timeline<CommunityMember>> {
3428        self.community_users(
3429            endpoints::MEMBERS_SLICE_TIMELINE_QUERY,
3430            community_id.into(),
3431            count,
3432            cursor,
3433        )
3434        .await
3435    }
3436
3437    /// Get community moderators.
3438    pub async fn get_community_moderators(
3439        &self,
3440        community_id: impl Into<String>,
3441        count: i64,
3442        cursor: Option<String>,
3443    ) -> Result<Timeline<CommunityMember>> {
3444        self.community_users(
3445            endpoints::MODERATORS_SLICE_TIMELINE_QUERY,
3446            community_id.into(),
3447            count,
3448            cursor,
3449        )
3450        .await
3451    }
3452
3453    async fn community_users(
3454        &self,
3455        endpoint: GqlEndpoint,
3456        community_id: String,
3457        count: i64,
3458        cursor: Option<String>,
3459    ) -> Result<Timeline<CommunityMember>> {
3460        let raw = self
3461            .inner
3462            .gql_get(
3463                endpoint,
3464                id_count_variables("communityId", community_id.clone(), count, cursor.clone()),
3465                Some(json!({"responsive_web_graphql_timeline_navigation_enabled": true})),
3466                None,
3467            )
3468            .await?;
3469        let features = Some(json!({"responsive_web_graphql_timeline_navigation_enabled": true}));
3470        Ok(self.pageable_gql_timeline(
3471            raw,
3472            GqlPageMethod::Post,
3473            endpoint,
3474            features,
3475            move |cursor| {
3476                id_count_variables("communityId", community_id.clone(), count, Some(cursor))
3477            },
3478            parse_community_member_timeline,
3479        ))
3480    }
3481
3482    /// Python parity helper for community users.
3483    pub async fn _get_community_users(
3484        &self,
3485        endpoint: GqlEndpoint,
3486        community_id: impl Into<String>,
3487        count: i64,
3488        cursor: Option<String>,
3489    ) -> Result<Timeline<CommunityMember>> {
3490        self.community_users(endpoint, community_id.into(), count, cursor)
3491            .await
3492    }
3493
3494    /// Search community tweets.
3495    pub async fn search_community_tweet(
3496        &self,
3497        community_id: impl Into<String>,
3498        query: impl Into<String>,
3499        count: i64,
3500        cursor: Option<String>,
3501    ) -> Result<Timeline<Tweet>> {
3502        let community_id = community_id.into();
3503        let query = query.into();
3504        let raw = self
3505            .inner
3506            .gql_get(
3507                endpoints::COMMUNITY_TWEET_SEARCH_MODULE_QUERY,
3508                community_search_tweet_variables(
3509                    community_id.clone(),
3510                    query.clone(),
3511                    count,
3512                    cursor.clone(),
3513                ),
3514                Some(constants::features()),
3515                None,
3516            )
3517            .await?;
3518        Ok(self.pageable_gql_timeline(
3519            raw,
3520            GqlPageMethod::Get,
3521            endpoints::COMMUNITY_TWEET_SEARCH_MODULE_QUERY,
3522            Some(constants::features()),
3523            move |cursor| {
3524                community_search_tweet_variables(
3525                    community_id.clone(),
3526                    query.clone(),
3527                    count,
3528                    Some(cursor),
3529                )
3530            },
3531            parse_tweet_timeline,
3532        ))
3533    }
3534
3535    /// Join community.
3536    pub async fn join_community(&self, community_id: impl Into<String>) -> Result<Community> {
3537        let raw = self
3538            .inner
3539            .gql_post(
3540                endpoints::JOIN_COMMUNITY,
3541                json!({"community_id": community_id.into()}),
3542                None,
3543                None,
3544            )
3545            .await?;
3546        Ok(Community::from_value_with_client(raw, Some(self.clone())))
3547    }
3548
3549    /// Leave community.
3550    pub async fn leave_community(&self, community_id: impl Into<String>) -> Result<Community> {
3551        let raw = self
3552            .inner
3553            .gql_post(
3554                endpoints::LEAVE_COMMUNITY,
3555                json!({"community_id": community_id.into()}),
3556                None,
3557                None,
3558            )
3559            .await?;
3560        Ok(Community::from_value_with_client(raw, Some(self.clone())))
3561    }
3562
3563    /// Get raw scheduled tweets.
3564    pub async fn get_scheduled_tweets(&self) -> Result<Vec<ScheduledTweet>> {
3565        let raw = self
3566            .inner
3567            .gql_get(
3568                endpoints::FETCH_SCHEDULED_TWEETS,
3569                json!({"ascending": true}),
3570                None,
3571                None,
3572            )
3573            .await?;
3574        let mut values = Vec::new();
3575        find_values(&raw, "scheduled_tweets", &mut values);
3576        Ok(values
3577            .into_iter()
3578            .flat_map(|v| v.as_array().cloned().unwrap_or_default())
3579            .map(|value| ScheduledTweet::from_value_with_client(value, Some(self.clone())))
3580            .collect())
3581    }
3582
3583    /// Delete scheduled tweet.
3584    pub async fn delete_scheduled_tweet(&self, tweet_id: impl Into<String>) -> Result<Value> {
3585        self.inner
3586            .gql_post(
3587                endpoints::DELETE_SCHEDULED_TWEET,
3588                json!({"scheduled_tweet_id": tweet_id.into()}),
3589                None,
3590                None,
3591            )
3592            .await
3593    }
3594
3595    /// Create scheduled tweet.
3596    pub async fn create_scheduled_tweet(
3597        &self,
3598        scheduled_at: impl Into<String>,
3599        text: impl Into<String>,
3600        media_ids: Vec<String>,
3601    ) -> Result<Value> {
3602        self.inner
3603            .gql_post(
3604                endpoints::CREATE_SCHEDULED_TWEET,
3605                json!({
3606                    "post_tweet_request": {
3607                        "auto_populate_reply_metadata": false,
3608                        "status": text.into(),
3609                        "exclude_reply_user_ids": [],
3610                        "media_ids": media_ids
3611                    },
3612                    "execute_at": scheduled_at.into()
3613                }),
3614                None,
3615                None,
3616            )
3617            .await
3618    }
3619
3620    /// Authenticated account user id.
3621    pub async fn user_id(&self) -> Result<String> {
3622        let settings = match self.get(endpoints::v11::settings()).await {
3623            Ok(settings) => settings,
3624            Err(err) => {
3625                if let Some(user_id) = self.inner.twid_user_id()? {
3626                    return Ok(user_id);
3627                }
3628                return Err(err);
3629            }
3630        };
3631        let screen_name = settings
3632            .get("screen_name")
3633            .and_then(Value::as_str)
3634            .map(ToOwned::to_owned);
3635        let Some(screen_name) = screen_name else {
3636            if let Some(user_id) = self.inner.twid_user_id()? {
3637                return Ok(user_id);
3638            }
3639            return Err(Error::Missing("screen_name"));
3640        };
3641        Ok(self.get_user_by_screen_name(screen_name).await?.id)
3642    }
3643
3644    /// Authenticated user.
3645    pub async fn user(&self) -> Result<User> {
3646        let id = self.user_id().await?;
3647        self.get_user_by_id(id).await
3648    }
3649
3650    /// Search users.
3651    pub async fn search_user(
3652        &self,
3653        query: impl Into<String>,
3654        count: i64,
3655        cursor: Option<String>,
3656    ) -> Result<Timeline<User>> {
3657        let query = query.into();
3658        let features = Some(constants::user_features());
3659        let (raw, endpoint) = self
3660            .search_timeline_raw(
3661                search_user_variables(query.clone(), count, cursor.clone()),
3662                features.clone(),
3663            )
3664            .await?;
3665        Ok(self.pageable_gql_timeline(
3666            raw,
3667            GqlPageMethod::Post,
3668            endpoint,
3669            features,
3670            move |cursor| search_user_variables(query.clone(), count, Some(cursor)),
3671            parse_user_timeline,
3672        ))
3673    }
3674
3675    /// Similar tweets.
3676    pub async fn get_similar_tweets(&self, tweet_id: impl Into<String>) -> Result<Vec<Tweet>> {
3677        let raw = self
3678            .inner
3679            .gql_get(
3680                endpoints::SIMILAR_POSTS,
3681                json!({"tweet_id": tweet_id.into()}),
3682                Some(constants::features()),
3683                None,
3684            )
3685            .await?;
3686        let mut values = Vec::new();
3687        find_values(&raw, "result", &mut values);
3688        Ok(values
3689            .into_iter()
3690            .filter_map(|v| Tweet::from_value_with_client(v.clone(), Some(self.clone())).ok())
3691            .collect())
3692    }
3693
3694    /// User highlights tweets.
3695    pub async fn get_user_highlights_tweets(
3696        &self,
3697        user_id: impl Into<String>,
3698        count: i64,
3699        cursor: Option<String>,
3700    ) -> Result<Timeline<Tweet>> {
3701        let user_id = user_id.into();
3702        let raw = self
3703            .inner
3704            .gql_get(
3705                endpoints::USER_HIGHLIGHTS_TWEETS,
3706                user_highlights_variables(user_id.clone(), count, cursor.clone()),
3707                Some(constants::features()),
3708                None,
3709            )
3710            .await?;
3711        Ok(self.pageable_gql_timeline(
3712            raw,
3713            GqlPageMethod::Get,
3714            endpoints::USER_HIGHLIGHTS_TWEETS,
3715            Some(constants::features()),
3716            move |cursor| user_highlights_variables(user_id.clone(), count, Some(cursor)),
3717            parse_tweet_timeline,
3718        ))
3719    }
3720
3721    /// Home For You timeline.
3722    pub async fn get_timeline(
3723        &self,
3724        count: i64,
3725        seen_tweet_ids: Vec<String>,
3726        cursor: Option<String>,
3727    ) -> Result<Timeline<Tweet>> {
3728        let raw = self
3729            .inner
3730            .gql_post(
3731                endpoints::HOME_TIMELINE,
3732                home_timeline_variables(count, seen_tweet_ids.clone(), cursor.clone()),
3733                Some(constants::features()),
3734                None,
3735            )
3736            .await?;
3737        Ok(self.pageable_gql_timeline(
3738            raw,
3739            GqlPageMethod::Post,
3740            endpoints::HOME_TIMELINE,
3741            Some(constants::features()),
3742            move |cursor| home_timeline_variables(count, seen_tweet_ids.clone(), Some(cursor)),
3743            parse_tweet_timeline,
3744        ))
3745    }
3746
3747    /// Home Following timeline.
3748    pub async fn get_latest_timeline(
3749        &self,
3750        count: i64,
3751        seen_tweet_ids: Vec<String>,
3752        cursor: Option<String>,
3753    ) -> Result<Timeline<Tweet>> {
3754        let raw = self
3755            .inner
3756            .gql_post(
3757                endpoints::HOME_LATEST_TIMELINE,
3758                home_timeline_variables(count, seen_tweet_ids.clone(), cursor.clone()),
3759                Some(constants::features()),
3760                None,
3761            )
3762            .await?;
3763        Ok(self.pageable_gql_timeline(
3764            raw,
3765            GqlPageMethod::Post,
3766            endpoints::HOME_LATEST_TIMELINE,
3767            Some(constants::features()),
3768            move |cursor| home_timeline_variables(count, seen_tweet_ids.clone(), Some(cursor)),
3769            parse_tweet_timeline,
3770        ))
3771    }
3772
3773    /// Multiple tweet lookup.
3774    pub async fn get_tweets_by_ids(&self, ids: Vec<String>) -> Result<Vec<Tweet>> {
3775        let raw = self
3776            .inner
3777            .gql_get(
3778                endpoints::TWEET_RESULTS_BY_REST_IDS,
3779                json!({"tweetIds": ids, "includePromotedContent": true, "withBirdwatchNotes": true, "withVoice": true, "withCommunity": true}),
3780                Some(constants::features()),
3781                None,
3782            )
3783            .await?;
3784        let mut values = Vec::new();
3785        find_values(&raw, "result", &mut values);
3786        Ok(values
3787            .into_iter()
3788            .filter_map(|v| Tweet::from_value_with_client(v.clone(), Some(self.clone())).ok())
3789            .collect())
3790    }
3791
3792    /// Retweeters.
3793    pub async fn get_retweeters(
3794        &self,
3795        tweet_id: impl Into<String>,
3796        count: i64,
3797        cursor: Option<String>,
3798    ) -> Result<Timeline<User>> {
3799        self.tweet_engagement_users(endpoints::RETWEETERS, tweet_id.into(), count, cursor)
3800            .await
3801    }
3802
3803    /// Favoriters.
3804    pub async fn get_favoriters(
3805        &self,
3806        tweet_id: impl Into<String>,
3807        count: i64,
3808        cursor: Option<String>,
3809    ) -> Result<Timeline<User>> {
3810        self.tweet_engagement_users(endpoints::FAVORITERS, tweet_id.into(), count, cursor)
3811            .await
3812    }
3813
3814    async fn tweet_engagement_users(
3815        &self,
3816        endpoint: GqlEndpoint,
3817        tweet_id: String,
3818        count: i64,
3819        cursor: Option<String>,
3820    ) -> Result<Timeline<User>> {
3821        let raw = self
3822            .inner
3823            .gql_get(
3824                endpoint,
3825                tweet_engagement_variables(tweet_id.clone(), count, cursor.clone()),
3826                Some(constants::features()),
3827                None,
3828            )
3829            .await?;
3830        Ok(self.pageable_gql_timeline(
3831            raw,
3832            GqlPageMethod::Get,
3833            endpoint,
3834            Some(constants::features()),
3835            move |cursor| tweet_engagement_variables(tweet_id.clone(), count, Some(cursor)),
3836            parse_user_timeline,
3837        ))
3838    }
3839
3840    /// Python parity helper for tweet engagements.
3841    pub async fn _get_tweet_engagements(
3842        &self,
3843        tweet_id: impl Into<String>,
3844        count: i64,
3845        cursor: Option<String>,
3846        endpoint: GqlEndpoint,
3847    ) -> Result<Timeline<User>> {
3848        self.tweet_engagement_users(endpoint, tweet_id.into(), count, cursor)
3849            .await
3850    }
3851
3852    /// Community note.
3853    pub async fn get_community_note(&self, note_id: impl Into<String>) -> Result<CommunityNote> {
3854        let raw = self
3855            .inner
3856            .gql_get(
3857                endpoints::FETCH_COMMUNITY_NOTE,
3858                json!({"note_id": note_id.into()}),
3859                Some(constants::features()),
3860                None,
3861            )
3862            .await?;
3863        Ok(CommunityNote::from_value_with_client(
3864            raw.pointer("/data/birdwatch_note_by_rest_id")
3865                .cloned()
3866                .unwrap_or(raw),
3867            Some(self.clone()),
3868        ))
3869    }
3870
3871    /// User followers.
3872    pub async fn get_user_followers(
3873        &self,
3874        user_id: impl Into<String>,
3875        count: i64,
3876        cursor: Option<String>,
3877    ) -> Result<Timeline<User>> {
3878        self.user_friendship_users(endpoints::FOLLOWERS, user_id.into(), count, cursor)
3879            .await
3880    }
3881
3882    /// User verified followers.
3883    pub async fn get_user_verified_followers(
3884        &self,
3885        user_id: impl Into<String>,
3886        count: i64,
3887        cursor: Option<String>,
3888    ) -> Result<Timeline<User>> {
3889        self.user_friendship_users(
3890            endpoints::BLUE_VERIFIED_FOLLOWERS,
3891            user_id.into(),
3892            count,
3893            cursor,
3894        )
3895        .await
3896    }
3897
3898    /// Followers you know.
3899    pub async fn get_user_followers_you_know(
3900        &self,
3901        user_id: impl Into<String>,
3902        count: i64,
3903        cursor: Option<String>,
3904    ) -> Result<Timeline<User>> {
3905        self.user_friendship_users(endpoints::FOLLOWERS_YOU_KNOW, user_id.into(), count, cursor)
3906            .await
3907    }
3908
3909    /// User following.
3910    pub async fn get_user_following(
3911        &self,
3912        user_id: impl Into<String>,
3913        count: i64,
3914        cursor: Option<String>,
3915    ) -> Result<Timeline<User>> {
3916        self.user_friendship_users(endpoints::FOLLOWING, user_id.into(), count, cursor)
3917            .await
3918    }
3919
3920    /// User subscriptions.
3921    pub async fn get_user_subscriptions(
3922        &self,
3923        user_id: impl Into<String>,
3924        count: i64,
3925        cursor: Option<String>,
3926    ) -> Result<Timeline<User>> {
3927        self.user_friendship_users(
3928            endpoints::USER_CREATOR_SUBSCRIPTIONS,
3929            user_id.into(),
3930            count,
3931            cursor,
3932        )
3933        .await
3934    }
3935
3936    async fn user_friendship_users(
3937        &self,
3938        endpoint: GqlEndpoint,
3939        user_id: String,
3940        count: i64,
3941        cursor: Option<String>,
3942    ) -> Result<Timeline<User>> {
3943        let raw = self
3944            .inner
3945            .gql_get(
3946                endpoint,
3947                friendship_variables(user_id.clone(), count, cursor.clone()),
3948                Some(constants::features()),
3949                None,
3950            )
3951            .await?;
3952        Ok(self.pageable_gql_timeline(
3953            raw,
3954            GqlPageMethod::Get,
3955            endpoint,
3956            Some(constants::features()),
3957            move |cursor| friendship_variables(user_id.clone(), count, Some(cursor)),
3958            parse_user_timeline,
3959        ))
3960    }
3961
3962    /// Python parity helper for user friendship.
3963    pub async fn _get_user_friendship(
3964        &self,
3965        user_id: impl Into<String>,
3966        count: i64,
3967        endpoint: GqlEndpoint,
3968        cursor: Option<String>,
3969    ) -> Result<Timeline<User>> {
3970        self.user_friendship_users(endpoint, user_id.into(), count, cursor)
3971            .await
3972    }
3973
3974    /// Followers ids via v1.1.
3975    pub async fn get_followers_ids(
3976        &self,
3977        user_id: Option<String>,
3978        screen_name: Option<String>,
3979        count: i64,
3980        cursor: Option<String>,
3981    ) -> Result<Timeline<i64>> {
3982        self.friendship_ids(
3983            endpoints::v11::followers_ids(),
3984            user_id,
3985            screen_name,
3986            count,
3987            cursor,
3988        )
3989        .await
3990    }
3991
3992    /// Friends ids via v1.1.
3993    pub async fn get_friends_ids(
3994        &self,
3995        user_id: Option<String>,
3996        screen_name: Option<String>,
3997        count: i64,
3998        cursor: Option<String>,
3999    ) -> Result<Timeline<i64>> {
4000        self.friendship_ids(
4001            endpoints::v11::friends_ids(),
4002            user_id,
4003            screen_name,
4004            count,
4005            cursor,
4006        )
4007        .await
4008    }
4009
4010    /// Latest followers via v1.1 list endpoint.
4011    pub async fn get_latest_followers(
4012        &self,
4013        user_id: Option<String>,
4014        screen_name: Option<String>,
4015        count: i64,
4016        cursor: Option<String>,
4017    ) -> Result<Timeline<User>> {
4018        self.latest_friendship_users(
4019            endpoints::v11::followers_list(),
4020            user_id,
4021            screen_name,
4022            count,
4023            cursor,
4024        )
4025        .await
4026    }
4027
4028    /// Latest friends via v1.1 list endpoint.
4029    pub async fn get_latest_friends(
4030        &self,
4031        user_id: Option<String>,
4032        screen_name: Option<String>,
4033        count: i64,
4034        cursor: Option<String>,
4035    ) -> Result<Timeline<User>> {
4036        self.latest_friendship_users(
4037            endpoints::v11::friends_list(),
4038            user_id,
4039            screen_name,
4040            count,
4041            cursor,
4042        )
4043        .await
4044    }
4045
4046    async fn latest_friendship_users(
4047        &self,
4048        endpoint: String,
4049        user_id: Option<String>,
4050        screen_name: Option<String>,
4051        count: i64,
4052        cursor: Option<String>,
4053    ) -> Result<Timeline<User>> {
4054        let params = friendship_params(user_id.clone(), screen_name.clone(), count, cursor);
4055        let raw = self
4056            .inner
4057            .request(
4058                Method::GET,
4059                endpoint.clone(),
4060                None,
4061                Some(params),
4062                None,
4063                true,
4064            )
4065            .await?;
4066        Ok(self.pageable_v11_timeline(
4067            raw,
4068            move |cursor| {
4069                (
4070                    endpoint.clone(),
4071                    friendship_params(user_id.clone(), screen_name.clone(), count, Some(cursor)),
4072                )
4073            },
4074            parse_latest_friendship_users,
4075        ))
4076    }
4077
4078    /// Python parity helper for v1.1 friendship users.
4079    pub async fn _get_user_friendship_2(
4080        &self,
4081        user_id: Option<String>,
4082        screen_name: Option<String>,
4083        count: i64,
4084        endpoint: String,
4085        cursor: Option<String>,
4086    ) -> Result<Timeline<User>> {
4087        self.latest_friendship_users(endpoint, user_id, screen_name, count, cursor)
4088            .await
4089    }
4090
4091    async fn friendship_ids(
4092        &self,
4093        endpoint: String,
4094        user_id: Option<String>,
4095        screen_name: Option<String>,
4096        count: i64,
4097        cursor: Option<String>,
4098    ) -> Result<Timeline<i64>> {
4099        let params = friendship_params(user_id.clone(), screen_name.clone(), count, cursor);
4100        let raw = self
4101            .inner
4102            .request(
4103                Method::GET,
4104                endpoint.clone(),
4105                None,
4106                Some(params),
4107                None,
4108                true,
4109            )
4110            .await?;
4111        Ok(self.pageable_v11_timeline(
4112            raw,
4113            move |cursor| {
4114                (
4115                    endpoint.clone(),
4116                    friendship_params(user_id.clone(), screen_name.clone(), count, Some(cursor)),
4117                )
4118            },
4119            parse_friendship_ids,
4120        ))
4121    }
4122
4123    /// Python parity helper for friendship ids.
4124    pub async fn _get_friendship_ids(
4125        &self,
4126        user_id: Option<String>,
4127        screen_name: Option<String>,
4128        count: i64,
4129        endpoint: String,
4130        cursor: Option<String>,
4131    ) -> Result<Timeline<i64>> {
4132        self.friendship_ids(endpoint, user_id, screen_name, count, cursor)
4133            .await
4134    }
4135
4136    /// Search list.
4137    pub async fn search_list(
4138        &self,
4139        query: impl Into<String>,
4140        count: i64,
4141        cursor: Option<String>,
4142    ) -> Result<Timeline<List>> {
4143        let query = query.into();
4144        let features = Some(constants::list_features());
4145        let (raw, endpoint) = self
4146            .search_timeline_raw(
4147                search_list_variables(query.clone(), count, cursor.clone()),
4148                features.clone(),
4149            )
4150            .await?;
4151        Ok(self.pageable_gql_timeline(
4152            raw,
4153            GqlPageMethod::Get,
4154            endpoint,
4155            features,
4156            move |cursor| search_list_variables(query.clone(), count, Some(cursor)),
4157            parse_list_timeline,
4158        ))
4159    }
4160
4161    /// Search community.
4162    pub async fn search_community(
4163        &self,
4164        query: impl Into<String>,
4165        cursor: Option<String>,
4166    ) -> Result<Timeline<Community>> {
4167        let query = query.into();
4168        let raw = self
4169            .inner
4170            .gql_get(
4171                endpoints::SEARCH_COMMUNITY,
4172                search_community_variables(query.clone(), cursor.clone()),
4173                None,
4174                None,
4175            )
4176            .await?;
4177        Ok(self.pageable_gql_timeline(
4178            raw,
4179            GqlPageMethod::Get,
4180            endpoints::SEARCH_COMMUNITY,
4181            None,
4182            move |cursor| search_community_variables(query.clone(), Some(cursor)),
4183            parse_community_timeline,
4184        ))
4185    }
4186
4187    /// Request to join community.
4188    pub async fn request_to_join_community(
4189        &self,
4190        community_id: impl Into<String>,
4191        answer: Option<String>,
4192    ) -> Result<Community> {
4193        let raw = self
4194            .inner
4195            .gql_post(
4196                endpoints::REQUEST_TO_JOIN_COMMUNITY,
4197                json!({"communityId": community_id.into(), "answer": answer.unwrap_or_default()}),
4198                None,
4199                None,
4200            )
4201            .await?;
4202        Ok(Community::from_value_with_client(raw, Some(self.clone())))
4203    }
4204
4205    /// Get streaming session.
4206    pub async fn get_streaming_session(
4207        &self,
4208        topics: std::collections::BTreeSet<String>,
4209        auto_reconnect: bool,
4210    ) -> Result<crate::streaming::StreamingSession> {
4211        crate::streaming::StreamingSession::connect(
4212            self.inner.http.clone(),
4213            self.inner.base_headers(),
4214            topics,
4215            auto_reconnect,
4216        )
4217        .await
4218    }
4219
4220    /// Python parity stream helper.
4221    pub async fn _stream(
4222        &self,
4223        topics: std::collections::BTreeSet<String>,
4224    ) -> Result<crate::streaming::StreamingSession> {
4225        self.get_streaming_session(topics, true).await
4226    }
4227
4228    /// Python parity update-subscriptions helper.
4229    pub async fn _update_subscriptions(
4230        &self,
4231        session: &mut crate::streaming::StreamingSession,
4232        subscribe: Option<std::collections::BTreeSet<String>>,
4233        unsubscribe: Option<std::collections::BTreeSet<String>>,
4234    ) -> Result<crate::streaming::Payload> {
4235        session.update_subscriptions(subscribe, unsubscribe).await
4236    }
4237
4238    fn more_replies_timeline(&self, tweet_id: String, raw: Value) -> Timeline<Tweet> {
4239        let entries = first_array_for_key(&raw, "entries");
4240        let tweets = entries
4241            .iter()
4242            .filter(|entry| {
4243                !entry
4244                    .get("entryId")
4245                    .and_then(Value::as_str)
4246                    .map(|id| id.starts_with("cursor") || id.starts_with("label"))
4247                    .unwrap_or(false)
4248            })
4249            .filter_map(|entry| tweet_from_entry(entry, self))
4250            .collect();
4251        let next_cursor = entries.last().and_then(cursor_value_from_entry);
4252        let fetch = {
4253            let client = self.clone();
4254            let tweet_id = tweet_id.clone();
4255            Arc::new(move |cursor: String| {
4256                let client = client.clone();
4257                let tweet_id = tweet_id.clone();
4258                async move {
4259                    let raw = client
4260                        .inner
4261                        .gql_get(
4262                            endpoints::TWEET_DETAIL,
4263                            tweet_detail_variables(tweet_id.clone(), Some(cursor)),
4264                            Some(constants::features()),
4265                            Some(json!({"fieldToggles": {"withAuxiliaryUserLabels": false}})),
4266                        )
4267                        .await?;
4268                    Ok(client.more_replies_timeline(tweet_id, raw))
4269                }
4270                .boxed()
4271            })
4272        };
4273        Timeline::new(tweets, next_cursor, None, raw).with_page_fetchers(Some(fetch), None)
4274    }
4275
4276    fn parse_tweet_detail(&self, tweet_id: String, raw: Value) -> Result<TweetDetail> {
4277        let entries = first_array_for_key(&raw, "entries");
4278        let mut focal = None;
4279        let mut reply_to = Vec::new();
4280        let mut replies = Vec::new();
4281        let mut related_tweets = Vec::new();
4282        let mut thread = Vec::new();
4283
4284        for entry in &entries {
4285            let entry_id = entry.get("entryId").and_then(Value::as_str).unwrap_or("");
4286            if entry_id.starts_with("cursor") {
4287                continue;
4288            }
4289            let Some(tweet) = tweet_from_entry(entry, self) else {
4290                continue;
4291            };
4292            if entry_id.starts_with("tweetdetailrelatedtweets") {
4293                related_tweets.push(tweet);
4294                continue;
4295            }
4296            if entry_id == format!("tweet-{tweet_id}") {
4297                focal = Some(tweet);
4298                continue;
4299            }
4300            if focal.is_none() {
4301                reply_to.push(tweet);
4302            } else {
4303                let nested = nested_reply_tweets(entry, self);
4304                if is_self_thread_entry(entry) {
4305                    thread.push(tweet.clone());
4306                    thread.extend(nested.clone());
4307                }
4308                replies.push(tweet);
4309                replies.extend(nested);
4310            }
4311        }
4312
4313        let tweet = focal
4314            .or_else(|| {
4315                tweet_result_from_tweet_detail(&raw)
4316                    .and_then(|v| Tweet::from_value_with_client(v, Some(self.clone())).ok())
4317            })
4318            .ok_or(Error::Missing("tweet result"))?;
4319        let next_cursor = entries.last().and_then(cursor_value_from_entry);
4320        let replies = Timeline::new(replies, next_cursor.clone(), None, raw.clone());
4321        Ok(TweetDetail {
4322            tweet,
4323            reply_to,
4324            replies,
4325            related_tweets,
4326            thread,
4327            raw,
4328        })
4329    }
4330
4331    /// Python parity more replies helper.
4332    pub async fn _get_more_replies(
4333        &self,
4334        tweet_id: impl Into<String>,
4335        cursor: impl Into<String>,
4336    ) -> Result<Timeline<Tweet>> {
4337        let tweet_id = tweet_id.into();
4338        let cursor = cursor.into();
4339        let raw = self
4340            .inner
4341            .gql_get(
4342                endpoints::TWEET_DETAIL,
4343                tweet_detail_variables(tweet_id.clone(), Some(cursor)),
4344                Some(constants::features()),
4345                Some(json!({"fieldToggles": {"withAuxiliaryUserLabels": false}})),
4346            )
4347            .await?;
4348        Ok(self.more_replies_timeline(tweet_id, raw))
4349    }
4350
4351    /// Python parity show-more-replies helper.
4352    pub async fn _show_more_replies(
4353        &self,
4354        tweet_id: impl Into<String>,
4355        cursor: impl Into<String>,
4356    ) -> Result<Timeline<Tweet>> {
4357        let raw = self
4358            .inner
4359            .gql_get(
4360                endpoints::TWEET_DETAIL,
4361                tweet_detail_variables(tweet_id.into(), Some(cursor.into())),
4362                Some(constants::features()),
4363                Some(json!({"fieldToggles": {"withAuxiliaryUserLabels": false}})),
4364            )
4365            .await?;
4366        Ok(show_more_replies_timeline(raw, self))
4367    }
4368
4369    /// Python parity user state helper.
4370    pub async fn _get_user_state(&self) -> Result<Value> {
4371        self.get(endpoints::v11::user_state()).await
4372    }
4373}
4374
4375/// Guest Twitter/X client.
4376#[derive(Debug, Clone)]
4377pub struct GuestClient {
4378    inner: InnerClient,
4379}
4380
4381impl GuestClient {
4382    fn as_client(&self) -> Client {
4383        Client {
4384            inner: self.inner.clone(),
4385            captcha_solver: None,
4386        }
4387    }
4388
4389    /// Start building a guest client.
4390    pub fn builder() -> ClientBuilder {
4391        ClientBuilder::default()
4392    }
4393
4394    /// Create a guest client.
4395    pub fn new(language: impl Into<Option<String>>) -> Result<Self> {
4396        ClientBuilder::default().language(language).build_guest()
4397    }
4398
4399    /// Base headers.
4400    pub fn _base_headers(&self) -> HeaderMap {
4401        self.inner.base_headers()
4402    }
4403
4404    /// Current proxy URL if configured.
4405    pub fn proxy(&self) -> Option<String> {
4406        self.inner.proxy.clone()
4407    }
4408
4409    /// Set or clear proxy, preserving cookies and guest token.
4410    pub fn set_proxy(&mut self, proxy: Option<String>) -> Result<()> {
4411        self.inner.set_proxy(proxy)
4412    }
4413
4414    /// Raw request.
4415    pub async fn request(&self, method: Method, url: impl Into<String>) -> Result<Value> {
4416        self.inner
4417            .request(method, url.into(), None, None, None, true)
4418            .await
4419    }
4420
4421    /// Raw GET.
4422    pub async fn get(&self, url: impl Into<String>) -> Result<Value> {
4423        self.request(Method::GET, url).await
4424    }
4425
4426    /// Raw POST JSON.
4427    pub async fn post(&self, url: impl Into<String>, body: Option<Value>) -> Result<Value> {
4428        self.inner
4429            .request(
4430                Method::POST,
4431                url.into(),
4432                None,
4433                None,
4434                body.map(RequestBody::Json),
4435                true,
4436            )
4437            .await
4438    }
4439
4440    /// Activate guest session and return guest token.
4441    pub async fn activate(&mut self) -> Result<String> {
4442        let raw = self
4443            .inner
4444            .request(
4445                Method::POST,
4446                endpoints::v11::guest_activate(),
4447                None,
4448                None,
4449                None,
4450                true,
4451            )
4452            .await?;
4453        let token = raw
4454            .get("guest_token")
4455            .and_then(Value::as_str)
4456            .ok_or(Error::Missing("guest_token"))?
4457            .to_string();
4458        self.inner.guest_token = Some(token.clone());
4459        Ok(token)
4460    }
4461
4462    /// Search tweets as guest.
4463    pub async fn search_tweet(
4464        &self,
4465        query: impl Into<String>,
4466        product: TweetSearchProduct,
4467        count: i64,
4468        cursor: Option<String>,
4469    ) -> Result<Timeline<Tweet>> {
4470        self.as_client()
4471            .search_tweet(query, product, count, cursor)
4472            .await
4473    }
4474
4475    /// Get user by screen name as guest.
4476    pub async fn get_user_by_screen_name(&self, screen_name: impl Into<String>) -> Result<User> {
4477        self.as_client().get_user_by_screen_name(screen_name).await
4478    }
4479
4480    /// Get user by id as guest.
4481    pub async fn get_user_by_id(&self, user_id: impl Into<String>) -> Result<User> {
4482        self.as_client().get_user_by_id(user_id).await
4483    }
4484
4485    /// Get tweet by id as guest.
4486    pub async fn get_tweet_by_id(&self, tweet_id: impl Into<String>) -> Result<Tweet> {
4487        self.as_client().get_tweet_by_id(tweet_id).await
4488    }
4489
4490    /// Get user tweets as guest.
4491    pub async fn get_user_tweets(
4492        &self,
4493        user_id: impl Into<String>,
4494        tweet_type: TweetType,
4495        count: i64,
4496        cursor: Option<String>,
4497    ) -> Result<Timeline<Tweet>> {
4498        self.as_client()
4499            .get_user_tweets(user_id, tweet_type, count, cursor)
4500            .await
4501    }
4502
4503    /// Get user highlights as guest.
4504    pub async fn get_user_highlights_tweets(
4505        &self,
4506        user_id: impl Into<String>,
4507        count: i64,
4508        cursor: Option<String>,
4509    ) -> Result<Timeline<Tweet>> {
4510        self.as_client()
4511            .get_user_highlights_tweets(user_id, count, cursor)
4512            .await
4513    }
4514}
4515
4516fn parse_tweet_timeline(raw: Value, client: &Client) -> Timeline<Tweet> {
4517    let mut result_values = Vec::new();
4518    find_values(&raw, "result", &mut result_values);
4519    let tweets = result_values
4520        .into_iter()
4521        .filter_map(|value| Tweet::from_value_with_client(value.clone(), Some(client.clone())).ok())
4522        .collect();
4523    let next_cursor = cursor_from_raw(&raw, "Bottom");
4524    let previous_cursor = cursor_from_raw(&raw, "Top");
4525    Timeline::new(tweets, next_cursor, previous_cursor, raw)
4526}
4527
4528fn parse_user_timeline(raw: Value, client: &Client) -> Timeline<User> {
4529    let mut result_values = Vec::new();
4530    find_values(&raw, "result", &mut result_values);
4531    let users = result_values
4532        .into_iter()
4533        .filter_map(|value| {
4534            if value.get("__typename").and_then(Value::as_str) == Some("UserUnavailable") {
4535                return None;
4536            }
4537            User::from_value_with_client(value.clone(), Some(client.clone())).ok()
4538        })
4539        .collect();
4540    let next_cursor = cursor_from_raw(&raw, "Bottom");
4541    let previous_cursor = cursor_from_raw(&raw, "Top");
4542    Timeline::new(users, next_cursor, previous_cursor, raw)
4543}
4544
4545fn parse_list_timeline(raw: Value, client: &Client) -> Timeline<List> {
4546    let mut values = Vec::new();
4547    find_values(&raw, "list", &mut values);
4548    Timeline::new(
4549        values
4550            .into_iter()
4551            .cloned()
4552            .map(|value| List::from_value_with_client(value, Some(client.clone())))
4553            .collect(),
4554        cursor_from_raw(&raw, "Bottom"),
4555        cursor_from_raw(&raw, "Top"),
4556        raw,
4557    )
4558}
4559
4560fn parse_community_timeline(raw: Value, client: &Client) -> Timeline<Community> {
4561    let mut values = Vec::new();
4562    find_values(&raw, "community", &mut values);
4563    Timeline::new(
4564        values
4565            .into_iter()
4566            .cloned()
4567            .map(|value| Community::from_value_with_client(value, Some(client.clone())))
4568            .collect(),
4569        cursor_from_raw(&raw, "Bottom"),
4570        cursor_from_raw(&raw, "Top"),
4571        raw,
4572    )
4573}
4574
4575fn parse_community_member_timeline(raw: Value, client: &Client) -> Timeline<CommunityMember> {
4576    let mut values = Vec::new();
4577    find_values(&raw, "member", &mut values);
4578    Timeline::new(
4579        values
4580            .into_iter()
4581            .cloned()
4582            .map(|value| CommunityMember::from_value_with_client(value, Some(client.clone())))
4583            .collect(),
4584        cursor_from_raw(&raw, "Bottom"),
4585        cursor_from_raw(&raw, "Top"),
4586        raw,
4587    )
4588}
4589
4590fn parse_notification_timeline(raw: Value, client: &Client) -> Timeline<Notification> {
4591    let mut values = Vec::new();
4592    find_values(&raw, "notifications", &mut values);
4593    let notifications = values
4594        .into_iter()
4595        .flat_map(|v| {
4596            v.as_object()
4597                .map(|m| m.values().cloned().collect::<Vec<_>>())
4598                .unwrap_or_default()
4599        })
4600        .map(|value| Notification::from_value_with_client(value, Some(client.clone())))
4601        .collect();
4602    Timeline::new(notifications, cursor_from_raw(&raw, "Bottom"), None, raw)
4603}
4604
4605fn parse_latest_friendship_users(raw: Value, client: &Client) -> Timeline<User> {
4606    let users = raw
4607        .get("users")
4608        .and_then(Value::as_array)
4609        .cloned()
4610        .unwrap_or_default()
4611        .into_iter()
4612        .filter_map(|v| {
4613            User::from_value_with_client(crate::utils::build_user_data(&v), Some(client.clone()))
4614                .ok()
4615        })
4616        .collect();
4617    let next_cursor = raw
4618        .get("next_cursor")
4619        .and_then(Value::as_i64)
4620        .map(|v| v.to_string());
4621    let previous_cursor = raw
4622        .get("previous_cursor")
4623        .and_then(Value::as_i64)
4624        .map(|v| v.to_string());
4625    Timeline::new(users, next_cursor, previous_cursor, raw)
4626}
4627
4628fn parse_friendship_ids(raw: Value, _client: &Client) -> Timeline<i64> {
4629    let ids = raw
4630        .get("ids")
4631        .and_then(Value::as_array)
4632        .cloned()
4633        .unwrap_or_default()
4634        .into_iter()
4635        .filter_map(|v| v.as_i64())
4636        .collect();
4637    let next_cursor = raw
4638        .get("next_cursor")
4639        .and_then(Value::as_i64)
4640        .map(|v| v.to_string());
4641    let previous_cursor = raw
4642        .get("previous_cursor")
4643        .and_then(Value::as_i64)
4644        .map(|v| v.to_string());
4645    Timeline::new(ids, next_cursor, previous_cursor, raw)
4646}
4647
4648fn parse_places(raw: Value, client: &Client) -> Vec<Place> {
4649    if let Some(places) = raw.pointer("/result/places").and_then(Value::as_array) {
4650        return places
4651            .iter()
4652            .cloned()
4653            .map(|value| Place::from_value_with_client(value, Some(client.clone())))
4654            .collect();
4655    }
4656    if let Some(places) = raw.get("places").and_then(Value::as_array) {
4657        return places
4658            .iter()
4659            .cloned()
4660            .map(|value| Place::from_value_with_client(value, Some(client.clone())))
4661            .collect();
4662    }
4663    raw.as_array()
4664        .cloned()
4665        .unwrap_or_else(|| vec![raw])
4666        .into_iter()
4667        .map(|value| Place::from_value_with_client(value, Some(client.clone())))
4668        .collect()
4669}
4670
4671fn parse_guide_trends(raw: &Value, category: &str, client: &Client) -> Vec<Trend> {
4672    let entry_id_prefix = if category == "trending" {
4673        "trends"
4674    } else {
4675        "Guide"
4676    };
4677    let entries = first_array_for_key(raw, "entries");
4678    if let Some(entry) = entries.iter().rev().find(|entry| {
4679        entry
4680            .get("entryId")
4681            .and_then(Value::as_str)
4682            .map(|id| id.starts_with(entry_id_prefix))
4683            .unwrap_or(false)
4684    }) {
4685        if let Some(items) = entry
4686            .pointer("/content/timelineModule/items")
4687            .and_then(Value::as_array)
4688        {
4689            return items
4690                .iter()
4691                .filter_map(|item| item.pointer("/item/content/trend").cloned())
4692                .map(|value| Trend::from_value_with_client(value, Some(client.clone())))
4693                .collect();
4694        }
4695    }
4696
4697    let mut values = Vec::new();
4698    find_values(raw, "trend", &mut values);
4699    values
4700        .into_iter()
4701        .cloned()
4702        .map(|value| Trend::from_value_with_client(value, Some(client.clone())))
4703        .collect()
4704}
4705
4706fn created_tweet_result(raw: &Value) -> Option<Value> {
4707    raw.pointer("/data/create_tweet/tweet_results/result")
4708        .or_else(|| raw.pointer("/data/notetweet_create/tweet_results/result"))
4709        .cloned()
4710        .or_else(|| {
4711            find_first(raw, "tweet_results")
4712                .and_then(|v| v.get("result"))
4713                .cloned()
4714        })
4715}
4716
4717fn first_array_for_key(raw: &Value, key: &str) -> Vec<Value> {
4718    let mut values = Vec::new();
4719    find_values(raw, key, &mut values);
4720    values
4721        .into_iter()
4722        .find_map(|value| value.as_array().cloned())
4723        .unwrap_or_default()
4724}
4725
4726fn tweet_result_from_entry(entry: &Value) -> Option<Value> {
4727    entry
4728        .pointer("/content/itemContent/tweet_results/result")
4729        .or_else(|| entry.pointer("/item/itemContent/tweet_results/result"))
4730        .or_else(|| entry.pointer("/tweet_results/result"))
4731        .cloned()
4732        .or_else(|| {
4733            let mut values = Vec::new();
4734            find_values(entry, "tweet_results", &mut values);
4735            values
4736                .into_iter()
4737                .find_map(|value| value.get("result").cloned())
4738        })
4739}
4740
4741fn tweet_result_from_tweet_detail(raw: &Value) -> Option<Value> {
4742    let entries = first_array_for_key(raw, "entries");
4743    entries
4744        .iter()
4745        .find(|entry| {
4746            entry
4747                .get("entryId")
4748                .and_then(Value::as_str)
4749                .map(|id| id.starts_with("tweet-") || id.starts_with("tweetdetail"))
4750                .unwrap_or(false)
4751        })
4752        .and_then(tweet_result_from_entry)
4753        .or_else(|| {
4754            let mut values = Vec::new();
4755            find_values(raw, "tweet_results", &mut values);
4756            values
4757                .into_iter()
4758                .find_map(|value| value.get("result").cloned())
4759        })
4760}
4761
4762fn tweet_from_entry(entry: &Value, client: &Client) -> Option<Tweet> {
4763    tweet_result_from_entry(entry)
4764        .and_then(|value| Tweet::from_value_with_client(value, Some(client.clone())).ok())
4765}
4766
4767fn nested_reply_tweets(entry: &Value, client: &Client) -> Vec<Tweet> {
4768    entry
4769        .pointer("/content/items")
4770        .and_then(Value::as_array)
4771        .into_iter()
4772        .flatten()
4773        .skip(1)
4774        .filter(|item| {
4775            item.get("entryId")
4776                .and_then(Value::as_str)
4777                .map(|id| id.contains("tweet") && !id.contains("tweetcomposer"))
4778                .unwrap_or(false)
4779        })
4780        .filter_map(|item| tweet_from_entry(item, client))
4781        .collect()
4782}
4783
4784fn is_self_thread_entry(entry: &Value) -> bool {
4785    let mut values = Vec::new();
4786    find_values(entry, "tweetDisplayType", &mut values);
4787    values
4788        .into_iter()
4789        .any(|value| value.as_str() == Some("SelfThread"))
4790}
4791
4792fn cursor_value_from_entry(entry: &Value) -> Option<String> {
4793    let entry_id = entry.get("entryId").and_then(Value::as_str)?;
4794    if !entry_id.starts_with("cursor") {
4795        return None;
4796    }
4797    entry
4798        .pointer("/content/itemContent/value")
4799        .or_else(|| entry.pointer("/content/value"))
4800        .and_then(Value::as_str)
4801        .map(ToOwned::to_owned)
4802}
4803
4804fn show_more_replies_timeline(raw: Value, client: &Client) -> Timeline<Tweet> {
4805    let items = first_array_for_key(&raw, "moduleItems");
4806    let tweets = items
4807        .iter()
4808        .filter(|item| {
4809            item.get("entryId")
4810                .and_then(Value::as_str)
4811                .map(|id| id.contains("tweet"))
4812                .unwrap_or(false)
4813        })
4814        .filter_map(|item| tweet_from_entry(item, client))
4815        .collect();
4816    Timeline::new(tweets, None, None, raw)
4817}
4818
4819fn guess_media_type(path: Option<&Path>) -> Option<String> {
4820    path.and_then(|path| mime_guess::from_path(path).first_raw())
4821        .map(ToOwned::to_owned)
4822}
4823
4824fn current_totp(secret: &str) -> Result<String> {
4825    let normalized: String = secret
4826        .chars()
4827        .filter(|c| !c.is_ascii_whitespace())
4828        .map(|c| c.to_ascii_uppercase())
4829        .collect::<String>()
4830        .trim_end_matches('=')
4831        .to_string();
4832    let key = BASE32_NOPAD
4833        .decode(normalized.as_bytes())
4834        .map_err(|e| Error::Unsupported(format!("invalid TOTP secret: {e}")))?;
4835    let unix = SystemTime::now()
4836        .duration_since(UNIX_EPOCH)
4837        .map_err(|e| Error::Unsupported(format!("system clock before UNIX epoch: {e}")))?;
4838    totp_at(&key, unix.as_secs())
4839}
4840
4841fn totp_at(key: &[u8], unix_secs: u64) -> Result<String> {
4842    let counter = unix_secs / 30;
4843    let mut mac = Hmac::<Sha1>::new_from_slice(key)
4844        .map_err(|e| Error::Unsupported(format!("invalid TOTP key: {e}")))?;
4845    mac.update(&counter.to_be_bytes());
4846    let digest = mac.finalize().into_bytes();
4847    let offset = (digest[19] & 0x0f) as usize;
4848    let binary = (((digest[offset] & 0x7f) as u32) << 24)
4849        | ((digest[offset + 1] as u32) << 16)
4850        | ((digest[offset + 2] as u32) << 8)
4851        | (digest[offset + 3] as u32);
4852    Ok(format!("{:06}", binary % 1_000_000))
4853}
4854
4855fn cursor_from_raw(raw: &Value, cursor_type: &str) -> Option<String> {
4856    let mut values = Vec::new();
4857    find_values(raw, "content", &mut values);
4858    values.into_iter().find_map(|content| {
4859        let is_cursor = content.get("__typename").and_then(Value::as_str)
4860            == Some("TimelineTimelineCursor")
4861            || content.get("entryType").and_then(Value::as_str) == Some("TimelineTimelineCursor");
4862        if !is_cursor {
4863            return None;
4864        }
4865        let matches_type = content
4866            .get("cursorType")
4867            .and_then(Value::as_str)
4868            .map(|s| s == cursor_type)
4869            .unwrap_or(false);
4870        if matches_type {
4871            content
4872                .get("value")
4873                .and_then(Value::as_str)
4874                .map(ToOwned::to_owned)
4875        } else {
4876            None
4877        }
4878    })
4879}
4880
4881async fn save_cookies(store: Arc<ReqwestCookieStoreMutex>, path: &Path) -> Result<()> {
4882    let mut bytes = Vec::new();
4883    {
4884        let guard = store.lock().map_err(|e| Error::Cookie(e.to_string()))?;
4885        #[allow(deprecated)]
4886        guard
4887            .save_json(&mut bytes)
4888            .map_err(|e| Error::Cookie(e.to_string()))?;
4889    }
4890    fs::write(path, bytes).await?;
4891    Ok(())
4892}
4893
4894async fn load_cookies(store: Arc<ReqwestCookieStoreMutex>, path: &Path) -> Result<()> {
4895    let bytes = fs::read(path).await?;
4896    #[allow(deprecated)]
4897    let loaded = CookieStore::load_json(std::io::Cursor::new(bytes))
4898        .map_err(|e| Error::Cookie(e.to_string()))?;
4899    let mut guard = store.lock().map_err(|e| Error::Cookie(e.to_string()))?;
4900    *guard = loaded;
4901    Ok(())
4902}
4903
4904fn browser_cookie_store(cookies: &Value) -> Result<CookieStore> {
4905    let values = cookies
4906        .get("cookies")
4907        .and_then(Value::as_array)
4908        .or_else(|| cookies.as_array())
4909        .ok_or(Error::Missing("cookies"))?;
4910    let request_url = Url::parse("https://x.com/")?;
4911    let mut store = CookieStore::default();
4912    for cookie in values {
4913        let name = cookie
4914            .get("name")
4915            .and_then(Value::as_str)
4916            .ok_or(Error::Missing("cookie.name"))?;
4917        let value = cookie
4918            .get("value")
4919            .and_then(Value::as_str)
4920            .ok_or(Error::Missing("cookie.value"))?;
4921        let domain = cookie
4922            .get("domain")
4923            .and_then(Value::as_str)
4924            .unwrap_or(".x.com");
4925        let path = cookie.get("path").and_then(Value::as_str).unwrap_or("/");
4926        let set_cookie = format!("{name}={value}; Domain={domain}; Path={path}");
4927        store
4928            .parse(&set_cookie, &request_url)
4929            .map_err(|e| Error::Cookie(e.to_string()))?;
4930    }
4931    Ok(store)
4932}
4933
4934fn parse_browser_cookies_json(bytes: &[u8]) -> Result<Value> {
4935    match serde_json::from_slice(bytes) {
4936        Ok(value) => Ok(value),
4937        Err(first_error) => {
4938            let text = std::str::from_utf8(bytes)
4939                .map_err(|_| Error::Json(first_error))?
4940                .trim();
4941            let wrapped = format!("{{{text}}}");
4942            serde_json::from_str(&wrapped).map_err(Error::Json)
4943        }
4944    }
4945}
4946
4947#[cfg(test)]
4948mod tests {
4949    use super::*;
4950
4951    #[test]
4952    fn guess_media_type_uses_path_extension() {
4953        assert_eq!(
4954            guess_media_type(Some(Path::new("video.mp4"))).as_deref(),
4955            Some("video/mp4")
4956        );
4957        assert_eq!(guess_media_type(None), None);
4958    }
4959
4960    #[test]
4961    fn remove_duplicate_ct0_cookie_leaves_single_token() {
4962        let client = Client::new(Some("en-US".to_string())).unwrap();
4963        {
4964            let mut store = client.inner.cookie_store.lock().unwrap();
4965            let root_url = Url::parse("https://x.com/").unwrap();
4966            let api_url = Url::parse("https://x.com/i/api").unwrap();
4967            store.parse("ct0=first; Path=/", &root_url).unwrap();
4968            store.parse("ct0=second; Path=/i", &api_url).unwrap();
4969        }
4970
4971        let count_before = client
4972            .inner
4973            .cookie_store
4974            .lock()
4975            .unwrap()
4976            .iter_any()
4977            .filter(|cookie| cookie.name() == "ct0")
4978            .count();
4979        assert_eq!(count_before, 2);
4980
4981        client._remove_duplicate_ct0_cookie();
4982
4983        let count_after = client
4984            .inner
4985            .cookie_store
4986            .lock()
4987            .unwrap()
4988            .iter_any()
4989            .filter(|cookie| cookie.name() == "ct0")
4990            .count();
4991        assert_eq!(count_after, 1);
4992    }
4993
4994    #[test]
4995    fn create_tweet_variables_include_extended_options() {
4996        let variables = create_tweet_variables(
4997            "hello".into(),
4998            vec![json!({"media_id": "1", "tagged_users": []})],
4999            CreateTweetOptions {
5000                poll_uri: Some("card://poll".into()),
5001                reply_to: Some("10".into()),
5002                conversation_control: Some(ConversationControl::Mentioned),
5003                attachment_url: Some("https://x.com/example/status/1".into()),
5004                community_id: Some("123".into()),
5005                share_with_followers: true,
5006                richtext_options: Some(json!([{"from_index": 0, "to_index": 5}])),
5007                edit_tweet_id: Some("9".into()),
5008                ..Default::default()
5009            },
5010        );
5011
5012        assert_eq!(variables["card_uri"], "card://poll");
5013        assert_eq!(variables["reply"]["in_reply_to_tweet_id"], "10");
5014        assert_eq!(variables["conversation_control"]["mode"], "ByInvitation");
5015        assert_eq!(
5016            variables["attachment_url"],
5017            "https://x.com/example/status/1"
5018        );
5019        assert_eq!(variables["semantic_annotation_ids"][0]["entity_id"], "123");
5020        assert_eq!(variables["broadcast"], true);
5021        assert_eq!(
5022            variables["richtext_options"]["richtext_tags"][0]["to_index"],
5023            5
5024        );
5025        assert_eq!(variables["edit_options"]["previous_tweet_id"], "9");
5026    }
5027
5028    #[test]
5029    fn more_replies_timeline_parses_entries_and_next_cursor() {
5030        let client = Client::new(Some("en-US".to_string())).unwrap();
5031        let raw = json!({
5032            "data": {
5033                "threaded_conversation_with_injections_v2": {
5034                    "instructions": [{
5035                        "entries": [
5036                            {"entryId": "label-1", "content": {}},
5037                            tweet_entry("tweet-1", "1"),
5038                            {"entryId": "cursor-bottom", "content": {"itemContent": {"value": "next-token"}}}
5039                        ]
5040                    }]
5041                }
5042            }
5043        });
5044
5045        let timeline = client.more_replies_timeline("root".into(), raw);
5046
5047        assert_eq!(timeline.items.len(), 1);
5048        assert_eq!(timeline.items[0].id, "1");
5049        assert_eq!(timeline.next_cursor.as_deref(), Some("next-token"));
5050    }
5051
5052    #[test]
5053    fn show_more_replies_timeline_parses_module_items() {
5054        let client = Client::new(Some("en-US".to_string())).unwrap();
5055        let raw = json!({
5056            "moduleItems": [
5057                {"entryId": "label-1", "item": {}},
5058                tweet_entry("conversationthread-tweet-2", "2")
5059            ]
5060        });
5061
5062        let timeline = show_more_replies_timeline(raw, &client);
5063
5064        assert_eq!(timeline.items.len(), 1);
5065        assert_eq!(timeline.items[0].id, "2");
5066        assert!(timeline.next_cursor.is_none());
5067    }
5068
5069    #[test]
5070    fn totp_matches_rfc_6238_vector() {
5071        let code = totp_at(b"12345678901234567890", 59).unwrap();
5072        assert_eq!(code, "287082");
5073    }
5074
5075    #[test]
5076    fn tweet_detail_extracts_focal_tweet() {
5077        let raw = json!({"entries": [tweet_entry("tweet-123", "123")]});
5078        let result = tweet_result_from_tweet_detail(&raw).unwrap();
5079        assert_eq!(result["rest_id"], "123");
5080    }
5081
5082    #[test]
5083    fn guide_trends_prefers_python_entry_shape() {
5084        let client = Client::new(Some("en-US".to_string())).unwrap();
5085        let raw = json!({
5086            "entries": [{
5087                "entryId": "trends-1",
5088                "content": {
5089                    "timelineModule": {
5090                        "items": [{
5091                            "item": {
5092                                "content": {
5093                                    "trend": {"name": "Rust", "trend_url": {"url": "https://x.com/search?q=Rust"}}
5094                                }
5095                            }
5096                        }]
5097                    }
5098                }
5099            }]
5100        });
5101
5102        let trends = parse_guide_trends(&raw, "trending", &client);
5103
5104        assert_eq!(trends.len(), 1);
5105        assert_eq!(
5106            trends[0].raw.get("name").and_then(Value::as_str),
5107            Some("Rust")
5108        );
5109    }
5110
5111    #[test]
5112    fn api_error_mapping_covers_python_specific_codes() {
5113        assert_eq!(
5114            api_error_from_json(&json!({"errors": [{"code": 187}]})),
5115            Some(ApiErrorKind::DuplicateTweet)
5116        );
5117        assert_eq!(
5118            api_error_from_json(&json!({"errors": [{"code": 324}]})),
5119            Some(ApiErrorKind::InvalidMedia)
5120        );
5121        assert_eq!(
5122            api_error_from_json(&json!({"errors": [{"code": 144}]})),
5123            Some(ApiErrorKind::TweetNotAvailable)
5124        );
5125    }
5126
5127    #[test]
5128    fn set_proxy_updates_and_clears_proxy() {
5129        let mut client = Client::new(Some("en-US".to_string())).unwrap();
5130        client
5131            .set_proxy(Some("http://127.0.0.1:8080".into()))
5132            .unwrap();
5133        assert_eq!(client.proxy().as_deref(), Some("http://127.0.0.1:8080"));
5134        client.set_proxy(None).unwrap();
5135        assert!(client.proxy().is_none());
5136    }
5137
5138    #[test]
5139    fn tweet_detail_collects_reply_to_replies_related_and_thread() {
5140        let client = Client::new(Some("en-US".to_string())).unwrap();
5141        let raw = json!({
5142            "entries": [
5143                tweet_entry("tweet-parent", "10"),
5144                tweet_entry("tweet-20", "20"),
5145                {
5146                    "entryId": "conversationthread-1",
5147                    "content": {
5148                        "tweetDisplayType": "SelfThread",
5149                        "itemContent": {"tweet_results": {"result": tweet_result("21")}},
5150                        "items": [
5151                            {"entryId": "conversationthread-root", "item": {}},
5152                            tweet_entry("conversationthread-tweet-22", "22")
5153                        ]
5154                    }
5155                },
5156                tweet_entry("tweetdetailrelatedtweets-1", "30"),
5157                {"entryId": "cursor-bottom", "content": {"itemContent": {"value": "next"}}}
5158            ]
5159        });
5160
5161        let detail = client.parse_tweet_detail("20".into(), raw).unwrap();
5162
5163        assert_eq!(detail.tweet.id, "20");
5164        assert_eq!(detail.reply_to.len(), 1);
5165        assert_eq!(detail.replies.items.len(), 2);
5166        assert_eq!(detail.related_tweets.len(), 1);
5167        assert_eq!(detail.thread.len(), 2);
5168        assert_eq!(detail.replies.next_cursor.as_deref(), Some("next"));
5169    }
5170
5171    #[test]
5172    fn browser_cookie_store_loads_browser_shape() {
5173        let store = browser_cookie_store(&json!({
5174            "cookies": [
5175                {"name": "auth_token", "value": "token"},
5176                {"name": "ct0", "value": "csrf"}
5177            ]
5178        }))
5179        .unwrap();
5180
5181        let names: Vec<_> = store.iter_any().map(|cookie| cookie.name()).collect();
5182        assert!(names.contains(&"auth_token"));
5183        assert!(names.contains(&"ct0"));
5184    }
5185
5186    #[test]
5187    fn parse_browser_cookies_json_accepts_fragment_shape() {
5188        let value = parse_browser_cookies_json(br#""cookies": [{"name": "ct0", "value": "csrf"}]"#)
5189            .unwrap();
5190        assert_eq!(value["cookies"][0]["name"], "ct0");
5191    }
5192
5193    fn tweet_entry(entry_id: &str, tweet_id: &str) -> Value {
5194        json!({
5195            "entryId": entry_id,
5196            "content": {
5197                "itemContent": {
5198                    "tweet_results": {
5199                        "result": tweet_result(tweet_id)
5200                    }
5201                }
5202            }
5203        })
5204    }
5205
5206    fn tweet_result(tweet_id: &str) -> Value {
5207        json!({
5208            "rest_id": tweet_id,
5209            "core": {
5210                "user_results": {
5211                    "result": {
5212                        "rest_id": "100",
5213                        "legacy": {"name": "Example", "screen_name": "example"}
5214                    }
5215                }
5216            },
5217            "legacy": {
5218                "full_text": "reply",
5219                "is_quote_status": false,
5220                "entities": {"hashtags": [], "urls": []}
5221            }
5222        })
5223    }
5224}