spark_api 1.2.1 → 1.3.0

data/History.txt

@@ -1,3 +1,15 @@
+== v1.3.0 2013-01-08
+* yajl is no longer a dependency. To use it, make sure the gem is installed.
+* JRuby support finalized
+* Increased default OAuthSession timeout to 12 hours
+* New API Support:
+  * field ordering service
+  * attaching/detaching contacts to saved searches, 
+  * agent portal administration
+  * contact commenting
+  * contact export, export all
+  * contact vow accounts
+  * activity stream retrieval
 == v1.2.0 2012-11-14
 * SSL verification enabled by default
 * Sparkbar token access support

data/README.md

@@ -1,5 +1,7 @@
 Spark API
 =====================
+[![Build Status](https://secure.travis-ci.org/sparkapi/spark_api.png)](http://travis-ci.org/sparkapi/spark_api) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/sparkapi/spark_api)
+
 A Ruby wrapper for the Spark REST API. Loosely based on ActiveResource to provide models to interact with remote services.
 
 
@@ -65,6 +67,11 @@ The client also provides ActiveModelesque interface for working with the api res
     # Top list price: $199999.99
     puts Account.find(:first, :_filter => "UserType Eq 'Member' And Name Eq 'John*'").Name
     # John Doe
+    
+
+JSON Parsing
+--------------
+By default, this gem uses the pure ruby json gem for parsing API responses for cross platform compatibility. Projects that include the yajl-ruby gem will see noticeable speed improvements when installed.
 
 
 Authentication Types

data/Rakefile

@@ -1,4 +1,5 @@
 require "rubygems"
+
 require 'rubygems/user_interaction'
 require 'flexmls_gems/tasks'
 require 'flexmls_gems/tasks/spec'

data/VERSION

@@ -1 +1 @@
-1.2.1
+1.3.0

data/lib/spark_api/authentication.rb

@@ -1,7 +1,4 @@
 
-require 'openssl'
-require 'faraday'
-require 'yajl'
 require 'date'
 
 require 'spark_api/authentication/base_auth'

data/lib/spark_api/authentication/oauth2.rb

@@ -159,7 +159,7 @@ module SparkApi
         @scope = options["scope"]
         @refresh_token = options["refresh_token"]
         @start_time = options.fetch("start_time", DateTime.now)
-        @refresh_timeout = options.fetch("refresh_timeout",3600)
+        @refresh_timeout = options.fetch("refresh_timeout", 43200)
         if @start_time.is_a? String
           @start_time = DateTime.parse(@start_time)
         end

data/lib/spark_api/configuration.rb

@@ -1,7 +1,12 @@
 module SparkApi
   module Configuration
 
-    MultiJson.engine = "yajl"
+    begin
+      require 'yajl'
+      MultiJson.engine = "yajl"
+    rescue LoadError => e
+      # Using pure ruby JSON parser
+    end
     
     # valid configuration options
     VALID_OPTION_KEYS = [:api_key, :api_secret, :api_user, :endpoint, 

data/lib/spark_api/models.rb

@@ -6,10 +6,13 @@ require 'spark_api/models/subresource'
 require 'spark_api/models/concerns'
 
 require 'spark_api/models/account'
+require 'spark_api/models/activity'
 require 'spark_api/models/connect_prefs'
 require 'spark_api/models/contact'
+require 'spark_api/models/comment'
 require 'spark_api/models/custom_fields'
 require 'spark_api/models/document'
+require 'spark_api/models/fields'
 require 'spark_api/models/idx_link'
 require 'spark_api/models/listing'
 require 'spark_api/models/listing_cart'
@@ -19,7 +22,9 @@ require 'spark_api/models/note'
 require 'spark_api/models/notification'
 require 'spark_api/models/open_house'
 require 'spark_api/models/photo'
+require 'spark_api/models/portal'
 require 'spark_api/models/property_types'
+require 'spark_api/models/rental_calendar'
 require 'spark_api/models/saved_search'
 require 'spark_api/models/shared_listing'
 require 'spark_api/models/standard_fields'
@@ -27,8 +32,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'
-require 'spark_api/models/subscription'
+require 'spark_api/models/vow_account'
 
 module SparkApi
   module Models

data/lib/spark_api/models/activity.rb

@@ -0,0 +1,10 @@
+module SparkApi
+  module Models
+
+    class Activity < Base
+      extend Finders
+      self.element_name = "activities"
+    end
+
+  end
+end

data/lib/spark_api/models/base.rb

@@ -7,14 +7,13 @@ module SparkApi
       extend Paginate
       include Dirty
 
-      attr_accessor :attributes, :errors
+      attr_accessor :attributes, :errors, :parent
 
       # Name of the resource as related to the path name
       def self.element_name
         # TODO I'd love to pull in active model at this point to provide default naming
         @element_name ||= "resource"
       end
-
       def self.element_name=(name)
         @element_name = name
       end
@@ -26,9 +25,25 @@ module SparkApi
       def self.prefix=(prefix)
         @prefix = prefix
       end
+
+      def resource_uri
+        self.ResourceUri.sub(/^\/#{SparkApi.client.version}/, "") if persisted?
+      end
+
       def self.path
         "#{prefix}#{element_name}"
       end
+      def path
+        if self.persisted?
+          resource_uri.sub(/\/[0-9]{26}$/, "")
+        else
+          if @parent
+            "#{@parent.class.path}/#{@parent.Id}#{self.class.path}"
+          else
+            self.class.path
+          end
+        end
+      end
 
       def self.connection
         SparkApi.client
@@ -61,6 +76,11 @@ module SparkApi
         connection.get(path, options.merge({:_pagination=>"count"}))
       end
 
+      # update/create hash (can be overridden)
+      def post_data
+        { resource_pluralized => [ attributes ] }
+      end
+
       def method_missing(method_symbol, *arguments)
         method_name = method_symbol.to_s
 
@@ -82,7 +102,7 @@ module SparkApi
         end
       end
 
-      def respond_to?(method_symbol, include_private=false)
+      def respond_to?(method_symbol)
         if super
           return true
         else
@@ -105,8 +125,8 @@ module SparkApi
         uri[/\/.*\/(.+)$/, 1]
       end
 
-      def persisted?
-        !(@attributes['Id'].nil? && @attributes['ResourceUri'].nil?)
+      def persisted?;
+        !@attributes['Id'].nil? && !@attributes['ResourceUri'].nil?
       end
 
       protected

data/lib/spark_api/models/comment.rb

@@ -0,0 +1,9 @@
+module SparkApi
+  module Models
+    class Comment < Base
+      include Concerns::Savable,
+              Concerns::Destroyable
+      self.element_name = "comments"
+    end
+  end
+end

data/lib/spark_api/models/concerns/destroyable.rb

@@ -17,7 +17,7 @@ module SparkApi
           false
         end
         def destroy!(arguments = {})
-          connection.delete("#{self.class.path}/#{self.Id}", arguments)
+          connection.delete(resource_uri, arguments) if persisted?
           @destroyed = true
           true
         end

data/lib/spark_api/models/concerns/savable.rb

@@ -21,10 +21,7 @@ module SparkApi
         end
 
         def create!(arguments = {})
-          results = connection.post self.class.path, {
-            resource_pluralized => [ attributes ]
-          }.merge(params_for_save), arguments
-
+          results = connection.post self.path, post_data.merge(params_for_save), arguments
           update_resource_identifiers(results.first)
           reset_dirty
           params_for_save.clear
@@ -32,8 +29,8 @@ module SparkApi
         end
 
         def update!(arguments = {})
-          return true unless changed?
-          connection.put "#{self.class.path}/#{self.Id}", dirty_attributes, arguments
+          return true unless changed? && persisted?
+          connection.put resource_uri, dirty_attributes, arguments
           reset_dirty
           params_for_save.clear
           true

data/lib/spark_api/models/contact.rb

@@ -6,7 +6,7 @@ module SparkApi
               Concerns::Destroyable
 
       self.element_name="contacts"
-      
+
       def self.by_tag(tag_name, arguments={})
         collect(connection.get("#{path}/tags/#{tag_name}", arguments))
       end
@@ -19,11 +19,48 @@ module SparkApi
         new(connection.get('/my/contact', arguments).first)
       end
             
+      def self.export(arguments={})
+        collect(connection.get("/contacts/export", arguments))
+      end
+
+      def self.export_all(arguments={})
+        collect(connection.get("/contacts/export/all", arguments))
+      end
+
       # Notify the agent of contact creation via a Spark notification.
       def notify?; params_for_save[:Notify] == true end
       def notify=(notify_me)
         params_for_save[:Notify] = notify_me
       end
+
+      def saved_searches(arguments = {})
+        @saved_searches ||= SavedSearch.collect(connection.get("/contacts/#{self.Id}/savedsearches", arguments))
+      end
+
+      def listing_carts(arguments = {})
+        @listing_carts ||= ListingCart.collect(connection.get("/contacts/#{self.Id}/listingcarts", arguments))
+      end
+
+      def comments(arguments = {})
+        @comments ||= Comment.collect(connection.get("/contacts/#{self.Id}/comments", arguments))
+      end
+      def comment(body)
+        comment = Comment.new({ :Comment => body })
+        comment.parent = self
+        comment.save
+        comment
+      end
+
+      def vow_account(arguments={})
+        return @vow_account if @vow_account
+        begin
+          @vow_account = VowAccount.new(connection.get("/contacts/#{self.Id}/portal", arguments).first)
+          @vow_account.parent = self
+          @vow_account
+        rescue NotFound
+          nil
+        end
+      end
       
     end
   end

data/lib/spark_api/models/dirty.rb

@@ -25,7 +25,7 @@ module SparkApi
 
       # hash with changed attributes and their new values
       def dirty_attributes
-        changed.inject({}) { |h, k| h[k] = attributes[k]; h }
+        changed.inject({}) { |h, k| h[k] = attributes[k.to_s]; h }
       end
 
       private

data/lib/spark_api/models/fields.rb

@@ -0,0 +1,12 @@
+module SparkApi
+  module Models
+    class Fields < Base
+      self.element_name="fields"
+
+      def self.order(property_type=nil, arguments={})
+        connection.get("#{self.path}/order#{"/"+property_type unless property_type.nil?}", arguments)
+      end
+
+    end
+  end
+end

data/lib/spark_api/models/listing_cart.rb

@@ -2,6 +2,9 @@ module SparkApi
   module Models
     class ListingCart < Base 
       extend Finders
+      include Concerns::Savable,
+              Concerns::Destroyable
+
       self.element_name="listingcarts"
 
       def ListingIds=(listing_ids)
@@ -10,19 +13,19 @@ module SparkApi
       def Name=(name)
         attributes["Name"] = name
       end
-      
+
       def add_listing(listing)
         id = listing.respond_to?(:Id) ? listing.Id : listing.to_s
         results = connection.post("#{self.class.path}/#{self.Id}", {"ListingIds" => [ listing ]})
         self.ListingCount = results.first["ListingCount"]
       end
-      
+
       def remove_listing(listing)
         id = listing.respond_to?(:Id) ? listing.Id : listing.to_s
         results = connection.delete("#{self.class.path}/#{self.Id}/listings/#{id}")
         self.ListingCount = results.first["ListingCount"]
       end
-      
+
       def self.for(listings,arguments={})
         keys = Array(listings).map { |l| l.respond_to?(:Id) ? l.Id : l.to_s }
         collect(connection.get("/#{self.element_name}/for/#{keys.join(",")}", arguments))
@@ -35,37 +38,6 @@ module SparkApi
       def self.portal(arguments={})
           collect(connection.get("/#{self.element_name}/portal", arguments))
       end
-      
-      def save(arguments={})
-        begin
-          return save!(arguments)
-        rescue BadResourceRequest => e
-        rescue NotFound => e
-          # log and leave
-          SparkApi.logger.error("Failed to save contact #{self}: #{e.message}")
-        end
-        false
-      end
-      def save!(arguments={})
-        attributes['Id'].nil? ? create!(arguments) : update!(arguments)
-      end
-      
-      def delete(args={})
-        connection.delete("#{self.class.path}/#{self.Id}", args)
-      end
-      
-      private 
-      def create!(arguments={})
-        results = connection.post self.class.path, {"ListingCarts" => [ attributes ]}, arguments
-        result = results.first
-        attributes['ResourceUri'] = result['ResourceUri']
-        attributes['Id'] = parse_id(result['ResourceUri'])
-        true
-      end
-      def update!(arguments={})
-        results = connection.put "#{self.class.path}/#{self.Id}", {"ListingCarts" => [ {"ListingIds" => attributes["ListingIds"],"Name" => attributes["Name"]} ] }, arguments
-        true
-      end
 
     end
   end

data/lib/spark_api/models/portal.rb

@@ -0,0 +1,37 @@
+module SparkApi
+  module Models
+
+    class Portal < Base
+      extend Finders
+      include Concerns::Savable
+
+      self.element_name = "portal"
+
+      def self.my(arguments = {})
+        portal = collect(connection.get("/portal", arguments)).first
+        portal = Portal.new if portal.nil?
+        portal
+      end
+
+      def enabled?
+        @attributes['Enabled'] == true
+      end
+
+      def enable
+        attribute_will_change! "Enabled"
+        @attributes['Enabled'] = true
+        save
+      end
+
+      def disable
+        attribute_will_change! "Enabled"
+        @attributes['Enabled'] = false
+        save
+      end
+
+      def post_data; attributes end
+
+    end
+
+  end
+end

data/lib/spark_api/models/saved_search.rb

@@ -16,10 +16,46 @@ module SparkApi
         end
       end
 
+      # list contacts (private role)
+      def contacts
+        return [] unless persisted?
+        results = connection.get("#{self.class.path}/#{@attributes["Id"]}")
+        @attributes['ContactIds'] = results.first['ContactIds']
+      end
+
+      # attach/detach contact (private role)
+      [:attach, :detach].each do |action|
+        method = (action == :attach ? :put : :delete)
+        define_method(action) do |contact|
+          return false unless persisted?
+          self.errors = []
+          contact_id = contact.is_a?(Contact) ? contact.Id : contact
+          begin
+            connection.send(method, "#{self.class.path}/#{@attributes["Id"]}/contacts/#{contact_id}")
+          rescue BadResourceRequest, NotFound => e
+            self.errors << { :code => e.code, :message => e.message }
+            SparkApi.logger.error("Failed to #{action} contact #{contact}: #{e.message}")
+            return false
+          end
+          update_contacts(action, contact_id)
+          true
+        end
+      end
+
       private
 
       def resource_pluralized; "SavedSearches" end
 
+      def update_contacts(method, contact_id)
+        @attributes['ContactIds'] = [] if @attributes['ContactIds'].nil?
+        case method
+        when :attach
+          @attributes['ContactIds'] << contact_id
+        when :detach
+          @attributes['ContactIds'].delete contact_id
+        end
+      end
+
     end
 
   end