twitter_labs_api 0.5.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f31f636cbf46ed53a3d35e61c3376b9f47184220db4b23277f4f7c504f4be251
-  data.tar.gz: be3ae4940e263fe6bf33661686072c62c807236f9c2814488661efc8da8799a8
+  metadata.gz: 5ce6092d6dc4256bc5db207476e6b5d74c822340b2a65287c6642d80ccd011ba
+  data.tar.gz: 6182b14e47a3bf227c12031cc674f115c178ae625e8278f192bf67dc5adc781e
 SHA512:
-  metadata.gz: 6062719f695c9979a327d94396795df7365559e92598fe08e727d2e87dc2e4a987a4f6bf689954cd2efc2b6c20f0ad5ae3003f651e0e45fc0caea12f46a57688
-  data.tar.gz: 7c1616a9f97582a2dda4061f2a0c540b7967d4d525c0bd344141643723450d91a4208357d919b8acf4d0d89a17d2046e0f6fba75a5c3eb6e9a10d9f6caa4df31
+  metadata.gz: ef6bf629eae0a91baa59eb43beb7d0770bca8e75243ca04d3884839987f3e466f25b6c763b4046b57d20cc07cb1e5605dd7febb935ddb5333f4ebf74bb2101b7
+  data.tar.gz: 84eb57aec3cde7b0b4e8e30f507016e1e97930c810f0777018593841507430b5a871fb3da6ba140ecf2c57462da6101f304deb0a4ab621efa61e4839aefcc2e3

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+# 0.7.1 - 28 August 2020
+
+- Fix: add missing require statement
+
+# 0.7.0 - 28 August 2020
+
+- Refactor interface for requesting custom response fields
+
+## Breaking Change
+
+Heads up, the argument to request fields was previously called `tweet_fields`; it is now called `fields`. 
+
+```ruby
+api.get_tweet(id: '123455683780', fields: requested_fields)
+```
+
+The `fields` parameter now supports multiple different data types (instead of just Tweet attributes). So for example, to request the URL of an embedded media item:
+
+```ruby
+requested_fields = { tweet: %w[id username], media: %w[url] }
+
+api.get_tweet(id: my_id, fields: requested_fields)
+```
+
+# 0.6.0 - 28 July 2020
+
+- Fix: broken dependency
+
+# 0.5.2 - 28 July 2020
+
+- Add `search`
+- Finish `rdoc` coverage
+
+# 0.5.1 - 28 July 2020
+
+- Add `User-Agent` request header
+- Add `hide_reply`
+
 # 0.5.0 - 27 July 2020
 
 - Refactor structure to prepare for adding additional API endpoints

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    twitter_labs_api (0.5.0)
+    twitter_labs_api (0.7.1)
       activesupport (~> 6.0)
       httplog (~> 1.4)
 
@@ -25,7 +25,7 @@ GEM
     cd (1.0.1)
     clipboard (1.0.6)
     coderay (1.1.3)
-    concurrent-ruby (1.1.6)
+    concurrent-ruby (1.1.7)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
     debugging (1.1.1)

data/README.md

@@ -1,13 +1,15 @@
 # twitter-labs-api
 
+[![Labs v2](https://img.shields.io/static/v1?label=Twitter%20API&message=Developer%20Labs%20v2&color=192430&style=flat&logo=Twitter)](https://developer.twitter.com/en/docs/labs/overview/versioning)
+
 A basic implementation of a Twitter Labs API client as a handy Ruby [gem](https://rubygems.org/gems/twitter_labs_api). This project uses the v2 endpoints announced [here](https://twittercommunity.com/t/releasing-a-new-version-of-labs-endpoints/134219/3).
 
 ## Usage
 
 ### Prerequisite
-All one needs is a Twitter [bearer token](https://developer.twitter.com/en/docs/basics/authentication/oauth-2-0/bearer-tokens) to get started.
+All one needs is a Twitter [bearer token](https://developer.twitter.com/en/docs/basics/authentication/oauth-2-0/bearer-tokens) to get started. The bearer token is available on the 'Tokens and Keys' page within your app's dashboard on the [Twitter for Developers](https://developer.twitter.com/) site.
 
-One easy way to get a bearer token is to use [this method](https://www.rubydoc.info/gems/twitter/Twitter/REST/Client#bearer_token%3F-instance_method) from https://github.com/sferik/twitter.
+Alternatively, one can get a bearer token using [this method](https://www.rubydoc.info/gems/twitter/Twitter/REST/Client#bearer_token%3F-instance_method) from https://github.com/sferik/twitter.
 
 ### Setup
 
@@ -30,14 +32,13 @@ api.get_tweet(id: '1234671272602193920')
 
 #### Specifying which fields to include in the response
 
-By default, the gem requests the 'default' fields for each entity. See the [API Reference](https://developer.twitter.com/en/docs/labs/tweets-and-users/api-reference) for available fields. One can customize the response payload like so:
+By default, the gem requests the 'default' fields for each entity. See the [API Reference](https://developer.twitter.com/en/docs/labs/tweets-and-users/api-reference) for available fields. One can customize the response payload, depending on the requested resource.
 
+For example, to request the URL of a Tweet's embedded media item:
 ```ruby
-my_fields = %w[id author_id created_at text]
-
-api.get_tweet(id: '1235508591232090112', tweet_fields: my_fields)
+requested_fields = { tweet: %w[id username], media: %w[url] }
 
->> {"author_id"=>"229708614", "created_at"=>"2020-03-05T10:12:57.000Z", "id"=>"1235508591232090112", "text"=>"Hot take: coronavirus will not boost remote work in the long run because spur-of-the-moment work-from-home for in-person companies is likely to be a shitshow."}
+api.get_tweet(id: my_id, fields: requested_fields)
 ```
 
 #### API Errors
@@ -62,6 +63,8 @@ Currently, the following endpoints are implemented:
 
 - `TwitterLabsAPI#get_tweet` ([docs](https://developer.twitter.com/en/docs/labs/tweets-and-users/api-reference/get-tweets-id)) - Retrieve a single Tweet object with an `id`
 - `TwitterLabsAPI#get_tweets` ([docs](https://developer.twitter.com/en/docs/labs/tweets-and-users/api-reference/get-tweets)) - Retrieve multiple Tweets with a collection of `ids`
+- `TwitterLabsAPI#hide_reply` ([docs](https://developer.twitter.com/en/docs/labs/hide-replies/api-reference/put-hidden)) - Hide a reply by referencing it's `id`; must be in a conversation belonging to the authenticating user
+- `TwitterLabsAPI#search` ([docs](https://developer.twitter.com/en/docs/labs/recent-search/api-reference/get-recent-search)) - Returns Tweets from the last 7 days that match a search query.
 
 #### Users
 
@@ -71,7 +74,9 @@ Currently, the following endpoints are implemented:
 
 ## Roadmap
 
-Since this project is initially driven by my own usage of the API, I will focus on implementing and refining the Tweets, Users, and Metrics endpoints. If this repo gets enough interest, I might implement the other endpoints and create a proper `.gemspec`. And of course, contributions are welcome :)
+Currently focused on implementing support for all v2 endpoints; if there is enough interest, I will add v1 endpoint support as well.
+
+And of course, contributions are welcome :)
 
 ## Dependencies
 

data/lib/twitter_labs_api/client.rb

@@ -1,4 +1,6 @@
+require_relative 'version'
 require_relative 'api_error'
+require_relative 'services/params_service'
 require_relative 'resources/tweet'
 require_relative 'resources/user'
 
@@ -17,13 +19,14 @@ module TwitterLabsAPI
 
     private
 
-    def make_request(url:, params: {}, is_collection: false)
+    def make_request(url:, params: {}, is_collection: false, method: :get)
       uri = URI.parse(url)
       uri.query = URI.encode_www_form(params)
-      request = Net::HTTP::Get.new(uri)
+      request = http_adapter(method).new(uri)
       request['Authorization'] = "Bearer #{bearer_token}"
+      request['User-Agent'] = "twitter_labs_api gem #{TwitterLabsAPI::VERSION}"
       req_options = { use_ssl: uri.scheme == 'https' }
-  
+
       self.api_response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
         http.request(request)
       end
@@ -36,7 +39,16 @@ module TwitterLabsAPI
   
       is_collection ? handle_collection : handle_single
     end
-  
+
+    def http_adapter(method)
+      case method
+      when :put
+        Net::HTTP::Put
+      else
+        Net::HTTP::Get
+      end
+    end
+
     def error_response?
       parsed_response.key?('errors')
     end

data/lib/twitter_labs_api/resources/tweet.rb

@@ -2,26 +2,54 @@ module TwitterLabsAPI
   module Resources
     module Tweet
       DEFAULT_TWEET_FIELDS = %w[id author_id created_at lang public_metrics].freeze
+      DEFAULT_FIELDS = { tweet: DEFAULT_TWEET_FIELDS }.freeze
 
+      # Returns a variety of information about a single Tweet specified by the requested ID.
       # @param [String] :id the ID of the requested Tweet
-      # @param [Array<String>] :tweet_fields (["id", "author_id", "created_at", "lang", "public_metrics"]) the list of fields to retrieve for the given tweet
-      def get_tweet(id:, tweet_fields: DEFAULT_TWEET_FIELDS)
+      # @param [Hash] :fields a hash for fields to include in the response payload; 
+      #
+      #     e.g.: { tweet: %w[id username], media: %w[url] }
+      # @return Hash an object with requested tweet fields
+      def get_tweet(id:, fields: DEFAULT_FIELDS)
         url = "https://api.twitter.com/labs/2/tweets/#{id}"
-        params = {
-          'tweet.fields' => tweet_fields.join(',')
-        }.compact
+        params = ParamsService.from_fields(fields)
 
         make_request(url: url, params: params)
       end
 
+      # Returns a variety of information about the Tweet specified by the requested ID or list of IDs.
       # @param [Array<String>] :ids the collection of requested Tweet IDs
-      # @param [Array<String>] :tweet_fields (["id", "author_id", "created_at", "lang", "public_metrics"]) the list of fields to retrieve for the given tweet
-      def get_tweets(ids:, tweet_fields: DEFAULT_TWEET_FIELDS)
+      # @param [Hash] :fields a hash for fields to include in the response payload; 
+      #
+      #     e.g.: { tweet: %w[id username], media: %w[url] }
+      # @return [Array<Hash>] of tweet objects with the requested tweet fields
+      def get_tweets(ids:, fields: DEFAULT_FIELDS)
         url = 'https://api.twitter.com/labs/2/tweets'
-        params = {
-          'ids' => ids.join(','),
-          'tweet.fields' => tweet_fields.join(',')
-        }.compact
+        params = ParamsService.from_fields(fields)
+        params.merge!({ ids: ids.join(',') })
+
+        make_request(url: url, params: params, is_collection: true)
+      end
+
+      # Hides or unhides a reply to a Tweet.
+      # @param [String] :id the ID of the requested Tweet; must belong to a conversation by the authenticated user
+      # @return boolean indicating the hidden status of the requested tweet
+      def hide_reply(id:)
+        url = "https://api.twitter.com/labs/2/tweets/#{id}/hidden"
+
+        make_request(url: url, method: :put)[:hidden]
+      end
+
+      # The Labs recent search endpoint returns Tweets from the last 7 days that match a search query.
+      # @param [String] :query the search query
+      # @param [Hash] :fields a hash for fields to include in the response payload; 
+      #
+      #     e.g.: { tweet: %w[id username], media: %w[url] }
+      # @return [Array<Hash>] of tweet objects with the requested tweet fields
+      def search(query:, fields: DEFAULT_FIELDS)
+        url = 'https://api.twitter.com/labs/2/tweets/search'
+        params = ParamsService.from_fields(fields)
+        params.merge!({ query: query })
 
         make_request(url: url, params: params, is_collection: true)
       end

data/lib/twitter_labs_api/resources/user.rb

@@ -2,38 +2,45 @@ module TwitterLabsAPI
   module Resources
     module User
       DEFAULT_USER_FIELDS = %w[id name username].freeze
+      DEFAULT_FIELDS = { user: DEFAULT_USER_FIELDS }.freeze
 
+      # Returns a variety of information about a single more user specified by the requested ID.
       # @param [String] :id the ID of the requested User
-      # @param [Array<String>] :user_fields (["name", "username"]) the list of fields to retrieve for the given User
-      def get_user(id:, user_fields: DEFAULT_USER_FIELDS)
+      # @param [Hash] :fields  a hash for fields to include in the response payload; 
+      #
+      #  e.g.: { user: %w[id name username] }
+      # @return Hash an object with requested user fields
+      def get_user(id:, fields: DEFAULT_FIELDS)
         url = "https://api.twitter.com/labs/2/users/#{id}"
-        params = {
-          'user.fields' => user_fields.join(',')
-        }.compact
+        params = ParamsService.from_fields(fields)
 
         make_request(url: url, params: params)
       end
 
+      # Returns a variety of information about one or more Users specified by the requested IDs.
       # @param [Array<String>] :ids the collection of requested User IDs
-      # @param [Array<String>] :user_fields (["name", "username"]) the list of fields to retrieve for the given User
-      def get_users(ids:, user_fields: DEFAULT_USER_FIELDS)
+      # @param [Hash] :fields  a hash for fields to include in the response payload; 
+      #
+      #  e.g.: { user: %w[id name username] }
+      # @return [Array<Hash>] of user objects with the requested user fields
+      def get_users(ids:, fields: DEFAULT_FIELDS)
         url = 'https://api.twitter.com/labs/2/users'
-        params = {
-          'ids' => ids.join(','),
-          'user.fields' => user_fields.join(',')
-        }.compact
+        params = ParamsService.from_fields(fields)
+        params.merge!({ ids: ids.join(',') })
 
         make_request(url: url, params: params, is_collection: true)
       end
 
+      # Returns a variety of information about one or more Users specified by the requested usernames.
       # @param [Array<String>] :usernames the collection of requested Usernames
-      # @param [Array<String>] :user_fields (["name", "username"]) the list of fields to retrieve for the given User
-      def get_users_by_usernames(usernames:, user_fields: DEFAULT_USER_FIELDS)
+      # @param [Hash] :fields  a hash for fields to include in the response payload; 
+      #
+      #  e.g.: { user: %w[id name username] }
+      # @return [Array<Hash>] of user objects with the requested user fields
+      def get_users_by_usernames(usernames:, fields: DEFAULT_FIELDS)
         url = 'https://api.twitter.com/labs/2/users/by'
-        params = {
-          'usernames' => usernames.join(','),
-          'user.fields' => user_fields.join(',')
-        }.compact
+        params = ParamsService.from_fields(fields)
+        params.merge!({ usernames: usernames.join(',') })
 
         make_request(url: url, params: params, is_collection: true)
       end

data/lib/twitter_labs_api/services/params_service.rb

@@ -0,0 +1,15 @@
+class ParamsService
+  # Convert user-passed fields hash to query params
+  # @param [Hash] :fields A hash of requested fields; see API Reference for details
+  # @return [Hash] A hash of query params for consumption by API client
+  # @example
+  #     input: { tweet: %w[id username], media: ['url'] }
+  #     output: { 'tweet.fields' => 'id,username', 'media.fields' => 'url }
+  def self.from_fields(fields)
+    fields.keys.inject({}) do |memo, key|
+      memo["#{key}.fields"] = fields[key].join(',')
+
+      memo
+    end
+  end
+end

data/lib/twitter_labs_api/version.rb

@@ -1,3 +1,3 @@
 module TwitterLabsAPI
-  VERSION = '0.5.0'.freeze
+  VERSION = '0.7.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: twitter_labs_api
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.1
 platform: ruby
 authors:
 - tomholford
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-27 00:00:00.000000000 Z
+date: 2020-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -90,6 +90,7 @@ files:
 - lib/twitter_labs_api/client.rb
 - lib/twitter_labs_api/resources/tweet.rb
 - lib/twitter_labs_api/resources/user.rb
+- lib/twitter_labs_api/services/params_service.rb
 - lib/twitter_labs_api/version.rb
 - twitter-labs-api.gemspec
 homepage: https://github.com/tomholford/twitter-labs-api