twitter_labs_api 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b280e642f8468d372684da3c0a04ce2effffd652b244e53a50e1925ade66d3fc
-  data.tar.gz: e1f1513a92468bc7fdb3e538bbc70b44ab15be2251f203485258f701b8c6b629
+  metadata.gz: f948545c92cea7e99843267178e59de531a72c6ae552b83d3e75e9166c15ef1a
+  data.tar.gz: 11a1eff22ea020997cfaa2242e2d53c3734d49d5bcf52ae6a505db5ed16d106a
 SHA512:
-  metadata.gz: 7166032d4689b43fd696fc5f627dfe00af89eec532b3f36a652d6b22d3c74732c75b60e36be3a18caa9683b68c3b4629abad0d9319985ad56ef01ee19264ad94
-  data.tar.gz: 259cb764a4c6f15ed5efb335bc46da7117fa447da3c19fd7754e931e40616bd2464847b547a9a17a7d5094f43195f717f196da6733ec47bfbf7d9c8470aa3e19
+  metadata.gz: b1ef6ca4d36e6c1fc0bbbeaa88a0ab764b66997b2ac8c1da2c546a8208f8368f9da6376341cdcc69a4d840a411ace4e5c38a30d71f6fa1463d1c24385a0164b2
+  data.tar.gz: 971f0fb5b2fe9d242ea98e1d7a51ee227f586580a04f14bf3c5af4e56541167c2e2f2d3e78977f7c3b78712a08ebf7af97e722ac7363da82cfe8e77e0ae8d387

data/.gitignore

