spark_api 1.0.0

data/History.txt

@@ -0,0 +1,139 @@
+== v0.7.1 2011-10-13
+* Updated connection dependencies
+* Added messaging model
+* ExpirationDate editable for Listing
+== v0.7.0 2011-10-03
+* Major changes to results object returned from the client (and models). Results are no longer allowed to be nil, and Array is decorated with non result response information.
+* Finished listing photo uploads
+* ListPrice save operation for listings
+* Listing contraints processing
+== v0.6.7 2011-09-02
+* YAML key management
+== v0.6.6 2011-08-30
+* Added methods for returning street, region, and full address for a listing
+== v0.6.5 2011-08-02
+*  Fixed some recursive gemspec issues from jewler by removing jeweler and going with some of our own custom rake tasks.
+== v0.6.4 2011-08-02
+*  added public method for the listing carts service specified
+*  added spec for portal listing cart method
+== v0.6.3 2011-08-02
+*  Fix gemspec error on CLI launch (bundler)
+== v0.6.2 2011-07-29
+*  Added command to make irb sessions rocktastic
+== v0.6.1 2011-07-14
+*  Fixed request headers to match api expectations
+*  OAuth2 grant types redesign
+*  "provided" saved searches
+*  Portal account saving
+== v0.5.9 2011-07-12
+*  Modify Collect to handle FixNums in the case of pagination=count to my/office listings
+== v0.5.8 2011-07-08
+*  Add finders to SharedListing model
+*  fixed log message
+== v0.5.7 2011-07-07
+*  Add /my/contact support
+== v0.5.6 2011-07-07
+*  More build woes.
+== v0.5.5 2011-07-07
+== v0.5.4 2011-07-01
+*  Added the add listing methods to the cart instance.
+*  Added the remove listing methods to the cart instance.
+*  Accounts service by office changes
+== v0.5.3 2011-06-28
+*  API error handling bugfix to log decent messages
+*  Fixed the OAuth flow.
+*  Provide primary image types
+== v0.5.2 2011-06-23
+== v0.5.1 2011-06-03
+*  Upgraded dependencies to latest releases.
+*  Added put / delete functionality.
+*  Make method_missing and respond_to? methods match the expected behavior and add specs to define those behaviors.
+*  Properly escape uri paths when making requests.
+*  SavedSearch resource.
+== v0.4.6 2011-05-13
+*  Added notify option to contacts
+*  Implementation of listing cart resource.
+*  Pass JSON instead of a querystring for the OAuth POST body
+*  API-101 client implementation for sharedlistings service.
+*  Added multiclient support
+*  Change client from sending credentials as request parameters to post data
+== v0.4.5 2011-05-06
+*  Restrict lists larger than 1,000 scroll items
+*  Fixed logging of oauth2 errors, removed redundant access_token from parameters.
+== v0.4.4 2011-05-06
+*  Need to skip spec/reports for CI builds (oops).
+== v0.4.3 2011-05-05
+*  Fixed semi important issue with timeout settings.
+== v0.4.2 2011-05-03
+*  Fixed some nasty session timeout issues that were reported.
+*  Raise proper exceptions for oauth grant errors.
+== v0.4.1 2011-04-11
+*  Removed unnecessary finders from property type model
+*  OAuth2 implementation and general auth redesign
+*  Upgraded ruby version supported.
+*  Add finders to Contact model
+*  Adds an inspect to make debug info easier to read
+*  Standard field support for _expanding and nearby
+== v0.3.9 2011-04-01
+*  Added notes model and specs
+*  Added a primary_logo method to the system info class
+*  Change owner param to arguments hash
+*  Add finders
+== v0.3.8 2011-03-24
+*  Interface change! Remove api user calls that are all over the place.
+*  Fix for empty count response.
+*  Parse date and times for tour
+== v0.3.7 2011-03-11
+*  Fix catch miss.
+*  Added tour of homes model.
+== v0.3.6 2011-03-08
+*  Added account model Also moved finders to a module.
+== v0.3.5 2011-03-08
+*  changing units on API request logging
+== v0.3.4 2011-02-08
+*  Fixed escaping special characters in the client.  This needs to happen after signing.
+== v0.3.3 2011-01-28
+*  Add session features to the api client.
+*  Remove redundant debug log call
+== v0.3.2 2011-01-28
+*  CustomFields class added
+== v0.3.1 2011-01-27
+*  Prep work for rubygems
+*  doc corrections
+== v0.3.0 2011-01-17
+*  Added license for release.
+== v0.2.9 2011-01-12
+*  misc project cleanup
+== v0.2.8 2011-01-10
+*  Fixed client to use http for all requests (except for session auth) by default.  Added :ssl option to enable https for all traffic.
+*  Fixed client connection and resets.
+== v0.2.7 2011-01-10
+*  Build troubles
+== v0.2.6 2011-01-10
+== v0.2.5 2011-01-10
+== v0.2.4 2011-01-10
+== v0.2.3 2011-01-10
+*  Handy startup script picking keys from the environment.
+== v0.2.2 2010-12-29
+*  per_page setting for the client models.
+*  Pagination support for the Spark api client
+*  Added branded? and unbranded? instance methods to Video
+*  Added document model
+*  Added virtual tours model
+*  Added videos model
+*  Contact model and saving
+*  Added `find_by_cart_id' method to Listing model
+*  allow finder to pass thru options
+*  Implemented Listing.find(:all, ...)
+== v0.2.1 2010-12-29
+*  fixed some error code issues.
+*  corrected default endpoint to include the URL scheme
+== v0.2.0 2010-12-27
+*  new gemspec
+*  Session caching 
+*  Major overhaul on the models for code reuse
+*  added Photo.find_by_listing_key
+== v0.1.1 2010-12-23
+*  IDX link and market stat models.
+== v0.1.0 2010-12-13
+* Initial usable release with request interface and models 

data/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2011 Financial Business Systems, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

data/README.md

@@ -0,0 +1,153 @@
+Spark API
+=====================
+A Ruby wrapper for the Spark REST API. Loosely based on ActiveResource to provide models to interact with remote services.
+
+
+Documentation
+-------------
+For full information on the API, see [http://sparkplatform.com/docs/overview/api](http://sparkplatform.com/docs/overview/api)
+
+
+Installation
+---------
+    gem install spark_api
+
+Usage Examples
+------------------------
+
+#### Ruby Script
+    # initialize the gem with your key/secret
+    # api_key and _api_secret are the only required settings
+    # other options and their defaults:
+    #  - endpoint:   'https://api.sparkapi.com'
+    #  - version:    'v1'
+    #  - ssl:         false
+    #  - user_agent: 'Spark API Ruby Gem'
+    SparkApi.configure do |config|
+        config.endpoint   = 'https://developers.sparkapi.com'
+        config.api_key    = 'my_api_key'
+        config.api_secret = 'my_api_secret'
+    end
+
+    # mixin the models so you can use them without prefix
+    include SparkApi::Models
+
+    # Grab your listings!
+    my_listings = Listing.my()
+
+
+#### Interactive Console
+Included in the gem is a simple setup script to run the client in IRB.  To use it, first create the file called _.spark_api_testing_ filling in the credentials for your account.
+
+    API_USER="12345678901234567890123456" # 26-digit identifier of an API user
+    API_ENDPOINT="https://developers.sparkapi.com"
+    API_KEY="my_api_key"
+    API_SECRET="my_api_secret"
+
+    export API_USER API_ENDPOINT API_KEY API_SECRET
+
+Now, to run with this setup, run the following from the command line:
+
+    > source .spark_api_testing
+    > spark_api
+    SparkApi> SparkApi.client.get '/my/account'
+
+You can also provide these options from the command line, see "spark_api -h" for more information
+
+
+Authentication Types
+--------------
+Authentication is handled transparently by the request framework in the gem, so you should never need to manually make an authentication request.  More than one mode of authentication is supported, so the client needs to be configured accordingly.
+
+#### 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_
+
+Error Codes
+---------------------
+<table>
+  <thead>
+    <tr>
+      <th>HTTP Code</th>
+      <th>Spark API Error Code</th>
+      <th>Exception Raised</th>
+      <th>Description</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><tt>401</tt></td>
+      <td><tt>1000</tt></td>
+      <td><tt></tt></td>
+      <td>Invalid API Key and/or Request signed improperly</td>
+    </tr>
+    <tr>
+      <td><tt>401</tt></td>
+      <td><tt>1010</tt></td>
+      <td><tt></tt></td>
+      <td>API key is disabled</td>
+    </tr>
+    <tr>
+      <td><tt>403</tt></td>
+      <td><tt>1015</tt></td>
+      <td><tt></tt></td>
+      <td><tt>ApiUser</tt> must be supplied, or the provided key does not have access to the supplied user</td>
+    </tr>
+    <tr>
+      <td><tt>401</tt></td>
+      <td><tt>1020</tt></td>
+      <td><tt></tt></td>
+      <td>Session token has expired</td>
+    </tr>
+    <tr>
+      <td><tt>403</tt></td>
+      <td><tt>1030</tt></td>
+      <td><tt></tt></td>
+      <td>SSL required for this type of request</td>
+    </tr>
+    <tr>
+      <td><tt>400</tt></td>
+      <td><tt>1035</tt></td>
+      <td><tt></tt></td>
+      <td>POST data not supplied as valid JSON. Issued if the <tt>Content-Type</tt> header is not <tt>application/json/</tt> and/or if the POST data is not in valid JSON format.</td>
+    </tr>
+    <tr>
+      <td><tt>400</tt></td>
+      <td><tt>1040</tt></td>
+      <td><tt></tt></td>
+      <td>The <tt>_filter</tt> syntax was invalid or a specified field to search on does not exist</td>
+    </tr>
+    <tr>
+      <td><tt>400</tt></td>
+      <td><tt>1050</tt></td>
+      <td><tt></tt></td>
+      <td>(message varies) A required parameter was not provided</td>
+    </tr>
+    <tr>
+      <td><tt>400</tt></td>
+      <td><tt>1053</tt></td>
+      <td><tt></tt></td>
+      <td>(message varies) A parameter was provided but does not adhere to constraints</td>
+    </tr>
+    <tr>
+      <td><tt>409</tt></td>
+      <td><tt>1055</tt></td>
+      <td><tt></tt></td>
+      <td>(message varies)Issued when a write is requested that will conflict with existing data. For example, adding a new contact with an e-mail that already exists.</td>
+    </tr>
+    <tr>
+      <td><tt>403</tt></td>
+      <td><tt>1500</tt></td>
+      <td><tt></tt></td>
+      <td>The resource is not available at the current API key's service level. For example, this error applies if a user attempts to access the IDX Links API via a free API key. </td>
+    </tr>
+    <tr>
+      <td><tt>503</tt></td>
+      <td><tt>1550</tt></td>
+      <td><tt></tt></td>
+      <td>Over rate limit</td>
+  </tbody>
+</table>
+

data/Rakefile

@@ -0,0 +1,18 @@
+require "rubygems"
+require 'rubygems/user_interaction'
+require 'flexmls_gems/tasks'
+require 'flexmls_gems/tasks/spec'
+require 'flexmls_gems/tasks/rdoc'
+
+desc "Run all the tests"
+task :default => :spec
+
+desc "Generate (and test) supported Spark API paths and methods"
+RSpec::Core::RakeTask.new(:api_support) do |t|
+  t.rspec_opts = ["--require spec/formatters/api_support_formatter",
+                  "--format ApiSupportFormatter",
+                  "--color",
+                  "--tag support"]
+  t.pattern = 'spec/unit/spark_api/models/**/*_spec.rb'
+  t.verbose = false
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/spark_api

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# File: bin/spark_api
+
+require File.dirname(__FILE__) + '/../lib/spark_api/cli'
+
+SparkApi::CLI::ConsoleCLI.execute(STDOUT, ARGV)
+
+

data/bin/spark_api~

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# File: bin/flexmls_api
+
+require File.dirname(__FILE__) + '/../lib/flexmls_api/cli'
+
+FlexmlsApi::CLI::ConsoleCLI.execute(STDOUT, ARGV)
+
+

data/lib/spark_api.rb

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'json'
+require 'logger'
+
+require 'spark_api/version'
+require 'spark_api/configuration'
+require 'spark_api/multi_client'
+require 'spark_api/authentication'
+require 'spark_api/response'
+require 'spark_api/paginate'
+require 'spark_api/request'
+require 'spark_api/connection'
+require 'spark_api/client'
+require 'spark_api/faraday'
+require 'spark_api/primary_array'
+require 'spark_api/models'
+
+module SparkApi
+  extend Configuration
+  extend MultiClient
+ 
+  #:nocov:
+  def self.logger
+    if @logger.nil?
+      @logger = Logger.new(STDOUT)
+      @logger.level = Logger::INFO
+    end
+    @logger
+  end
+  #:nocov:
+
+  def self.client(opts={})
+    Thread.current[:spark_api_client] ||= SparkApi::Client.new(opts)
+  end
+
+  def self.method_missing(method, *args, &block)
+    return super unless (client.respond_to?(method))
+    client.send(method, *args, &block)
+  end
+  
+  def self.reset
+    reset_configuration
+    Thread.current[:spark_api_client] = nil
+  end
+
+end

data/lib/spark_api/authentication.rb

@@ -0,0 +1,55 @@
+
+require 'openssl'
+require 'faraday'
+require 'faraday_middleware'
+require 'yajl'
+require 'date'
+
+require 'spark_api/authentication/base_auth'
+require 'spark_api/authentication/api_auth'
+require 'spark_api/authentication/oauth2'
+
+module SparkApi
+  # =Authentication
+  # Mixin module for handling client authentication and reauthentication to the spark api.  Makes 
+  # use of the configured authentication mode (API Auth by default).
+  module Authentication
+
+    # Main authentication step.  Run before any api request unless the user session exists and is 
+    # still valid.
+    #
+    # *returns*
+    #   The user session object when authentication succeeds
+    # *raises*
+    #   SparkApi::ClientError when authentication fails
+    def authenticate
+      start_time = Time.now
+      request_time = Time.now - start_time
+      new_session = @authenticator.authenticate
+      SparkApi.logger.info("[#{(request_time * 1000).to_i}ms]")
+      SparkApi.logger.debug("Session: #{new_session.inspect}")
+      new_session
+    end
+
+    # Test to see if there is an active session
+    def authenticated?
+      @authenticator.authenticated?
+    end
+    
+    # Delete the current session
+    def logout
+      SparkApi.logger.info("Logging out.")
+      @authenticator.logout
+    end
+
+    # Fetch the active session object
+    def session
+      @authenticator.session
+    end
+    # Save the active session object
+    def session=(active_session)
+      @authenticator.session=active_session
+    end
+ 
+  end
+end