x-twitter-scraper 0.7.2 → 0.9.0

data/lib/x_twitter_scraper/models/x/user_retrieve_followers_response.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module XTwitterScraper
+  module Models
+    module X
+      # Paginated user profiles. No-mode follower, following, and verified follower
+      # requests merge independent views automatically. Response fields, page size,
+      # aliases, filters, and per-returned-profile billing stay unchanged. Existing
+      # unprefixed cursors retain legacy behavior. Follow next_cursor while
+      # has_next_page is true.
+      #
+      # @see XTwitterScraper::Resources::X::Users#retrieve_followers
+      module UserRetrieveFollowersResponse
+        extend XTwitterScraper::Internal::Type::Union
+
+        # Paginated user profiles. No-mode follower, following, and verified follower requests merge independent views automatically. Response fields, page size, aliases, filters, and per-returned-profile billing stay unchanged. Existing unprefixed cursors retain legacy behavior. Follow next_cursor while has_next_page is true.
+        variant -> { XTwitterScraper::PaginatedUsers }
+
+        # Paginated user profiles. No-mode follower, following, and verified follower requests merge independent views automatically. Response fields, page size, aliases, filters, and per-returned-profile billing stay unchanged. Existing unprefixed cursors retain legacy behavior. Follow next_cursor while has_next_page is true.
+        variant -> { XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse }
+
+        class UserListCoverageResponse < XTwitterScraper::Models::PaginatedUsers
+          # @!attribute diagnostic
+          #   Coverage evidence across parallel relationship strategies.
+          #
+          #   @return [XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic]
+          required :diagnostic,
+                   -> { XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic }
+
+          # @!attribute has_next_page
+          #
+          #   @return [Boolean, XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::HasNextPage, nil]
+          optional :has_next_page,
+                   enum: -> { XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::HasNextPage }
+
+          # @!attribute next_cursor
+          #
+          #   @return [Symbol, XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::NextCursor, nil]
+          optional :next_cursor,
+                   enum: -> { XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::NextCursor }
+
+          # @!method initialize(diagnostic:, has_next_page: nil, next_cursor: nil)
+          #   Paginated user profiles. No-mode follower, following, and verified follower
+          #   requests merge independent views automatically. Response fields, page size,
+          #   aliases, filters, and per-returned-profile billing stay unchanged. Existing
+          #   unprefixed cursors retain legacy behavior. Follow next_cursor while
+          #   has_next_page is true.
+          #
+          #   @param diagnostic [XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic] Coverage evidence across parallel relationship strategies.
+          #
+          #   @param has_next_page [Boolean, XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::HasNextPage]
+          #
+          #   @param next_cursor [Symbol, XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::NextCursor]
+
+          class Diagnostic < XTwitterScraper::Internal::Type::BaseModel
+            # @!attribute complete
+            #   True when every strategy exhausted its source.
+            #
+            #   @return [Boolean]
+            required :complete, XTwitterScraper::Internal::Type::Boolean
+
+            # @!attribute cursor_failure_count
+            #
+            #   @return [Integer]
+            required :cursor_failure_count, Integer, api_name: :cursorFailureCount
+
+            # @!attribute deadline_reached
+            #
+            #   @return [Boolean]
+            required :deadline_reached, XTwitterScraper::Internal::Type::Boolean, api_name: :deadlineReached
+
+            # @!attribute duplicate_count
+            #
+            #   @return [Integer]
+            required :duplicate_count, Integer, api_name: :duplicateCount
+
+            # @!attribute failed_strategy_count
+            #
+            #   @return [Integer]
+            required :failed_strategy_count, Integer, api_name: :failedStrategyCount
+
+            # @!attribute malformed_count
+            #
+            #   @return [Integer]
+            required :malformed_count, Integer, api_name: :malformedCount
+
+            # @!attribute pages_fetched
+            #
+            #   @return [Integer]
+            required :pages_fetched, Integer, api_name: :pagesFetched
+
+            # @!attribute response_truncated
+            #   Whether credits or the requested limit reduced output.
+            #
+            #   @return [Boolean]
+            required :response_truncated,
+                     XTwitterScraper::Internal::Type::Boolean,
+                     api_name: :responseTruncated
+
+            # @!attribute result_limit_reached
+            #
+            #   @return [Boolean]
+            required :result_limit_reached,
+                     XTwitterScraper::Internal::Type::Boolean,
+                     api_name: :resultLimitReached
+
+            # @!attribute returned_users
+            #
+            #   @return [Integer]
+            required :returned_users, Integer, api_name: :returnedUsers
+
+            # @!attribute stalled_strategy_count
+            #
+            #   @return [Integer]
+            required :stalled_strategy_count, Integer, api_name: :stalledStrategyCount
+
+            # @!attribute strategies
+            #
+            #   @return [Array<XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic::Strategy>]
+            required :strategies,
+                     -> { XTwitterScraper::Internal::Type::ArrayOf[XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic::Strategy] }
+
+            # @!attribute strategy_count
+            #
+            #   @return [Integer]
+            required :strategy_count, Integer, api_name: :strategyCount
+
+            # @!attribute unique_users
+            #
+            #   @return [Integer]
+            required :unique_users, Integer, api_name: :uniqueUsers
+
+            # @!method initialize(complete:, cursor_failure_count:, deadline_reached:, duplicate_count:, failed_strategy_count:, malformed_count:, pages_fetched:, response_truncated:, result_limit_reached:, returned_users:, stalled_strategy_count:, strategies:, strategy_count:, unique_users:)
+            #   Coverage evidence across parallel relationship strategies.
+            #
+            #   @param complete [Boolean] True when every strategy exhausted its source.
+            #
+            #   @param cursor_failure_count [Integer]
+            #
+            #   @param deadline_reached [Boolean]
+            #
+            #   @param duplicate_count [Integer]
+            #
+            #   @param failed_strategy_count [Integer]
+            #
+            #   @param malformed_count [Integer]
+            #
+            #   @param pages_fetched [Integer]
+            #
+            #   @param response_truncated [Boolean] Whether credits or the requested limit reduced output.
+            #
+            #   @param result_limit_reached [Boolean]
+            #
+            #   @param returned_users [Integer]
+            #
+            #   @param stalled_strategy_count [Integer]
+            #
+            #   @param strategies [Array<XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic::Strategy>]
+            #
+            #   @param strategy_count [Integer]
+            #
+            #   @param unique_users [Integer]
+
+            class Strategy < XTwitterScraper::Internal::Type::BaseModel
+              # @!attribute duplicate_count
+              #
+              #   @return [Integer]
+              required :duplicate_count, Integer, api_name: :duplicateCount
+
+              # @!attribute pages_fetched
+              #
+              #   @return [Integer]
+              required :pages_fetched, Integer, api_name: :pagesFetched
+
+              # @!attribute stop_reason
+              #
+              #   @return [Symbol, XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic::Strategy::StopReason]
+              required :stop_reason,
+                       enum: -> { XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic::Strategy::StopReason },
+                       api_name: :stopReason
+
+              # @!attribute strategy
+              #
+              #   @return [Integer]
+              required :strategy, Integer
+
+              # @!attribute unique_added
+              #
+              #   @return [Integer]
+              required :unique_added, Integer, api_name: :uniqueAdded
+
+              # @!method initialize(duplicate_count:, pages_fetched:, stop_reason:, strategy:, unique_added:)
+              #   @param duplicate_count [Integer]
+              #   @param pages_fetched [Integer]
+              #   @param stop_reason [Symbol, XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic::Strategy::StopReason]
+              #   @param strategy [Integer]
+              #   @param unique_added [Integer]
+
+              # @see XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse::Diagnostic::Strategy#stop_reason
+              module StopReason
+                extend XTwitterScraper::Internal::Type::Enum
+
+                CURSOR_FAILURE = :cursor_failure
+                DEADLINE = :deadline
+                EXHAUSTED = :exhausted
+                FAILED = :failed
+                PAGE_LIMIT = :page_limit
+                RESULT_LIMIT = :result_limit
+                STALLED = :stalled
+
+                # @!method self.values
+                #   @return [Array<Symbol>]
+              end
+            end
+          end
+
+          module HasNextPage
+            extend XTwitterScraper::Internal::Type::Enum
+
+            FALSE = false
+
+            # @!method self.values
+            #   @return [Array<Boolean>]
+          end
+
+          module NextCursor
+            extend XTwitterScraper::Internal::Type::Enum
+
+            EMPTY = :""
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+
+        # @!method self.variants
+        #   @return [Array(XTwitterScraper::Models::PaginatedUsers, XTwitterScraper::Models::X::UserRetrieveFollowersResponse::UserListCoverageResponse)]
+      end
+    end
+  end
+end

