x-twitter-scraper 0.3.0

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

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      # Connected X account management
+      class Accounts
+        # Connect X account
+        #
+        # @overload create(email:, password:, username:, proxy_country: nil, totp_secret: nil, request_options: {})
+        #
+        # @param email [String] Account email
+        #
+        # @param password [String] Account password
+        #
+        # @param username [String] X username
+        #
+        # @param proxy_country [String] Proxy country code
+        #
+        # @param totp_secret [String] TOTP secret for 2FA
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::AccountCreateResponse]
+        #
+        # @see XTwitterScraper::Models::X::AccountCreateParams
+        def create(params)
+          parsed, options = XTwitterScraper::X::AccountCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "x/accounts",
+            body: parsed,
+            model: XTwitterScraper::Models::X::AccountCreateResponse,
+            security: {auth_api_key: true},
+            options: options
+          )
+        end
+
+        # Get X account details
+        #
+        # @overload retrieve(id, request_options: {})
+        #
+        # @param id [String] Resource ID (stringified bigint)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::AccountRetrieveResponse]
+        #
+        # @see XTwitterScraper::Models::X::AccountRetrieveParams
+        def retrieve(id, params = {})
+          @client.request(
+            method: :get,
+            path: ["x/accounts/%1$s", id],
+            model: XTwitterScraper::Models::X::AccountRetrieveResponse,
+            security: {auth_api_key: true},
+            options: params[:request_options]
+          )
+        end
+
+        # List connected X accounts
+        #
+        # @overload list(request_options: {})
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::AccountListResponse]
+        #
+        # @see XTwitterScraper::Models::X::AccountListParams
+        def list(params = {})
+          @client.request(
+            method: :get,
+            path: "x/accounts",
+            model: XTwitterScraper::Models::X::AccountListResponse,
+            security: {auth_api_key: true},
+            options: params[:request_options]
+          )
+        end
+
+        # Disconnect X account
+        #
+        # @overload delete(id, request_options: {})
+        #
+        # @param id [String] Resource ID (stringified bigint)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::AccountDeleteResponse]
+        #
+        # @see XTwitterScraper::Models::X::AccountDeleteParams
+        def delete(id, params = {})
+          @client.request(
+            method: :delete,
+            path: ["x/accounts/%1$s", id],
+            model: XTwitterScraper::Models::X::AccountDeleteResponse,
+            security: {auth_api_key: true},
+            options: params[:request_options]
+          )
+        end
+
+        # Re-authenticate X account
+        #
+        # @overload reauth(id, password:, totp_secret: nil, request_options: {})
+        #
+        # @param id [String] Resource ID (stringified bigint)
+        #
+        # @param password [String] Account password
+        #
+        # @param totp_secret [String] TOTP secret for 2FA
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::AccountReauthResponse]
+        #
+        # @see XTwitterScraper::Models::X::AccountReauthParams
+        def reauth(id, params)
+          parsed, options = XTwitterScraper::X::AccountReauthParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["x/accounts/%1$s/reauth", id],
+            body: parsed,
+            model: XTwitterScraper::Models::X::AccountReauthResponse,
+            security: {auth_api_key: true},
+            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/bookmarks.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      # X data lookups (subscription required)
+      class Bookmarks
+        # Get bookmarked tweets
+        #
+        # @overload list(cursor: nil, folder_id: nil, request_options: {})
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param folder_id [String] Optional bookmark folder ID
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::BookmarkListResponse]
+        #
+        # @see XTwitterScraper::Models::X::BookmarkListParams
+        def list(params = {})
+          parsed, options = XTwitterScraper::X::BookmarkListParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "x/bookmarks",
+            query: query.transform_keys(folder_id: "folderId"),
+            model: XTwitterScraper::Models::X::BookmarkListResponse,
+            options: options
+          )
+        end
+
+        # Get bookmark folders
+        #
+        # @overload retrieve_folders(request_options: {})
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::BookmarkRetrieveFoldersResponse]
+        #
+        # @see XTwitterScraper::Models::X::BookmarkRetrieveFoldersParams
+        def retrieve_folders(params = {})
+          @client.request(
+            method: :get,
+            path: "x/bookmarks/folders",
+            model: XTwitterScraper::Models::X::BookmarkRetrieveFoldersResponse,
+            options: params[:request_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/communities/join.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Communities
+        # X write actions (tweets, likes, follows, DMs)
+        class Join
+          # Join community
+          #
+          # @overload create(id, account:, request_options: {})
+          #
+          # @param id [String] Resource ID (stringified bigint)
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Communities::JoinCreateResponse]
+          #
+          # @see XTwitterScraper::Models::X::Communities::JoinCreateParams
+          def create(id, params)
+            parsed, options = XTwitterScraper::X::Communities::JoinCreateParams.dump_request(params)
+            @client.request(
+              method: :post,
+              path: ["x/communities/%1$s/join", id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Communities::JoinCreateResponse,
+              options: options
+            )
+          end
+
+          # Leave community
+          #
+          # @overload delete_all(id, account:, request_options: {})
+          #
+          # @param id [String] Resource ID (stringified bigint)
+          #
+          # @param account [String] X account (@username or account ID)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [XTwitterScraper::Models::X::Communities::JoinDeleteAllResponse]
+          #
+          # @see XTwitterScraper::Models::X::Communities::JoinDeleteAllParams
+          def delete_all(id, params)
+            parsed, options = XTwitterScraper::X::Communities::JoinDeleteAllParams.dump_request(params)
+            @client.request(
+              method: :delete,
+              path: ["x/communities/%1$s/join", id],
+              body: parsed,
+              model: XTwitterScraper::Models::X::Communities::JoinDeleteAllResponse,
+              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/communities/tweets.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Communities
+        # X data lookups (subscription required)
+        class Tweets
+          # Search tweets across all communities
+          #
+          # @overload list(q:, cursor: nil, query_type: nil, request_options: {})
+          #
+          # @param q [String] Search query
+          #
+          # @param cursor [String] Pagination cursor
+          #
+          # @param query_type [String] Sort order (Latest or Top)
+          #
+          # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [nil]
+          #
+          # @see XTwitterScraper::Models::X::Communities::TweetListParams
+          def list(params)
+            parsed, options = XTwitterScraper::X::Communities::TweetListParams.dump_request(params)
+            query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+            @client.request(
+              method: :get,
+              path: "x/communities/tweets",
+              query: query.transform_keys(query_type: "queryType"),
+              model: NilClass,
+              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/communities.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Communities
+        # X write actions (tweets, likes, follows, DMs)
+        # @return [XTwitterScraper::Resources::X::Communities::Join]
+        attr_reader :join
+
+        # X data lookups (subscription required)
+        # @return [XTwitterScraper::Resources::X::Communities::Tweets]
+        attr_reader :tweets
+
+        # Create community
+        #
+        # @overload create(account:, name:, description: nil, request_options: {})
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param name [String] Community name
+        #
+        # @param description [String] Community description
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::CommunityCreateResponse]
+        #
+        # @see XTwitterScraper::Models::X::CommunityCreateParams
+        def create(params)
+          parsed, options = XTwitterScraper::X::CommunityCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "x/communities",
+            body: parsed,
+            model: XTwitterScraper::Models::X::CommunityCreateResponse,
+            options: options
+          )
+        end
+
+        # Delete community
+        #
+        # @overload delete(id, account:, community_name:, request_options: {})
+        #
+        # @param id [String] Resource ID (stringified bigint)
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param community_name [String] Community name for confirmation
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::CommunityDeleteResponse]
+        #
+        # @see XTwitterScraper::Models::X::CommunityDeleteParams
+        def delete(id, params)
+          parsed, options = XTwitterScraper::X::CommunityDeleteParams.dump_request(params)
+          @client.request(
+            method: :delete,
+            path: ["x/communities/%1$s", id],
+            body: parsed,
+            model: XTwitterScraper::Models::X::CommunityDeleteResponse,
+            options: options
+          )
+        end
+
+        # Get community details
+        #
+        # @overload retrieve_info(id, request_options: {})
+        #
+        # @param id [String] Community ID
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::CommunityRetrieveInfoResponse]
+        #
+        # @see XTwitterScraper::Models::X::CommunityRetrieveInfoParams
+        def retrieve_info(id, params = {})
+          @client.request(
+            method: :get,
+            path: ["x/communities/%1$s/info", id],
+            model: XTwitterScraper::Models::X::CommunityRetrieveInfoResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # Get community members
+        #
+        # @overload retrieve_members(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] Community ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::CommunityRetrieveMembersParams
+        def retrieve_members(id, params = {})
+          parsed, options = XTwitterScraper::X::CommunityRetrieveMembersParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/communities/%1$s/members", id],
+            query: query,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Get community moderators
+        #
+        # @overload retrieve_moderators(id, cursor: nil, request_options: {})
+        #
+        # @param id [String] Community ID
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::CommunityRetrieveModeratorsParams
+        def retrieve_moderators(id, params = {})
+          parsed, options = XTwitterScraper::X::CommunityRetrieveModeratorsParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/communities/%1$s/moderators", id],
+            query: query,
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Search tweets across communities
+        #
+        # @overload retrieve_search(q:, cursor: nil, query_type: nil, request_options: {})
+        #
+        # @param q [String] Search query
+        #
+        # @param cursor [String] Pagination cursor
+        #
+        # @param query_type [String] Sort order (Latest or Top)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see XTwitterScraper::Models::X::CommunityRetrieveSearchParams
+        def retrieve_search(params)
+          parsed, options = XTwitterScraper::X::CommunityRetrieveSearchParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "x/communities/search",
+            query: query.transform_keys(query_type: "queryType"),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [XTwitterScraper::Client]
+        def initialize(client:)
+          @client = client
+          @join = XTwitterScraper::Resources::X::Communities::Join.new(client: client)
+          @tweets = XTwitterScraper::Resources::X::Communities::Tweets.new(client: client)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      class Dm
+        # Get DM conversation history
+        #
+        # @overload retrieve_history(user_id, cursor: nil, max_id: nil, request_options: {})
+        #
+        # @param user_id [String] Target user ID
+        #
+        # @param cursor [String] Pagination cursor from previous response
+        #
+        # @param max_id [String] Legacy pagination cursor (backward compat)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::DmRetrieveHistoryResponse]
+        #
+        # @see XTwitterScraper::Models::X::DmRetrieveHistoryParams
+        def retrieve_history(user_id, params = {})
+          parsed, options = XTwitterScraper::X::DmRetrieveHistoryParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: ["x/dm/%1$s/history", user_id],
+            query: query.transform_keys(max_id: "maxId"),
+            model: XTwitterScraper::Models::X::DmRetrieveHistoryResponse,
+            options: options
+          )
+        end
+
+        # Send direct message
+        #
+        # @overload send_(user_id, account:, text:, media_ids: nil, reply_to_message_id: nil, request_options: {})
+        #
+        # @param user_id [String] Recipient user ID
+        #
+        # @param account [String] X account (@username or account ID)
+        #
+        # @param text [String]
+        #
+        # @param media_ids [Array<String>]
+        #
+        # @param reply_to_message_id [String]
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::DmSendResponse]
+        #
+        # @see XTwitterScraper::Models::X::DmSendParams
+        def send_(user_id, params)
+          parsed, options = XTwitterScraper::X::DmSendParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["x/dm/%1$s", user_id],
+            body: parsed,
+            model: XTwitterScraper::Models::X::DmSendResponse,
+            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/followers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Resources
+    class X
+      # X data lookups (subscription required)
+      class Followers
+        # Check follow relationship
+        #
+        # @overload check(source:, target:, request_options: {})
+        #
+        # @param source [String] Username to check (without @)
+        #
+        # @param target [String] Target username (without @)
+        #
+        # @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [XTwitterScraper::Models::X::FollowerCheckResponse]
+        #
+        # @see XTwitterScraper::Models::X::FollowerCheckParams
+        def check(params)
+          parsed, options = XTwitterScraper::X::FollowerCheckParams.dump_request(params)
+          query = XTwitterScraper::Internal::Util.encode_query_params(parsed)
+          @client.request(
+            method: :get,
+            path: "x/followers/check",
+            query: query,
+            model: XTwitterScraper::Models::X::FollowerCheckResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [XTwitterScraper::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end