bad_pigeon 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3f86a627c1ab2f039167161fe3ecfbeb3db6d96a925673c23165cf74a3cc54b
-  data.tar.gz: f43ac43250395cc7f9200c5cc8bcc2bb2596827aac61f88110e078ae0210fa64
+  metadata.gz: 603fc8ee8a14e3cdeee420620d4457fcd20b3e86c83f104c714848ad384c27b9
+  data.tar.gz: 4d342a48e1b0b3478ee16e42ed3826b97f1056e09b53461e9cd2b4c3e3fbd348
 SHA512:
-  metadata.gz: 7c02d9d1fe34e0c97a05d0135db11fef8dc401261fd1f2c1fa7a3cd961d191e547e2e462b7792728ac602a5567db8c756f2f2f6906ff9308cdbd8a2cdf53be34
-  data.tar.gz: 8eb675eb61e1c2bfb9ace4e21b2aa2526fd878933eedcb48798b892d9261f80d82ce47b765a7b25a1911c9c6586cc899e16a8160ccb18d1d12cfb2b93d43cb96
+  metadata.gz: a70d24323f1b0973bc143e41d07842fce248a25316e24d3e642cea3f862a716867c4728e20254363dbe659d7392235dc40eeac394af09ee986ccc53d303957d9
+  data.tar.gz: ee3c1b8e89badd193f386a2f70a3c4642e6e40eb3767d1136f167534003f9cd51de45a2bf46e33de79e60710515f1c7ee45e0072fd5ff85a42b1b610f6b1b517

data/lib/bad_pigeon/elements/component.rb

@@ -2,6 +2,10 @@ module BadPigeon
   module Component
     # normal tweet in e.g. home/latest or a user's timeline
     ORGANIC_FEED_TWEET = "suggest_ranked_organic_tweet"
+    NORMAL_TWEET = "tweet"
+
+    # tweet in the latest timeline
+    FOLLOWING = "following_in_network"
 
     # tweet in a list timeline
     ORGANIC_LIST_TWEET = "suggest_organic_list_tweet"
@@ -19,6 +23,7 @@ module BadPigeon
 
     # promoted tweet (ad)
     PROMOTED_TWEET = "suggest_promoted"
+    FOLLOWING_PROMOTED = "following_promoted"
 
     # "Who to follow" block
     FOLLOW_SUGGESTIONS = "suggest_who_to_follow"

data/lib/bad_pigeon/elements/timeline_entry.rb

@@ -2,6 +2,13 @@ require 'bad_pigeon/elements/timeline_tweet'
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents an "entry" which is a part of a timeline response. An entry in most cases is a wrapper for either one
+  # tweet or a group of connected tweets (e.g. a parent and a reply).
+  #
+  # Tweets can be extracted from an entry using ({#items}) method, which returns an array of tweets as instances of
+  # {BadPigeon::TimelineTweet} class.
+
   class TimelineEntry
     include Assertions
 

data/lib/bad_pigeon/elements/timeline_instruction.rb

@@ -2,6 +2,12 @@ require 'bad_pigeon/elements/timeline_entry'
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents an "instruction" which is a part of a timeline response. An instruction can be e.g. pinning one entry
+  # to the top or adding some number of entries to the list view.
+  #
+  # A timeline includes one or more "entries" ({BadPigeon::TimelineEntry}), most of which contain one or more tweets.
+
   class TimelineInstruction
     include Assertions
 

data/lib/bad_pigeon/elements/timeline_tweet.rb

@@ -2,6 +2,12 @@ require 'bad_pigeon/models/tweet'
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a single tweet in a timeline (may possibly include no data in some cases).
+  #
+  # Use the {#tweet} method to get an instance of {BadPigeon::Tweet}, which is the final tweet model from which you can
+  # extract specific fields or a properly formatted JSON representation.
+
   class TimelineTweet
     include Assertions
 
@@ -9,26 +15,8 @@ module BadPigeon
       @json = json
     end
 
-    def result_type
-      @json['tweet_results']['result'] && @json['tweet_results']['result']['__typename']
-    end
-
-    def tweet_data
-      case result_type
-      when 'Tweet', 'TweetWithVisibilityResults'
-        @json['tweet_results']['result']
-      when 'TweetUnavailable'
-        nil
-      when nil
-        nil
-      else
-        assert("Unknown tweet result type: #{result_type}")
-        nil
-      end
-    end
-
     def tweet
-      tweet_data && Tweet.new(tweet_data)
+      @json['tweet_results']['result'] && Tweet.from_result(@json['tweet_results']['result'])
     end
   end
 end

data/lib/bad_pigeon/entry_filter.rb

@@ -9,6 +9,8 @@ module BadPigeon
       case entry.component
       when Component::ORGANIC_FEED_TWEET,
            Component::ORGANIC_LIST_TWEET,
+           Component::NORMAL_TWEET,
+           Component::FOLLOWING,
            Component::PINNED_TWEET,
            Component::EXTENDED_REPLY,
            Component::SOCIAL_CONTEXT,
@@ -17,6 +19,7 @@ module BadPigeon
            then true
 
       when Component::PROMOTED_TWEET,
+           Component::FOLLOWING_PROMOTED,
            Component::FOLLOW_SUGGESTIONS
            then false
 

data/lib/bad_pigeon/har/har_archive.rb

@@ -2,6 +2,11 @@ require_relative 'har_request'
 require 'json'
 
 module BadPigeon