data/lib/x_twitter_scraper/models/x/user_retrieve_followers_you_know_params.rb

@@ -17,31 +17,142 @@ module XTwitterScraper
         #   @return [String]
         required :id, String
 
+        # @!attribute bio_contains
+        #   Match any comma-separated or line-separated bio term, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :bio_contains, String
+
         # @!attribute cursor
         #   Pagination cursor for followers-you-know
         #
         #   @return [String, nil]
         optional :cursor, String
 
+        # @!attribute has_location
+        #   Only return profiles with a location.
+        #
+        #   @return [Boolean, nil]
+        optional :has_location, XTwitterScraper::Internal::Type::Boolean
+
+        # @!attribute has_website
+        #   Only return profiles with a website.
+        #
+        #   @return [Boolean, nil]
+        optional :has_website, XTwitterScraper::Internal::Type::Boolean
+
+        # @!attribute location_contains
+        #   Match a location substring, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :location_contains, String
+
+        # @!attribute max_followers
+        #   Maximum follower count. Missing counts pass this maximum.
+        #
+        #   @return [Integer, nil]
+        optional :max_followers, Integer
+
+        # @!attribute max_following
+        #   Maximum following count.
+        #
+        #   @return [Integer, nil]
+        optional :max_following, Integer
+
+        # @!attribute max_statuses
+        #   Maximum post count. maxPosts is also accepted.
+        #
+        #   @return [Integer, nil]
+        optional :max_statuses, Integer
+
+        # @!attribute min_account_age_days
+        #   Minimum account age in whole days.
+        #
+        #   @return [Integer, nil]
+        optional :min_account_age_days, Integer
+
+        # @!attribute min_followers
+        #   Minimum follower count. Filtering happens before billing.
+        #
+        #   @return [Integer, nil]
+        optional :min_followers, Integer
+
+        # @!attribute min_following
+        #   Minimum following count.
+        #
+        #   @return [Integer, nil]
+        optional :min_following, Integer
+
+        # @!attribute min_statuses
+        #   Minimum post count. minPosts is also accepted.
+        #
+        #   @return [Integer, nil]
+        optional :min_statuses, Integer
+
         # @!attribute page_size
