spark_api 1.0.1 → 1.0.2

data/README.md

@@ -15,6 +15,49 @@ Installation
 Usage Examples
 ------------------------
 
+#### Ruby Script: OAuth 2
+    # initialize the gem with your OAuth 2 key/secret.
+    # See also: script/oauth2_example.rb
+    # api_key, api_secret, and callback are all required.
+    # The following options are required:
+    #  - api_key: Your OAuth 2 client key
+    #  - api-secret: Your OAuth 2 client secret
+    #  - callback: Your OAuth 2 redirect_uri, which the end user will be redirected
+    #              to after authorizing your application to access their data.
+    #  - auth_endpoint: The URI to redirect the user's web browser to, in order for them to
+    #                   authorize your application to access their data.
+    # other options and their defaults:
+    #  - endpoint:   'https://api.sparkapi.com'
+    #  - version:    'v1'
+    #  - ssl:        true
+    #  - user_agent: 'Spark API Ruby Gem'
+    SparkApi.configure do |config|
+      config.authentication_mode = SparkApi::Authentication::OAuth2
+      config.api_key      = "YOUR_CLIENT_ID"
+      config.api_secret   = "YOUR_CLIENT_SECRET"
+      config.callback     = "YOUR_REDIRECT_URI"
+      config.auth_endpoint = "https://developers.sparkplatform.com/oauth2"
+      config.endpoint   = 'https://developers.sparkapi.com'
+    end
+
+    # Code is retrieved from the method. client.authenticator.authorization_url
+    # See script/oauth2_example.rb for more details.
+
+
+    SparkApi.client.oauth2_provider.code = "CODE_FROM_ABOVE_URI"
+    SparkApi.client.authenticate
+
+    # Alternatively, if you've already received an access token, you may
+    # do the following instead of the above two lines:
+    #SparkApi.client.session = SparkApi::Authentication::OAuthSession.new "access_token"=> "ACCESS_TOKEN", 
+    #                           "refresh_token" => "REFRESH_TOKEN", "expires_in" => 86400
+
+    # mixin the models so you can use them without prefix
+    include SparkApi::Models
+
+    # Grab your listings!
+    my_listings = Listing.my()
+
 #### Ruby Script
     # initialize the gem with your key/secret
     # api_key and _api_secret are the only required settings
@@ -62,8 +105,10 @@ Authentication is handled transparently by the request framework in the gem, so
 #### API Authentication (Default)
 Usually supplied for a single user, this authentication mode is the simplest, and is setup as the default.  The example usage above demonstrates how to get started using this authentication mode.
 
-#### OAuth2 Authentication
-Authentication mode the separates application and user authentication.  This mode requires further setup which is described in _lib/spark_api/authentication/oauth2.rb_
+#### OAuth2 Authorization (Preferred)
+Authorization mode the separates application and user authentication.  This mode requires the end user to be redirected to Spark Platform's auth endpoint.  See "script/oauth2_example.rb" for an example.
+
+Read more about Spark Platform's OAuth 2 flow <a href="http://sparkplatform.com/docs/authentication/oauth2_authentication">here</a>.
 
 Error Codes
 ---------------------

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.0.2

data/lib/spark_api/authentication/oauth2.rb

@@ -182,6 +182,7 @@ module SparkApi
       require 'spark_api/authentication/oauth2_impl/grant_type_code'
       require 'spark_api/authentication/oauth2_impl/grant_type_password'
       require 'spark_api/authentication/oauth2_impl/password_provider'
+      require 'spark_api/authentication/oauth2_impl/simple_provider'
       
       # Loads a provider class from a string
       def self.load_provider(string, args={})

data/lib/spark_api/authentication/oauth2_impl/simple_provider.rb

@@ -0,0 +1,22 @@
+module SparkApi
+  module Authentication
+    class SimpleProvider < BaseOAuth2Provider
+      def initialize(credentials)
+        super(credentials)
+        @grant_type = :authorization_code
+      end
+
+      def load_session
+        @session
+      end 
+
+      def save_session session
+        @session = session
+      end 
+
+      def destroy_session
+        @session = nil 
+      end 
+    end
+  end
+end

data/lib/spark_api/client.rb

@@ -7,6 +7,9 @@ module SparkApi
     include Connection
     include Authentication
     include Request
+
+    require File.expand_path('../configuration/oauth2_configurable', __FILE__)
+    include Configuration::OAuth2Configurable
     
     attr_accessor :authenticator
     attr_accessor *Configuration::VALID_OPTION_KEYS

