net 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cc39cfbf35cc2f608255699239173161bc22b946
-  data.tar.gz: d3b90279a21b9ec08ed7bc3940d688d4589b3d62
+  metadata.gz: e8d47667af5750fa95def0080edb95f64ebe5ec5
+  data.tar.gz: d2339bd6f4b728e27de7c9d3249877c10c000474
 SHA512:
-  metadata.gz: 0f06e52f69536e19e585dd252564328623094a755736b6a15a47221fe839cf0aba3a2218b893aae1afa4d6939f0ed078ce3828ce20b75602d2b33f959034639a
-  data.tar.gz: 3da6df355bb145b2da134d37881d69d23ce81168c172a56af6be02c2fbfbc68c5455556dffeb6102c76d5054a015d0156f735f86c9c480d1af5053e6166092eb
+  metadata.gz: f076d2cf3063b019795f320cbff740ed3fbf07d01e9d4b1b7a4295f5c16bbf25cccb3982a178a6f9dfba6cb0e2c27c6f6ce610f4b2609b9c22b83f39e87f3343
+  data.tar.gz: c5391de7b4762d3d3e3b7073cd27bae4aac635d21fedc6b696bef465205340bc9c365b07ea5d5180ea158766a1cb59309e7de5d6e2dddf572ee144531639f741

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--fail-fast

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+For more information about changelogs, check
+[Keep a Changelog](http://keepachangelog.com) and
+[Vandamme](http://tech-angels.github.io/vandamme).
+
+## 0.1.0 - 2014-10-13
+
+* Initial release with `Twitter::User` supporting `find_by`, `find_by!` and `where`.

data/{LICENSE.txt → MIT-LICENSE}

@@ -1,6 +1,4 @@
-Copyright (c) 2014 claudiob
-
-MIT License
+Copyright 2014 Fullscreen, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -19,4 +17,4 @@ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,29 +1,120 @@
-# Net
+Net - a Ruby client for social networks API
+===========================================
 
-TODO: Write a gem description
+Net helps you write apps that need to interact with Twitter.
 
-## Installation
 
-Add this line to your application's Gemfile:
+After [configuring your Twitter app](#configuring-your-app), you can run commands like:
 
-    gem 'net'
+```ruby
+user = Net::Twitter::User.find_by screen_name: 'fullscreen'
+user.screen_name #=> "Fullscreen"
+user.followers_count #=> 48_200
+```
 
-And then execute:
+How to install
+==============
 
-    $ bundle
+To install on your system, run
 
-Or install it yourself as:
+    gem install net
 
-    $ gem install net
+To use inside a bundled Ruby project, add this line to the Gemfile:
 
-## Usage
+    gem 'net', '~> 0.1.0'
 
-TODO: Write usage instructions here
+Since the gem follows [Semantic Versioning](http://semver.org),
+indicating the full version in your Gemfile (~> *major*.*minor*.*patch*)
+guarantees that your project won’t occur in any error when you `bundle update`
+and a new version of Net is released.
 
-## Contributing
+Available resources
+===================
 
-1. Fork it ( https://github.com/[my-github-username]/net/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+Net::Twitter::User
+-----------
+
+Use [Net::Account]() to:
+
+* retrieve a Twitter user by screen name
+* retrieve a list of Twitter users by screen names
+* access the number of followers of a Twitter user
+
+```ruby
+user = Net::Twitter::User.find_by screen_name: 'fullscreen'
+user.followers_count #=> 48_200
+
+users = Net::Twitter::User.where screen_name: ['fullscreen', 'brohemian6']
+users.map(&:followers_count).sort #=> [12, 48_200]
+```
+
+*The methods above require a configured Twitter app (see below).*
+
+Configuring your app
+====================
+
+In order to use Net you must create an app in the [Twitter Application Manager](https://apps.twitter.com/app/new).
+
+Once the app is created, copy the API key and secret and add them to your
+code with the following snippet of code (replacing with your own key and secret)
+:
+
+```ruby
+Net::Twitter.configure do |config|
+  config.apps.push key: 'abcd', secret: 'efgh'
+end
+```
+
+Configuring with environment variables
+--------------------------------------
+
+As an alternative to the approach above, you can configure your app with
+variables. Setting the following environment variables:
+
+```bash
+export TWITTER_API_KEY='abcd'
+export TWITTER_API_SECRET='efgh'
+```
+
+is equivalent to configuring your app with the initializer:
+
+```ruby
+Net::Twitter.configure do |config|
+  config.apps.push key: 'abcd', secret: 'efgh'
+end
+```
+
+so use the approach that you prefer.
+If a variable is set in both places, then `Net::Twitter.configure` takes precedence.
+
+How to test
+===========
+
+To run tests, type:
+
+```bash
+rspec
+```
+
+Net uses [VCR](https://github.com/vcr/vcr) so by default tests do not run
+HTTP requests.
+
+If you need to run tests against the live Twitter API,
+[configure your Twitter app](#configuring-your-app) using environment variables,
+erase the cassettes, then run `rspec`.
+
+
+How to release new versions
+===========================
+
+If you are a manager of this project, remember to upgrade the [Net gem](http://rubygems.org/gems/net)
+whenever a new feature is added or a bug gets fixed.
+
+Make sure all the tests are passing, document the changes in CHANGELOG.md and
+README.md, bump the version, then run
+
+    rake release
+
+Remember that the net gem follows [Semantic Versioning](http://semver.org).
+Any new release that is fully backward-compatible should bump the *patch* version (0.1.x).
+Any new version that breaks compatibility should bump the *minor* version (0.x.0)

data/lib/net.rb

@@ -1,5 +1,4 @@
 require "net/version"
 
 module Net
-  # Your code goes here...
 end

data/lib/net/twitter.rb

@@ -0,0 +1,11 @@
+require 'net/twitter/config'
+require 'net/twitter/errors'
+require 'net/twitter/models'
+
+module Net
+  module Twitter
+    extend Config
+    include Errors
+    include Models
+  end
+end

data/lib/net/twitter/api/configuration.rb

@@ -0,0 +1,16 @@
+module Net
+  module Twitter
+    module Api
+      class Configuration
+        attr_accessor :apps
+
+        def initialize
+          @apps = []          
+          env_key = ENV['TWITTER_API_KEY']
+          env_secret = ENV['TWITTER_API_SECRET']
+          @apps.push key: env_key, secret: env_secret if env_key && env_secret
+        end
+      end
+    end
+  end
+end

data/lib/net/twitter/api/request.rb

@@ -0,0 +1,121 @@
+require 'net/twitter/errors/response_error'
+require 'active_support'
+require 'active_support/core_ext'
+
+module Net
+  module Twitter
+    module Api
+      class Request
+        def initialize(attrs = {})
+          @host = 'api.twitter.com'
+          @path = attrs.fetch :path, "/1.1/#{attrs[:endpoint]}.json"
+          @query = attrs[:params].to_param if attrs[:params]
+          @block = attrs.fetch :block, -> (request) {add_access_token! request}
+          @method = attrs.fetch :method, :get
+        end
+
+        def run
+          print "#{as_curl}\n"
+
+          case response = run_http_request
+          when Net::HTTPOK
+            JSON response.body
+          when Net::HTTPTooManyRequests
+            store_rate_limit_reset response.header["x-rate-limit-reset"].to_i
+            run
+          else
+            raise Errors::ResponseError, response
+          end
+        end
+
+      private
+
+        def run_http_request
+          Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |http|
+            http.request http_request
+          end
+        end
+
+        def http_request
+          http_class = "Net::HTTP::#{@method.capitalize}".constantize
+          @http_request ||= http_class.new(uri.request_uri).tap do |request|
+            @block.call request
+          end
+        end
+
+        def uri
+          @uri ||= URI::HTTPS.build host: @host, path: @path, query: @query
+        end
+
+        def add_access_token!(request)
+          request.add_field 'Authorization', "Bearer #{access_token}"
+        end
+
+        def access_token
+          @@access_token ||= fetch_access_token
+        end
+
+        def fetch_access_token
+          path = '/oauth2/token'
+          block = -> (request) {add_client_credentials! request}
+          request = Request.new path: path, method: :post, block: block
+          authentication_data = request.run
+          authentication_data['access_token']
+        # rescue Errors::Suspended
+        #   require 'pry'; binding.pry; true;
+        end
+
+        def add_client_credentials!(request)
+          request.initialize_http_header client_credentials_headers
+          request.add_field 'Authorization', "Basic #{credentials}"
+          request.set_form_data grant_type: 'client_credentials'
+        end
+
+        def client_credentials_headers
+          content_type = 'application/x-www-form-urlencoded;charset=UTF-8'
+          {}.tap{|headers| headers['Content-Type'] = content_type}
+        end
+
+        def credentials
+          @@app = apps.find(next_available_app) do |app|
+            app[:limit_reset].to_i < Time.now.to_i
+          end
+          Base64.strict_encode64 "#{@@app[:key]}:#{@@app[:secret]}"
+        end
+
+        def next_available_app
+          Proc.new do
+            next_limit_reset = @@apps.map{|app| app[:limit_reset]}.min
+            sleep_time = next_limit_reset - Time.now.to_i
+            puts "Sleeping for #{sleep_time}s\n"
+            sleep sleep_time
+            puts "Waking up\n"
+            @@apps.find{|app| app[:limit_reset] == next_limit_reset}
+          end
+        end
+
+        def store_rate_limit_reset(limit_reset)
+          @@app[:limit_reset] = limit_reset
+          @@access_token, @@app, @http_request = nil, nil, nil
+        end
+
+        def apps
+          @@apps ||= Net::Twitter.configuration.apps.map do |app|
+            app.tap{app[:limit_reset] = nil}
+          end
+        end
+
+        def as_curl
+          'curl'.tap do |curl|
+            curl <<  " -X #{http_request.method}"
+            http_request.each_header do |name, value|
+              curl << %Q{ -H "#{name}: #{value}"}
+            end
+            curl << %Q{ -d '#{http_request.body}'} if http_request.body
+            curl << %Q{ "#{@uri.to_s}"}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/twitter/config.rb

@@ -0,0 +1,15 @@
+require 'net/twitter/api/configuration'
+
+module Net
+  module Twitter
+    module Config
+      def configure
+        yield configuration if block_given?
+      end
+
+      def configuration
+        @configuration ||= Api::Configuration.new
+      end
+    end
+  end
+end

data/lib/net/twitter/errors.rb

@@ -0,0 +1,4 @@
+require 'net/twitter/errors/response_error'
+require 'net/twitter/errors/suspended_user'
+require 'net/twitter/errors/too_many_users'
+require 'net/twitter/errors/unknown_user'

data/lib/net/twitter/errors/response_error.rb

@@ -0,0 +1,14 @@
+module Net
+  module Twitter
+    module Errors
+      class ResponseError < StandardError
+        attr_reader :response
+      
+        def initialize(response = {})
+          @response = response
+          super response
+        end
+      end
+    end
+  end
+end

data/lib/net/twitter/errors/suspended_user.rb

@@ -0,0 +1,11 @@
+module Net
+  module Twitter
+    module Errors
+      class SuspendedUser < StandardError
+        def message
+          'Suspended user'
+        end
+      end
+    end
+  end
+end

data/lib/net/twitter/errors/too_many_users.rb

@@ -0,0 +1,11 @@
+module Net
+  module Twitter
+    module Errors
+      class TooManyUsers < StandardError
+        def message
+          'Too many users in the request'
+        end
+      end
+    end
+  end
+end

data/lib/net/twitter/errors/unknown_user.rb

@@ -0,0 +1,11 @@
+module Net
+  module Twitter
+    module Errors
+      class UnknownUser < StandardError
+        def message
+          'Unknown user'
+        end
+      end
+    end
+  end
+end

data/lib/net/twitter/models.rb

@@ -0,0 +1 @@
+require 'net/twitter/models/user'

data/lib/net/twitter/models/user.rb

@@ -0,0 +1,80 @@
+require 'net/twitter/api/request'
+require 'net/twitter/errors'
+
+module Net
+  module Twitter
+    module Models
+      class User
+        attr_reader :screen_name, :followers_count
+
+        def initialize(attrs = {})
+          attrs.each{|k, v| instance_variable_set("@#{k}", v) unless v.nil?}
+        end
+
+        # Returns the existing Twitter user matching the provided attributes or
+        # nil when the user is not found.
+        #
+        # @return [Net::Twitter::Models::User] when the user is found.
+        # @return [nil] when the user is not found or suspended.
+        # @param [Hash] params the attributes to find a user by.
+        # @option params [String] :screen_name The Twitter user’s screen name
+        #   (case-insensitive).
+        def self.find_by(params = {})
+					find_by! params
+				rescue Errors::UnknownUser, Errors::SuspendedUser
+          nil
+        end
+
+        # Returns the existing Twitter user matching the provided attributes or
+        # raises an error when the user is not found or suspended.
+        #
+        # @return [Net::Twitter::Models::User] the Twitter user.
+        # @param [Hash] params the attributes to find a user by.
+        # @option params [String] :screen_name The Twitter user’s screen name
+        #   (case-insensitive).
+        # @raise [Net::Errors::UnknownUser] if the user cannot be found.
+        # @raise [Net::Errors::SuspendedUser] if the user account is suspended.
+        def self.find_by!(params = {})
+          request = Api::Request.new endpoint: 'users/show', params: params
+          user_data = request.run
+          new user_data
+        rescue Errors::ResponseError => error
+          case error.response
+            when Net::HTTPNotFound then raise Errors::UnknownUser
+            when Net::HTTPForbidden then raise Errors::SuspendedUser
+          end
+        end
+
+        # Returns up to 100 existing Twitter users matching the provided
+        # attributes. Raises an error when requesting more than 100 users.
+        # Does not return users in the same order that they are requested.
+
+        # @return [Array<Net::Twitter::Models::User>] the Twitter users.
+        # @param [Hash] conditions The attributes to find users by.
+        # @option conditions [Array<String>] screen_name The Twitter user's
+        #   screen names (case-insensitive).
+        # @raise [Net::Errors::TooManyUsers] when more than 100 Twitter users
+        #   match the provided attributes.
+        def self.where(conditions = {})
+          params = to_where_params conditions
+          request = Api::Request.new endpoint: 'users/lookup', params: params
+          users_data = request.run
+          users_data.map{|user_data| new user_data}
+        rescue Errors::ResponseError => error
+          case error.response
+            when Net::HTTPNotFound then []
+            when Net::HTTPForbidden then raise Errors::TooManyUsers
+          end
+        end
+
+			private
+
+				def self.to_where_params(conditions = {})
+          conditions.dup.tap do |params|
+            params.each{|k,v| params[k] = v.join(',') if v.is_a?(Array)}
+          end
+        end
+      end
+    end
+  end
+end