-        #   Maximum user profiles requested from this page (20-200, default 200). The
-        #   response can contain fewer profiles because the source returned fewer or
-        #   remaining credits cover fewer results. Keep requesting next_cursor while
-        #   has_next_page is true. The deprecated limit and count aliases remain accepted.
+        #   Maximum user profiles requested from this page (20-200, default 200). Source,
+        #   filters, or credits can return fewer profiles. Keep requesting next_cursor while
+        #   has_next_page is true. Deprecated aliases remain accepted.
         #
         #   @return [Integer, nil]
         optional :page_size, Integer
 
-        # @!method initialize(id:, cursor: nil, page_size: nil, request_options: {})
+        # @!attribute username_contains
+        #   Match a username substring, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :username_contains, String
+
+        # @!attribute verified_only
+        #   Only return verified profiles.
+        #
+        #   @return [Boolean, nil]
+        optional :verified_only, XTwitterScraper::Internal::Type::Boolean
+
+        # @!attribute verified_type
+        #   Match the verification type exactly, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :verified_type, String
+
+        # @!method initialize(id:, bio_contains: nil, cursor: nil, has_location: nil, has_website: nil, location_contains: nil, max_followers: nil, max_following: nil, max_statuses: nil, min_account_age_days: nil, min_followers: nil, min_following: nil, min_statuses: nil, page_size: nil, username_contains: nil, verified_only: nil, verified_type: nil, request_options: {})
         #   Some parameter documentations has been truncated, see
         #   {XTwitterScraper::Models::X::UserRetrieveFollowersYouKnowParams} for more
         #   details.
         #
         #   @param id [String]
         #
+        #   @param bio_contains [String] Match any comma-separated or line-separated bio term, ignoring case.
+        #
         #   @param cursor [String] Pagination cursor for followers-you-know
         #