+
+  # Represents a whole request archive bundle loaded from a *.har file.
+  # 
+  # An archive consists of some number of requests ({BadPigeon::HARRequest}).
+
   class HARArchive
     def initialize(data)
       @json = JSON.parse(data)

data/lib/bad_pigeon/har/har_request.rb

@@ -2,6 +2,15 @@ require 'addressable/uri'
 require 'json'
 
 module BadPigeon
+
+  # Represents info about one request and response to it, including the complete response data ({#response_body},
+  # or {#response_json} for a parsed JSON form).
+  #
+  # Requests that may potentially include tweet data return true from the {#includes_tweet_data?} method. The JSON
+  # data from each such request represents a "timeline" and may be parsed using a specific timeline class like
+  # {BadPigeon::HomeTimeline} or {BadPigeon::UserTimeline}; the {BadPigeon::TIMELINE_TYPES} hash provides a mapping
+  # of GraphQL endpoint names to timeline classes, and the endpoint name can be read using {#endpoint_name} method.
+
   class HARRequest
     def initialize(json)
       @json = json

data/lib/bad_pigeon/models/tweet.rb

@@ -6,11 +6,29 @@ require 'bad_pigeon/util/strict_hash'
 require 'time'
 
 module BadPigeon
+
+  #
+  # A model that represents one tweet with an interface matching that from the original `twitter` Ruby gem.
+  #
+
   class Tweet
     include Assertions
+    extend Assertions
 
     attr_reader :json
 
+    def self.from_result(json)
+      case json['__typename']
+      when 'Tweet', 'TweetWithVisibilityResults'
+        Tweet.new(json)
+      when nil, 'TweetUnavailable', 'TweetTombstone'
+        nil
+      else
+        assert("Unknown tweet result type: #{json['__typename']}")
+        nil
+      end
+    end
+
     def initialize(json)
       case json['__typename']
       when 'Tweet'
@@ -50,17 +68,17 @@ module BadPigeon
     alias retweeted_status? retweet?
 
     def retweeted_status
-      legacy['retweeted_status_result'] && Tweet.new(legacy['retweeted_status_result']['result'])
+      legacy['retweeted_status_result'] && Tweet.from_result(legacy['retweeted_status_result']['result'])
     end
 
     def quoted_status?
       # there is also legacy['is_quote_status'], but it may be true while quoted_status_result
       # is not set if the quoted status was deleted
-      !!json['quoted_status_result']
+      !!quoted_status
     end
 
     def quoted_status
-      json['quoted_status_result'] && Tweet.new(json['quoted_status_result']['result'])
+      json['quoted_status_result'] && Tweet.from_result(json['quoted_status_result']['result'])
     end
 
     alias quoted_tweet? quoted_status?

data/lib/bad_pigeon/models/url_entity.rb

@@ -1,6 +1,11 @@
 require 'addressable/uri'
 
 module BadPigeon
+
+  #
+  # A model that represents a "URL entity" of a tweet (a shortened link with info about the shortened and original URL).
+  #
+
   class URLEntity
     def initialize(json)
       @json = json

data/lib/bad_pigeon/models/user.rb

@@ -1,4 +1,9 @@
 module BadPigeon
+
+  #
+  # A model that represents a user with an interface matching that from the original `twitter` Ruby gem.
+  #
+
   class User
     attr_reader :json
 

data/lib/bad_pigeon/timelines/home_timeline.rb

@@ -2,6 +2,12 @@ require 'bad_pigeon/elements/timeline_instruction'
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a timeline response for user's "For You" or "Following" timeline.
+  #
+  # A timeline includes one or more "instructions" ({BadPigeon::TimelineInstruction}), and usually in particular a
+  # "TimelineAddEntries" instruction which provides one or more entries containing tweets.
+
   class HomeTimeline
     include Assertions
 

data/lib/bad_pigeon/timelines/list_timeline.rb

@@ -2,6 +2,12 @@ require 'bad_pigeon/elements/timeline_instruction'
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a timeline response for a list timeline.
+  #
+  # A timeline includes one or more "instructions" ({BadPigeon::TimelineInstruction}), and usually in particular a
+  # "TimelineAddEntries" instruction which provides one or more entries containing tweets.
+
   class ListTimeline
     include Assertions
 

data/lib/bad_pigeon/timelines/user_timeline.rb

@@ -2,6 +2,12 @@ require 'bad_pigeon/elements/timeline_instruction'
 require 'bad_pigeon/util/assertions'
 
 module BadPigeon
+
+  # Represents a timeline response for a timeline of user's posts as seen on their profile page.
+  #
+  # A timeline includes one or more "instructions" ({BadPigeon::TimelineInstruction}), and usually in particular a
+  # "TimelineAddEntries" instruction which provides one or more entries containing tweets.
+
   class UserTimeline
     include Assertions
 

data/lib/bad_pigeon/tweet_extractor.rb

@@ -6,6 +6,10 @@ require_relative 'timelines'
 require 'uri'
 
 module BadPigeon
+
+  # The main entry point to the library. Pass the contents of a HAR archive file to {#get_tweets_from_har} and get
+  # a flat list of all extracted tweets in return.
+
   class TweetExtractor
     include Assertions
 

data/lib/bad_pigeon/util/assertions.rb

@@ -19,5 +19,9 @@ module BadPigeon
         end
       end
     end
+
+    def self.extended(target)
+      included(target.singleton_class)
+    end
   end
 end

data/lib/bad_pigeon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BadPigeon
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bad_pigeon
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Kuba Suder
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-07-11 00:00:00.000000000 Z
+date: 2023-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable