x-twitter-scraper 0.3.0

data/lib/x_twitter_scraper/resources/x/lists.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      # X data lookups (subscription required)
+      class Lists
+        # Get list followers
+        #
+        # @overload retrieve_followers(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] List ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::ListRetrieveFollowersParams
+        def retrieve_followers(id, params = {})
+          parsed, options = XTwitterScraper::X::ListRetrieveFollowersParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/lists/%1$s/followers", id],
+            query: query,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Get list members
+        #
+        # @overload retrieve_members(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] List ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::ListRetrieveMembersParams
+        def retrieve_members(id, params = {})
+          parsed, options = XTwitterScraper::X::ListRetrieveMembersParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/lists/%1$s/members", id],
+            query: query,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Get list tweets
+        #
+        # @overload retrieve_tweets(id, cursor: nil, include_replies: nil, since_time: nil, until_time: nil, request_options: {})
+        #
+        # @param id [String] List ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param include_replies [Boolean] Include replies (default false)
+        #
+        # @param since_time [String] Unix timestamp - filter after
+        #
+        # @param until_time [String] Unix timestamp - filter before
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::ListRetrieveTweetsParams
+        def retrieve_tweets(id, params = {})
+          parsed, options = XTwitterScraper::X::ListRetrieveTweetsParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/lists/%1$s/tweets", id],
+            query: query.transform_keys(
+              include_replies: "includeReplies",
+              since_time: "sinceTime",
+              until_time: "untilTime"
+            ),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [XTwitterScraper::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/resources/x/media.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      # Media upload & download
+      class Media
+        # Download tweet media
+        #
+        # @overload download(tweet_ids: nil, tweet_input: nil, request_options: {})
+        #
+        # @param tweet_ids [Array<String>] Array of tweet URLs or IDs (bulk, max 50)
+        #
+        # @param tweet_input [String] Tweet URL or ID (single tweet)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::MediaDownloadResponse]
+        #
+        # @see XTwitterScraper::Models::X::MediaDownloadParams
+        def download(params = {})
+          parsed, options = XTwitterScraper::X::MediaDownloadParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "x/media/download",
+            body: parsed,
+            model: XTwitterScraper::Models::X::MediaDownloadResponse,
+            options: options
+          )
+        end
+
+        # Upload media
+        #
+        # @overload upload(account:, file:, is_long_video: nil, request_options: {})
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param file [Pathname, StringIO, IO, String, XTwitterScraper::FilePart] Media file to upload
+        #
+        # @param is_long_video [Boolean]
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::MediaUploadResponse]
+        #
+        # @see XTwitterScraper::Models::X::MediaUploadParams
+        def upload(params)
+          parsed, options = XTwitterScraper::X::MediaUploadParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "x/media",
+            headers: {"content-type" => "multipart/form-data"},
+            body: parsed,
+            model: XTwitterScraper::Models::X::MediaUploadResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [XTwitterScraper::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/resources/x/profile.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      # X write actions (tweets, likes, follows, DMs)
+      class Profile
+        # Update X profile
+        #
+        # @overload update(account:, description: nil, location: nil, name: nil, url: nil, request_options: {})
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param description [String] Bio description
+        #
+        # @param location [String]
+        #
+        # @param name [String] Display name
+        #
+        # @param url [String] Website URL
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::ProfileUpdateResponse]
+        #
+        # @see XTwitterScraper::Models::X::ProfileUpdateParams
+        def update(params)
+          parsed, options = XTwitterScraper::X::ProfileUpdateParams.dump_request(params)
+          @client.request(
+            method: :patch,
+            path: "x/profile",
+            body: parsed,
+            model: XTwitterScraper::Models::X::ProfileUpdateResponse,
+            options: options
+          )
+        end
+
+        # Update profile avatar
+        #
+        # @overload update_avatar(account:, file:, request_options: {})
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param file [Pathname, StringIO, IO, String, XTwitterScraper::FilePart] Avatar image (max 716KB)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::ProfileUpdateAvatarResponse]
+        #
+        # @see XTwitterScraper::Models::X::ProfileUpdateAvatarParams
+        def update_avatar(params)
+          parsed, options = XTwitterScraper::X::ProfileUpdateAvatarParams.dump_request(params)
+          @client.request(
+            method: :patch,
+            path: "x/profile/avatar",
+            headers: {"content-type" => "multipart/form-data"},
+            body: parsed,
+            model: XTwitterScraper::Models::X::ProfileUpdateAvatarResponse,
+            options: options
+          )
+        end
+
+        # Update profile banner
+        #
+        # @overload update_banner(account:, file:, request_options: {})
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param file [Pathname, StringIO, IO, String, XTwitterScraper::FilePart] Banner image (max 2MB)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::ProfileUpdateBannerResponse]
+        #
+        # @see XTwitterScraper::Models::X::ProfileUpdateBannerParams
+        def update_banner(params)
+          parsed, options = XTwitterScraper::X::ProfileUpdateBannerParams.dump_request(params)
+          @client.request(
+            method: :patch,
+            path: "x/profile/banner",
+            headers: {"content-type" => "multipart/form-data"},
+            body: parsed,
+            model: XTwitterScraper::Models::X::ProfileUpdateBannerResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [XTwitterScraper::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/resources/x/tweets/like.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Tweets
+        # X write actions (tweets, likes, follows, DMs)
+        class Like
+          # Like tweet
+          #
+          # @overload create(tweet_id, account:, request_options: {})
+          #
+          # @param tweet_id [String]
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Tweets::LikeCreateResponse]
+          #
+          # @see XTwitterScraper::Models::X::Tweets::LikeCreateParams
+          def create(tweet_id, params)
+            parsed, options = XTwitterScraper::X::Tweets::LikeCreateParams.dump_request(params)
+            @client.request(
+              method: :post,
+              path: ["x/tweets/%1$s/like", tweet_id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Tweets::LikeCreateResponse,
+              options: options
+            )
+          end
+
+          # Unlike tweet
+          #
+          # @overload delete(tweet_id, account:, request_options: {})
+          #
+          # @param tweet_id [String]
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Tweets::LikeDeleteResponse]
+          #
+          # @see XTwitterScraper::Models::X::Tweets::LikeDeleteParams
+          def delete(tweet_id, params)
+            parsed, options = XTwitterScraper::X::Tweets::LikeDeleteParams.dump_request(params)
+            @client.request(
+              method: :delete,
+              path: ["x/tweets/%1$s/like", tweet_id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Tweets::LikeDeleteResponse,
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [XTwitterScraper::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/resources/x/tweets/retweet.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Tweets
+        # X write actions (tweets, likes, follows, DMs)
+        class Retweet
+          # Retweet
+          #
+          # @overload create(tweet_id, account:, request_options: {})
+          #
+          # @param tweet_id [String]
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Tweets::RetweetCreateResponse]
+          #
+          # @see XTwitterScraper::Models::X::Tweets::RetweetCreateParams
+          def create(tweet_id, params)
+            parsed, options = XTwitterScraper::X::Tweets::RetweetCreateParams.dump_request(params)
+            @client.request(
+              method: :post,
+              path: ["x/tweets/%1$s/retweet", tweet_id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Tweets::RetweetCreateResponse,
+              options: options
+            )
+          end
+
+          # Unretweet
+          #
+          # @overload delete(tweet_id, account:, request_options: {})
+          #
+          # @param tweet_id [String]
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Tweets::RetweetDeleteResponse]
+          #
+          # @see XTwitterScraper::Models::X::Tweets::RetweetDeleteParams
+          def delete(tweet_id, params)
+            parsed, options = XTwitterScraper::X::Tweets::RetweetDeleteParams.dump_request(params)
+            @client.request(
+              method: :delete,
+              path: ["x/tweets/%1$s/retweet", tweet_id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Tweets::RetweetDeleteResponse,
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [XTwitterScraper::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/resources/x/tweets.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Tweets
+        # X write actions (tweets, likes, follows, DMs)
+        # @return [XTwitterScraper::Resources::X::Tweets::Like]
+        attr_reader :like
+
+        # X write actions (tweets, likes, follows, DMs)
+        # @return [XTwitterScraper::Resources::X::Tweets::Retweet]
+        attr_reader :retweet
+
+        # Create tweet
+        #
+        # @overload create(account:, text:, attachment_url: nil, community_id: nil, is_note_tweet: nil, media_ids: nil, reply_to_tweet_id: nil, request_options: {})
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param text [String]
+        #
+        # @param attachment_url [String]
+        #
+        # @param community_id [String]
+        #
+        # @param is_note_tweet [Boolean]
+        #
+        # @param media_ids [Array<String>]
+        #
+        # @param reply_to_tweet_id [String]
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetCreateResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetCreateParams
+        def create(params)
+          parsed, options = XTwitterScraper::X::TweetCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "x/tweets",
+            body: parsed,
+            model: XTwitterScraper::Models::X::TweetCreateResponse,
+            options: options
+          )
+        end
+
+        # Look up tweet
+        #
+        # @overload retrieve(tweet_id, request_options: {})
+        #
+        # @param tweet_id [String]
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetRetrieveResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetRetrieveParams
+        def retrieve(tweet_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["x/tweets/%1$s", tweet_id],
+            model: XTwitterScraper::Models::X::TweetRetrieveResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # Get multiple tweets by IDs
+        #
+        # @overload list(ids:, request_options: {})
+        #
+        # @param ids [String] Comma-separated tweet IDs (max 100)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::TweetListParams
+        def list(params)
+          parsed, options = XTwitterScraper::X::TweetListParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(method: :get, path: "x/tweets", query: query, model: NilClass, options: options)
+        end
+
+        # Delete tweet
+        #
+        # @overload delete(tweet_id, account:, request_options: {})
+        #
+        # @param tweet_id [String]
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetDeleteResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetDeleteParams
+        def delete(tweet_id, params)
+          parsed, options = XTwitterScraper::X::TweetDeleteParams.dump_request(params)
+          @client.request(
+            method: :delete,
+            path: ["x/tweets/%1$s", tweet_id],
+            body: parsed,
+            model: XTwitterScraper::Models::X::TweetDeleteResponse,
+            options: options
+          )
+        end
+
+        # Get users who liked a tweet
+        #
+        # @overload get_favoriters(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] Tweet ID
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetGetFavoritersResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetGetFavoritersParams
+        def get_favoriters(id, params = {})
+          parsed, options = XTwitterScraper::X::TweetGetFavoritersParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/tweets/%1$s/favoriters", id],
+            query: query,
+            model: XTwitterScraper::Models::X::TweetGetFavoritersResponse,
+            options: options
+          )
+        end
+
+        # Get quote tweets of a tweet
+        #
+        # @overload get_quotes(id, cursor: nil, include_replies: nil, since_time: nil, until_time: nil, request_options: {})
+        #
+        # @param id [String] Tweet ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param include_replies [Boolean] Include replies (default false)
+        #
+        # @param since_time [String] Unix timestamp - filter after
+        #
+        # @param until_time [String] Unix timestamp - filter before
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetGetQuotesResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetGetQuotesParams
+        def get_quotes(id, params = {})
+          parsed, options = XTwitterScraper::X::TweetGetQuotesParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/tweets/%1$s/quotes", id],
+            query: query.transform_keys(
+              include_replies: "includeReplies",
+              since_time: "sinceTime",
+              until_time: "untilTime"
+            ),
+            model: XTwitterScraper::Models::X::TweetGetQuotesResponse,
+            options: options
+          )
+        end
+
+        # Get replies to a tweet
+        #
+        # @overload get_replies(id, cursor: nil, since_time: nil, until_time: nil, request_options: {})
+        #
+        # @param id [String] Tweet ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param since_time [String] Unix timestamp - filter after
+        #
+        # @param until_time [String] Unix timestamp - filter before
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetGetRepliesResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetGetRepliesParams
+        def get_replies(id, params = {})
+          parsed, options = XTwitterScraper::X::TweetGetRepliesParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/tweets/%1$s/replies", id],
+            query: query.transform_keys(since_time: "sinceTime", until_time: "untilTime"),
+            model: XTwitterScraper::Models::X::TweetGetRepliesResponse,
+            options: options
+          )
+        end
+
+        # Get users who retweeted a tweet
+        #
+        # @overload get_retweeters(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] Tweet ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetGetRetweetersResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetGetRetweetersParams
+        def get_retweeters(id, params = {})
+          parsed, options = XTwitterScraper::X::TweetGetRetweetersParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/tweets/%1$s/retweeters", id],
+            query: query,
+            model: XTwitterScraper::Models::X::TweetGetRetweetersResponse,
+            options: options
+          )
+        end
+
+        # Get thread context for a tweet
+        #
+        # @overload get_thread(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] Tweet ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetGetThreadResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetGetThreadParams
+        def get_thread(id, params = {})
+          parsed, options = XTwitterScraper::X::TweetGetThreadParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/tweets/%1$s/thread", id],
+            query: query,
+            model: XTwitterScraper::Models::X::TweetGetThreadResponse,
+            options: options
+          )
+        end
+
+        # Search tweets
+        #
+        # @overload search(q:, cursor: nil, limit: nil, query_type: nil, since_time: nil, until_time: nil, request_options: {})
+        #
+        # @param q [String] Search query (keywords,
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param limit [Integer] Deprecated — use cursor-based pagination instead
+        #
+        # @param query_type [Symbol, XTwitterScraper::Models::X::TweetSearchParams::QueryType] Sort order — Latest (chronological) or Top (engagement-ranked)
+        #
+        # @param since_time [String] ISO 8601 timestamp — only return tweets after this time
+        #
+        # @param until_time [String] ISO 8601 timestamp — only return tweets before this time
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::TweetSearchResponse]
+        #
+        # @see XTwitterScraper::Models::X::TweetSearchParams
+        def search(params)
+          parsed, options = XTwitterScraper::X::TweetSearchParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "x/tweets/search",
+            query: query.transform_keys(
+              query_type: "queryType",
+              since_time: "sinceTime",
+              until_time: "untilTime"
+            ),
+            model: XTwitterScraper::Models::X::TweetSearchResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [XTwitterScraper::Client]
+        def initialize(client:)
+          @client = client
+          @like = XTwitterScraper::Resources::X::Tweets::Like.new(client: client)
+          @retweet = XTwitterScraper::Resources::X::Tweets::Retweet.new(client: client)
+        end
+      end
+    end
+  end
+end