-        #   @param page_size [Integer] Maximum user profiles requested from this page (20-200, default 200). The respon
+        #   @param has_location [Boolean] Only return profiles with a location.
+        #
+        #   @param has_website [Boolean] Only return profiles with a website.
+        #
+        #   @param location_contains [String] Match a location substring, ignoring case.
+        #
+        #   @param max_followers [Integer] Maximum follower count. Missing counts pass this maximum.
+        #
+        #   @param max_following [Integer] Maximum following count.
+        #
+        #   @param max_statuses [Integer] Maximum post count. maxPosts is also accepted.
+        #
+        #   @param min_account_age_days [Integer] Minimum account age in whole days.
+        #
+        #   @param min_followers [Integer] Minimum follower count. Filtering happens before billing.
+        #
+        #   @param min_following [Integer] Minimum following count.
+        #
+        #   @param min_statuses [Integer] Minimum post count. minPosts is also accepted.
+        #
+        #   @param page_size [Integer] Maximum user profiles requested from this page (20-200, default 200). Source, fi
+        #
+        #   @param username_contains [String] Match a username substring, ignoring case.
+        #
+        #   @param verified_only [Boolean] Only return verified profiles.
+        #
+        #   @param verified_type [String] Match the verification type exactly, ignoring case.
         #
         #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
       end

data/lib/x_twitter_scraper/models/x/user_retrieve_following_params.rb

@@ -23,28 +23,119 @@ module XTwitterScraper
         #   @return [String, nil]
         optional :after, String
 
+        # @!attribute bio_contains
+        #   Match any comma-separated or line-separated bio term, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :bio_contains, String
+
         # @!attribute cursor
-        #   Pagination cursor for following list
+        #   Cursor from the previous response. Xquik cursors resume automatic coverage.
+        #   Existing unprefixed cursors keep legacy standard behavior.
         #
         #   @return [String, nil]
         optional :cursor, String
 
+        # @!attribute has_location
+        #   Only return profiles with a location.
+        #
+        #   @return [Boolean, nil]
+        optional :has_location, XTwitterScraper::Internal::Type::Boolean
+
+        # @!attribute has_website
+        #   Only return profiles with a website.
+        #
+        #   @return [Boolean, nil]
+        optional :has_website, XTwitterScraper::Internal::Type::Boolean
+
         # @!attribute limit
-        #   Legacy page size alias. Prefer pageSize.
+        #   Legacy page-size alias outside explicit coverage mode. Coverage accepts 1-10000.
+        #   Prefer pageSize.
         #
         #   @return [Integer, nil]
         optional :limit, Integer
 
+        # @!attribute location_contains
+        #   Match a location substring, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :location_contains, String
+
+        # @!attribute max_followers
+        #   Maximum follower count. Missing counts pass this maximum.
+        #
+        #   @return [Integer, nil]
+        optional :max_followers, Integer
+
+        # @!attribute max_following
+        #   Maximum following count.
+        #
+        #   @return [Integer, nil]
+        optional :max_following, Integer
+
+        # @!attribute max_statuses
+        #   Maximum post count. maxPosts is also accepted.
+        #
+        #   @return [Integer, nil]
+        optional :max_statuses, Integer
+
+        # @!attribute min_account_age_days
+        #   Minimum account age in whole days.
+        #
+        #   @return [Integer, nil]
+        optional :min_account_age_days, Integer
+
+        # @!attribute min_followers
+        #   Minimum follower count. Filtering happens before billing.
+        #
+        #   @return [Integer, nil]
+        optional :min_followers, Integer
+
+        # @!attribute min_following
+        #   Minimum following count.
+        #
+        #   @return [Integer, nil]
+        optional :min_following, Integer
+
+        # @!attribute min_statuses
+        #   Minimum post count. minPosts is also accepted.
+        #
+        #   @return [Integer, nil]
+        optional :min_statuses, Integer
+
+        # @!attribute mode
+        #   Omit mode for resumable maximum coverage. Standard keeps legacy pagination.
+        #   Coverage returns diagnostics once and rejects cursors.
+        #
+        #   @return [Symbol, XTwitterScraper::Models::X::UserRetrieveFollowingParams::Mode, nil]
+        optional :mode, enum: -> { XTwitterScraper::X::UserRetrieveFollowingParams::Mode }
+
         # @!attribute page_size