@@ -0,0 +1 @@
+pkg/

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.2.0 - 5 March 2020
+
+- Fix: Handle 'successful' API errors (i.e., HTTP 200 response, but API error such as User Not Found)
+- Documented expansion fields
+- Documented methods
+
 # 0.1.0 - 5 March 2020
 
 Initial gem commit

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    twitter_labs_api (0.1.0)
+    twitter_labs_api (0.2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -21,7 +21,7 @@ GEM
     minitest (5.14.0)
     rack (2.2.2)
     rainbow (3.0.0)
-    rake (10.5.0)
+    rake (13.0.1)
     thread_safe (0.3.6)
     tzinfo (1.2.6)
       thread_safe (~> 0.1)
@@ -34,7 +34,7 @@ DEPENDENCIES
   activesupport
   bundler (~> 2.0)
   httplog
-  rake (~> 10.0)
+  rake (~> 13.0)
   twitter_labs_api!
 
 BUNDLED WITH

data/README.md

@@ -1,6 +1,6 @@
 # twitter-labs-api
 
-A basic implementation of a Twitter Labs API client in Ruby. This project uses the v2 endpoints announced [here](https://twittercommunity.com/t/releasing-a-new-version-of-labs-endpoints/134219/3).
+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
 
@@ -9,10 +9,17 @@ All one needs is a Twitter [bearer token](https://developer.twitter.com/en/docs/
 
 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.
 
+### Setup
+
+```shell
+gem install twitter_labs_api
+```
+
 ### Example
 
+#### Getting a Tweet by ID
 ```ruby
-requre `labs_api`
+requre `twitter_labs_api`
 
 api = TwitterLabsAPI.new(bearer_token: 'YOUR-BEARER-TOKEN')
 
@@ -21,6 +28,18 @@ api.get_tweet(id: '1234671272602193920')
 >> {"data"=>{"author_id"=>"44196397", "created_at"=>"2020-03-03T02:45:45.000Z", "id"=>"1234671272602193920", "lang"=>"und", "public_metrics"=>{"retweet_count"=>4534, "reply_count"=>1036, "like_count"=>43489, "quote_count"=>224}, "text"=>"✌️ bro https://t.co/nJ7CUyhr2j"}}
 ```
 
+#### 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:
+
+```ruby
+my_fields = %w[id author_id created_at text]
+
+api.get_tweet(id: '1235508591232090112', tweet_fields: my_fields)
+
+>> {"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."}
+```
+
 ### Status
 Currently, the following endpoints are implemented:
 

data/lib/twitter_labs_api.rb

@@ -3,13 +3,14 @@ require 'net/http'
 require 'uri'
 require 'active_support/core_ext/hash/indifferent_access'
 
-DEFAULT_TWEET_FIELDS = %w[id author_id created_at lang public_metrics].join(',').freeze
-DEFAULT_USER_FIELDS = %w[name username].join(',').freeze
+DEFAULT_TWEET_FIELDS = %w[id author_id created_at lang public_metrics].freeze
+DEFAULT_USER_FIELDS = %w[name username].freeze
 
 class TwitterLabsAPIError < StandardError; end
 
+# A basic implementation of a Twitter Labs API client.
 class TwitterLabsAPI
-  attr_accessor :bearer_token, :debug
+  attr_accessor :bearer_token, :debug, :api_response, :parsed_response
 
   def initialize(bearer_token:, debug: false)
     @bearer_token = bearer_token
@@ -17,39 +18,47 @@ class TwitterLabsAPI
     require 'httplog' if debug
   end
 
+  # @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)
     url = "https://api.twitter.com/labs/2/tweets/#{id}"
     params = {
-      'tweet.fields' => tweet_fields
+      'tweet.fields' => tweet_fields.join(',')
     }.compact
 
     make_request(url: url, params: params)
   end
 
+  # @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)
     url = 'https://api.twitter.com/labs/2/tweets'
     params = {
       'ids' => ids.join(','),
-      'tweet.fields' => tweet_fields
+      'tweet.fields' => tweet_fields.join(',')
     }.compact
 
     make_request(url: url, params: params, is_collection: true)
   end
 
+  # @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)
     url = "https://api.twitter.com/labs/2/users/#{id}"
     params = {
-      'user.fields' => user_fields
+      'user.fields' => user_fields.join(',')
     }.compact
 
     make_request(url: url, params: params)
   end
 
+  # @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)
     url = 'https://api.twitter.com/labs/2/users'
     params = {
       'ids' => ids.join(','),
-      'user.fields' => user_fields
+      'user.fields' => user_fields.join(',')
     }.compact
 
     make_request(url: url, params: params, is_collection: true)
@@ -64,28 +73,33 @@ class TwitterLabsAPI
     request['Authorization'] = "Bearer #{bearer_token}"
     req_options = { use_ssl: uri.scheme == 'https' }
 
-    response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
+    self.api_response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
       http.request(request)
     end
 
-    is_collection ? handle_collection(response) : handle_single(response)
-  end
+    raise TwitterLabsAPIError("#{api_response.code} #{api_response.msg}") unless api_response.is_a?(Net::HTTPSuccess)
+
+    self.parsed_response = JSON.parse(api_response.body)
 
-  # TODO: handle non-api errs (e.g., timeouts)
-  def handle_single(response)
-    return JSON.parse(response.body)['data'].with_indifferent_access if response.is_a?(Net::HTTPSuccess)
+    handle_api_error if error_response?
 
-    handle_api_error(response)
+    is_collection ? handle_collection : handle_single
   end
 
-  def handle_collection(response)
-    return JSON.parse(response.body)['data'].map(&:with_indifferent_access) if response.is_a?(Net::HTTPSuccess)
+  def error_response?
+    parsed_response.key?('errors')
+  end
+
+  def handle_single
+    parsed_response['data'].with_indifferent_access
+  end
 
-    handle_api_error(response)
+  def handle_collection
+    parsed_response['data'].map(&:with_indifferent_access)
   end
 
-  def handle_api_error(response)
-    error = JSON.parse(response.body)
+  def handle_api_error
+    error = parsed_response['errors'].first
 
     raise TwitterLabsAPIError, "#{error['title']}: #{error['detail']} #{error['type']}"
   end

data/lib/twitter_labs_api/version.rb

@@ -1,3 +1,3 @@
 class TwitterLabsAPI
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

data/twitter-labs-api.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: twitter_labs_api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - tomholford
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 description: 
 email:
 - tomholford@users.noreply.github.com
@@ -45,6 +45,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".gitignore"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock