x-twitter-scraper 0.3.0

data/rbi/x_twitter_scraper/resources/x/users.rbi

@@ -0,0 +1,221 @@
+# typed: strong
+
+module XTwitterScraper
+  module Resources
+    class X
+      # X data lookups (subscription required)
+      class Users
+        # X write actions (tweets, likes, follows, DMs)
+        sig { returns(XTwitterScraper::Resources::X::Users::Follow) }
+        attr_reader :follow
+
+        # Look up X user
+        sig do
+          params(
+            username: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::X::UserRetrieveResponse)
+        end
+        def retrieve(
+          # X username (without @)
+          username,
+          request_options: {}
+        )
+        end
+
+        # Get multiple users by IDs
+        sig do
+          params(
+            ids: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).void
+        end
+        def retrieve_batch(
+          # Comma-separated user IDs (max 100)
+          ids:,
+          request_options: {}
+        )
+        end
+
+        # Get user followers
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            page_size: Integer,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).void
+        end
+        def retrieve_followers(
+          # User ID or username
+          id,
+          # Pagination cursor
+          cursor: nil,
+          # Items per page (20-200, default 200)
+          page_size: nil,
+          request_options: {}
+        )
+        end
+
+        # Get followers you know for a user
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(
+            XTwitterScraper::Models::X::UserRetrieveFollowersYouKnowResponse
+          )
+        end
+        def retrieve_followers_you_know(
+          # User ID
+          id,
+          # Pagination cursor from previous response
+          cursor: nil,
+          request_options: {}
+        )
+        end
+
+        # Get users this user follows
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            page_size: Integer,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).void
+        end
+        def retrieve_following(
+          # User ID or username
+          id,
+          # Pagination cursor
+          cursor: nil,
+          # Items per page (20-200, default 200)
+          page_size: nil,
+          request_options: {}
+        )
+        end
+
+        # Get tweets liked by a user
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::X::UserRetrieveLikesResponse)
+        end
+        def retrieve_likes(
+          # User ID
+          id,
+          # Pagination cursor from previous response
+          cursor: nil,
+          request_options: {}
+        )
+        end
+
+        # Get media tweets by a user
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::X::UserRetrieveMediaResponse)
+        end
+        def retrieve_media(
+          # User ID
+          id,
+          # Pagination cursor from previous response
+          cursor: nil,
+          request_options: {}
+        )
+        end
+
+        # Get tweets mentioning a user
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            since_time: String,
+            until_time: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).void
+        end
+        def retrieve_mentions(
+          # User ID or username
+          id,
+          # Pagination cursor
+          cursor: nil,
+          # Unix timestamp - filter after
+          since_time: nil,
+          # Unix timestamp - filter before
+          until_time: nil,
+          request_options: {}
+        )
+        end
+
+        # Search users by name or username
+        sig do
+          params(
+            q: String,
+            cursor: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).void
+        end
+        def retrieve_search(
+          # Search query
+          q:,
+          # Pagination cursor
+          cursor: nil,
+          request_options: {}
+        )
+        end
+
+        # Get recent tweets by a user
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            include_parent_tweet: T::Boolean,
+            include_replies: T::Boolean,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).returns(XTwitterScraper::Models::X::UserRetrieveTweetsResponse)
+        end
+        def retrieve_tweets(
+          id,
+          # Pagination cursor from previous response
+          cursor: nil,
+          # Include parent tweet for replies
+          include_parent_tweet: nil,
+          # Include reply tweets
+          include_replies: nil,
+          request_options: {}
+        )
+        end
+
+        # Get verified followers
+        sig do
+          params(
+            id: String,
+            cursor: String,
+            request_options: XTwitterScraper::RequestOptions::OrHash
+          ).void
+        end
+        def retrieve_verified_followers(
+          # User ID or username
+          id,
+          # Pagination cursor
+          cursor: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig do
+          params(client: XTwitterScraper::Client).returns(T.attached_class)
+        end
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/x_twitter_scraper/resources/x.rbi

@@ -0,0 +1,101 @@
+# typed: strong
+
+module XTwitterScraper
+  module Resources
+    # X data lookups (subscription required)
+    class X
+      sig { returns(XTwitterScraper::Resources::X::Tweets) }
+      attr_reader :tweets
+
+      # X data lookups (subscription required)
+      sig { returns(XTwitterScraper::Resources::X::Users) }
+      attr_reader :users
+
+      # X data lookups (subscription required)
+      sig { returns(XTwitterScraper::Resources::X::Followers) }
+      attr_reader :followers
+
+      sig { returns(XTwitterScraper::Resources::X::Dm) }
+      attr_reader :dm
+
+      # Media upload & download
+      sig { returns(XTwitterScraper::Resources::X::Media) }
+      attr_reader :media
+
+      # X write actions (tweets, likes, follows, DMs)
+      sig { returns(XTwitterScraper::Resources::X::Profile) }
+      attr_reader :profile
+
+      sig { returns(XTwitterScraper::Resources::X::Communities) }
+      attr_reader :communities
+
+      # Connected X account management
+      sig { returns(XTwitterScraper::Resources::X::Accounts) }
+      attr_reader :accounts
+
+      # X data lookups (subscription required)
+      sig { returns(XTwitterScraper::Resources::X::Bookmarks) }
+      attr_reader :bookmarks
+
+      # X data lookups (subscription required)
+      sig { returns(XTwitterScraper::Resources::X::Lists) }
+      attr_reader :lists
+
+      # Retrieve the full content of an X Article (long-form post) by tweet ID.
+      sig do
+        params(
+          tweet_id: String,
+          request_options: XTwitterScraper::RequestOptions::OrHash
+        ).returns(XTwitterScraper::Models::XGetArticleResponse)
+      end
+      def get_article(tweet_id, request_options: {})
+      end
+
+      # Get home timeline
+      sig do
+        params(
+          cursor: String,
+          seen_tweet_ids: String,
+          request_options: XTwitterScraper::RequestOptions::OrHash
+        ).returns(XTwitterScraper::Models::XGetHomeTimelineResponse)
+      end
+      def get_home_timeline(
+        # Pagination cursor from previous response
+        cursor: nil,
+        # Comma-separated tweet IDs to exclude from results
+        seen_tweet_ids: nil,
+        request_options: {}
+      )
+      end
+
+      # Get notifications
+      sig do
+        params(
+          cursor: String,
+          type: XTwitterScraper::XGetNotificationsParams::Type::OrSymbol,
+          request_options: XTwitterScraper::RequestOptions::OrHash
+        ).returns(XTwitterScraper::Models::XGetNotificationsResponse)
+      end
+      def get_notifications(
+        # Pagination cursor from previous response
+        cursor: nil,
+        # Notification type filter
+        type: nil,
+        request_options: {}
+      )
+      end
+
+      # Get trending topics
+      sig do
+        params(request_options: XTwitterScraper::RequestOptions::OrHash).void
+      end
+      def get_trends(request_options: {})
+      end
+
+      # @api private
+      sig { params(client: XTwitterScraper::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/x_twitter_scraper/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module XTwitterScraper
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/x_twitter_scraper/client.rbs

@@ -0,0 +1,69 @@
+module XTwitterScraper
+  class Client < XTwitterScraper::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader api_key: String?
+
+    attr_reader bearer_token: String?
+
+    attr_reader account: XTwitterScraper::Resources::Account
+
+    attr_reader api_keys: XTwitterScraper::Resources::APIKeys
+
+    attr_reader subscribe: XTwitterScraper::Resources::Subscribe
+
+    attr_reader compose: XTwitterScraper::Resources::Compose
+
+    attr_reader drafts: XTwitterScraper::Resources::Drafts
+
+    attr_reader styles: XTwitterScraper::Resources::Styles
+
+    attr_reader radar: XTwitterScraper::Resources::Radar
+
+    attr_reader monitors: XTwitterScraper::Resources::Monitors
+
+    attr_reader events: XTwitterScraper::Resources::Events
+
+    attr_reader extractions: XTwitterScraper::Resources::Extractions
+
+    attr_reader draws: XTwitterScraper::Resources::Draws
+
+    attr_reader webhooks: XTwitterScraper::Resources::Webhooks
+
+    attr_reader integrations: XTwitterScraper::Resources::Integrations
+
+    attr_reader x: XTwitterScraper::Resources::X
+
+    attr_reader trends: XTwitterScraper::Resources::Trends
+
+    attr_reader bot: XTwitterScraper::Resources::Bot
+
+    attr_reader support: XTwitterScraper::Resources::Support
+
+    attr_reader credits: XTwitterScraper::Resources::Credits
+
+    private def auth_headers: (
+      security: { auth_api_key: bool, oauth_bearer: bool }
+    ) -> ::Hash[String, String]
+
+    private def auth_api_key: -> ::Hash[String, String]
+
+    private def oauth_bearer: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?bearer_token: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end

data/sig/x_twitter_scraper/errors.rbs

@@ -0,0 +1,117 @@
+module XTwitterScraper
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < XTwitterScraper::Errors::Error
+      def cause: -> StandardError?
+
+      def initialize: (
+        on: Class,
+        method: Symbol,
+        target: top,
+        value: top,
+        ?cause: StandardError?
+      ) -> void
+    end
+
+    class APIError < XTwitterScraper::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor headers: ::Hash[String, String]?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?headers: ::Hash[String, String]?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < XTwitterScraper::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < XTwitterScraper::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < XTwitterScraper::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class BadRequestError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: 400
+    end
+
+    class AuthenticationError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: 401
+    end
+
+    class PermissionDeniedError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: 403
+    end
+
+    class NotFoundError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: 404
+    end
+
+    class ConflictError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: 409
+    end
+
+    class UnprocessableEntityError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: 422
+    end
+
+    class RateLimitError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: 429
+    end
+
+    class InternalServerError < XTwitterScraper::Errors::APIStatusError
+      HTTP_STATUS: Range[Integer]
+    end
+  end
+end

data/sig/x_twitter_scraper/file_part.rbs

@@ -0,0 +1,21 @@
+module XTwitterScraper
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: (Pathname | String)?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/x_twitter_scraper/internal/transport/base_client.rbs

@@ -0,0 +1,135 @@
+module XTwitterScraper
+  module Internal
+    module Transport
+      class BaseClient
+        extend XTwitterScraper::Internal::Util::SorbetRuntimeSupport
+
+        type request_components =
+          {
+            method: Symbol,
+            path: String | ::Array[String],
+            query: ::Hash[String, (::Array[String] | String)?]?,
+            headers: ::Hash[String, (String
+            | Integer
+            | ::Array[(String | Integer)?])?]?,
+            body: top?,
+            unwrap: (Symbol
+            | Integer
+            | ::Array[(Symbol | Integer)]
+            | (^(top arg0) -> top))?,
+            page: Class?,
+            stream: Class?,
+            model: XTwitterScraper::Internal::Type::Converter::input?,
+            security: { auth_api_key: bool, oauth_bearer: bool }?,
+            options: XTwitterScraper::request_opts?
+          }
+        type request_input =
+          {
+            method: Symbol,
+            url: URI::Generic,
+            headers: ::Hash[String, String],
+            body: top,
+            max_retries: Integer,
+            timeout: Float
+          }
+
+        MAX_REDIRECTS: 20
+
+        PLATFORM_HEADERS: ::Hash[String, String]
+
+        def self.validate!: (
+          XTwitterScraper::Internal::Transport::BaseClient::request_components req
+        ) -> void
+
+        def self.should_retry?: (
+          Integer status,
+          headers: ::Hash[String, String]
+        ) -> bool
+
+        def self.follow_redirect: (
+          XTwitterScraper::Internal::Transport::BaseClient::request_input request,
+          status: Integer,
+          response_headers: ::Hash[String, String]
+        ) -> XTwitterScraper::Internal::Transport::BaseClient::request_input
+
+        def self.reap_connection!: (
+          Integer | XTwitterScraper::Errors::APIConnectionError status,
+          stream: Enumerable[String]?
+        ) -> void
+
+        attr_reader base_url: URI::Generic
+
+        attr_reader timeout: Float
+
+        attr_reader max_retries: Integer
+
+        attr_reader initial_retry_delay: Float
+
+        attr_reader max_retry_delay: Float
+
+        attr_reader headers: ::Hash[String, String]
+
+        attr_reader idempotency_header: String?
+
+        # @api private
+        attr_reader requester: XTwitterScraper::Internal::Transport::PooledNetRequester
+
+        def initialize: (
+          base_url: String,
+          ?timeout: Float,
+          ?max_retries: Integer,
+          ?initial_retry_delay: Float,
+          ?max_retry_delay: Float,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?],
+          ?idempotency_header: String?
+        ) -> void
+
+        private def auth_headers: -> ::Hash[String, String]
+
+        private def user_agent: -> String
+
+        private def generate_idempotency_key: -> String
+
+        private def build_request: (
+          XTwitterScraper::Internal::Transport::BaseClient::request_components req,
+          XTwitterScraper::request_options opts
+        ) -> XTwitterScraper::Internal::Transport::BaseClient::request_input
+
+        private def retry_delay: (
+          ::Hash[String, String] headers,
+          retry_count: Integer
+        ) -> Float
+
+        def send_request: (
+          XTwitterScraper::Internal::Transport::BaseClient::request_input request,
+          redirect_count: Integer,
+          retry_count: Integer,
+          send_retry_header: bool
+        ) -> [Integer, top, Enumerable[String]]
+
+        def request: (
+          Symbol method,
+          String | ::Array[String] path,
+          ?query: ::Hash[String, (::Array[String] | String)?]?,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?]?,
+          ?body: top?,
+          ?unwrap: (Symbol
+          | Integer
+          | ::Array[(Symbol | Integer)]
+          | (^(top arg0) -> top))?,
+          ?page: Class?,
+          ?stream: Class?,
+          ?model: XTwitterScraper::Internal::Type::Converter::input?,
+          ?security: { auth_api_key: bool, oauth_bearer: bool }?,
+          ?options: XTwitterScraper::request_opts?
+        ) -> top
+
+        def inspect: -> String
+      end
+    end
+  end
+end