-        #   Maximum user profiles requested from this page (20-200, default 200). The
-        #   response can contain fewer profiles because the source returned fewer or
-        #   remaining credits cover fewer results. Keep requesting next_cursor while
-        #   has_next_page is true. The deprecated limit and count aliases remain accepted.
+        #   Maximum user profiles: automatic 300; standard 200. Sources return fewer
+        #   profiles. Continue with has_next_page.
         #
         #   @return [Integer, nil]
         optional :page_size, Integer
 
-        # @!method initialize(id:, after: nil, cursor: nil, limit: nil, page_size: nil, request_options: {})
+        # @!attribute username_contains
+        #   Match a username substring, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :username_contains, String
+
+        # @!attribute verified_only
+        #   Only return verified profiles.
+        #
+        #   @return [Boolean, nil]
+        optional :verified_only, XTwitterScraper::Internal::Type::Boolean
+
+        # @!attribute verified_type
+        #   Match the verification type exactly, ignoring case.
+        #
+        #   @return [String, nil]
+        optional :verified_type, String
+
+        # @!method initialize(id:, after: nil, bio_contains: nil, cursor: nil, has_location: nil, has_website: nil, limit: nil, location_contains: nil, max_followers: nil, max_following: nil, max_statuses: nil, min_account_age_days: nil, min_followers: nil, min_following: nil, min_statuses: nil, mode: nil, page_size: nil, username_contains: nil, verified_only: nil, verified_type: nil, request_options: {})
         #   Some parameter documentations has been truncated, see
         #   {XTwitterScraper::Models::X::UserRetrieveFollowingParams} for more details.
         #
@@ -52,13 +143,55 @@ module XTwitterScraper
         #
         #   @param after [String] Deprecated following cursor alias. Prefer cursor.
         #
-        #   @param cursor [String] Pagination cursor for following list
+        #   @param bio_contains [String] Match any comma-separated or line-separated bio term, ignoring case.
+        #
+        #   @param cursor [String] Cursor from the previous response. Xquik cursors resume automatic coverage. Exis
+        #
+        #   @param has_location [Boolean] Only return profiles with a location.
+        #
+        #   @param has_website [Boolean] Only return profiles with a website.
+        #
+        #   @param limit [Integer] Legacy page-size alias outside explicit coverage mode. Coverage accepts 1-10000.
         #
-        #   @param limit [Integer] Legacy page size alias. Prefer pageSize.
+        #   @param location_contains [String] Match a location substring, ignoring case.
         #
-        #   @param page_size [Integer] Maximum user profiles requested from this page (20-200, default 200). The respon
+        #   @param max_followers [Integer] Maximum follower count. Missing counts pass this maximum.
+        #
+        #   @param max_following [Integer] Maximum following count.
+        #
+        #   @param max_statuses [Integer] Maximum post count. maxPosts is also accepted.
+        #
+        #   @param min_account_age_days [Integer] Minimum account age in whole days.
+        #
+        #   @param min_followers [Integer] Minimum follower count. Filtering happens before billing.
+        #
+        #   @param min_following [Integer] Minimum following count.
+        #
+        #   @param min_statuses [Integer] Minimum post count. minPosts is also accepted.
+        #
+        #   @param mode [Symbol, XTwitterScraper::Models::X::UserRetrieveFollowingParams::Mode] Omit mode for resumable maximum coverage. Standard keeps legacy pagination. Cove
+        #
+        #   @param page_size [Integer] Maximum user profiles: automatic 300; standard 200. Sources return fewer profile
+        #
+        #   @param username_contains [String] Match a username substring, ignoring case.
+        #
+        #   @param verified_only [Boolean] Only return verified profiles.
+        #
+        #   @param verified_type [String] Match the verification type exactly, ignoring case.
         #
         #   @param request_options [XTwitterScraper::RequestOptions, Hash{Symbol=>Object}]
+
+        # Omit mode for resumable maximum coverage. Standard keeps legacy pagination.
+        # Coverage returns diagnostics once and rejects cursors.
+        module Mode
+          extend XTwitterScraper::Internal::Type::Enum
+
+          STANDARD = :standard
+          COVERAGE = :coverage
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
       end
     end
   end