hash-blue 0.1 → 0.2

data/Gemfile

@@ -3,8 +3,6 @@ source "http://rubygems.org"
 # Specify your gem's dependencies in hash-blue.gemspec
 gemspec
 
-gem 'json'
-
 group :development, :test do
   gem 'rspec'
 end

data/README.md

@@ -1,8 +1,8 @@
-O2 Labs has exposed the power of #blue to developers via a simple REST & JSON based API, combined with oAuth2 to developers who can create  new ways for users to manage their texts and add combine the ubiquity of SMS with their applications, users simply grant an application access to their messages stream or just certain messages.
+O2 Labs has exposed the power of \#blue to developers via a simple REST & JSON based API, combined with oAuth2 to developers who can create  new ways for users to manage their texts and add combine the ubiquity of SMS with their applications, users simply grant an application access to their messages stream or just certain messages.
 
-_#_blue is not a service designed for users to text into applications rather it is aimed at enriching the users existing text experience by building on top of their day to day text use.
+\#blue is not a service designed for users to text into applications rather it is aimed at enriching the users existing text experience by building on top of their day to day text use.
 
-This gem provides a smooth access to _#_blue API.
+This gem provides a smooth access to \#blue API.
 
 # How to install
 
@@ -10,30 +10,63 @@ This gem provides a smooth access to _#_blue API.
 
 # Getting started
 
-There're three main entities in _#_blue:
+There're three main entities in \#blue:
 
 *   message: models a SMS sent/received by the user
 *   contact: friend's list including phone number, name and email address.
 *   account: describes the user account
 
-_#_blue client design is based on ActiveRecord model.
+\#blue client design is based on ActiveRecord model.
 
-## Retrieve a valid user token
+## Retrieve a valid user token using OAuth 2.0
 
-_#_blue API is based on oAuth secure mechanism so before using the API the user must grant permissions to your application. Follow the instructions on [the HashBlue documentation](https://api.hashblue.com/doc/Authentication)
+\#blue API is based on oAuth secure mechanism so before using the API the user must grant permissions to your application. Follow the instructions on [the HashBlue documentation](https://api.hashblue.com/doc/Authentication)
 
-### First step. Redirect user to HashBlue authorization page
+You can either use the Rails Engine or create your own logic.
+
+### Use the embedded Rails Engine
+
+* Insert in your rails application Gemfile the dependency hash-blue
+    gem 'hash-blue'
+
+* Two new endpoints are created (check running ''bundle install'' and ''rake routes''):
+    
+    \# this method redirects to hashblue web page to start the oAuth process
+    
+    /hashblue/index 
+    \# this method gets the Oauth response, asks for a valid access token and sends the data
+    
+    /hashblue/code
+
+* Configure in an application initializer your specific data (i.e. config/initializer/hashblue.rb)
+
+    Rails.application.config.hashblue.client_id = <app_client_id>
+    Rails.application.config.hashblue.client_secret = <app_client_secret>
+    \# Internal redirection to handle the HashBlue response. You'll receive a GET request to that action
+    \# after OAuth mechanism with user access token info: :access_token, :expires_in, :refresh_token 
+	Rails.application.config.hashblue.forward_action = <controller#action>
+	
+### Create the logic to handle the OAuth mechanism
+
+#### First step. Redirect user to HashBlue authorization page
 
     redirect_to "https://hashblue.com/oauth/authorize?client_id=<app_client_id>&redirect_uri=<your_callback_url>"
 
-### Second step. Get access token
+#### Second step. Get access token
 
     uri = URI.parse("https://hashblue.com")
     rest = Net::HTTP.new(uri.host, uri.port)
     rest.use_ssl = true
     code = <code_from_first_step>
 
-    query = "client_id=<app_client_id>&client_secret=<app_client_secret>&grant_type=authorization_code&code=#{code}&redirect_uri=<your_callback_url>"
+    params = {
+	    :client_id => <app_client_id>,
+	    :client_secret => <app_client_secret>,
+	    :grant_type => <authorization_code>,
+	    :code => code,
+	    :redirect_uri => <your_callback_url>
+    }
+    query = params.collect { |k, v| "#{k}=#{v.to_s}" }.join("&")) 
     access_token = rest.post( "/oauth/access_token?#{query}", nil)
 
 ## Configure the client with a valid access token