data/lib/spark_api/configuration/oauth2_configurable.rb

@@ -0,0 +1,30 @@
+module SparkApi
+  module Configuration
+    module OAuth2Configurable
+      def convert_to_oauth2?
+        self.authentication_mode == SparkApi::Authentication::OAuth2 &&
+          self.oauth2_provider.nil? 
+      end
+
+      def oauth2_enabled?
+        self.authentication_mode == SparkApi::Authentication::OAuth2
+      end
+
+      def oauthify!
+        self.oauth2_provider = SparkApi::Authentication::SimpleProvider.new(
+          :access_uri    => grant_uri,
+          :client_id     => self.api_key,
+          :client_secret => self.api_secret,
+          :authorization_uri => self.auth_endpoint,
+          :redirect_uri  => self.callback
+        )
+      end
+
+      def grant_uri
+        e = self.endpoint.gsub(/\/+$/,"")
+        v = self.version.gsub(/\/+/,"/")
+        "#{e}/#{v}/oauth2/grant"
+      end
+    end
+  end
+end

data/lib/spark_api/configuration.rb

@@ -2,7 +2,9 @@ module SparkApi
   module Configuration
     
     # valid configuration options
-    VALID_OPTION_KEYS = [:api_key, :api_secret, :api_user, :endpoint, :user_agent, :version, :ssl, :oauth2_provider, :authentication_mode].freeze
+    VALID_OPTION_KEYS = [:api_key, :api_secret, :api_user, :endpoint, 
+      :user_agent, :version, :ssl, :oauth2_provider, :authentication_mode, 
+      :auth_endpoint, :callback].freeze
     OAUTH2_KEYS = [:authorization_uri, :access_uri, :client_id, :client_secret,
       # Requirements for authorization_code grant type
       :redirect_uri,  
@@ -11,11 +13,15 @@ module SparkApi
     ]
       
     require File.expand_path('../configuration/yaml', __FILE__)
+    require File.expand_path('../configuration/oauth2_configurable', __FILE__)
+
+    include OAuth2Configurable
     
     DEFAULT_API_KEY = nil
     DEFAULT_API_SECRET = nil
     DEFAULT_API_USER = nil
     DEFAULT_ENDPOINT = 'https://api.sparkapi.com'
+    DEFAULT_AUTH_ENDPOINT = 'https://sparkplatform.com/openid'  # Ignored for Spark API Auth
     DEFAULT_VERSION = 'v1'
     DEFAULT_USER_AGENT = "Spark API Ruby Gem #{VERSION}"
     DEFAULT_SSL = true
@@ -25,7 +31,8 @@ module SparkApi
 
     attr_accessor *VALID_OPTION_KEYS
     def configure
-      yield self
+      yield(self)
+      oauthify! if convert_to_oauth2?
     end
 
     def self.extended(base)
@@ -43,6 +50,7 @@ module SparkApi
       self.api_secret  = DEFAULT_API_SECRET
       self.api_user    = DEFAULT_API_USER
       self.authentication_mode = SparkApi::Authentication::ApiAuth
+      self.auth_endpoint  = DEFAULT_AUTH_ENDPOINT
       self.endpoint    = DEFAULT_ENDPOINT
       self.oauth2_provider = DEFAULT_OAUTH2
       self.user_agent  = DEFAULT_USER_AGENT

data/lib/spark_api/models/listing.rb

@@ -2,7 +2,7 @@ module SparkApi
   module Models
     class Listing < Base 
       extend Finders
-      attr_accessor :photos, :videos, :virtual_tours, :documents
+      attr_accessor :photos, :videos, :virtual_tours, :documents, :open_houses, :tour_of_homes
       attr_accessor :constraints
       self.element_name="listings"
       DATA_MASK = "********"
@@ -14,9 +14,10 @@ module SparkApi
         @virtual_tours = []
         @documents = []
         @constraints = []
+        #@tour_of_homes = []
         
         if attributes.has_key?('StandardFields')
-          pics, vids, tours, docs = attributes['StandardFields'].values_at('Photos','Videos', 'VirtualTours', 'Documents')
+          pics, vids, tours, docs, ohouses, tourhomes = attributes['StandardFields'].values_at('Photos','Videos', 'VirtualTours', 'Documents', 'OpenHouses', 'TourOfHomes')
         end
         
         if pics != nil
@@ -39,6 +40,18 @@ module SparkApi
           attributes['StandardFields'].delete('Documents')
         end
         
+        if ohouses != nil
+          @open_houses = []
+          ohouses.collect { |ohouse| @open_houses.push(OpenHouse.new(ohouse)) }
+          attributes['StandardFields'].delete('OpenHouses')
+        end
+        
+        if tourhomes != nil
+          @tour_of_homes = []
+          tourhomes.collect { |tourhome| @tour_of_homes.push(TourOfHome.new(tourhome)) }
+          attributes['StandardFields'].delete('TourOfHomes')
+        end
+        
         super(attributes)
       end
 
@@ -60,18 +73,18 @@ module SparkApi
       end
       
       def self.nearby(latitude, longitude, arguments={})
-        nearby_args = {:Lat => latitude, :Lon => longitude}.merge(arguments)
+        nearby_args = {:_lat => latitude, :_lon => longitude}.merge(arguments)
         collect(connection.get("/listings/nearby", nearby_args))
       end
       
       def tour_of_homes(arguments={})
+        @tour_of_homes ||= TourOfHome.find_by_listing_key(self.Id, arguments)
         return @tour_of_homes unless @tour_of_homes.nil?
-        @tour_of_homes = TourOfHome.find_by_listing_key(self.Id, arguments)
       end
 
       def open_houses(arguments={})
+        @open_houses ||= OpenHouse.find_by_listing_key(self.Id, arguments)
         return @open_houses unless @open_houses.nil?
-        @open_houses = OpenHouse.find_by_listing_key(self.Id, arguments)
       end
       
       def my_notes

data/lib/spark_api/models/open_house.rb

@@ -16,6 +16,11 @@ module SparkApi
           attributes['StartTime'] = Time.parse("#{date}T#{attributes['StartTime']}") unless attributes['StartTime'].nil?
           attributes['EndTime'] = Time.parse("#{date}T#{attributes['EndTime']}") unless attributes['EndTime'].nil?
         end
+        
+        if attributes["Comments"].nil?
+          attributes["Comments"] = ""
+        end
+        
         super(attributes)
       end
       

data/script/oauth2_example.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+require "rubygems"
+
+Bundler.require(:default, "development") if defined?(Bundler)
+
+path = File.expand_path(File.dirname(__FILE__) + "/../lib/")
+$LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
+require path + '/spark_api'
+
+SparkApi.logger.info("Hello!")
+
+SparkApi.configure do |config|
+  config.authentication_mode = SparkApi::Authentication::OAuth2
+  config.api_key      = "YOUR_CLIENT_ID"
+  config.api_secret   = "YOUR_CLIENT_SECRET"
+  config.callback     = "YOUR_REDIRECT_URI"
+  config.version      = "v1"
+  config.endpoint     = "https://developers.sparkapi.com"
+  config.auth_endpoint = "https://developers.sparkplatform.com/oauth2"
+end
+
+client = SparkApi.client
+
+
+# Step 1:
+# To get your code to post to /v1/oauth2/grant, send the end user to this URI, replacing the all-capped strings with
+# the CGI-escaped credentials for your key:
+# https://developers.sparkplatform.com/oauth2?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI
+# When the user has finished, they will land at:
+# YOUR_REDIRECT_URI?code=CODE.
+puts "Go here and log in to get your code: #{client.authenticator.authorization_url}"
+
+# Step 2: Uncomment the following, and add your code in place of CODE_FROM_ABOVE_URI
+#         Hold on to the tokens.  Unless you lose them, you can now pass in these 
+#         values until the access_token expires.
+#client.oauth2_provider.code = "CODE_FROM_ABOVE_URI"
+#client.authenticate
+#puts "Access Token: #{client.session.access_token}, Refresh Token: #{client.session.refresh_token}"
+
+
+# Step 4: Comment out Step 3, and uncomment the following.
+#         Pass in your access_token and refresh_token to make authenticated requests to the API
+#client.session = SparkApi::Authentication::OAuthSession.new "access_token"=> "ACCESS_TOKEN", 
+#                    "refresh_token" => "REFRESH_TOKEN", "expires_in" => 86400
+
+
+# Step 3a and 4a: Uncomment with Step 3 and 4.
+#                 Make requests for authorized listing data
+#list = client.get '/contacts'
+#puts "client: #{list.inspect}"
+#list = SparkApi::Models::Contact.get
+#puts "model: #{list.inspect}"
+
+
+
+

data/spec/unit/spark_api/configuration_spec.rb

@@ -10,6 +10,7 @@ describe SparkApi::Client, "Client config"  do
       SparkApi.api_key.should be_nil
       SparkApi.api_secret.should be_nil
       SparkApi.version.should match("v1")
+      SparkApi.auth_endpoint.should match("sparkplatform.com/openid")
       SparkApi.endpoint.should match("api.sparkapi.com")
       SparkApi.user_agent.should match(/Spark API Ruby Gem .*/)
       SparkApi.api_key = "my_api_key"
@@ -20,18 +21,53 @@ describe SparkApi::Client, "Client config"  do
   describe "instance config" do
     it "should return a properly configured client" do
       client = SparkApi::Client.new(:api_key => "key_of_wade", 
-                                      :api_secret => "TopSecret", 
-                                      :api_user => "1234",
-                                      :endpoint => "http://api.wade.dev.fbsdata.com")
+                                    :api_secret => "TopSecret", 
+                                    :api_user => "1234",
+                                    :auth_endpoint => "https://login.wade.dev.fbsdata.com",
+                                    :endpoint => "http://api.wade.dev.fbsdata.com")
  
       client.api_key.should match("key_of_wade")
       client.api_secret.should match("TopSecret")
       client.api_user.should match("1234")
+      client.auth_endpoint.should match("https://login.wade.dev.fbsdata.com")
       client.endpoint.should match("http://api.wade.dev.fbsdata.com")
       client.version.should match("v1")
     end
   end
 
+  describe "oauth2 instance configuration" do
+    let(:oauth2_client) do
+      SparkApi::Client.new(:api_key => "key_of_wade", 
+                           :api_secret => "TopSecret", 
+                           :callback => "http://wade.dev.fbsdata.com/callback",
+                           :auth_endpoint => "https://login.wade.dev.fbsdata.com",
+                           :endpoint => "http://api.wade.dev.fbsdata.com",
+                           :authentication_mode => SparkApi::Authentication::OAuth2)
+    end
+
+    it "should convert the configuration to oauth2 when specified" do
+      oauth2_client.oauthify!
+      oauth2_client.oauth2_provider.should be_a(SparkApi::Authentication::SimpleProvider)
+    end
+
+    it "should say oauth2_enabled? when it is" do
+      oauth2_client.oauth2_enabled?().should be_true
+    end
+
+    it "should say oauth2_enabled? is false" do
+      client = SparkApi::Client.new(:api_key => "key_of_wade", 
+                                    :api_secret => "TopSecret", 
+                                    :callback => "http://wade.dev.fbsdata.com/callback",
+                                    :auth_endpoint => "https://login.wade.dev.fbsdata.com",
+                                    :endpoint => "http://api.wade.dev.fbsdata.com")
+      client.oauth2_enabled?().should be_false
+    end
+
+    it "should properly build a grant_uri from the endpoint" do
+      oauth2_client.grant_uri.should eq("http://api.wade.dev.fbsdata.com/v1/oauth2/grant")
+    end
+  end
+
   describe "block config" do
     it "should correctly set up the client" do
       SparkApi.configure do |config|
@@ -49,7 +85,20 @@ describe SparkApi::Client, "Client config"  do
       SparkApi.version.should match("veleventy")
       SparkApi.endpoint.should match("test.api.sparkapi.com")
       SparkApi.user_agent.should match("my useragent")
+      SparkApi.oauth2_enabled?().should be_false
+    end
 
+    it "should correctly set up the client for oauth2" do
+      SparkApi.configure do |config|
+        config.api_key = "my_key"
+        config.api_secret = "my_secret"
+        config.callback = "http://wade.dev.fbsdata.com/callback",
+        config.auth_endpoint = "https://login.wade.dev.fbsdata.com",
+        config.endpoint = "test.api.sparkapi.com"
+        config.user_agent = "my useragent"
+        config.authentication_mode = SparkApi::Authentication::OAuth2
+      end
+      SparkApi.oauth2_enabled?().should be_true
     end
     
     it "should reset" do

data/spec/unit/spark_api/models/listing_spec.rb

@@ -44,6 +44,13 @@ describe Listing do
           "Uri1280"=>"http=>//devresize.flexmls.com/fgo/1280x1024/true/20101115201631519737000000-o.jpg",
           "UriThumb"=>"http=>//images.dev.fbsdata.com/fgo/20101115201631519737000000-t.jpg",
           "Uri640"=>"http=>//devresize.flexmls.com/fgo/640x480/true/20101115201631519737000000-o.jpg"
