x-twitter-scraper 0.3.0

data/lib/x_twitter_scraper/resources/x/users/follow.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Users
+        # X write actions (tweets, likes, follows, DMs)
+        class Follow
+          # Follow user
+          #
+          # @overload create(user_id, account:, request_options: {})
+          #
+          # @param user_id [String] User ID to follow
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Users::FollowCreateResponse]
+          #
+          # @see XTwitterScraper::Models::X::Users::FollowCreateParams
+          def create(user_id, params)
+            parsed, options = XTwitterScraper::X::Users::FollowCreateParams.dump_request(params)
+            @client.request(
+              method: :post,
+              path: ["x/users/%1$s/follow", user_id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Users::FollowCreateResponse,
+              options: options
+            )
+          end
+
+          # Unfollow user
+          #
+          # @overload delete_all(user_id, account:, request_options: {})
+          #
+          # @param user_id [String] User ID to unfollow
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Users::FollowDeleteAllResponse]
+          #
+          # @see XTwitterScraper::Models::X::Users::FollowDeleteAllParams
+          def delete_all(user_id, params)
+            parsed, options = XTwitterScraper::X::Users::FollowDeleteAllParams.dump_request(params)
+            @client.request(
+              method: :delete,
+              path: ["x/users/%1$s/follow", user_id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Users::FollowDeleteAllResponse,
+              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/users.rb

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      # X data lookups (subscription required)
+      class Users
+        # X write actions (tweets, likes, follows, DMs)
+        # @return [XTwitterScraper::Resources::X::Users::Follow]
+        attr_reader :follow
+
+        # Look up X user
+        #
+        # @overload retrieve(username, request_options: {})
+        #
+        # @param username [String] X username (without @)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::UserRetrieveResponse]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveParams
+        def retrieve(username, params = {})
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s", username],
+            model: XTwitterScraper::Models::X::UserRetrieveResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # Get multiple users by IDs
+        #
+        # @overload retrieve_batch(ids:, request_options: {})
+        #
+        # @param ids [String] Comma-separated user IDs (max 100)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveBatchParams
+        def retrieve_batch(params)
+          parsed, options = XTwitterScraper::X::UserRetrieveBatchParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "x/users/batch",
+            query: query,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Get user followers
+        #
+        # @overload retrieve_followers(id, cursor: nil, page_size: nil, request_options: {})
+        #
+        # @param id [String] User ID or username
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param page_size [Integer] Items per page (20-200, default 200)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveFollowersParams
+        def retrieve_followers(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveFollowersParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/followers", id],
+            query: query.transform_keys(page_size: "pageSize"),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Get followers you know for a user
+        #
+        # @overload retrieve_followers_you_know(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] User ID
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::UserRetrieveFollowersYouKnowResponse]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveFollowersYouKnowParams
+        def retrieve_followers_you_know(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveFollowersYouKnowParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/followers-you-know", id],
+            query: query,
+            model: XTwitterScraper::Models::X::UserRetrieveFollowersYouKnowResponse,
+            options: options
+          )
+        end
+
+        # Get users this user follows
+        #
+        # @overload retrieve_following(id, cursor: nil, page_size: nil, request_options: {})
+        #
+        # @param id [String] User ID or username
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param page_size [Integer] Items per page (20-200, default 200)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveFollowingParams
+        def retrieve_following(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveFollowingParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/following", id],
+            query: query.transform_keys(page_size: "pageSize"),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Get tweets liked by a user
+        #
+        # @overload retrieve_likes(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] User ID
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::UserRetrieveLikesResponse]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveLikesParams
+        def retrieve_likes(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveLikesParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/likes", id],
+            query: query,
+            model: XTwitterScraper::Models::X::UserRetrieveLikesResponse,
+            options: options
+          )
+        end
+
+        # Get media tweets by a user
+        #
+        # @overload retrieve_media(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] User ID
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::UserRetrieveMediaResponse]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveMediaParams
+        def retrieve_media(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveMediaParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/media", id],
+            query: query,
+            model: XTwitterScraper::Models::X::UserRetrieveMediaResponse,
+            options: options
+          )
+        end
+
+        # Get tweets mentioning a user
+        #
+        # @overload retrieve_mentions(id, cursor: nil, since_time: nil, until_time: nil, request_options: {})
+        #
+        # @param id [String] User ID or username
+        #
+        # @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 [nil]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveMentionsParams
+        def retrieve_mentions(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveMentionsParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/mentions", id],
+            query: query.transform_keys(since_time: "sinceTime", until_time: "untilTime"),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Search users by name or username
+        #
+        # @overload retrieve_search(q:, cursor: nil, request_options: {})
+        #
+        # @param q [String] Search query
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveSearchParams
+        def retrieve_search(params)
+          parsed, options = XTwitterScraper::X::UserRetrieveSearchParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "x/users/search",
+            query: query,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Get recent tweets by a user
+        #
+        # @overload retrieve_tweets(id, cursor: nil, include_parent_tweet: nil, include_replies: nil, request_options: {})
+        #
+        # @param id [String]
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param include_parent_tweet [Boolean] Include parent tweet for replies
+        #
+        # @param include_replies [Boolean] Include reply tweets
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::UserRetrieveTweetsResponse]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveTweetsParams
+        def retrieve_tweets(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveTweetsParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/tweets", id],
+            query: query.transform_keys(
+              include_parent_tweet: "includeParentTweet",
+              include_replies: "includeReplies"
+            ),
+            model: XTwitterScraper::Models::X::UserRetrieveTweetsResponse,
+            options: options
+          )
+        end
+
+        # Get verified followers
+        #
+        # @overload retrieve_verified_followers(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] User ID or username
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::UserRetrieveVerifiedFollowersParams
+        def retrieve_verified_followers(id, params = {})
+          parsed, options = XTwitterScraper::X::UserRetrieveVerifiedFollowersParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/users/%1$s/verified-followers", id],
+            query: query,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [XTwitterScraper::Client]
+        def initialize(client:)
+          @client = client
+          @follow = XTwitterScraper::Resources::X::Users::Follow.new(client: client)
+        end
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/resources/x.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    # X data lookups (subscription required)
+    class X
+      # @return [XTwitterScraper::Resources::X::Tweets]
+      attr_reader :tweets
+
+      # X data lookups (subscription required)
+      # @return [XTwitterScraper::Resources::X::Users]
+      attr_reader :users
+
+      # X data lookups (subscription required)
+      # @return [XTwitterScraper::Resources::X::Followers]
+      attr_reader :followers
+
+      # @return [XTwitterScraper::Resources::X::Dm]
+      attr_reader :dm
+
+      # Media upload & download
+      # @return [XTwitterScraper::Resources::X::Media]
+      attr_reader :media
+
+      # X write actions (tweets, likes, follows, DMs)
+      # @return [XTwitterScraper::Resources::X::Profile]
+      attr_reader :profile
+
+      # @return [XTwitterScraper::Resources::X::Communities]
+      attr_reader :communities
+
+      # Connected X account management
+      # @return [XTwitterScraper::Resources::X::Accounts]
+      attr_reader :accounts
+
+      # X data lookups (subscription required)
+      # @return [XTwitterScraper::Resources::X::Bookmarks]
+      attr_reader :bookmarks
+
+      # X data lookups (subscription required)
+      # @return [XTwitterScraper::Resources::X::Lists]
+      attr_reader :lists
+
+      # Retrieve the full content of an X Article (long-form post) by tweet ID.
+      #
+      # @overload get_article(tweet_id, request_options: {})
+      #
+      # @param tweet_id [String]
+      # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [XTwitterScraper::Models::XGetArticleResponse]
+      #
+      # @see XTwitterScraper::Models::XGetArticleParams
+      def get_article(tweet_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["x/articles/%1$s", tweet_id],
+          model: XTwitterScraper::Models::XGetArticleResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Get home timeline
+      #
+      # @overload get_home_timeline(cursor: nil, seen_tweet_ids: nil, request_options: {})
+      #
+      # @param cursor [String] Pagination cursor from previous response
+      #
+      # @param seen_tweet_ids [String] Comma-separated tweet IDs to exclude from results
+      #
+      # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [XTwitterScraper::Models::XGetHomeTimelineResponse]
+      #
+      # @see XTwitterScraper::Models::XGetHomeTimelineParams
+      def get_home_timeline(params = {})
+        parsed, options = XTwitterScraper::XGetHomeTimelineParams.dump_request(params)
+        query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "x/timeline",
+          query: query.transform_keys(seen_tweet_ids: "seenTweetIds"),
+          model: XTwitterScraper::Models::XGetHomeTimelineResponse,
+          options: options
+        )
+      end
+
+      # Get notifications
+      #
+      # @overload get_notifications(cursor: nil, type: nil, request_options: {})
+      #
+      # @param cursor [String] Pagination cursor from previous response
+      #
+      # @param type [Symbol, XTwitterScraper::Models::XGetNotificationsParams::Type] Notification type filter
+      #
+      # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [XTwitterScraper::Models::XGetNotificationsResponse]
+      #
+      # @see XTwitterScraper::Models::XGetNotificationsParams
+      def get_notifications(params = {})
+        parsed, options = XTwitterScraper::XGetNotificationsParams.dump_request(params)
+        query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "x/notifications",
+          query: query,
+          model: XTwitterScraper::Models::XGetNotificationsResponse,
+          options: options
+        )
+      end
+
+      # Get trending topics
+      #
+      # @overload get_trends(request_options: {})
+      #
+      # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [nil]
+      #
+      # @see XTwitterScraper::Models::XGetTrendsParams
+      def get_trends(params = {})
+        @client.request(method: :get, path: "x/trends", model: NilClass, options: params[:request_options])
+      end
+
+      # @api private
+      #
+      # @param client [XTwitterScraper::Client]
+      def initialize(client:)
+        @client = client
+        @tweets = XTwitterScraper::Resources::X::Tweets.new(client: client)
+        @users = XTwitterScraper::Resources::X::Users.new(client: client)
+        @followers = XTwitterScraper::Resources::X::Followers.new(client: client)
+        @dm = XTwitterScraper::Resources::X::Dm.new(client: client)
+        @media = XTwitterScraper::Resources::X::Media.new(client: client)
+        @profile = XTwitterScraper::Resources::X::Profile.new(client: client)
+        @communities = XTwitterScraper::Resources::X::Communities.new(client: client)
+        @accounts = XTwitterScraper::Resources::X::Accounts.new(client: client)
+        @bookmarks = XTwitterScraper::Resources::X::Bookmarks.new(client: client)
+        @lists = XTwitterScraper::Resources::X::Lists.new(client: client)
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  VERSION = "0.3.0"
+end