login_radius 0.0.1

data/README.md

@@ -0,0 +1,417 @@
+# LoginRadius
+
+Ruby wrapper for the LoginRadius API. Get social graph information and send messages using LoginRadius'
+many social network clients!
+
+Optional Asynchronous EventMachine friendly option!
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'login_radius'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install login_radius
+
+## Usage
+
+Take a peek:
+
+    @user_profile = LoginRadius::UserProfile.new({
+      :token => "TOKEN",
+      :secret => "SECRET",
+      :async => false #Set to true if using EventMachine driven frameworks(must use Em Synchrony)
+    })
+    @user_profile.login
+    my_contacts = @user_profile.contacts
+		
+That's right, folks. It's that simple. In order to get access to LoginRadius API, you only
+need to create a UserProfile object with a user's login token and your apps secret, and login.
+
+### How to get a token and actually make a client
+
+On the LoginRadius website, you are able to enter your own callback URL for your app. You will need
+to setup a route on whatever framework you use, maybe "/callback." Then, get the gem forward(www.forwardhq.com)
+and use it to set up a public web address for your localhost server. Then, you can enter the callback on LoginRadius
+as https://jordanmatthew.fwd.wf/callback, for instance.
+
+Paste their example login stuff onto your index page, and then enter your FB/Twitter credentials on their site.
+
+Now you're ready to go with testing!
+
+When LoginRadius hits your callback after a user logs in, you'll see parameters like this:
+
+Parameters: {"token"=>"yourtokenhere"}
+
+This token is the token used in the above example. This is what you'll need to get your user's profile.
+Just paste it into the code above, and you can immediately grab their user profile on the callback,
+login, and grab their contacts.
+
+### Some examples
+
+Below is just code exemplifying some of the more interesting methods and what they return.
+Note if you have a user authed via facebook, and not twitter, methods like 
+
+    @user_profile.twitter_timeline
+    => false
+		
+Will return false, indicating you don't have access to that stream.
+
+#### Facebook Stuff
+
+    @user_profile.facebook_groups
+    => [{:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"}]
+    
+    @user_profile.facebook_groups
+    => [{:id=>"11111", :name=>"Name"},
+     {:id=>"11111", :name=>"Name"}]
+    
+    
+    @user_profile.facebook_events
+    => [{:id=>"11111",
+      :name=>"Name",
+      :start_time=>"3/14/2015 9:00:00 AM",
+      :rsvp_status=>"attending",
+      :location=>"Across the world!"}]
+
+And, finally, you can also make facebook posts:
+
+    params = {
+      :title => "Testing",
+      :url => "www.loginradius.com",
+      :status => "Wizzup",
+      :caption => "Testly",
+      :description => "Testing"
+    }
+    @user_profile.make_facebook_post(params)
+    => true
+
+Note that as of publishing, the :to option on facebook params does not work. You can't post to
+other people's walls.
+
+#### LinkedIn Stuff
+
+To send messages over linked in:
+
+    @user_profile.send_linked_in_message(@user_profile.contacts.first[:id], "Testing", "This is a test.")
+    => true
+		
+Notice how I grabbed my first contact and used his :id property.
+
+Also, you can grab a user's linked in companies:
+
+    @user_profile.linked_in_companies
+    => [{:id=>11111, :name=>"Name"}]
+		
+#### Twitter Stuff
+
+To send messages over twitter:
+	
+    @user_profile.send_linked_in_message(@user_profile.contacts.first[:id], "Testing", "This is a test.")
+    => true
+	
+Notice how I grabbed my first contact and used his :id property.
+	
+Grab your timelines and mentions:
+
+    @user_profile.twitter_timeline
+    => [{:id=>"11111",
+        :text=>"Stuff",
+        :date_time=>"5/20/2013 4:53:52 PM",
+        :likes=>0,
+        :place=>"",
+        :source=>
+         "<a href=\"http://twitterfeed.com\" rel=\"nofollow\">twitterfeed</a>",
+        :image_url=>nil,
+        :link_url=>nil,
+        :name=>"Name"}]
+        
+    @user_profile.twitter_mentions
+    => [{:id=>"11111",
+        :text=>"Stuff",
+        :date_time=>"3/31/2013 7:54:10 PM",
+        :likes=>0,
+        :place=>"",
+        :source=>"web",
+        :image_url=>nil,
+        :link_url=>nil,
+        :name=>"Name"}]
+		
+#### Social Network Contacts
+
+Note this is all the contacts from every social network the user is connected to.
+
+    @user_profile.contacts
+    => [{:name=>"Name",
+      :email_id=>"",
+      :phone_number=>"",
+      :id=>"11111",
+      :profile_url=>nil,
+      :image_url=>nil,
+      :status=>nil,
+      :industry=>nil,
+      :country=>nil,
+      :gender=>nil}]
+
+#### User Profile Stuff
+
+When you login, the API returns a hash of user profile information, which is then turned into methods
+on the LoginRadius::UserProfile object for your accessing pleasure. A quick call to methods will show this. 
+
+    @user_profile.methods
+    =>[:id,
+     :provider,
+     :prefix,
+     :first_name,
+     :middle_name,
+     :last_name,
+     :suffix,
+     :full_name,
+     :nick_name,
+     :profile_name,
+     :birth_date,
+     :gender,
+     :website,
+     :email,
+     :country,
+     ...]
+
+Calling .methods on a user profile right after a successful login call will reveal these. 
+For more information, please read the section in caveats on the matter, as it's a bit esoteric.
+
+## Caveats
+
+This section is for the nitpickers. It's got notes about the finer pickings of this API for those
+who are wondering, but is not strictly necessary reading.
+
+### The Bang Methods
+
+When authenticated, a method like contacts will return 
+
+    @user_profile.authenticated?
+    => true
+    @user_profile.contacts 
+    => [{:name=>"Name",
+      :email_id=>"",
+      :phone_number=>"",
+      :id=>"11111",
+      :profile_url=>nil,
+      :image_url=>nil,
+      :status=>nil,
+      :industry=>nil,
+      :country=>nil,
+      :gender=>nil},
+      ...
+		
+When unauthenticated, a method like contacts will return false.
+
+    @user_profile.authenticated?
+    => false
+    @user_profile.contacts
+    => false
+
+However, if you want to be a bit more flammable, try using contacts!, the bang version. It still returns
+the same results when authed, but when unauthed, will actually raise a LoginRadius::Exception.
+	
+### The LoginRadius::UserProfile object before and after login
+
+Once you've got a valid user_profile, you have many methods available to you. Let's quickly take a look 
+at the methods in a LoginRadius::UserProfile object that hasn't yet been authenticated:
+
+    @user_profile.authenticated?
+    => false
+    
+    @user_profile.methods - Object.new.methods
+    => [:secret,
+     :secret=,
+     :token,
+     :token=,
+     :async,
+     :async=,
+     :guid_valid?,
+     :authenticated?,
+     :call_api,
+     :send_twitter_message,
+     :send_linkedin_message,
+     :make_facebook_post,
+     :login!,
+     :login,
+     :twitter_mentions!,
+     :twitter_mentions,
+     :twitter_timeline!,
+     :twitter_timeline,
+     :linked_in_companies!,
+     :linked_in_companies,
+     :contacts!,
+     :contacts,
+     :facebook_groups!,
+     :facebook_groups,
+     :facebook_posts!,
+     :facebook_posts,
+     :facebook_events!,
+     :facebook_events]
+		
+Notice we've got a lot of stuff we can access. But we're not yet authenticated. Running login and then checking
+the new methods created, we see we have much more than before!
+		
+    @user_profile.login
+    => true
+    @user_profile.authenticated?
+    => true
+    @user_profile.methods - Object.new.methods
+    => [:id,
+    :provider,
+    :prefix,
+    :first_name,
+    :middle_name,
+    :last_name,
+    :suffix,
+    :full_name,
+    :nick_name,
+    :profile_name,
+    :birth_date,
+    :gender,
+    :website,
+    :email,
+    :country,
+    :thumbnail_image_url,
+    :image_url,
+    :favicon,
+    :profile_url,
+    :home_town,
+    :state,
+    :city,
+    :industry,
+    :about,
+    :time_zone,
+    :local_language,
+    :language,
+    :verified,
+    :updated_time,
+    :positions,
+    :educations,
+    :phone_numbers,
+    :im_accounts,
+    :addresses,
+    :main_address,
+    :created,
+    :local_city,
+    :profile_city,
+    :local_country,
+    :profile_country,
+    :relationship_status,
+    :quota,
+    :interested_in,
+    :interests,
+    :religion,
+    :political,
+    :sports,
+    :inspirational_people,
+    :https_image_url,
+    :followers_count,
+    :friends_count,
+    :is_geo_enabled,
+    :total_statuses_count,
+    :associations,
+    :num_recommenders,
+    :honors,
+    :skills,
+    :current_status,
+    :certifications,
+    :courses,
+    :volunteer,
+    :recommendations_received,
+    :languages,
+    :public_repository,
+    :hireable,
+    :repository_url,
+    :age,
+    :patents,
+    :favorite_things,
+    :professional_headline,
+    :provider_access_credential,
+    :secret,
+    :secret=,
+    :token,
+    :token=,
+    :async,
+    :async=,
+    :guid_valid?,
+    :authenticated?,
+    :call_api,
+    :send_twitter_message,
+    :send_linkedin_message,
+    :make_facebook_post,
+    :login!,
+    :login,
+    :twitter_mentions!,
+    :twitter_mentions,
+    :twitter_timeline!,
+    :twitter_timeline,
+    :linked_in_companies!,
+    :linked_in_companies,
+    :contacts!,
+    :contacts,
+    :facebook_groups!,
+    :facebook_groups,
+    :facebook_posts!,
+    :facebook_posts,
+    :facebook_events!,
+    :facebook_events]
+			
+Holy moly we got a whole bunch of new methods! That's because on login, all the user profile information
+returned by the API is turned into dynamically generated GETTERs on the object that you can then use later.
+
+### Running the tests in test/unit
+
+The base_test.rb file isn't meant to be run, it is inherited by user_profile_test.rb. In that file
+you'll notice the lines at the top of the file:
+
+    TOKEN = "yourtokenhere"
+    SECRET = "yoursecrethere"
+
+These are meant to be changed to your API secret and some user's token. What I do is I run a dummy
+rails app locally and use the forward gem so that it can receive requests from the internet. Then I setup
+a callback route and login page on the app and use it to have LoginRadius ping me with tokens that I can
+paste into this test file.
+
+*Beware, LoginRadius invalidates any token after 15 minutes, so during testing, you'll have to repeat the token
+creation A LOT*
+
+To run the tests, do:
+
+    bundle exec ruby -Itest test/unit/user_profile_test.rb
+		
+If you login with a facebook user, for instance, you'll notice all the twitter/linked in tests failing.
+This is to be expected, you don't have access to those streams!
+
+### Evented Frameworks
+
+I've built this gem to work with frameworks like Cramp. I've done a little bit of testing by creating
+a basic event loop script in basic_async_test.rb in the test folder, which you can run to see that
+things work there.
+
+I've also done some AB testing using a Cramp framework elsewhere, but you should take caution in using
+this gem in evented frameworks and make sure to use apache bench to test it for nonblocking yourself.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/hash.rb

@@ -0,0 +1,13 @@
+class Hash
+  def self.lr_convert_hash_keys(value) #lr_ appended so no method naming conflicts with other gems
+    case value
+      when Array
+        value.map { |v| lr_convert_hash_keys(v) }
+        # or `value.map(&method(:convert_hash_keys))`
+      when Hash
+        Hash[value.map { |k, v| [k.to_s.lr_underscore, lr_convert_hash_keys(v)] }]
+      else
+        value
+     end
+  end
+end

data/lib/login_radius/exception.rb

@@ -0,0 +1,4 @@
+module LoginRadius
+  class Exception < Exception
+  end
+end

data/lib/login_radius/messages.rb

@@ -0,0 +1,102 @@
+module LoginRadius
+  module Messages
+    
+    # Sends a message to a person using twitter
+    #
+    # @param sendto [String] Social ID of person you're contacting from contact list
+    # @param subject [String]
+    # @param message [String]
+    # @return [Boolean] Whether or not message succeeded
+    def send_twitter_message(sendto, subject, message)
+      send_message({:sendto => sendto, :subject => subject, :message => message})
+    end
+    
+    # Sends a message to a person using twitter
+    #
+    # @param sendto [String] Social ID of person you're contacting from contact list
+    # @param subject [String]
+    # @param message [String]
+    # @return [Boolean] Whether or not message succeeded
+    def send_twitter_message!(sendto, subject, message)
+      send_message({:sendto => sendto, :subject => subject, :message => message})
+    end
+    
+    # Sends a message to a person using linkedin
+    #
+    # @param sendto [String] Social ID of person you're contacting from contact list
+    # @param subject [String]
+    # @param message [String]
+    # @return [Boolean] Whether or not message succeeded
+    def send_linked_in_message(sendto, subject, message)
+      send_message({:sendto => sendto, :subject => subject, :message => message})
+    end
+    
+    # Sends a message to a person using linkedin
+    #
+    # @param sendto [String] Social ID of person you're contacting from contact list
+    # @param subject [String]
+    # @param message [String]
+    # @return [Boolean] Whether or not message succeeded
+    def send_linked_in_message!(sendto, subject, message)
+      send_message!({:sendto => sendto, :subject => subject, :message => message})
+    end
+    
+    # Sends a message to a person using facebook. Params hash takes following keys:
+    # to(optional) :- Person's wall it's going to, if blank, is your own
+    # title :- [optional parameter] status message title
+    # url:- [optional parameter] any url that you want post in status message
+    # imageurl :- [optional parameter] any image url that you want post in status message
+    # status :- your status message
+    # caption : [optional parameter] caption that you want post in status message
+    # description :- [optional parameter] description  that you want post in status message
+    #
+    # @param params [Hash] 
+    # @return [Boolean] Whether or not message succeeded
+    def make_facebook_post!(params = {})
+      call_api("status/update/#{secret}/#{token}", params)
+    end
+    
+    # Sends a message to a person using facebook. Params hash takes following keys:
+    # to(optional) :- Person's wall it's going to, if blank, is your own
+    # title :- [optional parameter] status message title
+    # url:- [optional parameter] any url that you want post in status message
+    # imageurl :- [optional parameter] any image url that you want post in status message
+    # status :- your status message
+    # caption : [optional parameter] caption that you want post in status message
+    # description :- [optional parameter] description  that you want post in status message
+    #
+    # @param params [Hash] 
+    # @return [Boolean] Whether or not message succeeded
+    def make_facebook_post(params = {})
+      make_facebook_post!(params)
+    rescue LoginRadius::Exception => e
+      false
+    end
+    
+    private
+    
+    # Sends a message to a person. Will use either twitter, facebook or linked in, depending
+    # on where the person you're sending it to came from, and the keys present in the hash.
+    # Other methods in this module describe the keys they use, they all call this method
+    # with the proper keys for their service type.
+    #
+    # @param params [Hash] Params hash describing what you'd like to send. 
+    # @return [Boolean] Whether or not message succeeded
+    def send_message!(params = {})
+      call_api("directmessage/#{secret}/#{token}",params)
+    end
+    
+    # Sends a message to a person. Will use either twitter, facebook or linked in, depending
+    # on where the person you're sending it to came from, and the keys present in the hash.
+    # Other methods in this module describe the keys they use, they all call this method
+    # with the proper keys for their service type.
+    #
+    # @param params [Hash] Params hash describing what you'd like to send. 
+    # @return [Boolean] Whether or not message succeeded
+    def send_message(params = {})
+      send_message!(params)
+    rescue LoginRadius::Exception => e
+      false
+    end
+  end
+end

data/lib/login_radius/user_profile.rb

@@ -0,0 +1,102 @@
+require 'net/http'
+module LoginRadius
+  class UserProfile
+    include UserProfileGetters
+    include Messages
+    
+    attr_accessor :secret, :token, :async
+    
+    API_ROOT = "https://hub.loginradius.com/"
+
+    # Takes a hash of account secret, token, and connection type(net_http or em_http)
+    # and uses it to auth against the LoginRadius API. Then it returns the Account object. The
+    # async key is optional, if set to true, will use Em::HTTP instead of Net::HTTP.
+    # 
+    # @param opts [Hash] Must have keys :token, :secret, and :async(optional)
+    # @return [LoginRadius::Account]
+    def initialize(opts = {})
+      self.token = opts[:token]
+      self.secret = opts[:secret]
+      self.async = opts[:async]
+      raise LoginRadius::Exception.new("Invalid Request") unless token
+      raise LoginRadius::Exception.new("Invalid Token") unless guid_valid?(token)
+      raise LoginRadius::Exception.new("Invalid Secret") unless guid_valid?(secret)
+    end
+
+    # Takes a guid and returns whether or not it is valid.
+    #
+    # @param guid [String]
+    # @return [Boolean]
+    def guid_valid?(guid)
+      guid.match(/^\{?[A-Z0-9]{8}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{4}-[A-Z0-9]{12}\}?$/i)
+    end
+
+    # Returns whether or not this object is authed.
+    #
+    # @return [Boolean]
+    def authenticated?
+      respond_to?(:id)
+    end
+
+    # Generic GET call function that other submodules can use to hit the API.
+    #
+    # @param url [String] Target URL to fetch data from.
+    # @param params [Hash] Parameters to send
+    # @return data [Hash] Parsed JSON data from the call
+    def call_api(url, params = {})
+      url = API_ROOT+url unless url.match(/^#{API_ROOT}/) #in case api root is included,
+      #as would happen in a recursive redirect call.
+      
+      if async
+        #UNTESTED
+        #if async is true, we expect you to be using EM::Synchrony submodule and to be in an eventloop,
+        #like with a thin server using the Cramp framework. Otherwise, this method blows up.
+        response = EM::Synchrony.sync EventMachine::HttpRequest.new(url).aget :redirects => 2, :query => params
+        response = response.response        
+      else
+        #synchronous version of the call.
+        url_obj = URI.parse(url)
+        url_obj.query = URI.encode_www_form(params)
+        
+        http = Net::HTTP.new(url_obj.host, url_obj.port)
+        http.use_ssl = true
+        http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        response = http.get(url_obj.request_uri)
+        
+        if response.is_a?(Net::HTTPTemporaryRedirect)
+          #for some reason, we always get redirected when calling server first time.
+          #so if we do, we scan body for the redirect url, and the scan returns
+          #an array of arrays. So we grab the array we know has what we need,
+          #and grab the first element.
+          redirect_url_array = response.body.scan(/<a href=\"([^>]+)\">/i)[1]
+          redirect_url = redirect_url_array.first
+          return call_api(redirect_url, params) 
+        end
+        
+        response = response.body
+      end
+      
+      # For some reason, this API returns true/false instead of JSON responses for certain calls.
+      # We catch this here.
+      return true if response.match(/^true/i)
+      return false if response.match(/^false/i)
+      
+      #We rescue this because sometimes the API returns HTML pages(which can't be JSON parsed)
+      #This mostly happens when people use expired tokens. So we go ahead and raise an exception
+      #About it if it gets caught.
+      begin
+        unconverted_response = JSON.parse(response)
+        #it's all String keys in CamelCase above, so...
+        # IF we got a hash back, convert it directly, if its an array, convert each item which is a hash
+        # into snake case
+        converted_response = unconverted_response.is_a?(Hash) ?
+                              Hash.lr_convert_hash_keys(unconverted_response).symbolize_keys! : 
+                              unconverted_response.map { |item| Hash.lr_convert_hash_keys(item).symbolize_keys! }
+      
+        return converted_response
+      rescue JSON::ParserError => e
+        raise LoginRadius::Exception.new("A JSON parsing error occured because the API returned an HTML page instead of JSON. This happens mostly when you're using an expired Token. Specifics: #{e.message}")
+      end 
+    end
+  end
+end