@@ -50,6 +83,18 @@ _#_blue API is based on oAuth secure mechanism so before using the API the user
 ### Retrieve a specific message
 
 	message = HashBlue::Message.find(<valid_message_id>)
+	
+### Retrieve the first message
+
+   message = HashBlue::Message.find(:first)
+
+### Retrieve messages since January 14th, 2011
+
+    messages = HashBlue::Message.find({:since => "2011-01-14T14:30Z")
+
+### Retrieve messages from 20 to 25
+
+    messages = HashBlue::Message.find({:first => 20, :count => 5)
 
 ### Retrieve a contact messages
 
@@ -93,6 +138,17 @@ _#_blue API is based on oAuth secure mechanism so before using the API the user
 
 	HashBlue::Account.find
 
+# Version 0.2 features
+
+- Rails Engine: includes OAuth 2.0 support
+- Message filtering: enables :first, {:since => date}, {:first => index, :count => number}
+
+# TODO
+- Enhance pagination mechanism for messages and contacts
+- Search by time: test the date format. Support both a string and a Date/Time with valid ISO 8601 format
+- Check q parameter in searches
+- Use ActiveSupport instead of json_pure
+
 # Author
 
 Juan de Bravo

data/app/controllers/hashblue_controller.rb

@@ -0,0 +1,91 @@
+require 'oauth/signature/hmac/sha1'
+require 'oauth/client/helper'
+require 'net/https'
+
+#
+# O2 Labs has exposed the power of #blue to developers via a simple REST & JSON based API, 
+# enabling new ways for users to manage their texts and add combine the ubiquity of SMS 
+# with their applications, users simply grant an application access to their messages stream 
+# or just certain messages.
+#
+# Juan de Bravo (juandebravo@gmail.com)
+# Ruby sensei at The Lab (http://thelab.o2.com)
+#
+
+class HashblueController < ApplicationController
+
+  # parameters required in both OAuth steps
+  DEFAULT_PARAMS = {
+    :client_id => Rails.application.config.hashblue.client_id    
+  }
+  
+  # OAuth step1: redirect to HashBlue endpoint with the application idenfitifer and the redirect uri
+  def index
+    hb_params = {
+      :redirect_uri => redirect_uri
+    }
+    hb_params.merge!(DEFAULT_PARAMS)
+    
+    redirect_to "#{endpoint}/oauth/authorize?".concat(hb_params.collect { |k, v| "#{k}=#{v.to_s}" }.join("&"))
+  end
+
+  # OAuth step2: retrieve the code from HashBlue, ask for a valid access token and
+  # forward to the user defined uri
+  def code
+    # This code is retrieved from HashBlue
+    code = params[:code]
+
+    hb_params = {
+      :redirect_uri => redirect_uri,
+      :client_secret => Rails.application.config.hashblue.client_secret,
+      :grant_type => "authorization_code",
+      :code => code
+    }
+    hb_params.merge!(DEFAULT_PARAMS)
+
+    response = rest.post( "/oauth/access_token?".concat(hb_params.collect { |k, v| "#{k}=#{v.to_s}" }.join("&")), nil)
+    
+    if response.code.eql?("200")
+      response = ActiveSupport::JSON.decode(response.body)
+
+      if response.has_key?("access_token")
+        Rails.application.config.hashblue.forward_action.nil? and raise RuntimeError, "Invalid forward_action value"
+        
+        url = Rails.application.config.hashblue.forward_action.split("#")
+        url.length == 2 or raise RuntimeError, "Invalid forward_action value"
+        redirect_to ({
+          :controller => url.first,
+          :action => url.last,
+          :access_token => response["access_token"],
+          :expires_in => response["expires_in"],
+          :refresh_token => response["refresh_token"]
+          })
+      elsif response.has_key?("error")
+        logger.error "Error while accessing to HashBlue #{response['error']}"
+        raise RuntimeError, response['error']
+      end
+    else
+      logger.error "Error #{response.code} while accessing to HashBlue #{response.body}"
+      raise RuntimeError, "Unable to access to hashblue"
+    end
+  end
+  
+  # rest client to HashBlue endpoint
+  def rest
+    @@rest ||= (uri = URI.parse(endpoint)
+    rest = Net::HTTP.new(uri.host, uri.port)
+    rest.use_ssl = true
+    rest)
+  end
+  
+  # HashBlue endpoint
+  def endpoint
+    Rails.application.config.hashblue.uri
+  end
+  
+  def redirect_uri
+    "#{request.protocol}#{request.host_with_port}/hashblue/code"
+  end
+  
+  
+end

data/config/routes.rb

@@ -0,0 +1,8 @@
+
+Rails.application.routes.draw do |map|
+
+  get "hashblue/index"
+  
+  get "hashblue/code"
+
+end

data/hash-blue.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Juan de Bravo"]
   s.email       = ["juandebravo@gmail.com"]
-  s.homepage    = "https://api.hashblue.com/doc/"
+  s.homepage    = "https://github.com/juandebravo/hash-blue"
   s.summary     = %q{This gem provides a smooth access to _#_blue API.}
   s.description = %q{O2 Labs has exposed the power of #blue to developers via a 
     simple REST & JSON based API, combined with oAuth2 to developers who can 
@@ -25,4 +25,6 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
+  s.add_dependency("json_pure" , ">= 1.4.3")
+  
 end

data/lib/hash-blue.rb

@@ -3,6 +3,8 @@ require 'hash_blue/contact'
 require 'hash_blue/message'
 require 'hash_blue/account'
 
+require 'hash_blue/engine' if defined?(Rails)
+
 #
 # O2 Labs has exposed the power of #blue to developers via a simple REST & JSON based API, 
 # enabling new ways for users to manage their texts and add combine the ubiquity of SMS 

data/lib/hash_blue/engine.rb

@@ -0,0 +1,49 @@
+require 'rails'
+require 'hash_blue/engine_config'
+
+#
+# O2 Labs has exposed the power of #blue to developers via a simple REST & JSON based API, 
+# enabling new ways for users to manage their texts and add combine the ubiquity of SMS 
+# with their applications, users simply grant an application access to their messages stream 
+# or just certain messages.
+#
+# Juan de Bravo (juandebravo@gmail.com)
+# Ruby sensei at The Lab (http://thelab.o2.com)
+#
+
+module HashBlue
+  #
+  # This class defines the HashBlue Rails Engine to handle OAuth authentication.
+  # The Engine defines two new routes to handle each of the OAuth steps
+  # 1.- forward the user request to HashBlue server
+  # 2.- get the oauth code, request a valid access token and forward the token info to a user defined action
+  #
+  # How to configure HashBlue Engine
+  #
+  # :uri => HashBlue API endpoint 
+  # :client_id => token that identifies your application in OAuth mechanism
+  # :client_secret => token that secures your communication in OAuth mechanism
+  # :forward_action => controller#action where hashblue#code action will redirect the user token data:
+  #           - :access_token
+  #           - :expires_in
+  #           - :refresh_token
+  #
+  # These configuration can be included in an application initializer, i.e. config/initializers/hashblue.rb
+  #
+  #      Rails.application.config.hashblue.client_id = "<client_id>"
+  #      Rails.application.config.hashblue.client_secret = "<client_secret"
+  #      Rails.application.config.hashblue.forward_action = "controller#action" that will receive the user token data
+  #
+  
+  class Engine < Rails::Engine
+    
+    # we need to create the hashblue config hash before loading the application initializer
+    initializer :hashblue, {:before => :load_config_initializers} do |app|
+
+      app.config.hashblue = HashBlue::EngineConfig.new
+      # HashBlue API endpoint
+      app.config.hashblue.uri = "https://hashblue.com"
+    end
+    
+  end
+end

data/lib/hash_blue/engine_config.rb

@@ -0,0 +1,18 @@
+#
+# O2 Labs has exposed the power of #blue to developers via a simple REST & JSON based API, 
+# enabling new ways for users to manage their texts and add combine the ubiquity of SMS 
+# with their applications, users simply grant an application access to their messages stream 
+# or just certain messages.
+#
+# Juan de Bravo (juandebravo@gmail.com)
+# Ruby sensei at The Lab (http://thelab.o2.com)
+#
+
+module HashBlue
+  # Array of elements that should be configured
+  # By default, :uri endpoint is configured in the Engine. The rest of parameters are client specific
+  hashblue_config = [:uri, :client_id, :client_secret, :forward_action]
+
+  class EngineConfig  < Struct.new(*hashblue_config)
+  end
+end

data/lib/hash_blue/message.rb

@@ -83,6 +83,10 @@ module HashBlue
       # @param arg:
       # =>  nil => retrieve all messages
       # =>  :all => retrieve all messages
+      # =>  :first => retrieve the first message
+      # => {:since => ISO 8601 format} => retrieve messages since the 
+      #                                   specified data (i.e. 2011-01-14T14:30Z)
+      # => {:first => index, :count => count} => retrieve count messages from index first
       # =>  {:contact => <contact_id>} => retrieve a specific contact messages
       # =>  id => retrieve a specific message using a valid unique identifier
       
@@ -92,14 +96,26 @@ module HashBlue
         elsif arg.is_a? Symbol
           if arg.eql?(:all)
             messages = get "/messages"
+          elsif arg.eql?(:first)
+            messages = get "/messages?per_page=1"
           else
             raise ArgumentError, "Invalid argument #{arg}"
           end
         elsif arg.is_a? String or arg.is_a? Fixnum
           messages = get "/messages/#{arg}"
         elsif arg.is_a? Hash
-          arg.has_key?(:contact) or raise ArgumentError, "Invalid argument #{arg}"
-          messages = get "/contacts/#{arg[:contact]}/messages"
+          if arg.has_key?(:contact)
+            messages = get "/contacts/#{arg[:contact]}/messages"
+          elsif arg.has_key?(:since)
+            arg[:since].is_a?(String) or arg[:since].is_a?
+            messages = get "/messages?since=#{arg[:since]}"
+          elsif arg.has_key?(:first)
+            messages = get "/messages?page=2&per_page=#{arg[:first]}"
+          else
+            raise ArgumentError, "Invalid argument #{arg}"
+          end
+        else
+          raise ArgumentError, "Invalid argument #{arg}"
         end
         parse_response(messages)
       end

data/lib/hash_blue/version.rb

@@ -9,5 +9,5 @@
 #
 
 module HashBlue
-  VERSION = "0.1"
+  VERSION = "0.2"
 end

data/spec/account_spec.rb

@@ -2,7 +2,6 @@ $:.unshift File.join(File.dirname(__FILE__),'..','lib')
 
 require 'hash-blue'
 require 'webmock/rspec'
-require 'json'
 
 describe HashBlue::Account  do
   before(:all) do

data/spec/contact_spec.rb

@@ -2,7 +2,6 @@ $:.unshift File.join(File.dirname(__FILE__),'..','lib')
 
 require 'hash-blue'
 require 'webmock/rspec'
-require 'json'
 
 describe HashBlue::Contact  do
   before(:all) do

data/spec/message_spec.rb

@@ -2,7 +2,6 @@ $:.unshift File.join(File.dirname(__FILE__),'..','lib')
 
 require 'hash-blue'
 require 'webmock/rspec'
-require 'json'
 
 describe HashBlue::Message  do
   before(:all) do
@@ -28,6 +27,60 @@ describe HashBlue::Message  do
       message.contact.email.should eql("mike@foo.com")
     end
   end
+  
+  context "find messages" do
+    it "should return a list of messages" do
+      stub_request(:get, "https://api.hashblue.com/messages").
+               with(:headers => {'Accept'=>'*/*', 'Authorization'=>'OAuth XXXXX'}).
+               to_return(:status => 200, :body => '{"messages":[{"uri":"https://api.hashblue.com/messages/foo","timestamp":"2011-05-09T21:43:52Z","sent":true,"contact":{"name":"Mike","uri":"https://api.hashblue.com/contacts/mike","messages":"https://api.hashblue.com/contacts/mike/messages","phone_number":"07711223344","msisdn":"447711223344","email":"mike@foo.com"},"content":"test","favourite":false}, {"uri":"https://api.hashblue.com/messages/bar","timestamp":"2011-05-09T21:43:52Z","sent":true,"contact":{"name":"Mike","uri":"https://api.hashblue.com/contacts/mike","messages":"https://api.hashblue.com/contacts/mike/messages","phone_number":"07711223344","msisdn":"447711223344","email":"mike@foo.com"},"content":"this is another test","favourite":true}]}', :headers => {})      
+
+      message = HashBlue::Message.find()
+      message.should be_an_instance_of(Array)
+      message.should respond_to(:length)
+      message.length.should eql(2)
+      message[0].should be_an_instance_of(HashBlue::Message)
+      message[1].should be_an_instance_of(HashBlue::Message)
+    end
+
+    it "should return the first message when paramter is :first" do
+      stub_request(:get, "https://api.hashblue.com/messages?per_page=1").
+               with(:headers => {'Accept'=>'*/*', 'Authorization'=>'OAuth XXXXX'}).
+               to_return(:status => 200, :body => '{"messages":[{"uri":"https://api.hashblue.com/messages/foo","timestamp":"2011-05-09T21:43:52Z","sent":true,"contact":{"name":"Mike","uri":"https://api.hashblue.com/contacts/mike","messages":"https://api.hashblue.com/contacts/mike/messages","phone_number":"07711223344","msisdn":"447711223344","email":"mike@foo.com"},"content":"test","favourite":false}]}', :headers => {})      
+
+      message = HashBlue::Message.find(:first)
+      message.should be_an_instance_of(Array)
+      message.should respond_to(:length)
+      message.length.should eql(1)
+      message[0].should be_an_instance_of(HashBlue::Message)
+    end
+    
+    it "should request messages since a specific date when parameter :since defined" do
+      date = "2011-01-14T14:30Z"
+      stub_request(:get, "https://api.hashblue.com/messages?since=#{date}").
+               with(:headers => {'Accept'=>'*/*', 'Authorization'=>'OAuth XXXXX'}).
+               to_return(:status => 200, :body => '{"messages":[{"uri":"https://api.hashblue.com/messages/foo","timestamp":"2011-05-09T21:43:52Z","sent":true,"contact":{"name":"Mike","uri":"https://api.hashblue.com/contacts/mike","messages":"https://api.hashblue.com/contacts/mike/messages","phone_number":"07711223344","msisdn":"447711223344","email":"mike@foo.com"},"content":"test","favourite":false}]}', :headers => {})      
+
+      message = HashBlue::Message.find({:since => date})
+      message.should be_an_instance_of(Array)
+      message.should respond_to(:length)
+      message.length.should eql(1)
+      message[0].should be_an_instance_of(HashBlue::Message)
+    end
+
+    it "should request messages since a specific index when parameter {:first} defined" do
+      first = 15
+      stub_request(:get, "https://api.hashblue.com/messages?page=2&per_page=#{first}").
+               with(:headers => {'Accept'=>'*/*', 'Authorization'=>'OAuth XXXXX'}).
+               to_return(:status => 200, :body => '{"messages":[{"uri":"https://api.hashblue.com/messages/foo","timestamp":"2011-05-09T21:43:52Z","sent":true,"contact":{"name":"Mike","uri":"https://api.hashblue.com/contacts/mike","messages":"https://api.hashblue.com/contacts/mike/messages","phone_number":"07711223344","msisdn":"447711223344","email":"mike@foo.com"},"content":"test","favourite":false}]}', :headers => {})      
+
+      message = HashBlue::Message.find({:first => first})
+      message.should be_an_instance_of(Array)
+      message.should respond_to(:length)
+      message.length.should eql(1)
+      message[0].should be_an_instance_of(HashBlue::Message)
+    end
+
+  end
 
   context "create a new message" do
     it "should create a message successfully when phone_number and content provided" do

metadata

@@ -2,7 +2,7 @@
 name: hash-blue
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: "0.1"
+  version: "0.2"
 platform: ruby
 authors: 
 - Juan de Bravo
@@ -10,10 +10,20 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-10 00:00:00 +02:00
+date: 2011-06-16 00:00:00 +03:00
 default_executable: 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json_pure
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.4.3
+  type: :runtime
+  version_requirements: *id001
 description: |-
   O2 Labs has exposed the power of #blue to developers via a 
       simple REST & JSON based API, combined with oAuth2 to developers who can 
@@ -33,18 +43,22 @@ files:
 - LICENSE.LGPLv3
 - README.md
 - Rakefile
+- app/controllers/hashblue_controller.rb
+- config/routes.rb
 - hash-blue.gemspec
 - lib/hash-blue.rb
 - lib/hash_blue/account.rb
 - lib/hash_blue/client.rb
 - lib/hash_blue/contact.rb
+- lib/hash_blue/engine.rb
+- lib/hash_blue/engine_config.rb
 - lib/hash_blue/message.rb
 - lib/hash_blue/version.rb
 - spec/account_spec.rb
 - spec/contact_spec.rb
 - spec/message_spec.rb
 has_rdoc: true
-homepage: https://api.hashblue.com/doc/
+homepage: https://github.com/juandebravo/hash-blue
 licenses: []
 
 post_install_message: