spark_api 1.0.2 → 1.0.4

data/README.md

@@ -15,13 +15,56 @@ Installation
 Usage Examples
 ------------------------
 
+#### Ruby Script: OpenId/OAuth2 Combined Flow
+    # initialize the gem with your key/secret.
+    # See also: script/combined_flow_example.rb
+    # api_key, api_secret, and callback are all required.
+    # The following options are required:
+    #  - api_key: Your client key
+    #  - api_secret: Your client secret
+    #  - callback: Your 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::OpenIdOAuth2Hybrid
+      config.api_key      = "YOUR_CLIENT_ID"
+      config.api_secret   = "YOUR_CLIENT_SECRET"
+      config.callback     = "YOUR_REDIRECT_URI"
+      config.auth_endpoint = "https://developers.sparkplatform.com/openid"
+      config.endpoint   = 'https://developers.sparkapi.com'
+    end
+
+    # Code is retrieved from the method: SparkApi.client.authenticator.authorization_url
+    # See script/combined_flow_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: 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
+    #  - 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
@@ -40,7 +83,7 @@ Usage Examples
       config.endpoint   = 'https://developers.sparkapi.com'
     end
 
-    # Code is retrieved from the method. client.authenticator.authorization_url
+    # Code is retrieved from the method. SparkApi.client.authenticator.authorization_url
     # See script/oauth2_example.rb for more details.
 
 
@@ -58,6 +101,36 @@ Usage Examples
     # Grab your listings!
     my_listings = Listing.my()
 
+
+#### Ruby Script: OpenId Only
+    # initialize the gem with your key/secret.
+    # api_key, api_secret, and callback are all required.
+    # The following options are required:
+    #  - api_key: Your client key
+    #  - api_secret: Your client secret
+    #  - callback: Your 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:
+    #  - user_agent: 'Spark API Ruby Gem'
+    SparkApi.configure do |config|
+      config.authentication_mode = SparkApi::Authentication::OpenId
+      config.api_key      = "YOUR_CLIENT_ID"
+      config.api_secret   = "YOUR_CLIENT_SECRET"
+      config.callback     = "YOUR_REDIRECT_URI"
+      config.auth_endpoint = "https://developers.sparkplatform.com/openid"
+    end
+
+    # Code is retrieved from the method: 
+    # See script/combined_flow_example.rb for more details.
+    # Optionally, additional a GET parameters can be supplied as a hash to
+    # authorization_url.
+    # SparkApi.client.authenticator.authorization_url
+
+    # That's it! No API Access is available when using OpenID alone.
+
+
 #### Ruby Script
     # initialize the gem with your key/secret
     # api_key and _api_secret are the only required settings
@@ -105,11 +178,21 @@ 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 Authorization (Preferred)
+#### OpenId/OAuth2 Combined Flow (Preferred)
+Authorization mode the separates application and user authentication.  This mode requires the end user to be redirected to Spark Platform's openid endpoint.  See "script/combined_flow_example.rb" for an example.
+
+Read more about Spark Platform's combined flow <a href="http://sparkplatform.com/docs/authentication/openid_oauth2_authentication">here</a>.
+
+#### OAuth2 Authorization
 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>.
 
+#### OpenId Authentication
+There is also the option to only access a user's Spark Platform identity without accessing any data (e.g. listings, contacts, etc.).  In circumstances where you ONLY with to authenticate users through the Spark Platform, but do not have a use case to access any of their data, consider the OpenId authentication flow in lieu of API Authentication or the Combined flow.
+
+Read more about Spark Platform's OpenId flow <a href="http://sparkplatform.com/docs/authentication/openid_authentication">here</a>.
+
 Error Codes
 ---------------------
 <table>

data/VERSION

@@ -1 +1 @@
-1.0.2
+1.0.4

data/lib/spark_api.rb

@@ -13,6 +13,7 @@ require 'spark_api/connection'
 require 'spark_api/client'
 require 'spark_api/faraday'
 require 'spark_api/primary_array'
+require 'spark_api/options_hash'
 require 'spark_api/models'
 
 module SparkApi

data/lib/spark_api/authentication/oauth2.rb

@@ -67,7 +67,6 @@ module SparkApi
         }
         "#{@provider.authorization_uri}?#{build_url_parameters(params)}"
       end
-
             
       protected
       
@@ -83,12 +82,54 @@ module SparkApi
       end
 
     end
+
+    #==OpenId/OAuth 2 Hybrid
+    # Uses OpenId for Authentication, but also uses OAuth2 for authorization.
+    class OpenIdOAuth2Hybrid < OAuth2
+      def authorization_url(parameters={})
+        params = openid_parameters.merge(parameters)
+        params["openid.spark.combined_flow"] = true
+        build_openid_uri(params)
+      end
+
+      protected
+
+      def build_openid_uri(params)
+        "#{@provider.authorization_uri}?#{build_url_parameters(params)}"
+      end
+
+      def openid_parameters
+        {
+          "openid.mode" => "checkid_setup",
+          "openid.spark.client_id" => @provider.client_id,
+          "openid.return_to" => @provider.redirect_uri
+        }
+      end
+    end
+
+    class OpenId < OpenIdOAuth2Hybrid
+      def authorization_url(parameters={})
+        params = openid_parameters.merge(parameters)
+        build_openid_uri(params)
+      end
+
+      def authenticate
+        raise RuntimeError, "API Authorization not available with an OpenId-only Auth instance"
+      end
+      
+      def request(method, path, body, options={})
+        raise RuntimeError, "API Data not available with an OpenId-only Auth instance"
+      end
+    end
     
     # Representation of a session with the api using oauth2
     class OAuthSession
       SESSION_ATTRIBUTES = [:access_token, :expires_in, :scope, :refresh_token, :refresh_timeout, :start_time]
       attr_accessor *SESSION_ATTRIBUTES
-      def initialize(options={})
+      def initialize(o={})
+
+        options = OptionsHash.new(o)
+
         @access_token = options["access_token"]
         @expires_in = options["expires_in"]
         @scope = options["scope"]

data/lib/spark_api/configuration/oauth2_configurable.rb

@@ -2,7 +2,9 @@ module SparkApi
   module Configuration
     module OAuth2Configurable
       def convert_to_oauth2?
-        self.authentication_mode == SparkApi::Authentication::OAuth2 &&
+        (self.authentication_mode == SparkApi::Authentication::OAuth2 ||
+         self.authentication_mode == SparkApi::Authentication::OpenId ||
+         self.authentication_mode == SparkApi::Authentication::OpenIdOAuth2Hybrid) &&
           self.oauth2_provider.nil? 
       end
 

data/lib/spark_api/models.rb

@@ -25,6 +25,7 @@ require 'spark_api/models/system_info'
 require 'spark_api/models/tour_of_home'
 require 'spark_api/models/video'
 require 'spark_api/models/virtual_tour'
+require 'spark_api/models/rental_calendar'
 
 module SparkApi
   module Models

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, :open_houses, :tour_of_homes
+      attr_accessor :photos, :videos, :virtual_tours, :documents, :open_houses, :tour_of_homes, :rental_calendars
       attr_accessor :constraints
       self.element_name="listings"
       DATA_MASK = "********"
@@ -12,6 +12,7 @@ module SparkApi
         @photos = []
         @videos = []
         @virtual_tours = []
+        @rental_calendars = []
         @documents = []
         @constraints = []
         #@tour_of_homes = []
@@ -20,6 +21,10 @@ module SparkApi
           pics, vids, tours, docs, ohouses, tourhomes = attributes['StandardFields'].values_at('Photos','Videos', 'VirtualTours', 'Documents', 'OpenHouses', 'TourOfHomes')
         end
         
+        if attributes.has_key?('RentalCalendar')
+          rentalcalendars = attributes['RentalCalendar']
+        end
+        
         if pics != nil
           pics.collect { |pic| @photos.push(Photo.new(pic)) } 
           attributes['StandardFields'].delete('Photos')
@@ -52,6 +57,11 @@ module SparkApi
           attributes['StandardFields'].delete('TourOfHomes')
         end
         
+        if rentalcalendars != nil
+          rentalcalendars.collect { |rentalcalendar| @rental_calendars.push(RentalCalendar.new(rentalcalendar)) }
+          attributes.delete('RentalCalendar')
+        end        
+        
         super(attributes)
       end
 
@@ -82,6 +92,12 @@ module SparkApi
         return @tour_of_homes unless @tour_of_homes.nil?
       end
 
+      def rental_calendars(arguments={})
+        @rental_calendars ||= RentalCalendar.find_by_listing_key(self.Id, arguments)
+        return @rental_calendars unless @rental_calendars.nil?
+      end
+
+
       def open_houses(arguments={})
         @open_houses ||= OpenHouse.find_by_listing_key(self.Id, arguments)
         return @open_houses unless @open_houses.nil?

data/lib/spark_api/models/rental_calendar.rb

@@ -0,0 +1,26 @@
+module SparkApi
+  module Models
+    class RentalCalendar < Base
+      extend Subresource
+      self.element_name="rentalcalendar"
+
+      def initialize(attributes={})
+        # Transform the date strings
+        unless attributes['StartDate'].nil?
+          date = Date.parse(attributes['StartDate'])
+          attributes['StartDate'] = date
+        end
+        unless attributes['EndDate'].nil?
+          date = Date.parse(attributes['EndDate'])
+          attributes['EndDate'] = date
+        end        
+        super(attributes)
+      end
+
+      def include_date? (day)
+        day >= self.StartDate && day <= self.EndDate
+      end
+
+    end
+  end
+end

data/lib/spark_api/options_hash.rb

@@ -0,0 +1,18 @@
+module SparkApi
+  # Used for API client options that accept string keys instead of symbols -- 
+  # turns all symbol keys into a string for consistancy, allowing applications
+  # using the client to pass in parameters as symbols or strings.
+  class OptionsHash < Hash 
+    def initialize(from_hash={})
+      from_hash.keys.each do |k|
+        if k.is_a?(Symbol)
+          self[k.to_s] = from_hash[k] 
+        else
+          self[k] = from_hash[k] 
+        end
+      end
+      self
+    end
+  end
+end
+    

data/script/combined_flow_example.rb

@@ -0,0 +1,55 @@
+#!/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::OpenIdOAuth2Hybrid
+  config.api_key      = "YOUR_CLIENT_ID"
+  config.api_secret   = "YOUR_CLIENT_SECRET"
+  config.callback     = "YOUR_REDIRECT_URI"
+  config.auth_endpoint = "https://developers.sparkplatform.com/openid"
+  config.endpoint   = 'https://developers.sparkapi.com'
+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 3: Comment out Step 2, 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 2a and 3a: 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/script/oauth2_example.rb

@@ -38,13 +38,13 @@ puts "Go here and log in to get your code: #{client.authenticator.authorization_
 #puts "Access Token: #{client.session.access_token}, Refresh Token: #{client.session.refresh_token}"
 
 
-# Step 4: Comment out Step 3, and uncomment the following.
+# Step 3: Comment out Step 2, 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.
+# Step 2a and 3a: Uncomment with Step 2 and 3.
 #                 Make requests for authorized listing data
 #list = client.get '/contacts'
 #puts "client: #{list.inspect}"

data/spec/fixtures/listings/rental_calendar.json

@@ -0,0 +1,19 @@
+{
+    "D": {
+        "Results": [
+            {
+                "EndDate": "2012-07-16",
+                "Id": "20120705192139246257000000",
+                "StartDate": "2012-07-12",
+                "Type": "Rented" 
+            },
+            {
+                "EndDate": "2012-07-23",
+                "Id": "20120705192148668143000000",
+                "StartDate": "2012-07-20",
+                "Type": "Rented"
+            }
+        ],
+        "Success": true
+    }
+}

data/spec/fixtures/listings/with_rental_calendar.json

@@ -0,0 +1,52 @@
+{
+    "D": {
+        "Results": [
+            {
+                "ResourceUri": "/v1/listings/20060813163018826257000000",
+                "StandardFields": {
+                    "StreetNumber": "2755",
+                    "Longitude": "-116.7506",
+                    "City": "Hayden",
+                    "ListingId": "06-10376",
+                    "PublicRemarks": "Incredible horse estate in Hayden. Over 14 acres with panoramic views. Cape Cod style residence, 4500+ sq ft w/4 bdrms, 4.5 baths. 82x60 horse barn, heated with hayloft & lg guest house. 70x160 indoor horse arean, heated, viewing area boasts large river rock fireplace & bbq area. The Ultimate in luxury living!",
+                    "BuildingAreaTotal": "5400.0",
+                    "YearBuilt": 1996,
+                    "StreetName": "SPRING ROCK LN",
+                    "ListPrice": "2950000.0",
+                    "PostalCode": "83835",
+                    "Latitude": "47.7959",
+                    "BathsThreeQuarter": null,
+                    "BathsFull": null,
+                    "BathsTotal": "4.5",
+                    "StateOrProvince": "ID",
+                    "PropertyType": "A",
+                    "StreetAdditionalInfo": null,
+                    "StreetDirPrefix": "E",
+                    "BedsTotal": 4,
+                    "StreetDirSuffix": null,
+                    "ListingKey": "20060813163018826257000000",
+                    "ListOfficeName": "Coldwell Banker Schneidmiller Realty",
+                    "BathsHalf": null,
+                    "ModificationTimestamp": "2010-11-22T20:52:54Z",
+                    "CountyOrParish": "Kootenai"
+                },
+                "Id": "20060813163018826257000000",
+                "RentalCalendar": [
+                  {
+                      "EndDate": "2012-07-16",
+                      "Id": "20120705192139246257000000",
+                      "StartDate": "2012-07-12",
+                      "Type": "Rented" 
+                  },
+                  {
+                      "EndDate": "2012-07-23",
+                      "Id": "20120705192148668143000000",
+                      "StartDate": "2012-07-20",
+                      "Type": "Rented"
+                  }
+                ]
+            }
+        ],
+        "Success": true
+    }
+}