+        }],
+        "OpenHouses" => [{
+          'ResourceUri'=>"/v1/listings/20060412165917817933000000/openhouses/20101127153422574618000000",
+          'Id'=>"20060412165917817933000000",
+          'Date'=>"10/01/2010",
+          'StartTime'=>"09:00:00-07:00",
+          'EndTime'=>"12:00:00-07:00"
         }]
       },
       "Id"=>"20080619000032866372000000"
@@ -250,17 +257,18 @@ describe Listing do
           l.photos.length.should == 0
           l.documents.length.should == 0
         end
-
-        on_get_it "should return tour of homes" do
-          stub_api_get("/listings/20060725224713296297000000", 'listings/no_subresources.json')
-          stub_api_get("/listings/20060725224713296297000000/tourofhomes", 'listings/tour_of_homes.json')
-
-          l = Listing.find('20060725224713296297000000')
-          l.tour_of_homes().length.should == 2
-          l.videos.length.should == 0
-          l.photos.length.should == 0
-          l.documents.length.should == 0
-        end
+        
+        ## TourOfHomes: Not implemented yet ##
+        #on_get_it "should return tour of homes" do
+          #stub_api_get("/listings/20060725224713296297000000", 'listings/no_subresources.json')
+          #stub_api_get("/listings/20060725224713296297000000/tourofhomes", 'listings/tour_of_homes.json')
+
+          #l = Listing.find('20060725224713296297000000')
+          #l.tour_of_homes().length.should == 2
+          #l.videos.length.should == 0
+          #l.photos.length.should == 0
+          #l.documents.length.should == 0
+        #end
 
         on_get_it "should return permissions" do
           stub_api_get("/listings/20060725224713296297000000", 'listings/with_permissions.json', { :_expand => "Permissions" })
@@ -306,7 +314,7 @@ describe Listing do
     context "/listings/nearby", :support do
       on_get_it "should return nearby homes" do
         stub_api_get("/listings/nearby",
-                     'listings/no_subresources.json', {:Lat => "45.45", :Lon => "-93.98"})
+                     'listings/no_subresources.json', {:_lat => "45.45", :_lon => "-93.98"})
         l = Listing.nearby(45.45, -93.98)
         l.length.should == 1
       end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: spark_api
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 19
   prerelease: 
   segments: 
   - 1
   - 0
-  - 1
-  version: 1.0.1
+  - 2
+  version: 1.0.2
 platform: ruby
 authors: 
 - Brandon Hornseth
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-04-30 00:00:00 Z
+date: 2012-07-11 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   version_requirements: &id001 !ruby/object:Gem::Requirement 
@@ -195,22 +195,14 @@ dependencies:
   version_requirements: &id011 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - "="
       - !ruby/object:Gem::Version 
-        hash: 11
+        hash: 1
         segments: 
         - 1
         - 7
-        - 0
-        version: 1.7.0
-    - - <
-      - !ruby/object:Gem::Version 
-        hash: 55
-        segments: 
-        - 1
-        - 8
-        - 0
-        version: 1.8.0
+        - 5
+        version: 1.7.5
   requirement: *id011
   prerelease: false
   name: webmock
@@ -307,6 +299,7 @@ files:
 - lib/spark_api/authentication/oauth2_impl/grant_type_code.rb
 - lib/spark_api/authentication/oauth2_impl/grant_type_code.rb~
 - lib/spark_api/authentication/oauth2_impl/grant_type_refresh.rb
+- lib/spark_api/authentication/oauth2_impl/simple_provider.rb
 - lib/spark_api/authentication/oauth2_impl/grant_type_password.rb~
 - lib/spark_api/authentication/oauth2_impl/grant_type_password.rb
 - lib/spark_api/authentication/oauth2_impl/grant_type_refresh.rb~
@@ -396,12 +389,14 @@ files:
 - lib/spark_api/configuration.rb~
 - lib/spark_api/configuration.rb
 - lib/spark_api/configuration/yaml.rb~
+- lib/spark_api/configuration/oauth2_configurable.rb
 - lib/spark_api/configuration/yaml.rb
 - lib/spark_api.rb
 - script/console~
 - script/console
 - script/example.rb
 - script/example.rb~
+- script/oauth2_example.rb
 - spec/fixtures/oauth2_error.json
 - spec/fixtures/errors/failure_with_constraint.json
 - spec/fixtures/errors/expired.json