flexmls_api 0.3.2

data/Gemfile

@@ -0,0 +1,20 @@
+source :rubygems
+
+gem 'faraday'
+gem 'curb'
+gem 'faraday_middleware'
+gem 'multi_json'
+gem 'json'
+gem 'yajl-ruby'
+gem 'builder', '2.1.2'
+
+gem 'will_paginate', '~> 3.0.pre2'
+
+group :test do
+  gem 'rspec'
+  gem 'webmock'
+  gem 'jeweler'
+  gem 'typhoeus' 
+  gem 'ci_reporter', '>=1.6.3'
+  gem 'rcov'
+end

data/Gemfile.lock

@@ -0,0 +1,60 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    addressable (2.2.2)
+    builder (2.1.2)
+    ci_reporter (1.6.3)
+      builder (>= 2.1.2)
+    crack (0.1.8)
+    curb (0.7.8)
+    diff-lcs (1.1.2)
+    faraday (0.5.3)
+      addressable (~> 2.2.2)
+      multipart-post (~> 1.0.1)
+      rack (>= 1.1.0, < 2)
+    faraday_middleware (0.3.1)
+      faraday (~> 0.5.3)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    json (1.4.6)
+    multi_json (0.0.5)
+    multipart-post (1.0.1)
+    rack (1.2.1)
+    rake (0.8.7)
+    rcov (0.9.9)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.3.0)
+    typhoeus (0.2.0)
+    webmock (1.4.0)
+      addressable (>= 2.2.2)
+      crack (>= 0.1.7)
+    will_paginate (3.0.pre2)
+    yajl-ruby (0.7.8)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  builder (= 2.1.2)
+  ci_reporter (>= 1.6.3)
+  curb
+  faraday
+  faraday_middleware
+  jeweler
+  json
+  multi_json
+  rcov
+  rspec
+  typhoeus
+  webmock
+  will_paginate (~> 3.0.pre2)
+  yajl-ruby

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,128 @@
+flexmls API
+=====================
+A Ruby wrapper for the flexmls REST API. Loosely based on ActiveResource to provide models to interact with remote services.
+
+
+Documentation
+-------------
+For full information on the API, see [http://www.flexmls.com/developers/](http://www.flexmls.com/developers/)
+
+
+Installation
+---------
+    gem install flexmls_api
+
+Usage Examples
+------------------------
+    # initialize the gem with your key/secret
+    # api_key and _api_secret are the only required settings
+    # other options and their defaults:
+    #  - endpoint:   'http://api.flexmls.com'  
+    #  - version:    'v1'
+    #  - ssl:         false
+    #  - user_agent: 'flexmls API Ruby Gem'
+    FlexmlsApi.configure do |config|
+        config.api_key    = 'your_api_key'
+        config.api_secret = 'your_api_secret'
+    end
+
+    # mixin the models so you can use them without prefix
+    include FlexmlsApi::Models
+
+    # Grab your listings!
+    my_listings = Listing.my()
+
+Authentication
+--------------
+Authentication is handled transparently by the request framework in the gem, so you should never need to manually make an authentication request.
+
+
+
+Error Codes
+---------------------
+<table>
+  <thead>
+    <tr>
+      <th>HTTP Code</th>
+      <th>flexmls 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,78 @@
+require "rubygems"
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'ci/reporter/rake/rspec'
+require "rspec"
+require 'rspec/core/rake_task'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "flexmls_api"
+    gemspec.summary = "A library for interacting with the flexmls web services."
+    gemspec.description = "A library for interacting with the flexmls web services."
+    gemspec.email = "api-support@flexmls.com"
+    gemspec.homepage = "https://github.com/flexmls/flexmls_api"
+    gemspec.authors = ["Brandon Hornseth"]
+    gemspec.files =  FileList["[A-Z]*", "{lib,spec}/**/*"]
+    gemspec.add_development_dependency "rspec"
+    gemspec.add_development_dependency "jeweler"
+    gemspec.add_development_dependency "curb"
+    gemspec.add_development_dependency "json"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end
+
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["-c", "-f progress"]
+  t.pattern = 'spec/**/*_spec.rb'
+  t.rcov = true
+  t.rcov_opts = %w{--exclude /usr/local/rvm/gems/,bundle,spec}
+end
+
+task :install do
+  require './lib/flexmls_api'
+  rm_rf "*.gem"
+  puts `gem build flexmls_api.gemspec`
+  puts `sudo gem install flexmls_api-#{FlexmlsApi::VERSION}.gem`
+end
+
+desc "Run all the tests"
+task :default => :spec
+
+Rake::TaskManager.class_eval do
+  def remove_task(task_name)
+    @tasks.delete(task_name.to_s)
+  end
+end
+
+def remove_task(task_name)
+  Rake.application.remove_task(task_name)
+end 
+
+Rake::RDocTask.new do |rdoc|
+  files =['lib/**/*.rb']
+  rdoc.rdoc_files.add(files)
+  rdoc.main = "README.md" # page to start on
+  rdoc.title = "flexmls_api Docs"
+  rdoc.rdoc_dir = 'doc/rdoc' # rdoc output folder
+  rdoc.options << '--line-numbers'
+end
+
+spec = Gem::Specification::load("flexmls_api.gemspec")
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+task :deploy do
+  gems = FileList['pkg/*.gem']
+  FileUtils.cp gems, '/opt/gems/dev/gems'
+  require 'rubygems'
+  require 'rubygems/indexer'
+  i=Gem::Indexer.new '/opt/gems/dev'
+  i.generate_index
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.2

data/lib/flexmls_api/authentication.rb

@@ -0,0 +1,104 @@
+require 'openssl'
+require 'faraday'
+require 'faraday_middleware'
+require 'yajl'
+require 'date'
+module FlexmlsApi
+  # =API Authentication
+  # Handles authentication and reauthentication to the flexmls api.
+  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:
+    #   FlexmlsApi::ClientError when authentication fails
+    def authenticate
+      sig = sign("#{@api_secret}ApiKey#{@api_key}")
+      FlexmlsApi.logger.debug("Authenticating to #{@endpoint}")
+      start_time = Time.now
+      request_path = "/#{version}/session?ApiKey=#{api_key}&ApiSig=#{sig}"
+      resp = connection(true).post request_path, ""
+      request_time = Time.now - start_time
+      FlexmlsApi.logger.info("[#{request_time}s] Api: POST #{request_path}")
+      @session = Session.new(resp.body.results[0])
+      FlexmlsApi.logger.debug("Authentication: #{@session.inspect}")
+      @session
+    end
+    
+    # Builds an ordered list of key value pairs and concatenates it all as one big string.  Used 
+    # specifically for signing a request.
+    def build_param_string(param_hash)
+      return "" if param_hash.nil?
+        sorted = param_hash.sort do |a,b|
+          a.to_s <=> b.to_s
+        end
+        params = ""
+        sorted.each do |key,val|
+          params += key.to_s + val.to_s
+        end
+        params
+    end
+    
+    # ==Session class
+    # Handle on the api user session information as return by the api session service, including 
+    # roles, tokens and expiration
+    class Session
+      attr_accessor :auth_token, :expires, :roles 
+      def initialize(options={})
+        @auth_token = options["AuthToken"]
+        @expires = DateTime.parse options["Expires"]
+        @roles = options["Roles"]
+      end
+      #  Is the user session token expired?
+      def expired?
+        DateTime.now > @expires
+      end
+    end
+    
+    # Main connection object for running requests.  Bootstraps the Faraday abstraction layer with 
+    # our client configuration.
+    def connection(force_ssl = false)
+      opts = {
+        :headers => headers
+      }
+      domain = @endpoint 
+      if(force_ssl || self.ssl)
+        opts[:ssl] = {:verify => false }
+        opts[:url] = @endpoint.sub /^http:/, "https:"
+      else 
+        opts[:url] = @endpoint.sub /^https:/, "http:"
+      end
+      conn = Faraday::Connection.new(opts) do |builder|
+        builder.adapter Faraday.default_adapter
+        builder.use Faraday::Response::ParseJson
+        builder.use FlexmlsApi::FaradayExt::FlexmlsMiddleware
+      end
+      FlexmlsApi.logger.debug("Connection: #{conn.inspect}")
+      conn
+    end
+    
+    # HTTP request headers
+    def headers
+      {
+        :accept => 'application/json',
+        :content_type => 'application/json',
+        :user_agent => user_agent,
+        'X-flexmlsApi-User-Agent' => user_agent
+      }
+    end
+    
+    # Sign a request
+    def sign(sig)
+      Digest::MD5.hexdigest(sig)
+    end
+
+    # Sign a request with request data.
+    def sign_token(path, params = {}, post_data="")
+      sign("#{@api_secret}ApiKey#{@api_key}ServicePath/#{version}#{path}#{build_param_string(params)}#{post_data}")
+    end
+    
+  end
+end

data/lib/flexmls_api/client.rb

@@ -0,0 +1,20 @@
+module FlexmlsApi
+  # =API Client
+  # Main class to setup and run requests on the API.  A default client is accessible globally as 
+  # FlexmlsApi::client if the global configuration has been set as well.  Otherwise, this class may 
+  # be instanciated separately with the configuration information.
+  class Client
+    include Authentication
+    include Request
+    
+    attr_accessor *Configuration::VALID_OPTION_KEYS
+    
+    def initialize(options={})
+      options = FlexmlsApi.options.merge(options)
+      Configuration::VALID_OPTION_KEYS.each do |key|
+        send("#{key}=", options[key])
+      end
+    end
+
+  end
+end

data/lib/flexmls_api/configuration.rb

@@ -0,0 +1,40 @@
+module FlexmlsApi
+  module Configuration
+    # valid configuration options
+    VALID_OPTION_KEYS = [:api_key, :api_secret, :endpoint, :user_agent, :version, :ssl].freeze
+
+    DEFAULT_API_KEY = nil
+    DEFAULT_API_SECRET = nil
+    DEFAULT_ENDPOINT = 'http://api.flexmls.com'
+    DEFAULT_VERSION = 'v1'
+    DEFAULT_USER_AGENT = "flexmls API Ruby Gem #{VERSION}"
+    DEFAULT_SSL = false
+
+    attr_accessor *VALID_OPTION_KEYS
+    def configure
+      yield self
+    end
+
+    def self.extended(base)
+      base.reset_configuration
+    end
+
+
+    def options
+      VALID_OPTION_KEYS.inject({}) do |opt,key|
+        opt.merge(key => send(key))
+      end
+    end
+
+
+    def reset_configuration
+      self.api_key     = DEFAULT_API_KEY
+      self.api_secret  = DEFAULT_API_SECRET
+      self.endpoint    = DEFAULT_ENDPOINT
+      self.version     = DEFAULT_VERSION
+      self.user_agent  = DEFAULT_USER_AGENT
+      self.ssl         = DEFAULT_SSL
+      self
+    end
+  end
+end